Anotaciones de accesibilidad en el handoff: qué escribir para desarrollo
Las anotaciones de accesibilidad dicen a desarrollo cómo debe comportarse un diseño con teclado y lector de pantalla: alt, encabezados, foco y nombres.
¿Qué son estas anotaciones?
Un diseño es una imagen fija. Un lector de pantalla y el teclado no ven la imagen: leen una estructura. Las anotaciones describen esa estructura en la capa del diseño, porque a menudo no está en el mockup. TestParty, un proveedor de software de accesibilidad, lo resume así: el diseño visual no dicta el orden de foco, y eso hay que indicarlo.
Son útiles en cualquier flujo de handoff, con o sin herramienta específica: lo importante es que la información viaje con el diseño. Microsoft Learn, por ejemplo, enseña a hacerlo en Figma con plugins que dibujan indicadores numerados de orden de foco, y con tablas de nombre, rol y estado.
¿Qué debe anotar un diseñador?
La lista depende de la pantalla, pero estas son las anotaciones más habituales:
| Anotación | Qué especifica | Ejemplo |
|---|---|---|
| Texto alternativo | Qué transmite la imagen, o que es decorativa | “Gráfico de barras: ventas por trimestre” o “decorativa” |
| Encabezados | Nivel jerárquico de cada título | “H1: Mis pedidos”, “H2: Pedidos pendientes” |
| Landmarks | Regiones principales de la página | Navegación, contenido principal, buscador |
| Nombre accesible | Lo que anuncia el lector de pantalla | Un icono de cerrar se llama “Cerrar diálogo” |
| Estados | Solo los que importan en el flujo | Un botón deshabilitado, un campo con error |
| Orden de foco | Secuencia de Tab en pantallas complejas | Del campo de búsqueda a los filtros, luego a los resultados |
| Comportamiento de teclado | Qué hacen Enter, Espacio o Escape | Enter y Espacio activan un botón |
| Avisos dinámicos | Cambios que se anuncian sin mover el foco | “Se encontraron 12 resultados” |
Algunas reglas que da Microsoft Learn:
- Encabezados: solo puede haber un H1 por página, y los niveles no se saltan (no pasas de H2 a H4 sin un H3).
- Landmarks: la mayoría de las veces bastan los encabezados; define landmarks solo en páginas largas o con regiones claras, y menos es mejor. Solo puede haber un banner.
- Nombres repetidos: si dos botones se llaman “Crear”, el lector de pantalla anuncia “Crear, Crear” al navegar por botones. Anota un nombre accesible que incluya el visible, como “Crear plantilla de bienvenida”.
- Estados: anótalos cuando ilustran una condición clave del flujo, como un botón deshabilitado.
- Alertas y mensajes de error: deben llegar al lector de pantalla sin robar el foco.
El texto alternativo tiene una regla práctica: si una imagen es decorativa, debe marcarse así. En HTML, el W3C indica un atributo alt vacío (alt="") para que las tecnologías de apoyo la ignoren. No conviene omitir el atributo, porque algunos lectores anunciarían el nombre del archivo. En la anotación basta con escribir “decorativa”.
¿Qué diferencia hay entre orden de foco y orden de lectura?
El orden de foco es la secuencia en que los elementos interactivos reciben el foco al navegar con Tab. El orden de lectura es el que sigue el lector de pantalla al recorrer el contenido. Muchas veces coinciden, pero no tienen por qué.
WCAG 2.2 pide, en el criterio 2.4.3 (nivel A), que los componentes enfocables reciban el foco en un orden que conserve el significado y la operabilidad. Según el W3C, el foco no tiene por qué seguir la disposición visual, pero sí respetar las relaciones que el diseño sugiere. El criterio 1.3.2 (nivel A) pide algo parecido para la secuencia de lectura: debe poder determinarse por software cuando afecta al significado. Sin scripts ni tabindex, el foco sigue el orden del código, así que si el código no coincide con el diseño, el diseñador tiene que decirlo.
Microsoft Learn recomienda mostrar la secuencia con indicadores numerados en el diseño. Esa numeración sirve sobre todo cuando el orden lógico no coincide con la disposición visual, por ejemplo en una tarjeta con el botón de acción a la izquierda de un título.
¿Cómo se anota el foco en un diálogo?
Los diálogos y los menús son el lugar donde más se rompe el foco. Microsoft Learn indica que, al abrir o cerrar un diálogo o un menú, el foco debe volver al componente que lo activó. TestParty señala que el comportamiento del foco en modales rara vez se especifica en los diseños y pide documentar dónde va el foco al abrirlos.
Anota también la acción de Escape cuando cierra el diálogo, y qué ocurre si el usuario llega al final de la lista de opciones.
¿Cómo se trabaja con desarrollo?
Las anotaciones no se escriben una vez y se olvidan. Un flujo que funciona:
- Anota antes de revisar con desarrollo, para tener una propuesta concreta.
- Recorre el flujo solo con teclado junto con la persona que implementa.
- Prueba con un lector de pantalla antes de cerrar los nombres y roles.
- Guarda las anotaciones en el mismo archivo del diseño o del sistema, no en un documento aparte que nadie abre.
Si el equipo ya usa un sistema de diseño, documentar los componentes con sus estados y comportamientos reduce la cantidad de anotaciones por pantalla.
¿Cuándo NO conviene anotar todo?
Digitala11y advierte que anotar todo rara vez es efectivo: el exceso de documentación abruma al equipo de desarrollo y entierra lo esencial. Su objetivo, dice, es guiar la intención y las prioridades, no reemplazar las pruebas. Prioriza:
- Componentes complejos: menús, tabs, acordeones, diálogos y selectores.
- Formularios: etiqueta visible, instrucciones y mensajes de error asociados.
- Pantallas donde el orden visual y el lógico no coinciden.
- Contenido que cambia sin recargar la página, como alertas o resultados de búsqueda.
El resto suele heredar el comportamiento de los componentes ya documentados.
Ejemplo
Ejemplo ilustrativo: un equipo diseña una pantalla de filtros para un catálogo. El mockup muestra los filtros a la izquierda y los resultados a la derecha. Sin anotaciones, desarrollo implementa el orden de foco tal como aparece en el código, que pasa por los resultados antes que los filtros. El diseñador añade una nota con el orden de foco numerado: primero los filtros, luego los resultados, y un aviso de que el número de resultados se anuncia al cambiar. La implementación queda alineada con la pantalla y con el teclado.
Errores comunes
- Dejar el texto alternativo para el final, y que termine siendo “imagen” o el nombre del archivo.
- Confundir nivel de encabezado con tamaño de texto: un H2 puede verse grande o pequeño.
- Anotar el orden de foco sin probarlo con teclado.
- Olvidar el foco al cerrar diálogos, lo que deja al usuario de teclado perdido.
- Usar nombres genéricos como “Crear” o “Enviar” repetidos, sin contexto para quien navega solo por botones.
- Pensar que la anotación reemplaza la prueba con personas que usan lector de pantalla.
Para validar lo que anotaste, las pruebas con lectores de pantalla son el siguiente paso natural. Si quieres entender el árbol de accesibilidad que construye el navegador a partir de tu diseño, el árbol de accesibilidad lo explica. Y para lo que no es técnico, accesibilidad cognitiva complementa estas notas con criterios de memoria y atención.
Fuentes
- Accessibility design specs with annotations: Annotations for keyboard and screen reader navigation, Microsoft Learn
- Understanding Success Criterion 2.4.3: Focus Order, W3C WAI
- Understanding Success Criterion 1.3.2: Meaningful Sequence, W3C WAI
- Decorative Images, W3C WAI Web Accessibility Tutorials
- From Figma to Prod: Fixing Accessibility at Design Handoff, TestParty (proveedor de software de accesibilidad)
- Why Figma Annotations Are Critical for a Shift-Left Accessibility Approach, Digitala11y (Monika Prasad, actualizado el 5 de febrero de 2026)