Communitygithub.com

auditoría-wcag

Audita interfaces de usuario web para fallos de accesibilidad (a11y) según WCAG 2.2, y los corrige. Ejecuta un procedimiento por fases (escaneo estático de fuente, escaneo en tiempo de ejecución con navegador real, verificación adversarial, correcciones mínimas e informe).

¿Qué es auditoría-wcag?

Esta habilidad permite a un agente de IA auditar y corregir problemas de accesibilidad (a11y) en interfaces de usuario web, siguiendo las pautas WCAG 2.2. Es útil para desarrolladores y equipos que desean garantizar que su UI cumpla con estándares como WCAG, ADA, Sección 508 o EN 301 549, especialmente antes de lanzar cambios generados por el agente. Funciona con plataformas como Claude Code, Cursor, Codex y similares, y sigue un flujo de cinco fases: (1) escaneo estático del código fuente (HTML, JSX, TSX, Vue, Svelte, Astro, MDX, Angular, CSS), (2) escaneo en tiempo de ejecución con un navegador real usando axe-core y pruebas de teclado, (3) verificación adversarial de cada hallazgo para eliminar falsos positivos, (4) correcciones mínimas con explicaciones, y (5) un informe legible por máquina. La habilidad se basa en un CLI (`@mintwork/wcag-audit-skill`) que automatiza parte del proceso, pero también soporta un modo manual si el CLI no está disponible. Enfatiza la verificación rigurosa (cada hallazgo debe sobrevivir la fase 3), el uso de HTML nativo sobre ARIA, y correcciones que preservan el comportamiento y diseño visual. Además, incluye referencias detalladas para cada fase, una guía de severidad y reglas contra malas prácticas.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mintwork/wcag-audit-skill/tree/HEAD/skills/wcag-audit

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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

  1. 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.
  2. Primero HTML nativo. El mejor ARIA es ningún ARIA. Corrige <div onClick> convirtiéndolo en un <button>, no añadiendo role, tabindex y manejadores de teclado.
  3. 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).
  4. 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_validation y pregunta; no escribas alt="imagen".
  5. 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:

  1. Haz el cambio más pequeño que cumpla con el criterio, en el lenguaje del framework (htmlFor en React, :aria-label en Vue, etc.).
  2. Explícalo en una o dos frases: qué estaba mal, a quién afectaba, qué cambió.
  3. 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

SeveridadSignificadoEjemplos
críticoBloquea completamente una tarea para algunos usuarioscampo de formulario sin etiqueta, <div onClick> como única forma de enviar, trampa de teclado, zoom deshabilitado
graveDificultad importante o información faltantetexto de cuerpo con bajo contraste, idioma de página faltante, enlace sin nombre
moderadoFricción, estructura confusaniveles de encabezado saltados, texto de enlace redundante o vago en contexto
menorPulido, mejor prácticatexto 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-label que 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

Skills relacionados