bbb-a11y-audit

Audita o cliente HTML5 do BigBlueButton contra WCAG 2.2 nível A e AA (EN 301 549 cláusula 9), um tópico por vez (diretriz, princípio ou critério) ou o cliente inteiro, e produz um relatório HTML organizado por princípio, diretriz e critério, onde cada critério termina como falha, aprovado ou não aplicável, com evidências, capturas de tela anotadas, correções e prioridades. Combina uma varredura estática, uma execução axe-core/Playwright contra uma reunião ativa e uma revisão de código guiada, e compara com a execução anterior do mesmo tópico. Use quando o usuário pedir uma auditoria de acessibilidade ou WCAG, para auditar uma diretriz ou critério, para um relatório de a11y, ou para verificar um componente ou branch quanto a regressões de acessibilidade.

O que é bbb-a11y-audit?

Esta skill automatiza a auditoria de acessibilidade do cliente HTML5 do BigBlueButton, seguindo os critérios WCAG 2.2 nível A e AA (EN 301 549 cláusula 9). O objetivo é produzir uma lista honesta de problemas de acessibilidade para um tópico específico (diretriz, princípio, critério) ou para todo o cliente, que possa ser transformada em tarefas pequenas e corrigida dentro da fase. A auditoria é somente leitura: não altera o código do aplicativo. A skill opera em vários modos: `guideline` (audita todos os critérios de uma diretriz), `criterion` (um ou mais critérios específicos), `full` (todos os 55 critérios), `path` (audita arquivos/pastas específicos) e `diff` (apenas arquivos alterados em relação a uma branch base). Ela combina três camadas de verificação: - **Camada estática**: executa um scanner de padrões e eslint com regras de acessibilidade para o tópico. - **Camada de execução (runtime)**: usa Playwright + axe-core contra uma reunião ativa do BigBlueButton, executando 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 produzindo capturas de tela e JSONs de violações. - **Revisão guiada**: para critérios marcados como 'V', o código-fonte dos fluxos relevantes é lido até que cada critério seja decidido. Os resultados são consolidados em um relatório HTML detalhado, organizado por princípio, diretriz e critério. Cada critério termina como 'pass' (aprovado), 'fail' (falha) ou 'na' (não aplicável), com evidências (citações de código, capturas de tela anotadas) e prioridades (impacto, esforço). A skill também garante consistência entre execuções: começa sempre a partir do relatório anterior para evitar duplicação e perda de achados. É ideal para desenvolvedores e equipes de QA que precisam garantir conformidade com WCAG 2.2 AA no BigBlueButton.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/gugeldev/bbb-a11y-audit/tree/main/bbb-a11y-audit

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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 cobertura
  • references/rubric.md: impacto, esforço, esta fase ou backlog, agrupamento, chaves estáveis, o esquema de findings.input.json
  • references/static-patterns.md: ferramentas estáticas, como triar cada padrão, mapeamentos eslint e axe
  • references/bbb-map.md: fluxos, locais de código, componentes compartilhados, como executar a camada de execução
  • references/manual-checks.md: scripts de leitor de tela
  • runtime/: 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) e wcagAuditAnnouncements.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çãoModoEscopo
/bbb-a11y-audit diretriz 2.1 (ou guideline; vários: diretriz 2.1 2.4; um princípio inteiro: principio 2)guidelinetodo 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)criterionum ou mais critérios, mesma profundidade
/bbb-a11y-audit ou fullfulltodos os 55 critérios (visão geral / mapa)
/bbb-a11y-audit <caminho>pathaquela pasta ou arquivo, todos os critérios
/bbb-a11y-audit diff [base]diffarquivos 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-runtimepula 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:

  1. Comece da execução anterior. Antes de procurar algo novo, abra o findings.json da última execução deste tópico (ou da última execução completa). Re-verifique cada achado anterior e cada entrada discarded contra o código atual: ainda presente → mantenha sua key (ou defina seu id); ausente → não é um achado, e diga em meta.summary por 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.
  2. Responda ao checklist, depois explore. Se references/checklists.json tiver itens para um critério no escopo, responda a cada item com pass, fail ou na e 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 em coverage[c].explored. Coisas recorrentes que você encontrar fora do checklist valem a pena ser propostas como novos itens de checklist na mensagem final.
  3. Comprove cada achado. Achados estáticos e de revisão carregam quote, o código exato em location.line; build-report.mjs rejeita 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.
  4. 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 incomplete e as verificações personalizadas (keyboard.noOutlineOrShadow, keyboard.obscured, reflow.offenders, textSpacing.newlyClipped, nonTextContrast) como candidatos: confirme antes de reportar. Os rejeitados vão para discarded.
  • 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: true significa 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 anexe shots aos achados (veja references/rubric.md) para que o relatório mostre onde cada problema está.
  • Um estado com ok: false ou uma verificação com erro significa que não foi auditado. Liste-o em meta.notCovered; não marque seus critérios como pass por 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 key anterior, ou defina id explicitamente, para cada problema que ainda estiver presente.
  • Preencha coverage para cada critério no escopo que não está falhando (e adicione method/how também para os que falham), seguindo a regra de cobertura em references/criteria.md: pass ou na com method e how, human apenas para o que realmente precisa de uma pessoa (com seu script), not-covered apenas 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.mjs recusa entradas ausentes.
  • Escreva manualChecks apenas para o que a automação não pode responder: um para cada critério human. 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.reviewedFlows e meta.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).

Habilidades Relacionadas