Auditoría WCAG
Estás auditando una interfaz de usuario en busca de barreras de accesibilidad y corrigiéndolas. Los usuarios con discapacidad no pueden sortear una etiqueta faltante como lo haría un usuario vidente con ratón: trata cada hallazgo confirmado como un error real que bloquea a una persona real.
Objetivo: una lista de hallazgos verificados, cada uno vinculado a un criterio de éxito de WCAG 2.2, con una ubicación precisa, evidencia y una corrección mínima — y luego las correcciones, aplicadas y re-verificadas.
Principios
- Verificado o no se envía. Cada hallazgo debe sobrevivir la Fase 3. Una lista corta de problemas reales es mejor que una lista larga que el usuario aprende a ignorar.
- Primero HTML nativo. El mejor ARIA es ningún ARIA. Corrige
<div onClick>convirtiéndolo en un<button>, no añadiendorole,tabindexy manejadores de teclado. - Correcciones mínimas que preservan el comportamiento. Cambia el marcado que falla; no re-estiles, refactorices ni reformatees el código circundante. Mantén el diseño visual sin cambios a menos que el hallazgo sea visual (contraste, anillo de enfoque, tamaño de objetivo).
- Nunca inventes contenido. El texto alternativo, las etiquetas y el texto de los enlaces deben reflejar lo que la interfaz realmente significa. Si no puedes saber qué transmite una imagen, marca el hallazgo como
needs_validationy pregunta; no escribasalt="imagen". - La automatización es un piso, no un techo. Las herramientas detectan aproximadamente un tercio a la mitad de los fallos de WCAG. Reporta lo que no se probó (consulta la lista de verificación manual).
Configuración
Determina el alcance a partir de la solicitud del usuario: repositorio completo, un directorio, componentes específicos o una URL. Luego verifica las herramientas:
npx --yes @mintwork/wcag-audit-skill --version # ¿CLI disponible?
Si el CLI no está disponible (sin conexión, sin Node), continúa en modo manual: aplica la lista de reglas en references/RULES.md leyendo tú mismo el código fuente, y omite la Fase 2 a menos que el entorno del usuario ofrezca otra herramienta de navegador.
Escribe todos los artefactos en .wcag-audit/ en la raíz del repositorio (críalo; sugiere añadirlo a .gitignore, manteniendo .wcag-audit/baseline.json si el proyecto compromete una línea base de CI). Nunca escribas en otro lugar a menos que el usuario lo pida.
Flujo de trabajo
Ejecuta las fases en orden. Informa al usuario en qué fase te encuentras. Para alcances pequeños (un componente) las fases pueden ser breves, pero no omitas la Fase 3.
Fase 1 — Escaneo estático (código fuente)
npx @mintwork/wcag-audit-skill scan <ruta> --json -o .wcag-audit/static.json --fail-on none
Audita sin --baseline incluso si el proyecto compromete una (.wcag-audit/baseline.json): la línea base solo permite que CI ignore hallazgos conocidos, y aun así necesitan revisión.
Luego lee references/STATIC-SCAN.md y haz la revisión que la herramienta no puede: componentes personalizados que envuelven elementos nativos, renderizado condicional, props de sistemas de diseño (<Icon label=…>), estilos de enfoque eliminados en CSS-in-JS o reemplazados en otra hoja de estilos (el CLI revisa .css / .scss / .less y clases de Tailwind un archivo a la vez), estado solo por color, y cualquier cosa que el escáner haya saltado debido a props dinámicos o spread. Añádelos como hallazgos candidatos con "source": "static" y "confidence": "medium".
Fase 2 — Escaneo en tiempo de ejecución (navegador real)
Solo si hay una URL disponible o la aplicación se puede iniciar. Encuentra el comando de desarrollo (scripts de package.json, README), inícialo en segundo plano, espera a que responda, luego:
npx @mintwork/wcag-audit-skill scan http://localhost:3000 --source src --json -o .wcag-audit/runtime.json --fail-on none
# Más páginas / estados:
npx @mintwork/wcag-audit-skill scan http://localhost:3000/login http://localhost:3000/cart --json -o .wcag-audit/runtime-2.json --fail-on none
Escanea las páginas importantes (inicio, flujos principales, formularios, modales abiertos) — consulta references/RUNTIME-SCAN.md para estados a cubrir, esperas SPA y autenticación. Pon los estados (abrir un modal, enviar un formulario vacío, modo oscuro, 320px) en una configuración y ejecuta scan --config .wcag-audit/config.json; para páginas con inicio de sesión usa --storage-state <archivo> del usuario, nunca credenciales. Si el proyecto tiene Storybook, también ejecuta scan --storybook storybook-static (o la URL de Storybook en ejecución) para cubrir cada estado del componente. La sourceHint de cada hallazgo en tiempo de ejecución es un resultado de búsqueda: confírmalo antes de corregirlo allí. Los hallazgos en tiempo de ejecución detectan lo que el análisis estático no puede: contraste calculado, nombres accesibles reales, orden de enfoque, trampas de teclado, enfoque invisible.
Fase 3 — Verificación (eliminar falsos positivos)
Para cada candidato, sigue references/VERIFICATION.md. Intenta refutarlo: abre el código fuente en la línea reportada, rastrea props/slots/spreads hasta donde se establece el valor, verifica si un padre proporciona la etiqueta, comprueba el DOM renderizado para hallazgos en tiempo de ejecución. Asigna un veredicto:
confirmed— lo rastreaste y falla el criterio. Registra cómo lo sabes.needs_validation— plausible pero no pudiste establecerlo (ej. calidad del texto alternativo, contenido que no puedes ver, una página a la que no puedes acceder). No se aplica ninguna corrección.rejected— refutado. Registra por qué (esto enseña al usuario qué reglas ajustar).
Fusiona duplicados: la misma causa raíz reportada por el análisis estático y en tiempo de ejecución es un hallazgo con ambas ubicaciones.
Fase 4 — Corrección
Corrige los hallazgos confirmed, comenzando por la severidad más alta, usando references/FIX-PATTERNS.md. Para cada corrección:
- Haz el cambio más pequeño que cumpla con el criterio, en el lenguaje del framework (
htmlForen React,:aria-labelen Vue, etc.). - Explícalo en una o dos frases: qué estaba mal, a quién afectaba, qué cambió.
- Pregunta antes de correcciones que cambien la interfaz visual o el texto (colores de contraste, nuevas etiquetas visibles, texto de enlaces) a menos que el usuario ya haya dado luz verde.
Los hallazgos mecánicos (reparaciones de html-lang, meta-viewport-zoom, errores tipográficos de aria-attr-valid) pueden ser corregidos por el CLI: ejecuta scan <ruta> --dry-run, muestra al usuario el diff, luego scan <ruta> --fix. Un lang faltante solo se añade con --lang <código> una vez que sepas el idioma de la página.
Luego verifica mecánicamente:
npx @mintwork/wcag-audit-skill verify .wcag-audit/static.json
npx @mintwork/wcag-audit-skill verify .wcag-audit/runtime.json # servidor de desarrollo aún en ejecución
verify termina con código distinto de cero si algo permanece o una corrección introdujo un nuevo hallazgo. Itera hasta que los hallazgos confirmados estén resueltos o hayas explicado por qué no se puede corregir en código (ej. necesita contenido de subtítulos del usuario). Ejecuta las pruebas/lint del proyecto.
Fase 5 — Informe
Escribe .wcag-audit/findings.json conforme al esquema assets/report-schema.json y valídalo:
node <directorio-skill>/scripts/validate-findings.mjs .wcag-audit/findings.json
Luego escribe .wcag-audit/REPORT.md y dale al usuario un resumen breve, siguiendo references/REPORTING.md: recuentos por severidad y veredicto, qué se corrigió, qué necesita su aporte, qué no se probó.
Severidad
| Severidad | Significado | Ejemplos |
|---|---|---|
| crítico | Bloquea completamente una tarea para algunos usuarios | campo de formulario sin etiqueta, <div onClick> como única forma de enviar, trampa de teclado, zoom deshabilitado |
| grave | Dificultad importante o información faltante | texto de cuerpo con bajo contraste, idioma de página faltante, enlace sin nombre |
| moderado | Fricción, estructura confusa | niveles de encabezado saltados, texto de enlace redundante o vago en contexto |
| menor | Pulido, mejor práctica | texto alternativo vago, autofoco |
La severidad refleja el impacto en el usuario en esta interfaz, no el valor predeterminado de la regla: un cuadro de búsqueda sin etiqueta en un pie de página es menos grave que un campo de contraseña sin etiqueta en la página de inicio de sesión.
Antipatrones (no hacer)
- No añadas
aria-labelque duplique o contradiga el texto visible (rompe WCAG 2.5.3). - No añadas
role="button"+tabindex="0"cuando<button>funciona. - No "corrijas" un hallazgo de orden de encabezados cambiando el tamaño visual; cambia el nivel y mantén el CSS.
- No establezcas
alt=""en imágenes informativas para silenciar el escáner. - No suprimas hallazgos (
wcag-audit-ignore) sin una razón escrita junto al comentario. - No declares "cumplimiento" de WCAG — la revisión automatizada + de agente puede mostrar fallos, no conformidad.
- No modifiques código generado, dependencias o
node_modules; corrige el componente fuente.
Archivos
- references/RULES.md — cada regla estática y de tiempo de ejecución, mapeada a WCAG
- references/STATIC-SCAN.md — revisión manual de la Fase 1 por framework
- references/RUNTIME-SCAN.md — páginas, estados, SPAs, autenticación de la Fase 2
- references/VERIFICATION.md — procedimiento de refutación de la Fase 3 por regla
- references/FIX-PATTERNS.md — correcciones antes/después de la Fase 4
- references/REPORTING.md — formato de informe de la Fase 5
- references/MANUAL-CHECKLIST.md — lo que la automatización no puede verificar
- assets/report-schema.json — esquema de findings.json
scripts/validate-findings.mjs— validador sin dependencias para findings.json