FrancoisChastel/a11y-eval

Reparador de accesibilidad

Estás ejecutando correcciones de accesibilidad. Tu entrada es una orden de trabajo de mitigación (mitigations.md, producida por a11y-eval); tu salida son cambios mínimos en el código fuente que hagan que los hallazgos desaparezcan para usuarios reales, verificados volviendo a ejecutar el evaluador.

Si aún no existe una orden de trabajo, genera una primero: node src/cli.ts --repo <dir> (o --url para una aplicación en ejecución) en un clon de a11y-eval, o node src/cli.ts mitigate --report <dir> a partir de un informe existente.

Instrucciones de corrección

Corrige las violaciones de accesibilidad con el cambio más pequeño que restaure el acceso real, en este orden de preferencia:

1. Semántica nativa primero. Reemplaza los widgets falsos con elementos reales: div onclick → <button type="button">, span de navegación → <a href>, entrada sin etiqueta → <label for> + input. Los elementos nativos aportan operabilidad por teclado, roles, nombres y estados de forma gratuita: las adaptaciones ARIA son el plan de respaldo, nunca el primer movimiento.
2. Contenido sobre atributos. El texto alternativo, las etiquetas, el texto de los enlaces y los mensajes de error deben transmitir la información real ("Los ingresos del tercer trimestre aumentaron un 12 %"), no reafirmar el elemento ("gráfico", "imagen", "enlace"). Escríbelo a partir del contexto circundante; marca para un humano si el significado no se puede inferir.
3. Corrige a nivel de token/componente. Cuando la misma regla se active en varias páginas, encuentra la causa compartida (una propiedad personalizada de CSS, un componente base, un contenedor de diseño) y corrígela una vez. Nunca remiendes cuarenta puntos de llamada cuando un solo componente es la causa raíz.
4. Conserva todo lo que el usuario pueda hacer o leer. El contenido textual, las capacidades interactivas y la jerarquía visual deben sobrevivir a la corrección. Eliminar una funcionalidad, ocultar un elemento (display:none, aria-hidden) o eliminar la capacidad de recibir enfoque para silenciar un hallazgo es una corrección fallida.
5. El contraste es aritmético, no estético. Calcula la relación (≥4.5:1 texto normal, ≥3:1 texto grande/componentes de interfaz); elige el tono aprobado más cercano del matiz previsto en lugar de saltar a blanco/negro.
6. El enfoque debe ser visible en todas partes. Elimina el outline: none generalizado; añade contornos :focus-visible (≥2px, desplazamiento, ≥3:1 contra el entorno). Verifica tabulando.
7. Un grupo de orden de trabajo por conjunto de cambios. Corrige cada instancia listada del grupo y luego verifica antes de comenzar el siguiente. Agrupar conjuntos de cambios no relacionados hace que las regresiones no sean rastreables.
8. Cada NO HACER en la orden de trabajo es vinculante. Cuando una corrección y un escollo entran en conflicto, el escollo gana: detente y reconsidera el enfoque.

Flujo de trabajo

1. Lee la orden de trabajo de principio a fin. Los grupos están ordenados por impacto y alcance: respeta el orden.
2. Localiza cada instancia en el código fuente: los hallazgos estáticos llevan archivo:línea:columna; los hallazgos en tiempo de ejecución llevan un selector CSS y un fragmento HTML: busca en el repositorio el fragmento, sus nombres de clase o el texto cercano.
3. Aplica la corrección del grupo a cada instancia, siguiendo las instrucciones de corrección anteriores y los pasos/escollos del grupo.
4. Verifica el lote: vuelve a ejecutar el comando de verificación de la orden de trabajo (la evaluación original + --baseline <informe anterior>). El grupo se considera resuelto cuando su regla aparece bajo "corregido" con cero hallazgos nuevos.
5. Secciones de fallos manuales: la evidencia del revisor es la especificación. Deriva el cambio a partir de ella, aplícalo y anota que el criterio necesita una nueva revisión por humano/agente: la automatización no puede confirmarlo.
6. Condiciones de parada: una instancia cuyo significado no puedas inferir (texto alternativo para una imagen desconocida, una etiqueta para un campo ambiguo) recibe un comentario TODO(a11y) más una nota en tu resumen: una suposición incorrecta es peor que una brecha marcada.
7. Informe: puntuación antes → después, grupos resueltos, nuevos hallazgos (deben ser cero), elementos marcados para humanos.

Grupos sospechosos VLM

Las órdenes de trabajo pueden contener grupos vlm-* (solo cuando la evaluación se ejecutó con --vlm). Sus filas de instancias llevan el razonamiento del modelo de visión — para vlm-alt-quality-suspect, un texto alternativo propuesto. Trata la propuesta como un borrador: verifícala contra la imagen real antes de aplicarla y nunca apliques un cambio propuesto por VLM que no puedas confirmar desde la página misma.

Qué no hacer

• INCORRECTO: tabindex + controladores de teclado añadidos a un div cuando un elemento nativo funciona
• INCORRECTO: alt="" en imágenes informativas; aria-label duplicando texto visible que no coincide
• INCORRECTO: suprimir reglas, eliminar elementos o aria-hidden para hacer desaparecer hallazgos
• INCORRECTO: ajustes de contraste a ojo sin calcular la relación
• INCORRECTO: afirmar que está listo sin una nueva verificación que muestre que las reglas han desaparecido

Habilidades relacionadas

• a11y-evaluator — produce el informe y la orden de trabajo que esta habilidad consume