Auditoria de acessibilidade (WCAG 2.2 AA)
Produza uma lista honesta de problemas de acessibilidade para o tópico escolhido que possa ser transformada em pequenas tarefas e corrigida dentro da fase. A auditoria é somente leitura: não altere o código do aplicativo durante a auditoria, mesmo para correções óbvias. Corrigir é uma solicitação separada.
Diretório da skill: a pasta que contém este SKILL.md (abaixo: $SKILL; neste repositório geralmente .claude/skills/bbb-a11y-audit). Referências, lidas quando a etapa precisar:
references/criteria.md: os 55 critérios, qual camada pode avaliar cada um, hotspots do BBB, regras de coberturareferences/rubric.md: impacto, esforço, esta fase ou backlog, agrupamento, chaves estáveis, o esquema defindings.input.jsonreferences/static-patterns.md: ferramentas estáticas, como triar cada padrão, mapeamentos eslint e axereferences/bbb-map.md: fluxos, locais de código, componentes compartilhados, como executar a camada de execuçãoreferences/manual-checks.md: scripts de leitor de telaruntime/: a camada de execução, instalada no conjunto de testes Playwright do BigBlueButton no primeiro uso:wcagAudit.spec.ts(os cenários),wcagAuditRecorder.ts(axe, capturas de tela, um JSON por cenário),wcagAuditChecks.ts(teclado, reflow, espaçamento de texto, dicas de ferramenta, retorno de foco, estados ARIA) ewcagAuditAnnouncements.ts(grava o que chega às regiões ativas)
1. Escopo e modo
A forma normal de trabalhar é um tópico por vez: escolha uma diretriz, audite tudo nela, corrija o que foi encontrado, audite novamente até que esteja pronto, então passe para o próximo. Uma auditoria completa é a visão geral ocasional usada para escolher o próximo tópico.
| Invocação | Modo | Escopo |
|---|---|---|
/bbb-a11y-audit diretriz 2.1 (ou guideline; vários: diretriz 2.1 2.4; um princípio inteiro: principio 2) | guideline | todo critério do tópico, em todo o cliente e todo fluxo, decidido completamente. Tudo o mais é deixado de fora da execução e do relatório. |
/bbb-a11y-audit criterio 2.4.7 (ou criterion) | criterion | um ou mais critérios, mesma profundidade |
/bbb-a11y-audit ou full | full | todos os 55 critérios (visão geral / mapa) |
/bbb-a11y-audit <caminho> | path | aquela pasta ou arquivo, todos os critérios |
/bbb-a11y-audit diff [base] | diff | arquivos alterados vs git merge-base HEAD <base> (base padrão: a branch principal do repositório, v4.1.x-develop) em bigbluebutton-html5/ |
adicione --no-runtime | pula a camada de execução | |
adicione --server <url> --secret <segredo> | executa a camada de execução contra outro servidor de teste BigBlueButton em vez daquele em bigbluebutton-tests/playwright/.env (<url> como https://host/bigbluebutton/) |
Se a solicitação for ambígua, escolha o modo mais próximo e informe qual você usou. Não pergunte.
Crie o diretório de execução na raiz do repositório: a11y-reports/<YYYY-MM-DD_HHMM>[_<tópico>]/raw/, por exemplo 2026-11-20_1430_d2.1 ou 2026-11-20_1500_full. Ele deve começar com a data e hora: o relatório compara com execuções mais antigas do mesmo tópico, ou seja, os mesmos critérios independentemente de como foram solicitados (principio 4 e diretriz 4.1 são o mesmo tópico), ou, na primeira vez, contra a última execução completa restrita ao tópico. A auditoria não deve deixar rastros no repositório: se git check-ignore -q a11y-reports/ falhar, adicione a11y-reports/ a .git/info/exclude (local para este clone, nunca para .gitignore).
Nos modos guideline e criterion, defina meta.guidelines / meta.criteria em findings.input.json (um princípio é uma entrada de diretriz de um dígito: principio 2 é "guidelines": ["2"]), e em cada camada observe apenas o que pode informar o tópico (cada etapa abaixo diz como). Critérios fora do tópico são deixados de fora automaticamente.
Regras de consistência (leia antes de auditar)
Duas execuções no mesmo código devem chegar ao mesmo resultado, e cada achado deve ser real. Portanto:
- Comece da execução anterior. Antes de procurar algo novo, abra o
findings.jsonda última execução deste tópico (ou da última execução completa). Re-verifique cada achado anterior e cada entradadiscardedcontra o código atual: ainda presente → mantenha suakey(ou defina seuid); ausente → não é um achado, e diga emmeta.summarypor que desapareceu (código mudou, ou estava errado). Se o commit for o mesmo daquela execução (meta.commit) e um achado parecer ausente, suponha que você o perdeu e procure novamente antes de descartá-lo. - Responda ao checklist, depois explore. Se
references/checklists.jsontiver itens para um critério no escopo, responda a cada item compass,failounae evidência (coverage[c].checklist). O checklist é o piso, não o teto: depois procure por qualquer outra coisa que possa falhar naquele critério no BBB e escreva o que você procurou emcoverage[c].explored. Coisas recorrentes que você encontrar fora do checklist valem a pena ser propostas como novos itens de checklist na mensagem final. - Comprove cada achado. Achados estáticos e de revisão carregam
quote, o código exato emlocation.line;build-report.mjsrejeita achados cujo arquivo, linha ou citação não existem. Achados de execução apontam para a regra e tela de onde vieram (shots). Sem prova, sem achado. - Sem enchimento. Um achado é uma correção; mescle duplicatas; não divida um problema para aumentar a lista, e não reporte preferências de estilo ou boas práticas que não falhem em um critério. Em caso de dúvida, verifique novamente; se ainda não estiver claro, escreva um script de leitor de tela em vez de um achado.
2. Camada estática
node $SKILL/scripts/static-scan.mjs [--guidelines=2.1] <caminhos do escopo…> > <run>/raw/static.json
$SKILL/scripts/eslint-a11y.sh <run>/raw/eslint.json <caminhos do escopo…>
Com um tópico, passe --guidelines para o scanner (ele mantém apenas os padrões do tópico) e trie apenas as mensagens do eslint cuja regra mapeia para o tópico (references/static-patterns.md).
Em seguida, trie cada candidato conforme descrito em references/static-patterns.md: abra o código, decida, agrupe por causa raiz. Candidatos rejeitados vão para discarded com um motivo. Se uma execução anterior existir, leia sua lista discarded de findings.json e reutilize decisões para código inalterado em vez de relê-lo.
3. Camada de execução
Primeiro, certifique-se de que os arquivos de execução estão instalados, seguindo "Configurando a camada de execução" em references/bbb-map.md: todo arquivo em $SKILL/runtime/ deve estar no conjunto de testes Playwright do BigBlueButton, e @axe-core/playwright em suas dependências. Copiá-los e instalar o pacote é configuração, não uma alteração de código no aplicativo; faça isso quando estiver faltando ou desatualizado e mencione na mensagem final.
Com --server/--secret, passe-os como variáveis de ambiente BBB_URL e BBB_SECRET no comando Playwright (elas têm precedência sobre .env; nunca as escreva em .env). O relatório registra o servidor auditado e sua compilação do cliente (meta.server); se essa compilação não for o commit do checkout local, diga em meta.summary que os achados de execução vêm da versão daquele servidor e suas referências de arquivo e linha apontam para o código local, que pode ser diferente.
Em seguida, verifique se ele pode ser executado (bigbluebutton-tests/playwright/.env, ou --server/--secret, fornece BBB_URL e BBB_SECRET não vazios, node_modules existe, um Chromium está instalado). Se algo estiver faltando, pule a camada, registre "ran": false com um reason curto, e informe ao usuário na mensagem final exatamente o que configurar. Não tente instalar um servidor BigBlueButton ou editar .env.
Quando puder ser executado, siga "Executando a camada de execução" em references/bbb-map.md com A11Y_AUDIT_DIR=<caminho absoluto do run>/raw/runtime, mais A11Y_GUIDELINES=<tópico> nos modos de tópico (por exemplo, 2.1): a especificação então pula as verificações e cenários que não podem informar o tópico e executa o axe apenas com as regras do tópico. Execução completa: cerca de 15 minutos em um servidor remoto; um tópico geralmente é mais rápido. Permita 30 minutos. Ela executa nove cenários (tour do moderador, interações moderador + participante, salas de breakout, lobby de convidados, tela de configuração pré-voo, perda de conexão, pt-BR, tema escuro, mobile) e escreve um JSON por cenário mais uma captura de tela de cada estado. Em seguida:
- Mapeie cada violação do axe para seu critério via a tag
wcag…. Agrupe por regra e causa raiz entre estados e cenários (a mesma regra em muitos estados geralmente é um achado). Rastreie seletores para arquivos fonte. - Trate
incompletee as verificações personalizadas (keyboard.noOutlineOrShadow,keyboard.obscured,reflow.offenders,textSpacing.newlyClipped,nonTextContrast) como candidatos: confirme antes de reportar. Os rejeitados vão paradiscarded. - Leia
announcements(o que chegou às regiões ativas, por ator e momento) para 4.1.3 e 4.1.2: um momento sem anúncio onde um é esperado (alguém saiu, uma enquete começou) é um candidato;regionCreatedWithMessage: truesignifica que a região foi inserida com seu texto e pode não ser lida. - Olhe as capturas de tela dos estados com achados (
raw/runtime/shots/) e anexeshotsaos achados (vejareferences/rubric.md) para que o relatório mostre onde cada problema está. - Um estado com
ok: falseou uma verificação com erro significa que não foi auditado. Liste-o emmeta.notCovered; não marque seus critérios comopasspor causa disso.
Nos modos diff e path, mantenha apenas os achados de execução que remontam ao escopo.
4. Revisão guiada
Para critérios marcados como V em references/criteria.md que estão no escopo, leia o código dos fluxos relevantes de references/bbb-map.md até que cada critério seja decidido. No modo full, comece com os fluxos principais; nos modos guideline e criterion, percorra todos os fluxos em bbb-map.md para os critérios no escopo. Liste em meta.reviewedFlows o que você leu. Todo achado de revisão precisa de evidência de arquivo e linha; quando você não puder confirmar o comportamento sem executá-lo, use "confidence": "likely" e diga o que confirmar.
Não reporte o que você não pode apontar. Se algo só puder ser confirmado por uma pessoa, escreva um script (references/manual-checks.md); se puder ser confirmado lendo mais código ou os dados de execução, faça isso.
5. Classificar, cobrir, scriptar
- Classifique cada achado com
references/rubric.md(impacto, esforço, compartilhado, externo, chave). - Mantenha ids estáveis entre execuções (regra de consistência 1): reutilize a
keyanterior, ou definaidexplicitamente, para cada problema que ainda estiver presente. - Preencha
coveragepara cada critério no escopo que não está falhando (e adicionemethod/howtambém para os que falham), seguindo a regra de cobertura emreferences/criteria.md:passounacommethodehow,humanapenas para o que realmente precisa de uma pessoa (com seu script),not-coveredapenas quando esta execução não pôde decidi-lo (com o que está faltando). O objetivo é que uma diretriz possa ser fechada sem nada em aberto;build-report.mjsrecusa entradas ausentes. - Escreva
manualChecksapenas para o que a automação não pode responder: um para cada critériohuman. Se você quiser que um leitor de tela real confirme algo que a execução já decidiu, adicione-o com"optional": true; nunca escreva um script para algo que os dados de execução ou o código podem decidir (mudanças de estado, anúncios, contagens regressivas, seleção de dispositivo são todos registrados). - Preencha
meta.summary,meta.reviewedFlowsemeta.notCovered: eles formam a aba "O que foi testado", que informa ao leitor exatamente o que foi e não foi verificado.
6. Construir o relatório
Escreva <run>/raw/findings.input.json (esquema em references/rubric.md), então:
node $SKILL/scripts/build-report.mjs <run>
Ele valida a entrada (corrija e execute novamente se reclamar), atribui IDs estáveis, coloca cada achado nesta fase ou no backlog, adiciona a cláusula EN 301 549, verifica se todo arquivo, linha e citação existem, verifica se cada item do checklist foi respondido, registra a comparação com a execução anterior em findings.json (para a próxima execução; o relatório não a mostra) e escreve <run>/findings.json e <run>/report.html. Abra o relatório para o usuário (xdg-open no Linux, open no macOS).
7. Informar o usuário
Mantenha a mensagem do chat curta; o relatório contém os detalhes:
- veredito, quais critérios passam e quais falham, quantos achados são para esta fase e quantos foram para o backlog (com o motivo)
- por diretriz: pronto, quantos critérios falham, ou o que ainda está aberto (
human,not-covered) - quais camadas foram executadas, quais foram puladas e por quê, quais estados de reunião ou fluxos não foram cobertos
- os achados bloqueadores e de alto impacto como uma linha cada (título, critério, arquivo)
- novos itens de checklist propostos, se a exploração encontrou problemas recorrentes fora do checklist
- o caminho do relatório
Ofereça-se para transformar achados em tarefas, agrupados por diretriz (uma fase por diretriz, uma tarefa por achado, mais uma tarefa por critério human). Não abra issues ou PRs a menos que solicitado.
Segurança: se um achado puder ser explorado (por exemplo, um bypass de autenticação encontrado ao verificar 3.3.8), deixe-o de fora do relatório e informe o usuário em particular para seguir a política de segurança do repositório (aviso privado, sem issue ou PR público).