SocialGouv/ultra11y

ultra11y — audita WCAG 2.2 AA y escribe marcado accesible

En accesibilidad, una herramienta automatizada solo ve parte del problema. ultra11y asume eso con una división del trabajo: el motor determinista, sin instalación (node scripts/ultra11y.mjs <comando> — sin npm install, sin clave; el analizador JSX/TSX está incrustado en el paquete) hace el trabajo mecánico — detecta las no conformidades comprobables por máquina y las vincula al criterio de éxito WCAG correcto — y el agente activo de codificación adjudica los criterios de juicio — relevancia del alt, propósito del enlace en contexto, orden de lectura — de forma estática, a partir de la evidencia que el motor recolecta (verify --manual), cada veredicto protegido por verify/check. Solo los criterios verdaderamente del DOM renderizado (contraste calculado, foco visible, zoom/reflow, contenido al pasar el ratón) recaen en el nivel scan (axe-core en un navegador real); un humano es, como máximo, una supervisión opcional. Las compuertas evitan que sobreviva cualquier no conformidad alucinada, y nada es nunca "conforme" en silencio.

No confundas reglas con criterios. El paquete incluye 93 comprobaciones estáticas, WCAG AA tiene 55 criterios de éxito y RGAA tiene 106 criterios. Varias reglas pueden evidenciar un criterio, una regla puede contribuir a varios criterios del paquete, y la mayoría de los criterios permanecen abiertos hasta que se realiza un escaneo o una adjudicación. La única cobertura honesta a nivel de ejecución es el recuento de procedencia en vivo de la cuadrícula (moteur + scan + agent, más cualquier residuo no decidible nombrado), nunca una promesa fija como "48 criterios del agente". Por lo tanto, los resúmenes de GitHub muestran decidido/total, no un porcentaje sobre el pequeño subconjunto decidido.

WCAG 2.2 Nivel AA es el núcleo mundial. Los estándares nacionales — RGAA de Francia, Sección 508 de EE. UU., EN 301 549 de la UE — son paquetes de estándares conectables que asignan sus criterios a WCAG. Agrega --standard rgaa para cambiar la clave de cada comando y cada salida, incluido audit, hallazgos y todo; conecta un paquete externo en tiempo de ejecución con --pack ./pack.json (o un .ultra11yrc.json), sin recompilar; o contribuye con tu país (consulta references/standards.md). Los paquetes (y sus guías de implementación concretas — los patrones buenos/malos de RGAA SocialGouv/etalab) pueden ser ingeridos por IA y protegidos por pack check para que nunca pase una asignación fabricada; consulta references/packs.md y references/guidance.md.

La mayor parte del trabajo es tuyo. De los 55 criterios de éxito de WCAG 2.2 AA, el motor puede decidir 3 directamente; 14 necesitan una página renderizada (scan) y 38 son juicios que el agente adjudica. Por lo tanto, la ejecución limpia del motor es un punto de partida, nunca un veredicto — y references/adjudication.md es la página desde la que realmente trabajas.

Reglas principales:

1. Nunca inventes una no conformidad: cada NC cita un elemento real y resoluble (check lo verifica).
2. HTML nativo primero, ARIA último; nunca dupliques semántica implícita.
3. Nunca inventes una conformidad tampoco: una C se cita exactamente como una NC — nombra en citations[] la evidencia recolectada que despejó, cada ancla resoluble y extraída de la evidencia que ese criterio realmente mostró. Un criterio presentado sin evidencia no puede ser C en absoluto; permanece manual. Tampoco puede serlo aquel cuya lectura fue INCOMPLETA (evidenceComplete: false): un criterio del que se te mostró parte aún puede fallar en lo que viste, pero nunca puede ser despejado sobre lo que no viste. Y una C adjudicada nunca se fusiona con una decidida por el motor: los informes la enumeran por separado y la mantienen fuera de la tasa de aprobación automática. 3b. Lo que se te muestra es la población completa, dicho una vez por cada cosa distinta. La evidencia es un representante por CLASE DE CONTENIDO, que lleva occurrences, los otros anclajes en alsoAt, y las pages en las que aparece — 887 enlaces en 38 páginas capturadas son 97 pares (texto, href) distintos. Juzgar al representante juzga a todos ellos, que es lo que hace que una C honesta sea alcanzable; y una cita que nombre CUALQUIER ocurrencia de una clase que el criterio lleva es aceptada, así que cita la que realmente abriste.
4. El residuo es explícito, nunca conforme en silencio: el agente de IA adjudica cada criterio de juicio (protegido por verify --manual), y los criterios de renderizado van a scan — que ahora CONCLUYE C (decidedBy: "scan") cuando cada regla que lleva un criterio se ejecutó en cada página del alcance y no generó nada, y permanece en silencio cuando aunque sea una página tuvo señales incompletas. Cualquier criterio aún no probado permanece "para evaluar manualmente" — ningún estado sin un veredicto registrado y justificado. Para convertir eso en una compuerta y no en una esperanza, check --in <audit.json> --require-decided falla mientras algo esté aún por evaluar, y --allow-undecided <file> toma los criterios que genuinamente no puedes decidir, cada uno con su motivo (una lista con nombre, nunca un umbral). --require-decided=pages mantiene la propia cuadrícula de CADA página en el mismo nivel: un criterio que falla en una ruta está resuelto para la ejecución y puede que aún no sea el veredicto de nadie en las rutas en las que nunca se activó, que es por lo que se juzga realmente un entregable por página. La lista de trabajo emitida es autorizada. Puede contener deliberadamente un criterio cuyo estado general de ejecución ya sea NC, porque esa falla no decidió el criterio en las otras páginas. Tal elemento no es redundante: devuelve un veredicto fundamentado para él (o un motivo manual explícito), nunca lo dejes en blanco porque el recuento global parece decidido.
5. Consulta el criterio; nunca lo recuerdes. criteria [--standard <pack>] <id> — o ultra11y_criteria a través de MCP — devuelve el texto del propio criterio, sus pruebas numeradas y las definiciones del glosario que esas pruebas citan. RGAA 8.3 no es "la página necesita un atributo lang"; es la prueba 8.3.1 con dos condiciones alternativas, y el glosario decide qué significan sus términos. Un bloque de auditor que cita 8.3.1 después de leerlo está fundamentado; uno que lo cita de memoria es una suposición disfrazada de referencia. Antes de auditar contra un estándar nacional, ejecuta el plan (ultra11y_method): te dice cuántos de sus criterios aún necesitan adjudicación para obtener una C — para RGAA, 104 de 106. Consulta references/mcp.md.
6. El HTML semántico renderizado FINAL debe ser correcto. El motor solo ve el código fuente; una biblioteca de componentes (DSFR/MUI…) o SFC .vue/.svelte/.astro oculta el marcado real, por lo que una auditoría de fuente verde no es una prueba. Verifica el HTML semántico producido — instala el recolector de captura sin intervención (render --setup) para que cada componente que tus pruebas renderizan se serialice en .ultra11y/captures y sea auditado, con audit --require-captures protegiendo los puntos ciegos. Consulta references/automation.md / references/rendered.md.
7. Idioma: PASA SIEMPRE --lang coincidiendo con el idioma de tu conversación con el usuario; pregunta al usuario cuando sea ambiguo. Sin la bandera, la CLI lo detecta automáticamente (repo <html lang> → la configuración regional predeterminada del estándar activo → inglés) — un respaldo para scripts/CI, no un sustituto de pasar --lang tú mismo.
8. Los tokens técnicos permanecen en inglés, incluso en prosa en francés. En cualquier entregable en francés que escribas (comentarios de informes, PRD, tickets de seguimiento, veredictos de juicio), los nombres de atributos/elementos/roles y sus valores son código, no prosa — nunca los traduzcas: aria-live sigue siendo aria-live (nunca « région live »), igual para tabindex, alt, role="alert", nombres de roles de puntos de referencia. El propio catálogo en francés del motor sigue esto; coincídele. El vocabulario normativo del estándar (redacción RGAA como « lien d'évitement ») mantiene su francés oficial.

La biblioteca de referencia

Primero el conocimiento del dominio, luego las herramientas. Lee el que coincida con la pregunta que tienes delante.

Conocimiento de accesibilidad
references/adjudication.md	Cómo decidir cada uno de los 52 criterios que el motor te entrega — la regla de decisión, cuándo NA es legítimo, las preguntas
references/naming.md	Cálculo del nombre accesible, 2.5.3 etiqueta-en-nombre, CSS visualmente oculto, nombrar imágenes/SVG/figuras
references/widgets.md	Patrones compuestos ARIA APG, contratos de teclado, gestión de foco, cambios de ruta SPA, regiones en vivo
references/forms-and-errors.md	Etiquetas e instrucciones, la lista de tokens autocomplete, identificación/sugerencia/prevención de errores, entrada redundante, autenticación accesible
references/structure.md	Encabezados, puntos de referencia, listas y dl, tablas simples y complejas, secuencia significativa
references/media-and-motion.md	Subtítulos/descripción de audio/transcripciones, gestos de puntero, tamaño del objetivo, orientación, reflow, movimiento reducido
references/forbidden-patterns.md	15 antipatrones: malo → por qué → solución nativa → criterio
references/focus-and-logic.md	Los criterios de foco/teclado que te pertenecen, y cómo razonar sobre ellos
references/criteria.md	Los 55 criterios: nivel, clase de automatizabilidad, reglas del motor, asignación de paquetes (generado)
references/rgaa-automation.md	RGAA 4.1.2: matriz generada de 106 criterios / 258 pruebas, reglas decisivas, señales candidatas y política de silencio
references/act.md	Lo que el motor está medido para detectar — y lo que demostrablemente no (generado)

Ejecutar la herramienta
references/runbook.md	La ejecución confiable: la receta única, el transporte a usar y por qué, y lo que cuesta un pase. Lee esto antes de pagar por una adjudicación
references/claude-code-report.md	La ruta de publicación detallada de Claude Code: alcance renderizado, adjudicación directa, verificación adversarial, Markdown + HTML + evidencia por página
references/audit.md	El bucle de auditoría de principio a fin, y la muestra de página normativa
references/judgment.md	Las listas de trabajo de adjudicación + refutación, vocabulario de veredictos, pliegue de cierre de fallo
references/verify.md	Las compuertas check/verify
references/false-positives.md	Dónde un hallazgo aún puede ser incorrecto, y cómo refutarlo
references/rendered.md · references/automation.md	Auditar HTML producido, capturas, hooks y CI
references/harnesses.md	Dónde se ejecuta esto: Claude Code, Codex CLI, OpenCode, y el respaldo AGENTS.md
references/orchestrators.md	Conducir el motor desde un motor de flujo de trabajo / CI que no sea GitHub: fijación, el pipeline de seis pasos, códigos de salida, el conjunto de tickets como JSON para cualquier rastreador
references/ci.md	`--format sarif
references/pages.md	Instantáneas de página + la cuadrícula de criterios por página (pages), y sus reglas de honestidad
references/e2e.md	render --e2e: auditar una página durante tu ejecución de Playwright/Cypress
references/devtools.md	dev: la superposición en vivo mientras construyes, y el tablero por página
references/extension.md	La extensión del navegador: audita la página que estás viendo, a través del side-car
references/dynamic.md	El nivel scan: tiempos de ejecución, sondas, páginas autenticadas
references/scale.md	Enfocar una auditoría en un repositorio grande
references/fix.md · references/correction.md	Aplicar correcciones, por prioridad, sin regresiones
references/prd.md	El bloque de auditor como un backlog (marcado)
references/tickets.md	Archivar ese backlog como tickets: GitHub, GitLab, Jira, y a qué granularidad
references/standards.md · references/packs.md · references/guidance.md	Estándares nacionales, crear un paquete, guía de implementación
references/mcp.md	Los estándares como un motor de reglas: consulta un criterio en lugar de recordarlo — sus pruebas numeradas, los términos que define, la corrección y el plan de trabajo. Como herramientas MCP y recursos std://, o los mismos datos en la CLI
references/methodology.md	Estados, tasa de aprobación, severidades, formato del informe
references/cross-file.md	--graph: importaciones y reglas entre archivos
references/orchestration.md	Distribuir las fases de juicio entre subagentes

Elige según la situación

• "Producir una auditoría/informe detallado en Claude Code" → usa la sesión activa de Claude como el auditor, cierra los criterios renderizados y de juicio, desafía sus afirmaciones, luego publica el informe Markdown fechado, HTML imprimible y dosieres por página con evidencia. Lee references/claude-code-report.md. Este es el perfil de publicación interactiva; termina con su conjunto completo de entregables. El resumen compacto es la rama de CI a continuación.
• "Auditoría / informe de cumplimiento" → node scripts/ultra11y.mjs audit … --json, luego report (tabla de síntesis + un bloque de conformidad del auditor por criterio NC — el mismo bloque que usan prd y tickets), luego check; lee references/audit.md.
• "Código renderizado por una librería (DSFR, MUI…) o un SFC .vue/.svelte/.astro / evitar falsos negativos" → audita el HTML producido, no la plantilla fuente. Lo más fácil: instala el recolector de captura sin intervención (render --setup) para que tus pruebas serialicen cada componente renderizado en .ultra11y/captures (ingerido automáticamente, hallazgos atribuidos al componente fuente; render --coverage y audit --require-captures rastrean puntos ciegos). O render (receta construir→auditar o instantánea SSR --scaffold) luego audit en la salida, y scan para el renderizado calculado. Los hallazgos de fuente SFC se marcan preliminary (una advertencia scope.sourceTemplate); lee references/rendered.md.
• "Un hallazgo parece incorrecto / falso positivo en un componente" → el motor suprime automáticamente la mayoría de los falsos positivos de componentes (nombres inyectados por slot/prop, hijos de componentes, enlaces dinámicos, encabezados condicionales) y marca los hallazgos de fuente SFC/biblioteca como preliminary; confirma o refuta el resto con verify --apply; lee references/false-positives.md.
• "Repositorio grande / auditar de forma inteligente" → enfoca: --changed (git diff), priorización de plantillas, dedup, --max-files; lee references/scale.md.
• "Análisis entre archivos (árbol + dependencias), JSX/TSX como un AST real" → audit --graph resuelve importaciones y aplica reglas entre archivos

…

[truncado para traducción]