Auditoría de accesibilidad (WCAG 2.2 AA)
Produce una lista honesta de problemas de accesibilidad para el tema elegido que se puedan convertir en tareas pequeñas y corregir dentro de la fase. La auditoría es de solo lectura: no modifiques el código de la aplicación mientras auditas, ni siquiera para correcciones obvias. La corrección es una solicitud aparte.
Directorio de la skill: la carpeta que contiene este SKILL.md (abajo: $SKILL; en este repositorio normalmente .claude/skills/bbb-a11y-audit). Referencias, léelas cuando el paso las necesite:
references/criteria.md: los 55 criterios, qué capa puede evaluar cada uno, puntos críticos de BBB, reglas de coberturareferences/rubric.md: impacto, esfuerzo, esta fase o backlog, agrupación, claves estables, el esquema defindings.input.jsonreferences/static-patterns.md: herramientas estáticas, cómo clasificar cada patrón, mapeos de eslint y axereferences/bbb-map.md: flujos, ubicaciones de código, componentes compartidos, cómo ejecutar la capa runtimereferences/manual-checks.md: scripts de lector de pantallaruntime/: la capa runtime, instalada en la suite de Playwright de BigBlueButton en el primer uso:wcagAudit.spec.ts(los escenarios),wcagAuditRecorder.ts(axe, capturas de pantalla, un JSON por escenario),wcagAuditChecks.ts(teclado, reflujo, espaciado de texto, tooltips, retorno de foco, estados ARIA) ywcagAuditAnnouncements.ts(registra lo que llega a las regiones en vivo)
1. Alcance y modo
La forma normal de trabajar es un tema a la vez: elige una pauta, audita todo lo que contiene, corrige lo que se encuentre, audítala de nuevo hasta que esté lista, luego pasa a la siguiente. Una auditoría completa es la visión general ocasional que se usa para elegir el siguiente tema.
| Invocación | Modo | Alcance |
|---|---|---|
/bbb-a11y-audit diretriz 2.1 (o guideline; varios: diretriz 2.1 2.4; un principio completo: principio 2) | guideline | cada criterio del tema, en todo el cliente y cada flujo, decidido por completo. Todo lo demás queda fuera de la ejecución y del informe. |
/bbb-a11y-audit criterio 2.4.7 (o criterion) | criterion | uno o más criterios, misma profundidad |
/bbb-a11y-audit o full | full | los 55 criterios (visión general / mapa) |
/bbb-a11y-audit <ruta> | path | esa carpeta o archivo, todos los criterios |
/bbb-a11y-audit diff [base] | diff | archivos modificados vs git merge-base HEAD <base> (base por defecto: la rama principal del repositorio, v4.1.x-develop) bajo bigbluebutton-html5/ |
añade --no-runtime | omite la capa runtime | |
añade --server <url> --secret <secret> | ejecuta la capa runtime contra otro servidor de prueba de BigBlueButton en lugar del que está en bigbluebutton-tests/playwright/.env (<url> como https://host/bigbluebutton/) |
Si la solicitud es ambigua, elige el modo más cercano y di cuál usaste. No preguntes.
Crea el directorio de ejecución en la raíz del repositorio: a11y-reports/<YYYY-MM-DD_HHMM>[_<tema>]/raw/, por ejemplo 2026-11-20_1430_d2.1 o 2026-11-20_1500_full. Debe comenzar con la fecha y la hora: el informe se compara con ejecuciones anteriores del mismo tema, es decir, los mismos criterios independientemente de cómo se hayan solicitado (principio 4 y diretriz 4.1 son el mismo tema), o, la primera vez, contra la última ejecución completa restringida al tema. La auditoría no debe dejar rastro en el repositorio: si git check-ignore -q a11y-reports/ falla, añade a11y-reports/ a .git/info/exclude (local a este clon, nunca a .gitignore).
En los modos guideline y criterion, establece meta.guidelines / meta.criteria en findings.input.json (un principio es una entrada de pauta de un solo dígito: principio 2 es "guidelines": ["2"]), y en cada capa mira solo lo que puede informar al tema (cada paso a continuación dice cómo). Los criterios fuera del tema se omiten automáticamente.
Reglas de consistencia (léelas antes de auditar)
Dos ejecuciones sobre el mismo código deben llegar al mismo resultado, y cada hallazgo debe ser real. Por lo tanto:
- Empieza desde la ejecución anterior. Antes de buscar algo nuevo, abre el
findings.jsonde la última ejecución de este tema (o la última ejecución completa). Vuelve a verificar cada hallazgo anterior y cada entradadiscardedcontra el código actual: ¿todavía presente? → conserva sukey(o establece suid); ¿desaparecido? → no es un hallazgo, y di enmeta.summarypor qué desapareció (código cambiado, o era incorrecto). Si el commit es el mismo que el de esa ejecución (meta.commit) y un hallazgo parece desaparecido, asume que lo pasaste por alto y vuelve a buscarlo antes de descartarlo. - Responde la lista de verificación, luego explora. Si
references/checklists.jsontiene elementos para un criterio dentro del alcance, responde cada elemento conpass,failonay evidencia (coverage[c].checklist). La lista de verificación es el piso, no el techo: luego busca cualquier otra cosa que pueda fallar ese criterio en BBB y escribe lo que buscaste encoverage[c].explored. Las cosas recurrentes que encuentres fuera de la lista de verificación merecen proponerse como nuevos elementos de la lista en el mensaje final. - Prueba cada hallazgo. Los hallazgos estáticos y de revisión llevan
quote, el código exacto enlocation.line;build-report.mjsrechaza hallazgos cuyo archivo, línea o cita no existan. Los hallazgos de runtime apuntan a la regla y la pantalla de donde provienen (shots). Sin prueba, no hay hallazgo. - Sin relleno. Un hallazgo es una corrección; fusiona duplicados; no dividas un problema para hacer la lista más larga, y no reportes preferencias de estilo o mejores prácticas que no fallen un criterio. Ante la duda, verifica de nuevo; si aún no está claro, escribe un script de lector de pantalla en lugar de un hallazgo.
2. Capa estática
node $SKILL/scripts/static-scan.mjs [--guidelines=2.1] <rutas de alcance…> > <ejecucion>/raw/static.json
$SKILL/scripts/eslint-a11y.sh <ejecucion>/raw/eslint.json <rutas de alcance…>
Con un tema, pasa --guidelines al escaneo (conserva solo los patrones del tema) y clasifica solo los mensajes de eslint cuya regla se asigna al tema (references/static-patterns.md).
Luego clasifica cada candidato como se describe en references/static-patterns.md: abre el código, decide, agrupa por causa raíz. Los candidatos rechazados van a discarded con un motivo. Si existe una ejecución anterior, lee su lista discarded de findings.json y reutiliza las decisiones para el código no modificado en lugar de volver a leerlo.
3. Capa runtime
Primero asegúrate de que los archivos runtime estén instalados, siguiendo "Configuración de la capa runtime" en references/bbb-map.md: cada archivo en $SKILL/runtime/ debe estar en la suite de Playwright de BigBlueButton, y @axe-core/playwright en sus dependencias. Copiarlos e instalar el paquete es configuración, no un cambio de código en la aplicación; hazlo cuando falten o estén desactualizados y menciónalo en el mensaje final.
Con --server/--secret, pásalos como variables de entorno BBB_URL y BBB_SECRET en el comando de Playwright (tienen prioridad sobre .env; nunca los escribas en .env). El informe registra el servidor auditado y su compilación del cliente (meta.server); si esa compilación no coincide con el commit del checkout local, di en meta.summary que los hallazgos de runtime provienen de la versión de ese servidor y sus referencias de archivo y línea apuntan al código local, que puede diferir.
Luego verifica si puede ejecutarse (bigbluebutton-tests/playwright/.env, o --server/--secret, proporciona BBB_URL y BBB_SECRET no vacíos, node_modules existe, Chromium está instalado). Si falta algo, omite la capa, registra "ran": false con un breve reason, e indica al usuario en el mensaje final exactamente qué configurar. No intentes instalar un servidor BigBlueButton ni editar .env.
Cuando pueda ejecutarse, sigue "Ejecución de la capa runtime" en references/bbb-map.md con A11Y_AUDIT_DIR=<directorio de ejec absoluto>/raw/runtime, más A11Y_GUIDELINES=<tema> en modos de tema (ej. 2.1): la especificación luego omite las comprobaciones y escenarios que no pueden informar al tema y ejecuta axe solo con las reglas del tema. Ejecución completa: unos 15 minutos en un servidor remoto; un tema suele ser más rápido. Permite 30 minutos. Ejecuta nueve escenarios (recorrido del moderador, interacciones moderador + asistente, salas de reuniones, lobby de invitados, pantalla de configuración previa al vuelo, conexión perdida, pt-BR, tema oscuro, móvil) y escribe un JSON por escenario más una captura de pantalla de cada estado. Luego:
- Asigna cada violación de axe a su criterio a través de la etiqueta
wcag…. Agrupa por regla y causa raíz entre estados y escenarios (la misma regla en muchos estados suele ser un solo hallazgo). Traza los selectores a los archivos fuente. - Trata
incompletey las comprobaciones personalizadas (keyboard.noOutlineOrShadow,keyboard.obscured,reflow.offenders,textSpacing.newlyClipped,nonTextContrast) como candidatos: confírmalos antes de reportarlos. Los rechazados van adiscarded. - Lee
announcements(lo que llegó a las regiones en vivo, por actor y momento) para 4.1.3 y 4.1.2: un momento sin anuncio cuando se espera uno (alguien se fue, comenzó una encuesta) es un candidato;regionCreatedWithMessage: truesignifica que la región se insertó con su texto y puede que no se lea. - Mira las capturas de pantalla de los estados con hallazgos (
raw/runtime/shots/), y adjuntashotsa los hallazgos (verreferences/rubric.md) para que el informe muestre dónde está cada problema. - Un estado con
ok: falseo una comprobación con un error significa que no fue auditado. Enuméralo bajometa.notCovered; no marques sus criterios comopassdebido a ello.
En los modos diff y path, conserva solo los hallazgos de runtime que se remontan al alcance.
4. Revisión guiada
Para los criterios marcados como V en references/criteria.md que estén dentro del alcance, lee el código de los flujos relevantes de references/bbb-map.md hasta que cada criterio esté decidido. En modo full comienza con los flujos principales; en modos guideline y criterion recorre cada flujo en bbb-map.md para los criterios dentro del alcance. Enumera en meta.reviewedFlows lo que leíste. Cada hallazgo de revisión necesita evidencia de archivo y línea; cuando no puedas confirmar el comportamiento sin ejecutarlo, usa "confidence": "likely" y di qué confirmar.
No reportes lo que no puedas señalar. Si algo solo puede ser confirmado por una persona, escribe un script (references/manual-checks.md); si se puede confirmar leyendo más código o los datos de runtime, haz eso en su lugar.
5. Clasifica, cubre, escribe scripts
- Clasifica cada hallazgo con
references/rubric.md(impacto, esfuerzo, compartido, externo, clave). - Mantén los ids estables entre ejecuciones (regla de consistencia 1): reutiliza la
keyanterior, o estableceidexplícitamente, para cada problema que aún exista. - Completa
coveragepara cada criterio dentro del alcance que no esté fallando (y añademethod/howtambién para los que fallan), siguiendo la regla de cobertura enreferences/criteria.md:passonaconmethodyhow,humansolo para lo que realmente necesita una persona (con su script),not-coveredsolo cuando esta ejecución no pudo decidirlo (con lo que falta). El objetivo es que una pauta pueda cerrarse sin dejar nada abierto;build-report.mjsrechaza entradas faltantes. - Escribe
manualCheckssolo para lo que la automatización no puede responder: uno por cada criteriohuman. Si quieres que un lector de pantalla real confirme algo que el runtime ya decidió, agrégalo con"optional": true; nunca escribas un script para algo que los datos de runtime o el código pueden decidir (cambios de estado, anuncios, cuentas atrás, selección de dispositivos están todos registrados). - Completa
meta.summary,meta.reviewedFlowsymeta.notCovered: forman la pestaña "O que foi testado", que le dice al lector exactamente qué se verificó y qué no.
6. Construye el informe
Escribe <ejecucion>/raw/findings.input.json (esquema en references/rubric.md), luego:
node $SKILL/scripts/build-report.mjs <ejecucion>
Valida la entrada (corrige y vuelve a ejecutar si se queja), asigna IDs estables, coloca cada hallazgo en esta fase o en backlog, añade la cláusula EN 301 549, verifica que cada archivo, línea y cita existan, verifica que cada elemento de la lista de verificación esté respondido, registra la comparación con la ejecución anterior en findings.json (para la próxima ejecución; el informe no la muestra) y escribe <ejecucion>/findings.json y <ejecucion>/report.html. Abre el informe para el usuario (xdg-open en Linux, open en macOS).
7. Informa al usuario
Mantén el mensaje de chat breve; el informe contiene los detalles:
- veredicto, qué criterios pasan y cuáles fallan, cuántos hallazgos son para esta fase y cuántos fueron a backlog (con el motivo)
- por pauta: hecho, cuántos criterios fallan, o qué sigue abierto (
human,not-covered) - qué capas se ejecutaron, cuáles se saltaron y por qué, qué estados de reunión o flujos no se cubrieron
- el bloqueador y los hallazgos de alto impacto como una línea cada uno (título, criterio, archivo)
- nuevos elementos de lista de verificación propuestos, si la exploración encontró problemas recurrentes fuera de la lista
- la ruta del informe
Ofrece convertir los hallazgos en tareas, agrupadas por pauta (una fase por pauta, una tarea por hallazgo, más una tarea por criterio human). No abras issues ni PRs a menos que te lo pidan.
Seguridad: si un hallazgo pudiera ser explotado (por ejemplo, una omisión de autenticación encontrada al verificar 3.3.8), déjalo fuera del informe e informa al usuario de forma privada para que siga la política de seguridad del repositorio (aviso privado, sin issue ni PR público).