Accesibilidad que viene con el oficio
La accesibilidad no es una casilla de verificación de cumplimiento que se agrega al final; es el piso del oficio de interfaces. La mayor parte es gratuita si usas la plataforma: los elementos nativos vienen con soporte de teclado, las etiquetas reales se anuncian a sí mismas y un anillo de foco visible es una regla CSS. Aplica estos principios al construir o revisar código de UI, y adáptate al sistema de estilos existente del proyecto (Tailwind vs. CSS plano vs. CSS-in-JS) al aplicar correcciones.
Al revisar, recorre la interfaz primero como usuario solo de teclado (cada flujo debe completarse sin mouse), luego como usuario de lector de pantalla: ¿cada control anuncia un nombre, un rol y su estado? Cuando no estés seguro, prefiere la plataforma predeterminada sobre una reconstrucción personalizada, y elimina ARIA en lugar de agregarlo.
La medición de contraste de pares renderizados y la remediación de color están cubiertas por el skill better-colors; el tamaño visual del texto y el zoom de iOS en better-typography; el layout espacial RTL en better-layout.
Referencia rápida
| Categoría | Cuándo usarla |
|---|---|
| Foco y teclado | Anillos de foco, enlaces de salto, tabindex, trampas de foco, patrones de teclado APG |
| Semántica y ARIA | Elementos nativos primero, botón vs enlace, puntos de referencia, nombres accesibles, estados deshabilitados |
| Formularios | Etiquetas, autocompletado, mensajes de error, tipos de entrada |
| Lectores de pantalla | Contenido visualmente oculto, regiones en vivo, toasts, texto alternativo, SVG |
| Áreas de toque | Tamaños de objetivo, expansión de áreas de toque, reglas de colisión |
| Movimiento y zoom | prefers-reduced-motion, reproducción automática y UI temporizada, zoom al 200%, reflujo, rem vs px |
Principios fundamentales
1. Elementos nativos primero
La primera regla de ARIA: no uses ARIA cuando exista un elemento nativo. <button> para acciones, <a href> para navegación (debe soportar Cmd/Ctrl/clic medio), nunca <div onClick>. Sin ARIA es mejor que ARIA incorrecta.
2. Anillos de foco visibles
Aplica estilo a :focus-visible, no a :focus simple, para que los usuarios de teclado obtengan un anillo y los de mouse normalmente no. Prefiere el indicador de foco sin modificar del navegador. Si el diseño necesita un anillo personalizado, usa un token de foco del proyecto u otro color explícito y verifica el indicador completo contra cada color adyacente que cruce; currentColor es aceptable solo después de la misma verificación. Usa al menos un perímetro sólido de 2px o un área visible equivalente. Nunca uses outline: none sin un reemplazo verificado, y conserva los colores del sistema en el modo forced-colors.
3. Soporte completo de teclado
Cada interacción con el puntero necesita una ruta de teclado, siguiendo los patrones APG de ARIA: Escape cierra superposiciones, las teclas de flecha se mueven dentro de widgets compuestos (pestañas, menús, listboxes), Tab se mueve entre widgets, Enter y Espacio activan. Solo tabindex="0" (unirse al orden de tabulación natural) y tabindex="-1" (foco programático), nunca valores positivos, que rompen el orden natural. Los widgets compuestos usan roving tabindex: el elemento activo es 0, todos los demás -1.
4. Atrapar y restaurar el foco
Los modales establecen inert en el contenido de fondo, mueven el foco adentro al abrirse y devuelven el foco al activador al cerrarse. Agrega overscroll-behavior: contain para que el contenido de fondo no se desplace.
5. Área de toque mínima
La línea base del Nivel AA de WCAG 2.5.8 es un objetivo de 24×24 píxeles CSS o una de sus excepciones definidas (espaciado, control equivalente, en línea, agente de usuario o esencial). Para una activación más fácil, apunta a 44×44px en contextos táctiles y 40×40px en interfaces de escritorio cuando la densidad lo permita. Extiende con un pseudoelemento si el elemento visible debe mantenerse más pequeño. Nunca dejes que las áreas de toque extendidas se superpongan.
6. Etiqueta y tipo de cada control
Cada entrada tiene un <label for> o un <label> envolvente; un marcador de posición nunca es una etiqueta, y la etiqueta y el control comparten un objetivo de toque: sin zonas muertas entre una casilla de verificación y su texto. Agrega autocomplete con un name significativo, y el type e inputmode correctos para el teclado. Nunca bloquees el pegado; los usuarios pegan contraseñas y códigos de un solo uso.
7. Errores que se anuncian
Mantén el envío habilitado hasta que comience la solicitud, luego deshabilítalo con un spinner mientras conservas la etiqueta original. Valida al enviar: marca los campos que fallan con aria-invalid="true", apunta aria-describedby al texto de error en línea, y enfoca el primer campo inválido. Usa disabled nativo cuando un control nativo no esté genuinamente disponible. Usa aria-disabled="true" solo cuando retener la capacidad de enfoque o descubrimiento sea intencional; luego bloquea el comportamiento del puntero, teclado y formulario en el código y estiliza el estado explícitamente.
8. Nombres accesibles en todas partes
Los botones de solo icono necesitan un aria-label descriptivo. El texto de la etiqueta visible debe aparecer en el nombre accesible. Los elementos decorativos obtienen aria-hidden="true", nunca en un elemento enfocable.
9. No confíes solo en el color
El estado necesita una señal redundante: icono, texto o subrayado junto con el color. Determina qué requisito de contraste WCAG aplica según el contenido y el estado, luego usa better-colors para medir el par renderizado de primer plano/fondo. Cuando el contraste falle, reporta el par y el requisito que no cumple; no cambies los colores del proyecto a menos que te lo pidan.
10. Honra prefers-reduced-motion
Envuelve la animación en @media (prefers-reduced-motion: no-preference) para que sea opcional. Con movimiento reducido, reemplaza deslizamientos y escalas con fundidos cruzados de opacidad; elimina el paralaje y la reproducción automática por completo. Independientemente de la preferencia: los medios de reproducción automática necesitan un control de pausa visible, y los toasts que contienen acciones o errores permanecen hasta que se descartan.
11. Anuncia contenido dinámico
Usa aria-describedby para validación específica de campo, una región en vivo cortés (role="status") para actualizaciones no urgentes no vinculadas a un control, como toasts o conteos de resultados, y role="alert" solo para errores urgentes no vinculados a un control. Para anuncios corteses repetidos confiables, renderiza una región vacía estable antes de actualizar su texto; las alertas insertadas dinámicamente tienen soporte diferente y deben probarse con los lectores de pantalla objetivo.
12. Texto alternativo según el propósito
Las imágenes decorativas obtienen alt="", las informativas describen el significado, las funcionales describen la acción: un botón de icono de búsqueda es alt="Buscar", no alt="lupa".
13. La estructura es navegación
Usa encabezados que describan sus secciones y formen un esquema coherente; un <h1> a nivel de página y niveles anidados adecuadamente son la recomendación predeterminada, no reglas independientes de aprobación/fallo de WCAG. Expón un punto de referencia <main> primario visible. Cuando la navegación repetida o el cromo lo precedan, haz que un enlace "Saltar al contenido" sea el primer elemento enfocable. Los encabezados anclados obtienen scroll-margin-top.
14. Sobrevive al zoom y al cambio de tamaño de texto
La página debe funcionar con zoom al 200% y reflujo a 320px de ancho sin desplazamiento horizontal. Usa min-height en lugar de height fija en contenedores de texto, prefiere puntos de interrupción rem donde se ajusten a las convenciones del código base, y mantén la meta de viewport sin limitar hasta dónde puede hacer zoom el lector.
Errores comunes
| Error | Corrección |
|---|---|
outline: none para eliminar el anillo de foco | Aplica estilo a :focus-visible; los clics del mouse no lo mostrarán |
| Color de foco personalizado asumido que funciona en todas partes | Verifica el indicador completo contra cada color adyacente y en modo forced-colors |
<div onClick> para un botón o enlace | <button> para acciones, <a href> para navegación |
| Marcador de posición usado como única etiqueta | Agrega un <label for> visible; los marcadores de posición desaparecen al escribir |
tabindex positivo para arreglar el orden de foco | Arregla el orden del DOM; solo usa 0 y -1 |
| Actualización cortés repetida anunciada de forma inconsistente | Mantén una región de estado vacía estable y actualiza su texto; prueba los lectores de pantalla objetivo |
Región en vivo assertive para un toast rutinario | Usa polite; reserva assertive para errores |
aria-hidden="true" en un elemento enfocable | Elimínalo o haz que el elemento no sea enfocable |
| Texto alternativo de icono funcional que describe la imagen | Describe la acción: alt="Buscar", no alt="lupa" |
| Envío deshabilitado hasta que el formulario sea válido | Mantenlo habilitado; valida al enviar y enfoca el primer error |
Formato de salida de revisión
Usa este formato solo cuando el usuario solicite una revisión de accesibilidad independiente. Cuando better-interface orqueste la revisión, proporciona evidencia del dominio y hallazgos a ese skill y deja que su formato de salida, escala de gravedad, reglas de consolidación, límite y veredicto tengan prioridad.
Presenta la revisión independiente en dos partes.
Hallazgos
Agrupa todos los hallazgos confirmados por principio. Usa una tabla de markdown con las columnas Gravedad, Ubicación, Antes, Después y Por qué. Nunca uses líneas separadas "Antes:" / "Después:".
- Gravedad:
ALTAimpide una tarea, oculta contenido a la tecnología de asistencia o crea una falla sistémica de accesibilidad;MEDIAhace que una interacción sea significativamente más difícil;BAJAes pulido aislado. - Ubicación: cita
ruta/al/archivo:línea. Si el artefacto no tiene archivos fuente, cita la pantalla y el componente exactos en su lugar. - Antes / Después: muestra la implementación actual y un reemplazo procesable.
- Por qué: nombra el principio violado y su impacto en el usuario.
Consolida un problema sistémico repetido en una fila y enumera cada ubicación afectada. Omite principios sin hallazgos.
Ejemplo
Nombres accesibles en todas partes
| Gravedad | Ubicación | Antes | Después | Por qué |
|---|---|---|---|---|
| ALTA | src/Dialog.tsx:42 | <button><XIcon /></button> | Agrega aria-label="Cerrar"; marca el icono aria-hidden="true" | El control de solo icono no tiene un nombre accesible |
| ALTA | src/Nav.tsx:18 | <a href="/settings"><GearIcon /></a> | Agrega aria-label="Configuración" | El destino del enlace no está disponible para los lectores de pantalla |
Anillos de foco visibles
| Gravedad | Ubicación | Antes | Después | Por qué |
|---|---|---|---|---|
| ALTA | src/button.css:12 | button:focus { outline: none; } | button:focus-visible { outline: 2px solid; outline-offset: 2px; } | Los usuarios de teclado no pueden ver el foco |
| ALTA | src/Menu.tsx:31 | focus:outline-none | focus-visible:outline-2 focus-visible:outline-offset-2 | La navegación del menú no tiene un indicador de foco visible |
Errores que se anuncian
| Gravedad | Ubicación | Antes | Después | Por qué |
|---|---|---|---|---|
| ALTA | src/EmailField.tsx:27 | Error mostrado solo como border-red-500 | Agrega aria-invalid="true" + aria-describedby="email-error" con texto de error en línea | Solo el color no explica ni anuncia el error |
| MEDIA | src/SignupForm.tsx:64 | Envío deshabilitado hasta que el formulario sea válido | Mantén el envío habilitado; si falla, enfoca el primer campo inválido | Una acción deshabilitada oculta lo que debe corregirse |
Área de toque mínima
| Gravedad | Ubicación | Antes | Después | Por qué |
|---|---|---|---|---|
| MEDIA | src/Toolbar.tsx:22 | Botón de solo icono size-4 | Extiende el área de toque a 44×44px con after:absolute after:size-11 | El objetivo es demasiado pequeño para una entrada táctil confiable |
Verificación y veredicto
Después de los hallazgos:
- Verificación: enumera las verificaciones exactas realizadas y sus resultados observados, incluyendo recorrido de teclado, inspección de nombres accesibles y comprobaciones de lector de pantalla o automatizadas cuando sea aplicable. Si no se realizó una verificación, indica qué aún necesita verificación.
- Veredicto:
Bloqueadosi queda algún hallazgoALTO,Requiere cambiossi solo quedan hallazgosMEDIOoBAJO, yAprobarsolo cuando no queden hallazgos procesables.
Cuando no haya hallazgos, omite las tablas, indica "No hay hallazgos de accesibilidad procesables", reporta la verificación y termina con Aprobar.