26. Accesibilidad: WCAG, teclado, ARIA y pruebas

26.1 Qué vas a poder hacer al terminar

• Explicar qué es el árbol de accesibilidad, cómo lo construye el navegador a partir del DOM y por qué es la única cosa que un lector de pantalla puede leer.
• Calcular a mano el nombre accesible de cualquier elemento y saber qué fuente gana sobre cuál, que es la causa de la mitad de los fallos de etiquetado.
• Leer un criterio de WCAG y traducirlo a una comprobación concreta sobre tu código, distinguiendo con criterio qué exige el nivel A, qué el AA y qué el AAA.
• Sustituir la mayor parte del ARIA de un proyecto por HTML semántico correcto, y justificar técnicamente por qué eso es una mejora y no un atajo.
• Aplicar la primera regla de ARIA y, cuando de verdad haga falta, escribir los roles, estados y propiedades correctos sin dejar el componente en un estado inconsistente.
• Construir cualquier componente interactivo (menú, pestañas, diálogo, combo, árbol) con el contrato de teclado que el estándar de authoring practices especifica.
• Resolver el problema que Angular no resuelve solo: la gestión del foco en una aplicación de una sola página, al cambiar de ruta, al abrir un diálogo y al eliminar un elemento de una lista.
• Diseñar formularios accesibles de verdad: etiquetas asociadas, agrupaciones, campos obligatorios, errores anunciados y validación en el momento adecuado, integrado con los formularios reactivos del capítulo 5.
• Auditar un sistema de tokens de color, comprobar los ratios de contraste que exige la norma y detectar la información que viaja solo en el color.
• Anunciar contenido dinámico —cargas, notificaciones, resultados de búsqueda, tablas que se refrescan— con regiones activas y el nivel de urgencia correcto.
• Usar el paquete de accesibilidad del CDK de Angular (FocusTrap, LiveAnnouncer, FocusMonitor, gestores de teclado) y saber exactamente qué te da Angular Material de serie y qué no.
• Montar una estrategia de pruebas en tres capas: reglas de linter en las plantillas, axe en la suite automatizada con una puerta en integración continua, y un protocolo manual de teclado y lector de pantalla que cabe en cinco minutos.
• Extender la accesibilidad al lado servidor: correos transaccionales, PDF generados e informes descargables.

26.2 El problema real: quién usa tu aplicación

Cuando un equipo diseña una interfaz, lo hace implícitamente para un usuario concreto: alguien con visión normal, mirando una pantalla grande y bien iluminada, con las dos manos libres, un ratón preciso, una conexión estable y toda su capacidad de atención disponible. Ese usuario existe, pero es una minoría de los momentos de uso reales, no la mayoría. La accesibilidad no consiste en añadir un modo especial para un colectivo aparte: consiste en dejar de asumir que todo el mundo usa la aplicación en las condiciones en las que tú la desarrollas.

26.2.1 Tipos de discapacidad y qué implica cada uno técnicamente

Conviene pensar en categorías funcionales, no en diagnósticos médicos. Lo que importa para el código no es la etiqueta clínica, sino por qué canal entra la información y por qué canal sale la acción.

26.2.2 Discapacidad situacional y temporal: el argumento que convence a un gestor de producto

Aquí está el punto que suele desbloquear la conversación en un comité de priorización. Las limitaciones no son solo permanentes. Microsoft popularizó una clasificación muy útil que distingue tres duraciones para la misma limitación funcional, y las tres se benefician exactamente de las mismas soluciones técnicas.

La consecuencia práctica es que el arreglo accesible casi nunca beneficia solo a quien tiene una discapacidad permanente. El indicador de foco visible sirve al usuario ciego y también al comercial que rellena el formulario de alta de proyecto con el teclado porque va más rápido. Los subtítulos del vídeo de onboarding de TaskFlow los usa la persona sorda y los usa la mayoría silenciosa que ve vídeos sin sonido. Un objetivo de pulsación amplio sirve a quien tiene temblor y a cualquiera que use el móvil de pie en un autobús. Es el mismo efecto que el bordillo rebajado de una acera: se legisló para sillas de ruedas y lo usan carritos, maletas, bicicletas y repartidores.

26.2.3 El marco legal: por qué esto entra en los pliegos

La razón por la que la accesibilidad aparece en los contratos no es ética, es contractual. En el ámbito europeo hay dos piezas que conviene conocer por nombre, porque son las que citan los pliegos de licitación:

• La norma armonizada EN 301 549, «Requisitos de accesibilidad para productos y servicios TIC». Es el documento técnico de referencia en Europa. Para el contenido web, su capítulo correspondiente remite directamente a WCAG en nivel AA: no reinventa los criterios, los adopta. Además cubre cosas que WCAG no toca, como el hardware, la documentación de soporte o los servicios de atención al cliente. Si un pliego dice «conforme a EN 301 549», en la práctica te está pidiendo WCAG AA más un puñado de requisitos adicionales de documentación.
• Las directivas europeas de accesibilidad. La primera obliga a los organismos del sector público a que sus sitios web y aplicaciones móviles sean accesibles, con declaración de accesibilidad y mecanismo de reclamación. La segunda, conocida como Acta Europea de Accesibilidad, extiende obligaciones a determinados productos y servicios del sector privado —comercio electrónico, banca, transporte, libros electrónicos, entre otros—. Cada Estado miembro las transpone a su propia norma nacional, que es la que finalmente te aplica.

Hay un segundo efecto legal, menos citado y más frecuente en la práctica: la declaración de accesibilidad. Muchas normativas obligan a publicar un documento que diga en qué grado cumples, qué contenido queda fuera y cómo reclamar. Eso convierte la accesibilidad en algo auditable por terceros con nombres y apellidos. Un equipo que no sabe qué criterios incumple no puede firmar esa declaración, y firmarla en falso es un riesgo mucho mayor que reconocer una excepción concreta.

26.2.4 El coste de arreglarlo tarde

El argumento económico es el que decide las prioridades, así que merece la pena plantearlo con precisión. La accesibilidad tiene una propiedad incómoda: su coste de corrección crece con la profundidad arquitectónica del fallo, no con el número de pantallas afectadas.

COSTE DE CORREGIR EL MISMO FALLO SEGÚN CUÁNDO SE DETECTA

  DISEÑO          Paleta con contraste insuficiente para el texto secundario.
  ─────────       Arreglo: cambiar dos valores en el archivo de tokens.
  coste: 1        Nadie ha escrito código todavía.

  DESARROLLO      El componente <app-boton-icono> nace sin nombre accesible.
  ─────────       Arreglo: añadir la entrada `etiqueta` obligatoria al componente.
  coste: 3        Hay 4 usos; el compilador te los señala uno a uno.

  QA / PREPRO     Los 180 usos de <app-boton-icono> están repartidos por 40 pantallas.
  ─────────       Arreglo: mismo cambio + revisar 180 llamadas + redactar 180 textos
  coste: 30       + volver a probar 40 pantallas.

  PRODUCCIÓN      Auditoría externa. El «botón» es un <div> con (click) heredado
  ─────────       de un componente base del que dependen 12 widgets, ninguno
  coste: 150      recibe foco y el diálogo que abren no atrapa el foco.
                  Arreglo: rediseño del componente base + 12 widgets + regresión
                  visual completa + plazo legal encima.

Los saltos de escala del diagrama no son arbitrarios, responden a tres mecanismos concretos:

• Multiplicación por reutilización. Un componente compartido mal diseñado propaga el fallo a cada uso. Es la misma matemática que una firma de método mal elegida: cuanto más se usa, más caro es cambiarla.
• Acoplamiento con el diseño visual. Corregir el contraste en producción implica tocar la identidad visual del producto, y eso deja de ser una decisión de ingeniería para convertirse en una negociación con diseño, marketing y a veces dirección.
• Contenido, no solo código. Los textos alternativos, las etiquetas de los iconos, los subtítulos y los mensajes de error son contenido. Escribir 180 textos alternativos útiles requiere a alguien que conozca el dominio, y ese alguien no es quien arregla el código.

La conclusión operativa es sencilla y es la que aplicaremos en el resto del capítulo: la accesibilidad se resuelve en los componentes base y en los tokens de diseño. Si el botón de icono de TaskFlow exige un nombre accesible en su API, si el diálogo del sistema atrapa el foco por construcción y si la paleta cumple contraste desde el archivo de tokens, entonces la accesibilidad del 90 % de la aplicación es una consecuencia automática, no una tarea recurrente.

// El nombre accesible es OPCIONAL: cada uso decide, y casi
// ninguno se acuerda. Con 180 usos, 150 quedarán sin nombre.
@Component({
  selector: 'app-boton-icono',
  template: `<button class="icono"><svg>…</svg></button>`,
})
export class BotonIconoComponent {
  readonly icono = input.required<string>();
  readonly etiqueta = input<string>();   // opcional = inexistente
}

// El nombre accesible es parte del CONTRATO del componente.
// Olvidarlo es un error de compilación, no un hallazgo de auditoría.
@Component({
  selector: 'app-boton-icono',
  template: `<button class="icono" type="button"
                     [attr.aria-label]="etiqueta()">
               <svg aria-hidden="true" focusable="false">…</svg>
             </button>`,
})
export class BotonIconoComponent {
  readonly icono = input.required<string>();
  readonly etiqueta = input.required<string>();   // obligatoria
}

Fíjate en lo que hace realmente la versión correcta: convierte un requisito de accesibilidad en una restricción del sistema de tipos. Ese es el patrón mental de todo el capítulo. Cada vez que puedas mover una regla de accesibilidad desde «hay que acordarse» hasta «el compilador, el linter o el test lo impiden», habrás hecho el trabajo bien.

26.3 Cómo funciona un lector de pantalla por dentro

Es imposible razonar sobre accesibilidad sin un modelo mental correcto de qué lee un lector de pantalla. La intuición habitual —«lee el texto de la pantalla»— es falsa y conduce a errores sistemáticos. Un lector de pantalla no ve la pantalla y no lee el DOM. Lee una estructura de datos intermedia que el navegador construye y publica: el árbol de accesibilidad.

26.3.1 El árbol de accesibilidad

El navegador mantiene varias representaciones paralelas del documento. El árbol del DOM es la estructura de nodos. El árbol de renderizado (o de layout) es lo que se pinta, con cajas y posiciones. Y existe un tercero, el árbol de accesibilidad, que es una proyección del DOM pensada para tecnologías de asistencia: elimina lo que no aporta semántica, añade la información implícita de cada elemento HTML y expone cada nodo con cuatro datos fundamentales.

Hay un quinto elemento implícito que suele olvidarse: la descripción accesible, un texto secundario y opcional que se anuncia después del nombre y con una pausa. Es donde van las instrucciones de ayuda y los mensajes de error de un campo.

DEL DOM AL SONIDO: LA CADENA COMPLETA

 1. HTML                      2. DOM                    3. ÁRBOL DE ACCESIBILIDAD
 ─────────────────────       ───────────────────       ─────────────────────────────────
 <main>                       main                      main
  <h1>Tareas</h1>             ├─ h1                      ├─ heading  nivel=1  "Tareas"
  <div class="wrap">          ├─ div.wrap  ────────►     │  (el div no aporta semántica:
   <ul>                       │   └─ ul                  │   NO aparece en el árbol)
    <li>                      │       └─ li              ├─ list  "3 elementos"
     <input type="checkbox"   │           ├─ input       │   └─ listitem
            id="t1">          │           └─ label       │       ├─ checkbox  "Revisar API"
     <label for="t1">         │                          │       │   estado: checked=false
       Revisar API            │                          │       │   propiedad: required=false
     </label>                 │                          │       └─ (el label se ha CONSUMIDO
    </li>                     │                          │           como nombre del checkbox)
  <span aria-hidden="true">   └─ span[aria-hidden]        │
     ✔                                                   └─ (rama podada: aria-hidden)
  </span>
 </main>

 4. API DE ACCESIBILIDAD DEL SISTEMA OPERATIVO
 ─────────────────────────────────────────────────────────────────────────
    Windows: UI Automation / IAccessible2   ·   macOS/iOS: NSAccessibility
    Android: AccessibilityNodeInfo          ·   Linux: AT-SPI
    El navegador PUBLICA el árbol en esta API; no habla con el lector.

 5. LECTOR DE PANTALLA                       6. SALIDA
 ─────────────────────────────────────       ────────────────────────────────
    Consulta la API, aplica su propio           Voz:    "Revisar API,
    diccionario de verbosidad, decide           casilla, no marcada"
    el orden y el idioma de la voz.             Braille: revisar api  ( )

 CONSECUENCIA CLAVE
 ─────────────────────────────────────────────────────────────────────────
 Si un dato (rol, nombre, estado) no está en el paso 3, NO EXISTE.
 Da igual que se vea perfectamente en pantalla en el paso 2.

De este diagrama se derivan casi todas las reglas prácticas del capítulo. Vale la pena hacerlas explícitas:

• Los elementos sin semántica no aparecen. Un <div> o un <span> sin rol ni contenido textual se poda del árbol. Por eso un <div> con un manejador de clic es literalmente invisible: el lector no tiene nada que anunciar.
• El árbol es más plano que el DOM. Doce niveles de div de maquetación se colapsan. Eso es bueno: la estructura que percibe el usuario de lector es la semántica, no la de tu sistema de rejillas.
• Algunos nodos se consumen. El texto de un <label> o el contenido de un <button> se convierten en el nombre del elemento padre y no se anuncian dos veces.
• El árbol es vivo. Cada cambio en el DOM lo actualiza y el navegador emite eventos hacia la API del sistema. Esto es lo que permite que funcione aria-live, y también lo que hace que un cambio masivo de DOM sin avisar deje al usuario desorientado.
• Lo oculto visualmente suele estar oculto también aquí. display: none, visibility: hidden, el atributo hidden y aria-hidden="true" excluyen del árbol. En cambio, la técnica de «solo para lectores de pantalla» (posición absoluta con un recorte de 1 píxel) sí aparece.
• El lector de pantalla decide la locución final. El navegador publica datos; el lector elige palabras, orden, idioma y nivel de detalle. Por eso el mismo HTML se oye distinto en NVDA y en VoiceOver, y por eso probar en uno solo no basta.

26.3.2 El nombre accesible y cómo se calcula

El nombre accesible es la cadena que identifica un elemento. Es el dato más importante del árbol y el que más se estropea, porque no se escribe en un solo sitio: el navegador lo calcula a partir de varias fuentes posibles siguiendo un algoritmo especificado, con una jerarquía estricta. Conocer esa jerarquía es lo que te permite explicar por qué un botón se anuncia «botón» a secas teniendo texto dentro.

CÁLCULO DEL NOMBRE ACCESIBLE (orden de precedencia, se para en el primero que exista)

  ┌─ 1 ─ aria-labelledby   ─► gana SIEMPRE. Concatena el texto de los ids
  │                            referenciados, en el orden en que se listan.
  │                            Ignora por completo lo que haya dentro.
  │
  ├─ 2 ─ aria-label        ─► cadena literal. Pisa el contenido visible.
  │
  ├─ 3 ─ NOMBRE NATIVO DEL HOST      (depende del elemento)
  │        <input>, <select>, <textarea>  ─► su <label for> o label envolvente
  │        <img>                           ─► atributo alt
  │        <fieldset>                      ─► su <legend>
  │        <table>                         ─► su <caption>
  │        <a>, <button>, <th>, <summary>  ─► su contenido de texto
  │        <svg>                           ─► su <title> hijo
  │
  ├─ 4 ─ CONTENIDO DE TEXTO   ─► solo para roles que lo permiten (button, link,
  │                              heading, option, cell, tab…). NO para textbox.
  │
  └─ 5 ─ atributo title       ─► último recurso. Frágil: no se ve con teclado,
                                 no se ve en táctil, algunos lectores lo omiten.

  Si tras los cinco pasos el nombre es la cadena vacía  ─►  ELEMENTO SIN NOMBRE.
  El lector anuncia solo el rol: "botón", "enlace", "casilla".
  Es el fallo de accesibilidad número uno en aplicaciones reales.

<!-- 1. sin nombre: solo hay un icono, y el svg se poda -->
<button><svg class="i-trash"></svg></button>

<!-- 2. el aria-label PISA el texto visible: rompe 2.5.3 -->
<button aria-label="Eliminar">Borrar tarea</button>

<!-- 3. title como único nombre: frágil y no visible con teclado -->
<button title="Duplicar"><svg class="i-copy"></svg></button>

<!-- 4. nombre no único: 40 filas anuncian "Editar, botón" -->
<button>Editar</button>

<!-- 5. el placeholder NO es un nombre fiable -->
<input type="text" placeholder="Título de la tarea">

<!-- 1. nombre explícito; el icono queda fuera del árbol -->
<button type="button" aria-label="Eliminar tarea">
  <svg class="i-trash" aria-hidden="true" focusable="false"></svg>
</button>

<!-- 2. el nombre CONTIENE el texto visible -->
<button type="button" aria-label="Borrar tarea Revisar API">
  Borrar tarea
</button>

<!-- 3. texto real oculto visualmente: siempre funciona -->
<button type="button">
  <svg class="i-copy" aria-hidden="true" focusable="false"></svg>
  <span class="solo-lectores">Duplicar tarea</span>
</button>

<!-- 4. nombre único por fila, compuesto con labelledby -->
<h3 id="t-42">Revisar API</h3>
<button type="button" id="ed-42" aria-labelledby="ed-42 t-42">Editar</button>

<!-- 5. label de verdad, asociada por id -->
<label for="titulo">Título de la tarea</label>
<input type="text" id="titulo">

El caso 4 merece un comentario, porque es un patrón que se usa muchísimo y casi nadie conoce. Un usuario de lector de pantalla navega a menudo pidiendo «lista de botones de esta página». Si la tabla de tareas de TaskFlow tiene cuarenta filas, esa lista muestra cuarenta entradas idénticas: «Editar, Editar, Editar…». La solución es componer el nombre con aria-labelledby apuntando primero al propio elemento y después al título de la fila. El navegador concatena en el orden indicado y produce «Editar Revisar API». El texto visible sigue siendo «Editar», el nombre accesible es único y contiene el texto visible, así que se cumple 2.5.3.

/* Texto disponible para el árbol de accesibilidad, invisible en pantalla.
   NO uses display:none ni visibility:hidden: eliminan el nodo del árbol.
   Tampoco font-size:0 ni text-indent:-9999px: rompen el braille y el zoom. */
.solo-lectores {
  position: absolute;
  width: 1px;
  height: 1px;
  margin: -1px;          /* evita que el píxel afecte al flujo */
  padding: 0;
  overflow: hidden;
  clip-path: inset(50%); /* recorte moderno; clip está obsoleto */
  white-space: nowrap;   /* sin esto, el texto se parte y algunos
                            lectores lo leen letra a letra */
  border: 0;
}

/* Variante para enlaces de salto: invisible hasta que recibe el foco.
   Si el elemento es enfocable, DEBE poder verse al enfocarlo (2.4.7). */
.solo-lectores-focusable:not(:focus):not(:focus-within) {
  position: absolute;
  width: 1px; height: 1px;
  overflow: hidden;
  clip-path: inset(50%);
  white-space: nowrap;
}

26.3.3 Rol, estado y propiedades: el contrato de un componente

El rol no es una etiqueta descriptiva: es un contrato. Cuando declaras role="checkbox" estás prometiendo tres cosas a la vez, y las tres son obligatorias:

1. Que expones el estado que ese rol requiere. Un checkbox sin aria-checked es un componente roto: el lector anuncia «casilla» y no puede decir si está marcada.
2. Que respondes al teclado como ese rol. El usuario que oye «casilla» pulsará Espacio. Si tu componente solo escucha click de ratón, has mentido.
3. Que la estructura alrededor es la que el rol exige. Un role="option" tiene que estar dentro de un role="listbox"; un role="tab", dentro de un role="tablist". Fuera de su contenedor, muchos lectores ignoran el rol.

La diferencia entre estado y propiedad es práctica, no cosmética. Los estados cambian durante la vida del componente y hay que actualizarlos en cada interacción; las propiedades se definen una vez y describen algo estructural. Esta tabla recoge los que de verdad se usan a diario:

26.3.4 Los lectores reales y en qué se diferencian

Escribir para «el lector de pantalla» en abstracto es como escribir CSS para «el navegador». Hay varios, con cuotas de uso muy distintas por plataforma, y sus diferencias de comportamiento son la razón por la que el ARIA exótico falla en producción aunque la especificación diga que debería funcionar.

Las diferencias que de verdad te van a morder son estas cuatro, y conviene tenerlas presentes antes de diseñar un componente:

• Modo de navegación frente a modo de formulario. Los lectores de Windows tienen dos modos. En modo lectura, las teclas son atajos del propio lector (H salta al siguiente encabezado, B al siguiente botón, T a la siguiente tabla) y no llegan a tu aplicación. Al entrar en un campo de texto o en un widget con rol de aplicación, el lector cambia a modo formulario y las teclas pasan al DOM. Un componente que asume que siempre recibe las pulsaciones de flecha se comporta de forma imprevisible según el modo. Los roles ARIA que declaras son justo lo que decide ese cambio de modo.
• Verbosidad y silencios. Cada lector decide qué es redundante. Uno anuncia «región principal, marco»; otro no dice nada. Si tu diseño depende de que el usuario oiga literalmente una frase concreta, no es robusto.
• Soporte real de ARIA. Los roles y estados antiguos y ampliamente implantados (button, dialog, tab, aria-expanded, aria-live) funcionan en todas partes. Los más recientes o exóticos (role="feed", aria-details, role="treegrid" con celdas editables) tienen soporte irregular. La página de referencia sobre soporte de ARIA por lector y navegador es de consulta obligada antes de apostar por un rol poco común.
• El braille no es voz. Una línea braille muestra pocos caracteres y sin entonación. Nombres larguísimos generados automáticamente («botón eliminar tarea número 42 del proyecto migración de la plataforma de pagos») son inservibles ahí. Sé conciso.

26.4 WCAG explicado de forma útil

Las Pautas de Accesibilidad para el Contenido Web (WCAG, por sus siglas en inglés) son la norma técnica que define qué significa «accesible» de forma comprobable. Las publica el W3C a través de su Iniciativa de Accesibilidad Web y son el documento al que remiten prácticamente todas las legislaciones del mundo, incluida la norma europea EN 301 549. Su estructura es jerárquica y merece la pena entenderla antes de leer un criterio suelto.

ESTRUCTURA DE WCAG

  4 PRINCIPIOS            Perceptible · Operable · Comprensible · Robusto
        │
        ├── 13 PAUTAS         objetivos generales, NO comprobables
        │        │            («1.4 Distinguible», «2.4 Navegable»)
        │        │
        │        └── ~90 CRITERIOS DE CONFORMIDAD  ◄── ESTO es lo que se audita
        │                 │                            Verificables: se cumplen o no.
        │                 │                            Cada uno tiene nivel A, AA o AAA.
        │                 │
        │                 ├── Técnicas suficientes    formas conocidas de cumplirlo
        │                 └── Fallos documentados     formas conocidas de incumplirlo
        │
        └── Documentos de apoyo (informativos, NO normativos)
                 "Understanding WCAG"  ·  "Techniques for WCAG"

  SOLO los criterios de conformidad son normativos.
  Las técnicas son sugerencias: puedes cumplir un criterio de otra forma.

26.4.1 Los cuatro principios

Los principios no se auditan, pero son la mejor herramienta de diagnóstico que existe. Cuando encuentres un problema y no sepas por dónde atacarlo, pregúntate a cuál de los cuatro pertenece: la respuesta suele contener el arreglo.

26.4.2 Niveles A, AA y AAA: por qué el objetivo profesional es AA

Cada criterio de conformidad tiene asignado un nivel. Es importante entender que los niveles no son grados de calidad de un mismo criterio, sino una clasificación de criterios distintos por su impacto y por la dificultad de aplicarlos de forma general.

26.4.3 Versiones: 2.0, 2.1 y 2.2

Las versiones de WCAG son retrocompatibles por diseño: cada una añade criterios y no elimina los anteriores, con una única excepción notable. Si cumples 2.2 en nivel AA, cumples también 2.1 y 2.0 en el mismo nivel.

• WCAG 2.0 es la base histórica y la que aún citan algunas normativas antiguas. Se escribió antes de que el móvil y las aplicaciones de una sola página fueran lo normal, y eso se nota.
• WCAG 2.1 añade lo que faltaba para el mundo móvil y táctil, y para la baja visión: reflujo, espaciado del texto, orientación, contraste de elementos no textuales, gestos de puntero y contenido que aparece al pasar el ratón. Es la versión que la norma europea EN 301 549 toma como referencia en su edición vigente cuando se escribe este capítulo.
• WCAG 2.2 añade criterios muy pegados a problemas cotidianos de aplicaciones de gestión: foco no oscurecido por barras fijas, tamaño mínimo del objetivo de pulsación, alternativa a los movimientos de arrastre, no repetir información ya introducida y autenticación accesible sin pruebas cognitivas. La excepción a la retrocompatibilidad está aquí: el antiguo criterio de parsing (4.1.1) quedó obsoleto porque los navegadores modernos y el DOM lo hacían irrelevante.

26.4.4 Los criterios que de verdad incumplen los proyectos reales

De los aproximadamente noventa criterios, un puñado concentra la inmensa mayoría de los hallazgos en auditorías de aplicaciones de gestión como TaskFlow. Esta tabla es la que conviene tener a mano en la revisión de código: cada fila tiene el criterio, el fallo tal y como aparece en un proyecto y el arreglo concreto.

26.5 HTML semántico: el 70 % del problema sin escribir una línea de ARIA

Antes de cualquier atributo aria-* está el HTML. Y no es una cuestión de purismo: cada elemento semántico del HTML trae de fábrica un rol, un nombre calculado automáticamente, un comportamiento de teclado y una integración con la API de accesibilidad del sistema operativo que llevan más de dos décadas puliéndose en todos los navegadores y todos los lectores. Reimplementar eso con div y ARIA no es más flexible: es escribir a mano, con peor resultado, algo que ya tienes gratis.

26.5.1 Puntos de referencia de la página

Los puntos de referencia (o landmarks) son la tabla de contenidos estructural de la página. Los usuarios de lector de pantalla los usan constantemente para saltar entre zonas sin recorrer todo el contenido, con un atajo dedicado en todos los lectores. Cada elemento semántico de HTML mapea a un rol de punto de referencia sin que tengas que declararlo.

<div class="app">
  <div class="topbar">
    <div class="logo">TaskFlow</div>
    <div class="menu">
      <div class="link" (click)="ir('/tareas')">Tareas</div>
      <div class="link" (click)="ir('/equipo')">Equipo</div>
    </div>
  </div>
  <div class="sidebar">
    <div class="titulo">Proyectos</div>
    <div class="proyecto" *ngFor="let p of proyectos">{{ p.nombre }}</div>
  </div>
  <div class="content">
    <router-outlet />
  </div>
</div>
<!-- Árbol de accesibilidad resultante: NADA.
     Ni puntos de referencia, ni encabezados, ni enlaces, ni foco.
     Un usuario de lector de pantalla no puede ni empezar. -->

<a class="salto-contenido" href="#contenido">Saltar al contenido</a>

<header>
  <a routerLink="/" aria-label="TaskFlow, inicio">TaskFlow</a>
  <nav aria-label="Principal">
    <ul>
      <li><a routerLink="/tareas" routerLinkActive="activo"
             ariaCurrentWhenActive="page">Tareas</a></li>
      <li><a routerLink="/equipo" routerLinkActive="activo"
             ariaCurrentWhenActive="page">Equipo</a></li>
    </ul>
  </nav>
</header>

<nav aria-labelledby="tit-proyectos">
  <h2 id="tit-proyectos">Proyectos</h2>
  <ul>
    <li *ngFor="let p of proyectos">
      <a [routerLink]="['/proyectos', p.id]">{{ p.nombre }}</a>
    </li>
  </ul>
</nav>

<main id="contenido" tabindex="-1">
  <router-outlet />
</main>

<footer><p>TaskFlow {{ version }}</p></footer>

Tres detalles de la versión correcta que no son casuales. El aria-label="Principal" distingue esa navegación de la de proyectos, así que la lista de puntos de referencia dice «navegación Principal» y «navegación Proyectos». La directiva ariaCurrentWhenActive de RouterLinkActive pone aria-current="page" en el enlace de la sección activa, que es la forma estándar de comunicar «estás aquí» —el color de fondo no lo comunica—. Y el tabindex="-1" en <main> existe porque el enlace de salto necesita un destino que pueda recibir el foco mediante programación; sin él, algunos navegadores mueven el scroll pero dejan el foco donde estaba.

26.5.2 Encabezados y jerarquía

Los encabezados son, con diferencia, el mecanismo de navegación más usado por los usuarios de lector de pantalla: mucho más que los puntos de referencia y muchísimo más que los enlaces de salto. Al entrar en una pantalla, el gesto habitual es pedir la lista de encabezados para entender la estructura de un vistazo, exactamente igual que una persona vidente recorre la página con la mirada.

• Un solo <h1> por pantalla, que diga de qué va esa pantalla. En una aplicación de una sola página, eso significa que el h1 cambia al cambiar de ruta: «Tareas de Proyecto Pagos», no «TaskFlow».
• No saltes niveles al descender. Un h4 justo después de un h2 le dice al usuario que se ha perdido un nivel intermedio y le hace buscar contenido que no existe. Subir varios niveles de golpe sí es correcto: cerrar una sección de h3 y abrir el siguiente h2 es lo normal.
• El nivel no es un tamaño de letra. Es el único error importante aquí: se elige h4 «porque se ve bien». El nivel expresa la profundidad en el esquema del documento; el tamaño lo decides con CSS.
• Los encabezados deben describir. Cinco h2 que dicen «Datos», «Datos», «Detalles»… no sirven de índice. El criterio 2.4.6 exige que encabezados y etiquetas sean descriptivos.
• No uses un encabezado para dar énfasis a un texto que no encabeza nada, ni pongas texto suelto en un <h3> por su estética.

<main id="contenido" tabindex="-1">
  <h1>Tareas de Proyecto Pagos</h1>                    <!-- nivel 1: la pantalla -->

  <section aria-labelledby="h-filtros">
    <h2 id="h-filtros">Filtros</h2>                    <!-- nivel 2: bloque -->
    <h3>Por estado</h3>                                <!-- nivel 3: subbloque -->
    <h3>Por responsable</h3>
  </section>

  <section aria-labelledby="h-lista">
    <h2 id="h-lista">Listado</h2>
    <!-- Cada tarjeta de tarea lleva su propio encabezado de nivel 3.
         Así el usuario puede saltar de tarea en tarea con la tecla de
         encabezado de nivel 3 de su lector, sin tabular por los botones. -->
    <article *ngFor="let t of tareas()">
      <h3>{{ t.titulo }}</h3>
      <p>{{ t.descripcion }}</p>
    </article>
  </section>
</main>

<!-- Lo que oye el usuario al pedir la lista de encabezados:
     h1  Tareas de Proyecto Pagos
       h2  Filtros
         h3  Por estado
         h3  Por responsable
       h2  Listado
         h3  Revisar contrato con el proveedor
         h3  Migrar la pasarela de pago
     Un índice completo de la pantalla en dos segundos. -->

26.5.3 Listas y tablas de datos

Las listas parecen un detalle irrelevante y no lo son: cuando un lector encuentra una <ul> anuncia «lista de 12 elementos» y, dentro, «elemento 3 de 12». Esa información de cardinalidad y posición es enormemente valiosa y desaparece por completo si la lista de tareas son doce <div> hermanos. El usuario no sabe cuántas tareas hay ni por dónde va.

Con las tablas la diferencia es aún más brutal. Una tabla de datos correcta permite al lector anunciar, en cada celda, a qué columna y a qué fila pertenece. Sin cabeceras declaradas, el usuario oye una secuencia de valores sueltos: «Revisar contrato, Alta, 12/09/2026, Marta, En curso» y tiene que recordar el orden de las columnas de memoria mientras recorre cuarenta filas.

<!-- Tabla construida con divs: el rol de tabla no existe,
     no hay filas, no hay celdas, no hay cabeceras. -->
<div class="tabla">
  <div class="fila cabecera">
    <div class="celda">Título</div>
    <div class="celda">Prioridad</div>
    <div class="celda">Vence</div>
  </div>
  <div class="fila" *ngFor="let t of tareas()">
    <div class="celda">{{ t.titulo }}</div>
    <div class="celda">{{ t.prioridad }}</div>
    <div class="celda">{{ t.vence | date }}</div>
  </div>
</div>

<!-- Y esta variante tampoco vale: tabla real,
     pero la fila de cabecera usa td. -->
<table>
  <tr><td><b>Título</b></td><td><b>Prioridad</b></td></tr>
</table>

<table>
  <!-- caption: nombre accesible de la tabla. Se anuncia al entrar
       y aparece en la lista de tablas del lector. -->
  <caption>
    Tareas de Proyecto Pagos
    <span class="small muted">{{ tareas().length }} resultados</span>
  </caption>
  <thead>
    <tr>
      <th scope="col">Título</th>
      <th scope="col">Prioridad</th>
      <th scope="col">Vence</th>
      <th scope="col"><span class="solo-lectores">Acciones</span></th>
    </tr>
  </thead>
  <tbody>
    <tr *ngFor="let t of tareas()">
      <!-- scope="row": convierte el título en la cabecera de la fila,
           así cada celda se anuncia con el nombre de la tarea. -->
      <th scope="row">{{ t.titulo }}</th>
      <td>{{ t.prioridad }}</td>
      <td>
        <time [attr.datetime]="t.vence | date:'yyyy-MM-dd'">
          {{ t.vence | date:'dd/MM/yyyy' }}
        </time>
      </td>
      <td>
        <button type="button" [attr.aria-label]="'Editar ' + t.titulo">
          Editar
        </button>
      </td>
    </tr>
  </tbody>
</table>

• scope no es decorativo. scope="col" asocia la cabecera a toda su columna; scope="row", a toda su fila. Con ambos, el lector puede anunciar «Prioridad, Alta, fila Revisar contrato» en una sola celda.
• Una tabla, un propósito. Si la usas para maquetar, ponle role="presentation" para eliminar su semántica. En correo electrónico esto es habitual y necesario (sección 26.15).
• Cabeceras complejas (dos filas de cabecera, celdas que abarcan varias columnas) requieren id en las cabeceras y headers en las celdas. Es laborioso y falla con facilidad: si puedes, divide la tabla en varias más simples.
• La columna de acciones necesita cabecera. Una <th> vacía deja al usuario sin saber en qué columna está; pon un texto oculto.
• Si la tabla tiene scroll horizontal en pantallas estrechas, su contenedor necesita tabindex="0" y un nombre accesible para que un usuario de teclado pueda desplazarla.

26.5.4 Por qué un <div> no sustituye a un <button>

Este es el fallo más común y el más ilustrativo, porque permite enumerar exactamente lo que un elemento nativo aporta. Cuando escribes <div (click)="borrar()">Borrar</div> no estás renunciando a «un poco de semántica»: estás renunciando a once comportamientos distintos, cada uno de los cuales tendrías que reimplementar.

<!-- 1. Invisible para el teclado y para el lector -->
<div class="btn" (click)="borrar(t)">Borrar</div>

<!-- 2. El intento «arreglado» sigue estando mal: Espacio hace
     scroll, no hay estado deshabilitado y el usuario del modo
     de contraste forzado no ve ningún botón. -->
<div class="btn" role="button" tabindex="0"
     (click)="borrar(t)"
     (keydown.enter)="borrar(t)">Borrar</div>

<!-- 3. Enlace usado como botón: se anuncia "enlace", se abre
     en pestaña nueva con Ctrl y ensucia el historial. -->
<a href="#" (click)="borrar(t)">Borrar</a>

<!-- 4. Botón sin type dentro de un form: envía el formulario -->
<form><button (click)="filtrar()">Filtrar</button></form>

<!-- Un elemento nativo. Todo lo demás sale gratis. -->
<button type="button" class="btn" (click)="borrar(t)">
  Borrar
</button>

<!-- Con estado durante la petición: aria-disabled mantiene el
     botón enfocable y anunciable como no disponible. -->
<button type="button" class="btn"
        [attr.aria-disabled]="borrando() ? 'true' : null"
        (click)="borrando() || borrar(t)">
  {{ borrando() ? 'Borrando…' : 'Borrar' }}
</button>

<!-- Navegación = enlace. Acción = botón. Sin excepciones. -->
<a [routerLink]="['/tareas', t.id]">Ver detalle</a>

<!-- type explícito siempre: el defecto es "submit" -->
<form (ngSubmit)="filtrar()">
  <button type="submit">Filtrar</button>
  <button type="button" (click)="limpiar()">Limpiar</button>
</form>

Si aun así necesitas construir un control interactivo sobre un elemento no semántico —porque el diseño exige que toda una tarjeta sea pulsable, por ejemplo—, la solución correcta no es poner role="button" a la tarjeta. Es poner un <button> o un <a> real dentro, con el nombre correcto, y extender su área de pulsación con un pseudoelemento absoluto que cubra la tarjeta. Así el elemento enfocable y anunciable es el nativo, y la zona sensible al ratón es toda la tarjeta.

@Component({
  selector: 'app-tarjeta-tarea',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <article class="tarjeta">
      <h3>
        <a class="tarjeta__enlace" [routerLink]="['/tareas', tarea().id]">
          {{ tarea().titulo }}
        </a>
      </h3>
      <p>{{ tarea().descripcion }}</p>
      <!-- Este botón debe quedar POR ENCIMA de la capa del enlace,
           o sería inalcanzable con el ratón. -->
      <button type="button" class="tarjeta__accion"
              [attr.aria-label]="'Marcar ' + tarea().titulo + ' como hecha'"
              (click)="completar.emit(tarea().id)">
        <svg aria-hidden="true" focusable="false">…</svg>
      </button>
    </article>`,
  styles: `
    .tarjeta { position: relative; }
    /* El enlace real conserva rol, foco y teclado; su área crece. */
    .tarjeta__enlace::after {
      content: ''; position: absolute; inset: 0;
    }
    /* El foco se dibuja en la TARJETA, no en el texto del enlace:
       :focus-within propaga el estado al contenedor. */
    .tarjeta:focus-within {
      outline: 3px solid var(--color-foco);
      outline-offset: 2px;
    }
    .tarjeta__enlace:focus-visible { outline: none; }  /* ya lo pinta la tarjeta */
    .tarjeta__accion { position: relative; z-index: 1; }
  `,
})
export class TarjetaTareaComponent {
  readonly tarea = input.required<Tarea>();
  readonly completar = output<string>();
}

26.6 ARIA: la primera regla es no usar ARIA

ARIA (Accessible Rich Internet Applications) es una especificación del W3C que define un vocabulario de atributos para describir roles, estados y propiedades que el HTML no puede expresar. Nació a mediados de la década de 2000, cuando las aplicaciones web empezaron a construir widgets complejos —árboles, rejillas editables, menús— que no tenían equivalente en el HTML de la época. Es una pieza imprescindible… y la herramienta más mal usada de todo el desarrollo web.

La razón es que ARIA tiene una propiedad contraintuitiva: no hace nada. No añade comportamiento, no captura teclas, no mueve el foco, no cambia el aspecto. Lo único que hace es modificar lo que el navegador publica en el árbol de accesibilidad. Es una promesa que haces al usuario, y si el comportamiento real no la cumple, has empeorado la situación: antes el usuario no sabía qué era aquello; ahora cree que es un menú que responde a las flechas, y no responde.

26.6.1 Las cinco reglas de uso de ARIA

La especificación de prácticas de uso enuncia cinco reglas. Están ordenadas por importancia y la primera es la que se incumple siempre:

1. Si puedes usar un elemento o atributo nativo de HTML con la semántica y el comportamiento que necesitas, úsalo en lugar de reutilizar un elemento y añadirle ARIA. Esta regla resuelve la mayoría de los casos por sí sola.
2. No cambies la semántica nativa salvo que sea imprescindible. <h2 role="tab"> destruye el encabezado: pierdes la navegación por encabezados. Envuelve o anida en lugar de sobrescribir.
3. Todo control interactivo debe ser operable con teclado. Si añades role="button", tienes que añadir foco y manejadores de Enter y Espacio.
4. No pongas role="presentation" ni aria-hidden="true" en un elemento enfocable. Produce el peor estado posible: un elemento que recibe el foco pero que el lector no puede anunciar. El usuario tabula y oye silencio.
5. Todo elemento interactivo debe tener un nombre accesible. Sin nombre, el rol por sí solo no basta: «botón» a secas no dice qué hace.

¿NECESITO ARIA? · ÁRBOL DE DECISIÓN

   ┌───────────────────────────────────────────────┐
   │ ¿Existe un elemento HTML que ya haga esto?    │
   └───────────────┬───────────────────────────────┘
          SÍ ──────┤                        │────── NO
                   ▼                        ▼
   ┌───────────────────────────┐   ┌────────────────────────────────────┐
   │ ÚSALO. No añadas ARIA.    │   │ ¿Es una COMBINACIÓN de nativos?    │
   │ button, a, input, select, │   │ (p. ej. details+summary para un    │
   │ details, dialog, table,   │   │  acordeón; input+datalist para un  │
   │ fieldset, progress, meter │   │  autocompletado sencillo)          │
   └───────────────────────────┘   └────────┬───────────────┬───────────┘
                                     SÍ ────┤               │──── NO
                                            ▼               ▼
                     ┌──────────────────────────┐   ┌────────────────────────────┐
                     │ COMBÍNALOS. Casi siempre │   │ ¿Existe el patrón en la    │
                     │ es la mejor opción.      │   │ guía de authoring (APG)?   │
                     └──────────────────────────┘   └───────┬────────────┬───────┘
                                                     SÍ ────┤            │──── NO
                                                            ▼            ▼
                                    ┌───────────────────────────┐  ┌──────────────────────┐
                                    │ IMPLEMENTA EL PATRÓN      │  │ PARA. Rediseña la    │
                                    │ COMPLETO: roles + estados │  │ interacción con      │
                                    │ + TODAS las teclas.       │  │ piezas conocidas.    │
                                    │ A medias = roto.          │  │ Inventar un widget   │
                                    │                           │  │ nuevo es un proyecto │
                                    │ Antes de escribirlo:      │  │ de meses, no una     │
                                    │ ¿lo tiene ya el CDK o     │  │ tarea de un sprint.  │
                                    │ Angular Material? (26.13) │  │                      │
                                    └───────────────────────────┘  └──────────────────────┘

   ATAJO PRÁCTICO: en una aplicación de gestión normal, el ARIA legítimo
   se reduce a  aria-label / aria-labelledby / aria-describedby /
   aria-live / aria-expanded / aria-current / aria-invalid / aria-hidden.
   Si tu plantilla tiene roles exóticos, sospecha del diseño antes que del código.

26.6.2 aria-label, aria-labelledby y texto visible

Ya vimos en 26.3.2 que hay una jerarquía de precedencia. Aquí va el criterio de elección, que es lo que se pregunta en cada revisión de código:

<!-- 1. Texto visible: lo mejor. Nada que añadir. -->
<button type="button" (click)="guardar()">Guardar tarea</button>

<!-- 2. labelledby: el nombre del diálogo YA está en su h2 -->
<div role="dialog" aria-modal="true" aria-labelledby="dlg-tit" aria-describedby="dlg-desc">
  <h2 id="dlg-tit">Eliminar tarea</h2>
  <p id="dlg-desc">Esta acción no se puede deshacer.</p>
</div>

<!-- 3. label: no hay texto visible posible y no debe haberlo -->
<button type="button" aria-label="Cerrar diálogo">
  <svg aria-hidden="true" focusable="false">…</svg>
</button>

<!-- 4. Texto oculto: complementa el visible SIN pisarlo.
     Nombre resultante: "Editar tarea Revisar API". -->
<button type="button">
  Editar<span class="solo-lectores"> tarea {{ t.titulo }}</span>
</button>

<!-- 5. labelledby COMPUESTO: el propio botón primero, luego la fila.
     El navegador concatena en el orden de los ids. -->
<th scope="row" [id]="'fila-' + t.id">{{ t.titulo }}</th>
<td>
  <button type="button" [id]="'del-' + t.id"
          [attr.aria-labelledby]="'del-' + t.id + ' fila-' + t.id">
    Eliminar
  </button>
</td>

<!-- 6. Distinguir dos regiones del mismo tipo -->
<nav aria-label="Principal">…</nav>
<nav aria-label="Migas de pan">…</nav>

26.6.3 aria-describedby: la descripción accesible

Mientras el nombre identifica, la descripción amplía. Se anuncia después del nombre, normalmente tras una breve pausa, y en muchos lectores se puede silenciar por configuración. Eso define exactamente para qué sirve y para qué no: información complementaria útil pero no imprescindible para identificar el control.

• Sí: formato esperado de un campo («dd/mm/aaaa»), requisitos de una contraseña, mensaje de error de validación, aclaración de una acción destructiva, atajo de teclado asociado a un botón.
• No: el nombre del campo, información sin la cual la acción es ambigua, o textos larguísimos. Recuerda que se puede desactivar.
• Acepta varios id separados por espacios y los concatena. Es justo lo que necesitas para un campo que tiene a la vez un texto de ayuda permanente y un mensaje de error condicional.
• El elemento referenciado puede estar oculto visualmente, pero no con display: none: eso lo saca del árbol y la referencia queda vacía.

<label for="vence">Fecha de vencimiento</label>

<input id="vence" type="text" formControlName="vence"
       autocomplete="off"
       [attr.aria-invalid]="mostrarError() ? 'true' : null"
       [attr.aria-describedby]="descripciones()">

<!-- Ayuda PERMANENTE: siempre presente en el DOM y siempre visible. -->
<p id="vence-ayuda" class="ayuda">Formato dd/mm/aaaa. No puede ser anterior a hoy.</p>

<!-- Error CONDICIONAL. Ojo: si lo quitas del DOM con @if, el id
     desaparece; por eso describedby se recalcula (ver la clase). -->
<p id="vence-error" class="error" *ngIf="mostrarError()">
  <svg aria-hidden="true" focusable="false" class="i-alerta"></svg>
  La fecha debe tener el formato dd/mm/aaaa.
</p>

<!-- Lo que se oye al enfocar con error:
     "Fecha de vencimiento, edición, no válido,
      Formato dd/mm/aaaa. No puede ser anterior a hoy.
      La fecha debe tener el formato dd/mm/aaaa."
     Nombre → rol → estado → descripciones, en ese orden. -->

export class CampoFechaComponent {
  readonly control = input.required<FormControl<string>>();
  readonly enviado = input(false);

  /** Un error se muestra cuando es inválido y el usuario ya salió del
   *  campo o ya intentó enviar (mismo criterio que el capítulo 5). */
  readonly mostrarError = computed(() => {
    const c = this.control();
    return c.invalid && (c.touched || this.enviado());
  });

  /** aria-describedby SOLO puede citar ids que existan en el DOM.
   *  Una referencia a un id inexistente no es "vacía": en algunos
   *  lectores anula la descripción entera, incluida la ayuda válida. */
  readonly descripciones = computed(() =>
    ['vence-ayuda', this.mostrarError() ? 'vence-error' : null]
      .filter((x): x is string => x !== null)
      .join(' '));
}

26.6.4 aria-live y las regiones activas

Una región activa es un contenedor cuyo contenido, al cambiar, se anuncia automáticamente sin mover el foco. Es la única forma de comunicar a un usuario de lector de pantalla algo que ha ocurrido en un sitio de la pantalla donde no está trabajando: «Tarea guardada», «12 resultados», «Se ha perdido la conexión».

<!-- 1. La región nace junto con el mensaje: silencio. -->
@if (mensaje()) {
  <div role="status">{{ mensaje() }}</div>
}

<!-- 2. assertive para una confirmación trivial: interrumpe
     al usuario en mitad de una frase. -->
<div aria-live="assertive">{{ ultimoGuardado() }}</div>

<!-- 3. Región activa que envuelve TODA la tabla: cada
     recarga lee las cuarenta filas en voz alta. -->
<div aria-live="polite">
  <table>…40 filas…</table>
</div>

<!-- 4. El mismo texto dos veces no se anuncia la segunda. -->
<div role="status">{{ 'Guardado' }}</div>

<!-- 1. Contenedor SIEMPRE en el DOM; el @if va dentro. -->
<div role="status" aria-atomic="true" class="solo-lectores">
  @if (mensaje()) { {{ mensaje() }} }
</div>

<!-- 2. polite para lo normal; assertive solo para lo urgente. -->
<div role="status" class="solo-lectores">{{ ultimoGuardado() }}</div>
<div role="alert" class="aviso-critico">
  @if (sesionCaduca()) { La sesión caducará en 2 minutos. }
</div>

<!-- 3. Se anuncia el RESUMEN, no los datos. La tabla queda
     fuera de la región y se marca ocupada al recargar. -->
<div role="status" class="solo-lectores">
  @if (!cargando()) { {{ tareas().length }} tareas encontradas }
</div>
<table [attr.aria-busy]="cargando() ? 'true' : null">…</table>

<!-- 4. Mensajes repetidos: añade una marca que los diferencie
     o usa LiveAnnouncer del CDK, que gestiona esto por ti. -->
<div role="status" class="solo-lectores">{{ aviso()?.texto }}</div>

26.6.5 aria-expanded y aria-current

Son los dos estados que más se olvidan y los que producen fallos más silenciosos, porque todo parece funcionar.

aria-expanded va en el control que despliega, nunca en el panel desplegado. Su valor debe estar enlazado al mismo estado que gobierna la visibilidad: si están en dos sitios distintos, se desincronizarán. Sin él, el usuario no sabe si el acordeón está abierto ni si su pulsación ha tenido efecto: pulsa, oye silencio y vuelve a pulsar, cerrándolo.

aria-current marca el elemento actual dentro de un conjunto. Sus valores son un conjunto cerrado —page, step, location, date, time, true— y hay que elegir el correcto: page para navegación, step para un asistente por pasos, date para el día seleccionado en un calendario. Es el sustituto semántico del «lo pinto de otro color».

@Component({
  selector: 'app-filtros-acordeon',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <h3>
      <!-- El botón va DENTRO del encabezado: así el usuario puede
           navegar por encabezados y activar desde ahí. Regla 2 de
           ARIA: no pongas role="button" en el propio h3. -->
      <button type="button"
              [attr.aria-expanded]="abierto()"
              [attr.aria-controls]="panelId"
              (click)="abierto.set(!abierto())">
        Filtros avanzados
        <svg class="chevron" aria-hidden="true" focusable="false">…</svg>
      </button>
    </h3>

    <!-- El panel se oculta con [hidden], no se destruye. Así el id
         referenciado por aria-controls existe siempre y no se pierde
         el estado de los campos al plegar. -->
    <div [id]="panelId" [hidden]="!abierto()">
      <ng-content />
    </div>`,
})
export class FiltrosAcordeonComponent {
  /** UNA sola fuente de verdad: la señal alimenta a la vez el
   *  atributo aria-expanded y la visibilidad real. Imposible que
   *  se desincronicen, que es el fallo clásico de este widget. */
  readonly abierto = signal(false);
  protected readonly panelId = `panel-${crypto.randomUUID()}`;
}

26.6.6 aria-hidden y el error clásico de ocultar algo enfocable

aria-hidden="true" poda un nodo y toda su descendencia del árbol de accesibilidad, sin afectar en absoluto a lo que se ve. Sus usos legítimos son pocos y concretos:

• Iconos decorativos que acompañan a un texto que ya dice lo mismo. Un <svg> junto a la palabra «Guardar» solo añadiría ruido.
• Duplicados visuales: el mismo dato mostrado dos veces por diseño (un valor en la barra de progreso y en su etiqueta).
• Contenido fuera de pantalla que sigue en el DOM: los paneles inactivos de un carrusel, la parte del listado ya desplazada en una animación.
• El resto de la página mientras hay un diálogo modal abierto, aunque para esto el atributo inert es hoy la herramienta correcta, porque además desactiva el foco y los eventos de puntero.

<!-- 1. El panel está fuera de pantalla y "oculto" a ARIA,
     pero sus botones siguen recibiendo foco. Al tabular:
     silencio absoluto en 6 paradas. -->
<div class="panel fuera-de-pantalla" aria-hidden="true">
  <button type="button">Aplicar</button>
  <a routerLink="/ayuda">Ayuda</a>
</div>

<!-- 2. aria-hidden en el propio botón: enfocable y mudo. -->
<button type="button" aria-hidden="true" (click)="cerrar()">
  Cerrar
</button>

<!-- 3. Icono con aria-hidden que era el ÚNICO contenido:
     el botón se queda sin nombre accesible. -->
<button type="button">
  <svg aria-hidden="true">…</svg>
</button>

<!-- 1. inert: quita el foco, los eventos de puntero y la
     semántica de golpe. Es la respuesta moderna. -->
<div class="panel" [attr.inert]="cerrado() ? '' : null">
  <button type="button">Aplicar</button>
  <a routerLink="/ayuda">Ayuda</a>
</div>

<!-- 2. Si no debe usarse, quítalo del DOM o deshabilítalo;
     no lo dejes enfocable y mudo. -->
@if (sePuedeCerrar()) {
  <button type="button" (click)="cerrar()">Cerrar</button>
}

<!-- 3. El icono se oculta y el nombre lo aporta otra cosa. -->
<button type="button" aria-label="Cerrar panel">
  <svg aria-hidden="true" focusable="false">…</svg>
</button>

26.7 Teclado: el denominador común de toda la accesibilidad

Si tuvieras que elegir una sola cosa que probar en una aplicación, elige el teclado. Es el canal de entrada que usan los lectores de pantalla, los conmutadores, el control por voz, el seguimiento ocular y los teclados en pantalla; y también el usuario avanzado que rellena formularios sin soltar las manos. Una aplicación completamente operable con teclado ya cumple gran parte de los criterios del principio «operable» y, de paso, es una aplicación mejor para todos.

26.7.1 Orden de tabulación: no lo toques

El navegador construye el orden de tabulación siguiendo el orden del DOM entre los elementos enfocables. Esa regla, que parece limitante, es en realidad la garantía de que el orden es coherente. Los tres valores posibles de tabindex tienen usos muy distintos:

26.7.2 El indicador de foco visible

Vamos a decirlo sin rodeos: outline: none sin sustituto es probablemente la peor línea de CSS que se puede escribir. No es un fallo de accesibilidad menor; es dejar sin usar la aplicación a cualquiera que navegue con teclado, porque el usuario deja de saber dónde está. Imagina usar un ratón cuyo cursor fuera invisible: pulsas y ocurre algo, en algún sitio.

Aparece siempre por el mismo motivo: el contorno por defecto del navegador es feo y aparecía también al hacer clic con el ratón. Ese segundo problema está resuelto desde que existe :focus-visible, que aplica el estilo solo cuando el navegador considera que el usuario se beneficia de verlo —al tabular sí, al pulsar un botón con el ratón normalmente no—.

/* 1. El clásico. Deja la aplicación inutilizable con teclado. */
*:focus { outline: none; }

/* 2. Variante disfrazada: el reset "moderno" copiado de un blog. */
button, a, input { outline: 0; box-shadow: none; }

/* 3. Sustituto insuficiente: 1 píxel de un gris claro sobre
   fondo blanco no llega a 3:1 (incumple 1.4.11). */
:focus { outline: 1px solid #d0d0d0; }

/* 4. Solo cambia el color de fondo: invisible para quien no
   distingue ese par de colores, y muy sutil. */
button:focus { background: #f7f7f7; }

/* 5. Sin offset: el contorno se pega al borde y se confunde
   con el borde del propio control. */
:focus { outline: 2px solid blue; outline-offset: 0; }

/* Un único indicador para toda la aplicación, con contraste
   suficiente y separado del control para que se vea siempre. */
:root {
  --foco-color: #0b5fff;      /* comprobado ≥ 3:1 sobre los fondos */
  --foco-grosor: 3px;
}

:focus-visible {
  outline: var(--foco-grosor) solid var(--foco-color);
  outline-offset: 2px;
  /* Doble anillo: garantiza visibilidad sobre fondos oscuros
     y sobre fondos claros sin calcular caso por caso. */
  box-shadow: 0 0 0 calc(var(--foco-grosor) + 2px) #fff;
  border-radius: 3px;
}

/* Quitar el contorno del clic de ratón es LEGÍTIMO; quitar el
   de teclado, no. Esto es exactamente esa distinción. */
:focus:not(:focus-visible) { outline: none; }

/* En modo de contraste forzado el color se ignora: usa la
   palabra clave del sistema para el color del foco. */
@media (forced-colors: active) {
  :focus-visible { outline-color: Highlight; }
}

/* 2.4.11: que una barra fija no tape el elemento enfocado. */
:root { scroll-padding-block: 5rem; }

26.7.3 Enlace de salto al contenido

En TaskFlow, el menú lateral tiene los proyectos del usuario: pueden ser treinta enlaces. Sin un mecanismo de salto, un usuario de teclado los recorre en cada cambio de pantalla antes de llegar al contenido. El criterio 2.4.1 exige poder evitar esos bloques repetidos, y el enlace de salto es la técnica más simple y la más eficaz.

<!-- PRIMER elemento enfocable del documento, antes del header. -->
<a class="salto-contenido" href="#contenido">Saltar al contenido principal</a>
<a class="salto-contenido" href="#nav-proyectos">Saltar a la lista de proyectos</a>

<header>…</header>
<nav id="nav-proyectos" aria-labelledby="tit-proyectos">…</nav>

<!-- El destino necesita tabindex="-1": sin él, algunos navegadores
     desplazan el scroll pero dejan el foco en el enlace, así que la
     siguiente pulsación de Tab vuelve al menú. -->
<main id="contenido" tabindex="-1">…</main>

/* Oculto hasta que recibe el foco. NO uses display:none:
   dejaría de ser enfocable y el enlace no existiría. */
.salto-contenido {
  position: absolute;
  top: 0;
  left: 0;
  transform: translateY(-200%);   /* fuera de la vista */
  z-index: 1000;
  padding: 0.75rem 1.25rem;
  background: var(--color-fondo);
  color: var(--color-texto);
  border: 2px solid var(--foco-color);
  border-radius: 0 0 4px 0;
}

/* Al enfocarlo, entra en pantalla. Sin transición si el usuario
   ha pedido movimiento reducido (sección 26.11). */
.salto-contenido:focus {
  transform: translateY(0);
}

/* El destino recibe el foco por programación: no queremos un
   contorno permanente ahí, pero sí conviene marcarlo al llegar. */
main:focus { outline: none; }
main:focus-visible { outline: 3px solid var(--foco-color); }

26.7.4 Atajos de teclado

Los atajos son una gran mejora de productividad y una fuente inagotable de conflictos. La regla básica: un atajo de una sola tecla, sin modificador, es peligroso. Los usuarios de lector de pantalla y de reconocimiento de voz emiten pulsaciones de tecla constantemente; si tu aplicación interpreta N como «nueva tarea», cada vez que alguien dicte una palabra con «n» creará tareas. WCAG 2.1 añadió un criterio específico sobre atajos de una sola tecla (2.1.4) que exige poder desactivarlos, reasignarlos o limitarlos al elemento con foco.

• Usa modificadores (Ctrl, Alt, Meta) para los atajos globales, y comprueba que no pisas los del navegador ni los del lector de pantalla.
• Ámbito local siempre que puedas. Un atajo que solo funciona cuando el foco está dentro de la tabla de tareas no molesta a nadie.
• Documéntalos y hazlos descubribles: un diálogo de ayuda con la lista, accesible desde un botón, y aria-keyshortcuts en los controles correspondientes para que el lector los anuncie.
• Permite desactivarlos en las preferencias del usuario.
• Nunca captures teclas dentro de un campo de texto sin comprobar el destino del evento: Espacio y las letras pertenecen al usuario mientras escribe.

@Injectable({ providedIn: 'root' })
export class AtajosService {
  private readonly doc = inject(DOCUMENT);
  private readonly router = inject(Router);
  private readonly preferencias = inject(PreferenciasService);

  /** Elementos donde el usuario está escribiendo: sus teclas son suyas. */
  private escribiendo(destino: EventTarget | null): boolean {
    const el = destino as HTMLElement | null;
    if (!el) return false;
    const etiqueta = el.tagName;
    return etiqueta === 'INPUT' || etiqueta === 'TEXTAREA'
        || etiqueta === 'SELECT' || el.isContentEditable;
  }

  registrar(): void {
    fromEvent<KeyboardEvent>(this.doc, 'keydown')
      .pipe(
        filter(() => this.preferencias.atajosActivos()),   // desactivables
        filter((e) => !this.escribiendo(e.target)),        // no pisar la escritura
        filter((e) => !e.repeat),                          // ignorar autorrepetición
        takeUntilDestroyed(),
      )
      .subscribe((e) => {
        // Modificador obligatorio: nada de teclas sueltas globales.
        if (!(e.altKey && !e.ctrlKey && !e.metaKey)) return;
        switch (e.key.toLowerCase()) {
          case 'n':
            e.preventDefault();
            this.router.navigate(['/tareas', 'nueva']);
            break;
          case 'b':
            e.preventDefault();
            this.doc.getElementById('busqueda')?.focus();
            break;
          case '?':
            e.preventDefault();
            this.abrirAyudaAtajos();
            break;
        }
      });
  }
}

26.7.5 Patrones de interacción: el contrato de teclas

La guía de prácticas de autoría de ARIA (conocida por sus siglas inglesas, APG) documenta, para cada patrón de widget, los roles necesarios, los estados que hay que mantener y —lo más valioso— exactamente qué debe hacer cada tecla. No es una recomendación estética: es el comportamiento que el usuario ya conoce de su sistema operativo y que espera encontrar. Un menú que no responde a las flechas es tan sorprendente como un ascensor cuyos botones no se pulsan.

26.8 Gestión del foco en una aplicación de una sola página

Aquí está el fallo más grave y menos conocido de las aplicaciones Angular, y no es culpa de Angular: es una consecuencia estructural del enrutado del lado del cliente. En una web tradicional, al pulsar un enlace el navegador carga un documento nuevo: anuncia el título de la página, reinicia el foco al principio del documento y el usuario de lector de pantalla sabe con certeza que ha cambiado de pantalla. En una aplicación de una sola página no ocurre nada de eso: el navegador no ha navegado, solo se ha reemplazado un trozo de DOM.

El resultado es demoledor. El usuario pulsa «Proyecto Pagos» en el menú, el lector se queda en silencio, el foco permanece en un enlace que ya no existe —Angular ha destruido ese nodo— y el navegador lo devuelve al <body>. Al pulsar Tab, el usuario aparece al principio de la página, sin saber si la navegación funcionó, si tardó, si falló o si sigue en la misma pantalla. Se ha probado en decenas de auditorías: la reacción típica es pulsar el enlace tres o cuatro veces más.

import { DOCUMENT, inject, Injectable } from '@angular/core';
import { LiveAnnouncer } from '@angular/cdk/a11y';
import { NavigationEnd, Router } from '@angular/router';
import { Title } from '@angular/platform-browser';
import { filter } from 'rxjs';

/**
 * Restituye lo que el navegador hace gratis en una web multipágina:
 * anunciar el cambio de pantalla y reubicar el foco.
 * Se activa UNA vez, al arrancar la aplicación.
 */
@Injectable({ providedIn: 'root' })
export class NavegacionA11yService {
  private readonly router = inject(Router);
  private readonly doc = inject(DOCUMENT);
  private readonly titulo = inject(Title);
  private readonly locutor = inject(LiveAnnouncer);

  iniciar(): void {
    this.router.events
      .pipe(filter((e): e is NavigationEnd => e instanceof NavigationEnd))
      .subscribe(() => {
        // 1. ANUNCIAR. 'polite' para no interrumpir; el título ya lo ha
        //    fijado el router a partir de la propiedad `title` de la ruta.
        this.locutor.announce(`${this.titulo.getTitle()}. Página cargada.`, 'polite');

        // 2. REUBICAR EL FOCO. El destino ideal es el h1 de la nueva
        //    pantalla; si no existe, el contenedor principal.
        //    setTimeout con 0: la vista de la ruta nueva aún no está
        //    en el DOM cuando se emite NavigationEnd.
        setTimeout(() => {
          const destino =
            this.doc.querySelector<HTMLElement>('main h1') ??
            this.doc.querySelector<HTMLElement>('main');
          if (!destino) return;
          // tabindex -1 temporal: enfocable por programación, pero sin
          // añadir una parada permanente al orden de tabulación.
          if (!destino.hasAttribute('tabindex')) {
            destino.setAttribute('tabindex', '-1');
            destino.addEventListener('blur', () => destino.removeAttribute('tabindex'),
                                     { once: true });
          }
          // preventScroll: el router ya ha restaurado la posición.
          destino.focus({ preventScroll: true });
        });
      });
  }
}

Dos decisiones de este servicio merecen justificación. La primera: se enfoca el h1, no el <main> completo. Enfocar el contenedor hace que algunos lectores lean toda la pantalla de golpe, lo que es peor que el silencio. Enfocar el encabezado anuncia «Tareas de Proyecto Pagos, encabezado de nivel 1» y deja al usuario justo al principio del contenido, exactamente como en una navegación real. La segunda: se anuncia además de mover el foco, porque el anuncio confirma que la navegación terminó incluso si el foco tarda, y porque algunos lectores no verbalizan el elemento al recibir foco por programación.

26.8.1 Trampa de foco en diálogos

Un diálogo modal establece un contrato claro: mientras esté abierto, el resto de la aplicación no existe. Visualmente eso se comunica con un fondo oscurecido. Para el teclado hay que implementarlo: si el foco puede salir del diálogo, el usuario acaba tabulando por elementos que no ve, pulsando botones invisibles y sin forma de volver.

RECORRIDO DEL FOCO EN UN DIÁLOGO MODAL

  ANTES DE ABRIR
  ─────────────────────────────────────────────────────────────
   [Nueva tarea] [Filtrar] [Eliminar]◄── FOCO      ← se GUARDA la referencia
   ┌─────────────────────────────────────────┐        a este elemento
   │ tabla de tareas (40 filas enfocables)   │
   └─────────────────────────────────────────┘

  AL ABRIR
  ─────────────────────────────────────────────────────────────
   ░░░░░░░░ resto de la página: inert ░░░░░░░░   ← sin foco, sin clic,
   ░░░░░░░░ (o aria-hidden="true")    ░░░░░░░░     fuera del árbol
        ┌───────────────────────────────────────┐
        │ role="dialog" aria-modal="true"       │
        │ aria-labelledby="dlg-tit"             │
        │                                       │
        │  Eliminar tarea            [ X ]◄─┐   │
        │  Esta acción no se puede deshacer.│   │
        │                                   │   │
        │            [Cancelar]  [Eliminar]─┘   │  ← FOCO INICIAL:
        └───────────────────────────────────────┘     el primer enfocable,
                                                      o el más seguro
  CICLO CERRADO (la "trampa")
  ─────────────────────────────────────────────────────────────
              ┌──────────────────────────────────┐
    Tab  ────►│ X  →  Cancelar  →  Eliminar  ─┐  │
              │ ▲                             │  │
              │ └─────────────────────────────┘  │  Tab en el ÚLTIMO
              └──────────────────────────────────┘  vuelve al PRIMERO
    Shift+Tab: el mismo ciclo en sentido inverso.
    Esc: cierra.

  AL CERRAR
  ─────────────────────────────────────────────────────────────
   [Nueva tarea] [Filtrar] [Eliminar]◄── FOCO RESTITUIDO
                                         al elemento guardado
   Si no se restituye: el foco cae al <body> y el usuario
   vuelve al principio de la página. Cerrar un diálogo NO
   debe costar treinta tabulaciones.

Escribir esto a mano es más difícil de lo que parece: hay que calcular qué elementos son enfocables (una consulta CSS no basta, porque un elemento puede estar oculto por un ancestro), reaccionar a los cambios del contenido del diálogo, gestionar diálogos anidados y tratar el caso en que el elemento que abrió el diálogo ya no existe al cerrarlo. Por eso el CDK de Angular lo trae resuelto, y por eso el MatDialog de Material lo hace todo por defecto. Si tienes que construirlo, este es el esqueleto correcto:

@Component({
  selector: 'app-dialogo',
  imports: [A11yModule],
  template: `
    <!-- cdkTrapFocus crea la trampa; cdkTrapFocusAutoCapture mueve
         el foco dentro al aparecer y lo DEVUELVE al destruirse. -->
    <div class="dialogo" role="dialog" aria-modal="true"
         [attr.aria-labelledby]="tituloId"
         [attr.aria-describedby]="descripcionId"
         cdkTrapFocus [cdkTrapFocusAutoCapture]="true"
         (keydown.escape)="cerrar.emit()">
      <h2 [id]="tituloId">{{ titulo() }}</h2>
      <p [id]="descripcionId"><ng-content /></p>
      <div class="acciones">
        <!-- cdkFocusInitial: el foco va aquí, no al botón destructivo -->
        <button type="button" cdkFocusInitial (click)="cerrar.emit()">Cancelar</button>
        <button type="button" class="peligro" (click)="confirmar.emit()">
          {{ textoConfirmar() }}
        </button>
      </div>
    </div>`,
})
export class DialogoComponent {
  readonly titulo = input.required<string>();
  readonly textoConfirmar = input('Aceptar');
  readonly cerrar = output<void>();
  readonly confirmar = output<void>();
  protected readonly tituloId = `dlg-tit-${crypto.randomUUID()}`;
  protected readonly descripcionId = `dlg-desc-${crypto.randomUUID()}`;
}

26.8.2 El foco tras eliminar un elemento de una lista

Caso cotidiano en TaskFlow: cuarenta filas, cada una con su botón «Eliminar». El usuario elimina la fila 17. Angular destruye ese nodo del DOM y, con él, el botón que tenía el foco. El navegador devuelve el foco al <body>: el usuario está de nuevo al principio de la página y tiene que recorrer diecisiete filas para seguir trabajando. Con tres borrados seguidos, la tarea se vuelve inviable.

La regla general es sencilla y aplica a cualquier destrucción de un elemento enfocado: decide siempre el destino del foco antes de destruir. El orden de preferencia es el elemento equivalente siguiente, si no el anterior, y si la lista queda vacía, el contenedor o el encabezado de la lista.

export class ListaTareasComponent {
  private readonly host = inject(ElementRef<HTMLElement>);
  private readonly locutor = inject(LiveAnnouncer);
  private readonly api = inject(TareasApi);
  readonly tareas = signal<Tarea[]>([]);

  async eliminar(indice: number): Promise<void> {
    const tarea = this.tareas()[indice];
    await this.api.eliminar(tarea.id);

    const restantes = this.tareas().filter((t) => t.id !== tarea.id);
    this.tareas.set(restantes);

    // Confirmación audible: el usuario no ve desaparecer la fila.
    this.locutor.announce(`Tarea ${tarea.titulo} eliminada. ${restantes.length} tareas.`);

    // Destino: siguiente → anterior → encabezado de la lista.
    // afterNextRender garantiza que el DOM nuevo ya está pintado.
    afterNextRender(() => {
      const objetivo = restantes[indice] ?? restantes[indice - 1];
      const selector = objetivo
        ? `[data-borrar="${objetivo.id}"]`
        : '[data-lista-vacia]';
      this.host.nativeElement.querySelector<HTMLElement>(selector)?.focus();
    }, { injector: this.injector });
  }
}

El mismo razonamiento aplica a otros tres casos que aparecen constantemente y que casi nunca se tratan: al colapsar una sección cuyo contenido tenía el foco (devuélvelo al botón que la controla), al completar un asistente por pasos (foco en el encabezado del paso nuevo, y anúncialo), y al reemplazar una lista por un resultado de búsqueda (no muevas el foco, que el usuario sigue escribiendo, pero anuncia el número de resultados en una región activa).

26.9 Formularios accesibles a fondo

El formulario es donde se concentran más criterios de WCAG por metro cuadrado de interfaz y donde un fallo de accesibilidad tiene consecuencias más directas: si el usuario no puede completar el alta de tarea, no puede usar TaskFlow. Esta sección construye el formulario de tarea entero, primero como suele estar y después como debe estar, sobre los formularios reactivos del capítulo 5.

26.9.1 Etiquetas de verdad

• Todo campo necesita una <label> asociada por for e id, o envolviendo al campo. La asociación explícita con for es preferible: funciona con cualquier estructura de marcado y permite que al pulsar la etiqueta el foco vaya al campo, lo que amplía el área de pulsación (útil para 2.5.8).
• El placeholder no es una etiqueta. Desaparece al escribir —el usuario pierde la referencia justo cuando la necesita para revisar—, tiene contraste insuficiente por diseño en todos los navegadores, no siempre se anuncia y no es traducible por herramientas de terceros. Incumple 3.3.2 y a menudo 1.4.3. Sirve como ejemplo de formato, nunca como nombre.
• La etiqueta flotante (el efecto de que el texto sube al enfocar) es aceptable si es una <label> real que se mueve con CSS, no un placeholder animado. Angular Material lo hace bien.
• Nunca uses title como etiqueta: no se ve con teclado, no se ve en táctil y algunos lectores lo ignoran.

26.9.2 Agrupación con fieldset y legend

Un grupo de botones de radio o de casillas plantea un problema específico: la etiqueta de cada opción dice «Alta», «Media», «Baja», pero ninguna dice de qué. Un usuario que llega al grupo tabulando oye «Alta, botón de radio, 1 de 3» y no sabe si está eligiendo la prioridad, la urgencia o el nivel de riesgo. El <fieldset> con su <legend> resuelve exactamente esto: el lector anuncia la leyenda al entrar en el grupo, y muchos la repiten con cada opción.

Es también el mecanismo correcto para agrupar campos relacionados (una dirección, un rango de fechas «desde/hasta») y para las secciones de un formulario largo. Alternativa cuando el marcado no admite fieldset: role="group" con aria-labelledby, que produce un resultado equivalente con menos garantías de soporte.

26.9.3 Errores: asociados, anunciados y en el momento correcto

Tres preguntas hay que responder bien, y son independientes entre sí:

1. ¿Cuándo se valida? Nunca mientras el usuario escribe la primera vez: marcar en rojo un correo incompleto tras la tercera letra es hostil y confunde. El criterio del capítulo 5 es el correcto: mostrar el error cuando el control es inválido y el usuario ya salió del campo o ya intentó enviar. En la corrección sí conviene validar en vivo, para que el error desaparezca en cuanto se arregla.
2. ¿Cómo se asocia el mensaje al campo? Con aria-describedby apuntando al id del mensaje, más aria-invalid="true" en el campo. Sin la asociación, el mensaje está en la pantalla pero el usuario de lector nunca lo encuentra: oye «no válido» y no sabe por qué.
3. ¿Cómo se entera el usuario al enviar? Con un resumen de errores al principio del formulario, dentro de una región activa, que enumere los campos con problema y enlace a cada uno. Después, foco al resumen o al primer campo inválido. Es la única forma de que un formulario de veinte campos con tres errores sea manejable.

<form [formGroup]="form" (ngSubmit)="enviar()">
  <h3>Nueva tarea</h3>

  <!-- placeholder como etiqueta: sin nombre accesible -->
  <input formControlName="titulo" placeholder="Título"
         class="campo" [class.error]="form.controls.titulo.invalid">
  <!-- error NO asociado y con el color como único canal -->
  <span class="rojo" *ngIf="form.controls.titulo.invalid">Obligatorio</span>

  <!-- el asterisco no se anuncia; no hay required -->
  <label>Proyecto *</label>
  <select formControlName="proyectoId">…</select>

  <!-- grupo de radios sin fieldset: "Alta, 1 de 3" ¿de qué? -->
  <div class="radios">
    <label><input type="radio" formControlName="prioridad" value="alta"> Alta</label>
    <label><input type="radio" formControlName="prioridad" value="media"> Media</label>
  </div>

  <!-- div con clic: inalcanzable con teclado -->
  <div class="btn-primario" (click)="enviar()">Crear</div>
</form>

<!-- Y al enviar con errores: nada se anuncia, el foco no se mueve
     y el usuario no sabe qué campo ha fallado. -->

<form [formGroup]="form" (ngSubmit)="enviar()"
      aria-labelledby="f-tit" novalidate>
  <h2 id="f-tit">Nueva tarea</h2>

  <!-- RESUMEN DE ERRORES: siempre en el DOM, con role="alert"
       para que se anuncie al aparecer, y con enlaces al campo. -->
  <div role="alert" #resumen tabindex="-1" class="resumen-errores">
    @if (errores().length) {
      <h3>No se ha podido crear la tarea</h3>
      <p>Revisa {{ errores().length }} campos:</p>
      <ul>
        @for (e of errores(); track e.campo) {
          <li><a [href]="'#' + e.campo">{{ e.etiqueta }}: {{ e.mensaje }}</a></li>
        }
      </ul>
    }
  </div>

  <!-- Campo con etiqueta real, required nativo, ayuda y error -->
  <div class="campo-grupo">
    <label for="titulo">
      Título <span class="req" aria-hidden="true">*</span>
    </label>
    <input id="titulo" type="text" formControlName="titulo" required
           autocomplete="off" maxlength="120"
           aria-describedby="titulo-ayuda titulo-error"
           [attr.aria-invalid]="malo('titulo') ? 'true' : null">
    <p id="titulo-ayuda" class="ayuda">Entre 3 y 120 caracteres.</p>
    <p id="titulo-error" class="error">
      @if (malo('titulo')) {
        <svg class="i-alerta" aria-hidden="true" focusable="false"></svg>
        {{ mensaje('titulo') }}
      }
    </p>
  </div>

  <!-- Grupo de opciones: fieldset + legend -->
  <fieldset>
    <legend>Prioridad</legend>
    @for (p of prioridades; track p.valor) {
      <div>
        <input type="radio" [id]="'pri-' + p.valor" [value]="p.valor"
               formControlName="prioridad">
        <label [for]="'pri-' + p.valor">{{ p.etiqueta }}</label>
      </div>
    }
  </fieldset>

  <!-- Botón real, activo siempre; el estado se anuncia -->
  <button type="submit" [attr.aria-disabled]="enviando() ? 'true' : null">
    {{ enviando() ? 'Creando…' : 'Crear tarea' }}
  </button>
</form>

Fíjate en dos detalles finos de la versión correcta. El asterisco de campo obligatorio lleva aria-hidden="true": el lector no dice «asterisco», dice «Título, edición, requerido», porque esa información ya la aporta el atributo required nativo. Y el párrafo del mensaje de error existe siempre en el DOM con su id, con el @if por dentro; así aria-describedby puede referenciarlo de forma estática y no hay que recalcular la lista de descripciones en cada cambio de validez.

const ETIQUETAS: Record<string, string> = {
  titulo: 'Título', proyectoId: 'Proyecto', vence: 'Fecha de vencimiento',
};
const MENSAJES: Record<string, (e: unknown) => string> = {
  required: () => 'Es obligatorio.',
  minlength: (e) => `Necesita al menos ${(e as { requiredLength: number }).requiredLength} caracteres.`,
  fechaPasada: () => 'No puede ser anterior a hoy. Formato dd/mm/aaaa.',
};

export class TareaFormComponent {
  private readonly fb = inject(NonNullableFormBuilder);
  private readonly resumen = viewChild.required<ElementRef<HTMLElement>>('resumen');
  readonly enviando = signal(false);
  readonly intentado = signal(false);
  readonly form = this.fb.group({ /* … capítulo 5 … */ });

  /** Mismo criterio de visualización que en el capítulo 5. */
  malo(nombre: string): boolean {
    const c = this.form.get(nombre)!;
    return c.invalid && (c.touched || this.intentado());
  }

  mensaje(nombre: string): string {
    const errores = this.form.get(nombre)?.errors ?? {};
    const clave = Object.keys(errores)[0];
    return clave ? MENSAJES[clave]?.(errores[clave]) ?? 'Valor no válido.' : '';
  }

  /** Alimenta el resumen. Es una señal derivada: no hay estado duplicado. */
  readonly errores = computed(() => {
    if (!this.intentado()) return [];
    return Object.keys(ETIQUETAS)
      .filter((campo) => this.form.get(campo)?.invalid)
      .map((campo) => ({ campo, etiqueta: ETIQUETAS[campo], mensaje: this.mensaje(campo) }));
  });

  enviar(): void {
    this.intentado.set(true);
    if (this.form.invalid) {
      this.form.markAllAsTouched();
      // El foco va al RESUMEN, no al primer campo: así el usuario
      // conoce el total de errores antes de empezar a corregir, y
      // desde ahí navega con los enlaces. role="alert" además lo lee.
      afterNextRender(() => this.resumen().nativeElement.focus(),
                      { injector: this.injector });
      return;
    }
    this.enviando.set(true);
    // … envío, y mapeo de errores 400 de NestJS a los controles
    //   exactamente como en el capítulo 5, marcándolos como touched
    //   para que aparezcan en el resumen.
  }
}

26.10 Color y contraste

El contraste es el criterio de WCAG que más fallos acumula en auditorías reales de productos de gestión como TaskFlow, y es también el más barato de prevenir si se fija en el sistema de tokens. Tres ratios importan en el día a día y conviene memorizarlos porque salen en cada revisión:

El ratio es la relación de luminancia relativa entre primer plano y fondo, definida en WCAG con una fórmula concreta. No lo calcules a ojo ni con una captura: usa una herramienta (DevTools de Chrome/Firefox, Contrast Checker de WebAIM, el panel Accessibility de Firefox) o calcula a partir de los tokens. El valor AAA (7:1 para texto normal) es deseable en entornos clínicos o de administración pública, pero el objetivo contractual habitual es AA.

26.10.1 El color no puede ser el único portador de información

El criterio 1.4.1 Uso del color (nivel A) es independiente del contraste: incluso con colores perfectos, si el estado de una tarea se comunica solo con un punto rojo/ámbar/verde, una persona con daltonismo —o cualquiera mirando la pantalla bajo el sol— no distingue los estados. La regla operativa es simple: todo lo que el color comunica debe tener un segundo canal (texto, icono con forma distinta, patrón, etiqueta).

<!-- Solo color: incumple 1.4.1 -->
<span class="punto" [style.background]="colorDe(tarea.estado)"></span>
<span>{{ tarea.titulo }}</span>

<span class="estado" [attr.data-estado]="tarea.estado">
  <svg class="i-estado" aria-hidden="true" focusable="false"></svg>
  <span class="sr-only">{{ etiquetaEstado(tarea.estado) }}:</span>
  <span>{{ tarea.titulo }}</span>
</span>
<!-- CSS: forma + color + texto visible o sr-only -->

En gráficas del sprint, la leyenda no basta si las series solo se distinguen por tono: añade patrón (rayas, puntos) o etiquetas directas sobre las barras. En campos con error, el borde rojo debe ir acompañado de icono y texto; el color refuerza, no sustituye.

26.10.2 Tokens de diseño: el único sitio donde se decide el contraste

Si cada componente elige su gris «a ojo», el contraste se rompe en cada sprint. La paleta de TaskFlow se define una sola vez como tokens CSS (o tokens de diseño exportados a CSS), con pares primer plano / fondo verificados, y los componentes solo consumen esos tokens.

:root {
  /* Texto sobre superficie: ratio ≥ 4,5:1 medido */
  --tf-fg: #1a1f2c;
  --tf-fg-muted: #4a5163;   /* ≥ 4,5:1 sobre --tf-bg */
  --tf-bg: #ffffff;
  --tf-bg-subtle: #f4f6fa;

  /* Acción primaria: texto blanco sobre marca ≥ 4,5:1 */
  --tf-brand: #0b5fff;
  --tf-brand-fg: #ffffff;

  /* Borde de control: ≥ 3:1 frente a --tf-bg (1.4.11) */
  --tf-border: #6b7280;

  /* Foco: ≥ 3:1 frente a adyacentes */
  --tf-focus: #0b5fff;
  --tf-focus-offset: #ffffff;

  /* Estados: color + se usará icono/texto en componentes */
  --tf-ok: #0f7a3a;
  --tf-warn: #9a5b00;
  --tf-danger: #b42318;
}

@media (prefers-color-scheme: dark) {
  :root {
    --tf-fg: #eef1f6;
    --tf-fg-muted: #b6bdd0;
    --tf-bg: #0f1419;
    --tf-bg-subtle: #1a222d;
    --tf-border: #8b93a7;
    --tf-brand: #6b9fff;
    --tf-brand-fg: #0a1020;
  }
}

import { readFileSync } from 'node:fs';

/** Luminancia relativa según WCAG 2. */
function lum(hex: string): number {
  const n = hex.replace('#', '');
  const rgb = [0, 2, 4].map((i) => {
    const c = parseInt(n.slice(i, i + 2), 16) / 255;
    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
  });
  return 0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2];
}

function ratio(a: string, b: string): number {
  const [L1, L2] = [lum(a), lum(b)].sort((x, y) => y - x);
  return (L1 + 0.05) / (L2 + 0.05);
}

const pares: [string, string, number, string][] = [
  ['#1a1f2c', '#ffffff', 4.5, 'fg / bg'],
  ['#4a5163', '#ffffff', 4.5, 'fg-muted / bg'],
  ['#ffffff', '#0b5fff', 4.5, 'brand-fg / brand'],
  ['#6b7280', '#ffffff', 3.0, 'border / bg (UI)'],
];

for (const [fg, bg, min, nombre] of pares) {
  const r = ratio(fg, bg);
  if (r < min) {
    console.error(`FALLO ${nombre}: ${r.toFixed(2)} < ${min}`);
    process.exitCode = 1;
  } else {
    console.log(`OK ${nombre}: ${r.toFixed(2)}`);
  }
}

Enlaza este script al pipeline junto a las pruebas de axe. No sustituye una auditoría visual, pero impide que un cambio de marca baje el contraste sin que nadie se entere.

26.10.3 Temas del sistema y contraste forzado

Además del modo claro/oscuro, Windows ofrece temas de contraste alto. Con forced-colors: active el navegador sustituye gran parte de tu paleta por colores del sistema. Los bordes hechos solo con box-shadow o fondos semitransparentes pueden desaparecer. La defensa mínima:

@media (forced-colors: active) {
  .tf-btn {
    border: 1px solid ButtonText;
    forced-color-adjust: none; /* solo si redefines con system colors */
  }
  .tf-btn:focus-visible {
    outline: 2px solid Highlight;
    outline-offset: 2px;
  }
  .estado[data-estado='bloqueada'] {
    /* No confíes en el color: el icono y el texto ya van en el HTML */
  }
}

26.11 Contenido dinámico

En una SPA como TaskFlow casi todo el contenido llega después de la primera pintura: listas que se cargan, toasts de «tarea guardada», resultados de filtrado, contadores del tablero. El usuario visual lo percibe porque ve el movimiento; el usuario de lector de pantalla solo se entera si tú anuncias el cambio. La herramienta es la región activa (aria-live / role="status" / role="alert"), ya introducida en 26.6.4; aquí la aplicamos a los patrones concretos del producto.

26.11.1 Estados de carga

Un spinner sin nombre es decoración muda. Tres piezas: (1) un indicador visible con texto o nombre accesible, (2) aria-busy="true" en el contenedor que se está actualizando, (3) un anuncio al terminar («12 tareas cargadas») en una región polite.

<section aria-labelledby="titulo-lista"
         [attr.aria-busy]="cargando() ? 'true' : null">
  <h2 id="titulo-lista">Tareas del proyecto</h2>

  @if (cargando()) {
    <p class="carga" role="status">
      <span class="spinner" aria-hidden="true"></span>
      Cargando tareas…
    </p>
  } @else {
    <ul>…</ul>
  }
</section>

<!-- Contenedor SIEMPRE en el DOM (regla de 26.6.4) -->
<div class="sr-only" aria-live="polite" aria-atomic="true">
  @if (!cargando() && anuncio()) { {{ anuncio() }} }
</div>

readonly cargando = signal(true);
readonly anuncio = signal('');

async ngOnInit(): Promise<void> {
  this.cargando.set(true);
  const tareas = await this.api.listar();
  this.tareas.set(tareas);
  this.cargando.set(false);
  this.anuncio.set(`${tareas.length} tareas cargadas`);
}

26.11.2 Notificaciones y toasts

Un toast de éxito es role="status" (equivalente a aria-live="polite"). Un aviso de «la sesión caduca en un minuto» es role="alert". Nunca uses alert para confirmaciones rutinarias: interrumpir al lector cada vez que se guarda una tarea lo vuelve inutilizable. Si usas el CDK, LiveAnnouncer encapsula exactamente este contrato (sección 26.13).

@Injectable({ providedIn: 'root' })
export class ToastService {
  private readonly live = inject(LiveAnnouncer);
  readonly actual = signal<{ texto: string; tono: 'ok' | 'error' } | null>(null);

  async exito(texto: string): Promise<void> {
    this.actual.set({ texto, tono: 'ok' });
    await this.live.announce(texto, 'polite');
  }

  async error(texto: string): Promise<void> {
    this.actual.set({ texto, tono: 'error' });
    await this.live.announce(texto, 'assertive');
  }
}

26.11.3 prefers-reduced-motion

El criterio 2.3.3 (animación desde interacciones, AAA) y la buena práctica general exigen respetar la preferencia del sistema. En TaskFlow: sin parallax, sin carruseles automáticos, transiciones cortas o nulas, y ningún movimiento esencial para entender el estado (el estado debe existir también en estático).

:root {
  --tf-dur: 180ms;
  --tf-ease: cubic-bezier(0.2, 0.8, 0.2, 1);
}

@media (prefers-reduced-motion: reduce) {
  :root { --tf-dur: 0.01ms; }
  .tf-slide, .tf-fade, .skeleton-shine {
    animation: none !important;
    transition: none !important;
  }
}

/** Útil para desactivar animaciones de Angular Animations. */
export function prefiereMenosMovimiento(): boolean {
  return typeof matchMedia === 'function'
    && matchMedia('(prefers-reduced-motion: reduce)').matches;
}

26.12 Imágenes, iconos y multimedia

El criterio 1.1.1 (contenido no textual) es el más antiguo de WCAG y sigue siendo de los más incumplidos. La regla se resume en una pregunta: si quito la imagen, ¿se pierde información? Si sí, necesita alternativa textual. Si no (es decorativa), debe ocultarse del árbol de accesibilidad.

26.12.1 alt útil frente a alt vacío

<!-- alt omitido: el lector puede leer la URL del fichero -->
<img src="/avatars/{{ usuario.id }}.png">
<!-- alt inútil -->
<img src="chart.png" alt="imagen">
<!-- icono clicable sin nombre -->
<button type="button" (click)="borrar()">
  <img src="trash.svg" alt="">
</button>

<img [src]="usuario.avatarUrl"
     [alt]="'Avatar de ' + usuario.nombre">

<img src="chart.png"
     alt="Burndown del sprint 14"
     aria-describedby="desc-burndown">
<p id="desc-burndown">Quedan 32 puntos; la tendencia…</p>

<button type="button"
        [attr.aria-label]="'Eliminar tarea ' + tarea.titulo"
        (click)="borrar()">
  <svg aria-hidden="true" focusable="false"></svg>
</button>

26.12.2 Iconos con nombre accesible

Un icono SVG inline es, por defecto, un gráfico sin rol útil. Patrones correctos:

• Icono decorativo junto a texto visible: aria-hidden="true" y focusable="false" en el SVG. El nombre lo aporta el texto.
• Botón o enlace solo icono: nombre en el control (aria-label o texto .sr-only), SVG oculto.
• Icono informativo sin texto: role="img" + aria-label en el SVG, o <title> dentro del SVG referenciado con aria-labelledby.

<!-- Informativo, sin texto hermano -->
<svg role="img" aria-label="Prioridad alta" width="16" height="16">
  <use href="sprite.svg#prioridad-alta"></use>
</svg>

<!-- Decorativo junto a etiqueta visible -->
<span class="badge">
  <svg aria-hidden="true" focusable="false"></svg>
  Prioridad alta
</span>

26.12.3 Vídeo y audio de ayuda

Si TaskFlow incluye un vídeo de onboarding o un podcast interno: subtítulos sincronizados (1.2.2), descripción de audio o transcripción cuando haya información visual no hablada (1.2.3/1.2.5), y control de reproducción operable por teclado. No reproduzcas automáticamente con sonido (1.4.2). Un PDF o una página HTML con la misma información suele ser la alternativa más robusta para formación interna.

26.13 Angular: CDK a11y, Material y el linter de plantillas

Angular no te hace accesible por magia, pero el paquete @angular/cdk/a11y concentra utilidades que resolverías mal si las reimplementas. Angular Material las usa por debajo. El linter de plantillas atrapa otra familia de errores antes de llegar al navegador.

26.13.1 FocusTrap y CdkTrapFocus

Un diálogo modal debe mantener el Tab dentro de sí (2.1.2, 2.4.3). El CDK ofrece una directiva declarativa y un servicio imperativo.

import { A11yModule, CdkTrapFocus } from '@angular/cdk/a11y';

@Component({
  selector: 'tf-confirmar-borrado',
  imports: [A11yModule],
  template: `
    <div class="dialogo" role="dialog" aria-modal="true"
         aria-labelledby="dlg-titulo" cdkTrapFocus cdkTrapFocusAutoCapture>
      <h2 id="dlg-titulo">¿Eliminar la tarea?</h2>
      <p>Esta acción no se puede deshacer.</p>
      <button type="button" (click)="cancelar()">Cancelar</button>
      <button type="button" class="peligro" (click)="confirmar()">
        Eliminar
      </button>
    </div>
  `,
})
export class ConfirmarBorradoComponent {
  /* Al destruir el diálogo, el servicio que lo abrió
     restaura el foco al disparador (patrón de 26.8). */
}

cdkTrapFocusAutoCapture mueve el foco al primer tabulable al crear la trampa. Sin restaurar el foco al cerrar, el usuario de teclado «salta» al inicio del documento: es el fallo más reportado en SPAs con modales caseros.

26.13.2 LiveAnnouncer

En lugar de gestionar a mano un nodo aria-live (con la trampa del contenedor que debe existir antes), el CDK mantiene una región oculta y expone announce(texto, 'polite' | 'assertive').

import { LiveAnnouncer } from '@angular/cdk/a11y';

export class TableroComponent {
  private readonly live = inject(LiveAnnouncer);

  async moverTarea(t: Tarea, columna: string): Promise<void> {
    await this.api.mover(t.id, columna);
    await this.live.announce(
      `Tarea ${t.titulo} movida a ${columna}`,
      'polite',
    );
  }
}

26.13.3 FocusMonitor

Distingue el origen del foco (teclado, ratón, táctil, programa). Sirve para aplicar estilos de foco solo cuando importan —complemento de :focus-visible— y para telemetría interna de componentes de diseño.

import { FocusMonitor } from '@angular/cdk/a11y';

export class TfButtonComponent implements OnInit, OnDestroy {
  private readonly fm = inject(FocusMonitor);
  private readonly host = inject(ElementRef<HTMLElement>);
  readonly origen = signal<string | null>(null);

  ngOnInit(): void {
    this.fm.monitor(this.host, true).subscribe((origen) => {
      this.origen.set(origen);
      // origen === 'keyboard' → anillo visible forzado por clase
    });
  }

  ngOnDestroy(): void {
    this.fm.stopMonitoring(this.host);
  }
}

26.13.4 Material y el linter de plantillas

Angular Material construye diálogos, menús, selectores y snackbars sobre el CDK: atrapan foco, gestionan Escape, anuncian aperturas. Si tu diseño lo permite, extiende Material en lugar de reinventar el modal. Lo que Material no resuelve solo: tu semántica de dominio (nombres de botones de icono, textos de error, estructura de la página, contraste de la tema personalizada).

El compilador de plantillas de Angular, con las opciones de accesibilidad del esquema, avisa de img sin alt, elementos clicables sin teclado, contrastes básicos y atributos ARIA inválidos. Actívalo en el proyecto:

{
  "projects": {
    "taskflow": {
      "architect": {
        "build": {
          "options": {
            "optimization": true
          }
        },
        "lint": {
          "builder": "@angular-eslint/builder:lint",
          "options": {
            "lintFilePatterns": ["src/**/*.ts", "src/**/*.html"]
          }
        }
      }
    }
  }
}

// Extiende plugin:@angular-eslint/template/accessibility
export default [
  {
    files: ['**/*.html'],
    extends: [
      'plugin:@angular-eslint/template/recommended',
      'plugin:@angular-eslint/template/accessibility',
    ],
    rules: {
      '@angular-eslint/template/click-events-have-key-events': 'error',
      '@angular-eslint/template/interactive-supports-focus': 'error',
      '@angular-eslint/template/label-has-associated-control': 'error',
      '@angular-eslint/template/alt-text': 'error',
      '@angular-eslint/template/valid-aria': 'error',
    },
  },
];

26.14 Cómo se prueba la accesibilidad

La accesibilidad no se «siente» en una demo con el ratón. Se verifica con tres capas que se refuerzan: automatización (barata, incompleta), teclado (obligatoria, rápida) y lector de pantalla (cara en tiempo, insustituible en componentes nuevos). Una regla empírica fiable: las herramientas automáticas detectan en torno al 30–40 % de los problemas reales. El resto es interacción y semántica que solo un humano encuentra.

26.14.1 axe y Lighthouse

axe-core (Deque) es el motor de reglas más usado en la industria. Lo ejecutas en el navegador (extensión axe DevTools), en Lighthouse (auditoría Accessibility) o embebido en pruebas. Lighthouse Accessibility es, en gran parte, axe con una puntuación agregada: útil como señal, peligroso como único KPI («hemos llegado a 100» no significa conforme a WCAG).

# En Chrome: instalar axe DevTools
# Abrir TaskFlow → panel axe → Scan ALL of my page
# Priorizar violaciones "serious" y "critical"
# Exportar JSON y abrir incidencias enlazadas al criterio WCAG

26.14.2 Protocolo de teclado (cinco minutos)

Antes de cada merge de UI, alguien del equipo (no solo el autor) recorre esto sin tocar el ratón:

1. Tab desde la barra de dirección hasta el final de la vista: ¿se ve el foco en todo momento? ¿El orden es lógico?
2. ¿Se puede llegar a todos los controles y activarlos con Enter/Espacio?
3. Abrir el diálogo de confirmación: ¿Tab cicla dentro? ¿Escape cierra? ¿El foco vuelve al disparador?
4. Menú de usuario y selector de proyecto: ¿flechas, Home/End, Escape según el patrón APG?
5. Formulario de nueva tarea: etiquetas, errores anunciados, envío y foco al resumen si falla.

Si algo falla aquí, no hace falta VoiceOver todavía: ya tienes un defecto bloqueante.

26.14.3 Lector de pantalla

Mínimo viable por plataforma: NVDA + Firefox o Chrome en Windows (gratuito), VoiceOver + Safari en macOS/iOS, TalkBack en Android para la vista móvil. No intentes dominar los tres el mismo día: elige el de tus usuarios mayoritarios y documenta un guion de cinco pantallas críticas (login, lista, detalle, formulario, diálogo). Escucha el nombre, el rol y el estado; si oyes «grupo» o «clicable» genérico donde esperabas «botón» o «casilla», el árbol está mal.

26.14.4 jest-axe / vitest-axe en componentes

import { TestBed } from '@angular/core/testing';
import { axe, toHaveNoViolations } from 'jest-axe';
import { TareaFormComponent } from './tarea-form.component';

expect.extend(toHaveNoViolations);

describe('TareaFormComponent a11y', () => {
  beforeEach(() => {
    TestBed.configureTestingModule({
      imports: [TareaFormComponent],
    });
  });

  it('no tiene violaciones axe en estado inicial', async () => {
    const fixture = TestBed.createComponent(TareaFormComponent);
    fixture.detectChanges();
    const resultados = await axe(fixture.nativeElement);
    expect(resultados).toHaveNoViolations();
  });

  it('no tiene violaciones con errores visibles', async () => {
    const fixture = TestBed.createComponent(TareaFormComponent);
    const cmp = fixture.componentInstance;
    cmp.intentado.set(true);
    fixture.detectChanges();
    const resultados = await axe(fixture.nativeElement);
    expect(resultados).toHaveNoViolations();
  });
});

Configura axe con las reglas WCAG 2.1 AA (o 2.2 AA si es tu compromiso). Desactiva reglas solo con justificación documentada en el propio test; un rules: { 'color-contrast': { enabled: false } } global es una deuda disfrazada de verde.

26.14.5 Puerta en integración continua

name: a11y
on: [pull_request]
jobs:
  lint-y-axe:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx ng lint
      - run: npm test -- --coverage=false
      - run: npx ng build --configuration=production
      - run: npx playwright test e2e/a11y.spec.ts

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test.describe('Auditoría axe de rutas críticas', () => {
  for (const ruta of ['/login', '/proyectos', '/proyectos/1/tareas']) {
    test(`${ruta} sin violaciones graves`, async ({ page }) => {
      await page.goto(ruta);
      const resultados = await new AxeBuilder({ page })
        .withTags(['wcag21aa', 'wcag22aa'])
        .analyze();
      const graves = resultados.violations.filter(
        (v) => v.impact === 'critical' || v.impact === 'serious',
      );
      expect(graves).toEqual([]);
    });
  }
});

26.15 Documentos del servidor: correos y PDF

La accesibilidad no termina en el navegador. NestJS genera correos transaccionales («te han asignado una tarea»), PDF de informes de sprint y, a veces, HTML de facturación. Esos artefactos también están sujetos a EN 301 549 / WCAG cuando el cliente es administración pública o el contrato lo exige, y en cualquier caso son la única interfaz de muchos usuarios en ese momento.

26.15.1 Correos HTML

• HTML semántico simple: encabezados reales, listas, enlaces con texto descriptivo («Abrir tarea Diseño de API»), no «pincha aquí».
• Texto en HTML, no en imagen. Si el logotipo es imagen, alt="TaskFlow".
• Contraste de texto y botones igual que en la web (4,5:1 / 3:1).
• Versión en texto plano multipart alternativa: muchos lectores y clientes corporativos la prefieren.
• No dependas del color del semáforo de prioridad: incluye la palabra «Alta» / «Media» / «Baja».

<!-- Plantilla de correo: marcado lineal y predecible -->
<h1>Nueva tarea asignada</h1>
<p>Hola {{nombre}},</p>
<p>{{asignador}} te ha asignado la tarea
  <strong>{{titulo}}</strong>
  (prioridad {{prioridadEtiqueta}})
  en el proyecto {{proyecto}}.</p>
<p><a href="{{url}}">Abrir la tarea {{titulo}} en TaskFlow</a></p>
<p>Si el botón no funciona, copia esta URL:<br>{{url}}</p>

async enviarAsignacion(datos: AsignacionCorreo): Promise<void> {
  const html = this.motor.render('correo-asignacion', datos);
  const text = [
    `Nueva tarea asignada`,
    `Hola ${datos.nombre},`,
    `${datos.asignador} te ha asignado «${datos.titulo}»`,
    `(prioridad ${datos.prioridadEtiqueta}) en ${datos.proyecto}.`,
    `Abrir: ${datos.url}`,
  ].join('\n\n');

  await this.mailer.sendMail({
    to: datos.email,
    subject: `TaskFlow: te han asignado «${datos.titulo}»`,
    html,
    text, // alternativa accesible y robusta
  });
}

26.15.2 PDF generados

Un PDF de «solo imagen» (impresión a mapa de bits o canvas sin etiquetas) es un muro para lectores de pantalla. Si generas PDF en el servidor:

• Usa un motor que produzca PDF etiquetado (tagged PDF): estructura de encabezados, párrafos, listas y tablas reales (p. ej. rutas con HTML→PDF que preserven semántica, o bibliotecas que escriban roles de etiqueta).
• Orden de lectura coherente con el orden visual.
• Texto seleccionable, no escaneado.
• Idioma del documento declarado.
• Cuando el PDF sea un anexo de cumplimiento, ofrece también HTML o CSV con los mismos datos.

/**
 * Preferimos generar HTML semántico y convertirlo con un motor
 * que preserve etiquetas. Si el cliente solo pide Excel/CSV para
 * datos tabulares, es más accesible y más barato que un PDF bonito.
 */
async generarInforme(sprintId: string): Promise<Buffer> {
  const datos = await this.repo.resumen(sprintId);
  const html = this.vista.render('informe-sprint', {
    ...datos,
    lang: 'es',
    titulo: `Informe del sprint ${datos.nombre}`,
  });
  return this.pdf.desdeHtmlEtiquetado(html, { lang: 'es' });
}

26.16 Errores comunes y cómo solucionarlos

26.17 Buenas y malas prácticas

26.18 Preguntas frecuentes

26.19 Ejercicios

import { LiveAnnouncer } from '@angular/cdk/a11y';
import { debounceTime, distinctUntilChanged } from 'rxjs';

export class FiltroTareasComponent {
  private readonly live = inject(LiveAnnouncer);
  readonly query = signal('');
  readonly visibles = computed(() => this.filtrar(this.query()));

  constructor() {
    // Debounce: no anunciar en cada tecla.
    toObservable(this.query).pipe(
      debounceTime(300),
      distinctUntilChanged(),
    ).subscribe(() => {
      const n = this.visibles().length;
      const msg = n === 0
        ? 'Ninguna tarea coincide con el filtro'
        : `${n} tareas coinciden`;
      void this.live.announce(msg, 'polite');
    });
  }
}

@Injectable({ providedIn: 'root' })
export class DialogoBorradoService {
  private disparador: HTMLElement | null = null;

  abrir(disparador: HTMLElement, tarea: Tarea): void {
    this.disparador = disparador;
    // Abre el overlay/dialog; el template usa cdkTrapFocusAutoCapture
    this.ref.set({ tarea });
  }

  cerrar(): void {
    this.ref.set(null);
    // Devolver el foco en el siguiente frame, cuando el diálogo ya no está
    queueMicrotask(() => this.disparador?.focus());
    this.disparador = null;
  }
}

<div role="dialog" aria-modal="true" aria-labelledby="t"
     cdkTrapFocus cdkTrapFocusAutoCapture>
  <h2 id="t">¿Eliminar «{{ tarea.titulo }}»?</h2>
  <button type="button" (click)="svc.cerrar()">Cancelar</button>
  <button type="button" (click)="confirmar()">Eliminar</button>
</div>

import { axe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);

it('formulario inválido anunciado sigue sin violaciones', async () => {
  const fixture = TestBed.createComponent(TareaFormComponent);
  const cmp = fixture.componentInstance;
  cmp.intentado.set(true);
  cmp.form.markAllAsTouched();
  fixture.detectChanges();

  // El resumen de errores debe estar en el DOM con role="alert"
  const alert = fixture.nativeElement.querySelector('[role="alert"]');
  expect(alert).toBeTruthy();

  const resultados = await axe(fixture.nativeElement, {
    runOnly: { type: 'tag', values: ['wcag21aa'] },
  });
  expect(resultados).toHaveNoViolations();
});

26.20 Resumen del capítulo

26.21 Recursos adicionales