Auditoria WCAG
Você está auditando uma interface de usuário para barreiras de acessibilidade e corrigindo-as. Usuários com deficiência não conseguem contornar a falta de um rótulo da mesma forma que um usuário de mouse com visão normal: trate cada achado confirmado como um bug real que bloqueia uma pessoa real.
Objetivo: uma lista de achados verificados, cada um vinculado a um critério de sucesso da WCAG 2.2, com localização precisa, evidências e uma correção mínima — e então as correções, aplicadas e re-verificadas.
Princípios
- Verificado ou não é enviado. Cada achado deve sobreviver à Fase 3. Uma lista curta de problemas verdadeiros é melhor do que uma lista longa que o usuário aprende a ignorar.
- HTML nativo primeiro. O melhor ARIA é nenhum ARIA. Corrija
<div onClick>transformando-o em um<button>, e não adicionandorole,tabindexe manipuladores de teclado. - Correções mínimas e que preservam o comportamento. Altere a marcação que falha; não reestilize, refatore ou reformate o código ao redor. Mantenha o design visual inalterado, a menos que o achado seja visual (contraste, anel de foco, tamanho do alvo).
- Nunca invente conteúdo. Texto alternativo, rótulos e texto do link devem refletir o que a interface realmente significa. Se você não puder dizer o que uma imagem transmite, marque o achado como
needs_validatione pergunte; não escrevaalt="image". - Automação é um piso, não um teto. Ferramentas detectam aproximadamente um terço a metade das falhas da WCAG. Relate o que não foi testado (veja a lista de verificação manual).
Configuração
Decida o escopo a partir da solicitação do usuário: repositório inteiro, um diretório, componentes específicos ou uma URL. Em seguida, verifique as ferramentas:
npx --yes @mintwork/wcag-audit-skill --version # CLI disponível?
Se a CLI não estiver disponível (offline, sem Node), continue no modo manual: aplique a lista de regras em references/RULES.md lendo o código-fonte você mesmo e pule a Fase 2, a menos que o ambiente do usuário ofereça outra ferramenta de navegador.
Escreva todos os artefatos em .wcag-audit/ na raiz do repositório (crie-o; sugira adicioná-lo ao .gitignore, mantendo .wcag-audit/baseline.json se o projeto confirmar uma linha de base de CI). Nunca escreva em outro lugar, a menos que o usuário solicite.
Fluxo de Trabalho
Execute as fases em ordem. Informe ao usuário em qual fase você está. Para escopos pequenos (um componente), as fases podem ser breves, mas não pule a Fase 3.
Fase 1 — Varredura estática (código-fonte)
npx @mintwork/wcag-audit-skill scan <caminho> --json -o .wcag-audit/static.json --fail-on none
Audite sem --baseline mesmo que o projeto confirme uma linha de base (.wcag-audit/baseline.json): a linha de base apenas permite que a CI ignore achados conhecidos, e eles ainda precisam de revisão.
Em seguida, leia references/STATIC-SCAN.md e faça a revisão que a ferramenta não consegue: componentes personalizados que encapsulam elementos nativos, renderização condicional, props de design system (<Icon label=…>), estilos de foco removidos em CSS-in-JS ou substituídos em outra folha de estilo (a CLI verifica arquivos .css / .scss / .less e classes Tailwind um arquivo por vez), estado baseado apenas em cor e qualquer coisa que o scanner pulou devido a props spread ou valores dinâmicos. Adicione-os como achados candidatos com "source": "static" e "confidence": "medium".
Fase 2 — Varredura em tempo real (navegador real)
Somente se uma URL estiver disponível ou o aplicativo puder ser iniciado. Encontre o comando de desenvolvimento (scripts package.json, README), inicie-o em segundo plano, aguarde a resposta e então:
npx @mintwork/wcag-audit-skill scan http://localhost:3000 --source src --json -o .wcag-audit/runtime.json --fail-on none
# Mais 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
Varra as páginas importantes (início, fluxos principais, formulários, modais abertos) — veja references/RUNTIME-SCAN.md para estados a cobrir, esperas de SPA e autenticação. Coloque estados (abrir um modal, enviar um formulário vazio, modo escuro, 320px) em uma configuração e execute scan --config .wcag-audit/config.json; para páginas logadas, use --storage-state <arquivo> do usuário, nunca credenciais. Se o projeto tiver Storybook, execute também scan --storybook storybook-static (ou a URL do Storybook em execução) para cobrir todos os estados dos componentes. O sourceHint de cada achado de tempo real é um resultado de pesquisa: confirme-o antes de corrigir lá. Achados de tempo real detectam o que a análise estática não consegue: contraste computado, nomes acessíveis reais, ordem de foco, armadilhas de teclado, foco invisível.
Fase 3 — Verificação (remover falsos positivos)
Para cada candidato, siga references/VERIFICATION.md. Tente refutá-lo: abra o código-fonte na linha relatada, rastreie props/slots/spreads até onde o valor é definido, verifique se um pai fornece o rótulo, verifique o DOM renderizado para achados de tempo real. Atribua um veredito:
confirmed— você rastreou e ele falha no critério. Registre como você sabe.needs_validation— plausível, mas você não conseguiu estabelecê-lo (por exemplo, qualidade do texto alternativo, conteúdo que você não pode ver, uma página que você não pode alcançar). Nenhuma correção é aplicada.rejected— refutado. Registre por que (isso ensina ao usuário quais regras ajustar).
Mescle duplicatas: a mesma causa raiz relatada por varredura estática e de tempo real é um achado com ambos os locais.
Fase 4 — Correção
Corrija achados confirmed, começando pela severidade mais alta, usando references/FIX-PATTERNS.md. Para cada correção:
- Faça a menor alteração que satisfaça o critério, no idioma do framework (
htmlForno React,:aria-labelno Vue, etc.). - Explique em uma ou duas frases: o que estava errado, quem afetou, o que mudou.
- Pergunte antes de correções que alterem a interface visual ou cópia (cores de contraste, novos rótulos visíveis, texto do link), a menos que o usuário já tenha autorizado.
Achados mecânicos (reparos de html-lang, meta-viewport-zoom, erros de digitação aria-attr-valid) podem ser corrigidos pela CLI: execute scan <caminho> --dry-run, mostre ao usuário o diff, depois scan <caminho> --fix. Um lang ausente é adicionado apenas com --lang <código> depois que você souber o idioma da página.
Em seguida, re-verifique mecanicamente:
npx @mintwork/wcag-audit-skill verify .wcag-audit/static.json
npx @mintwork/wcag-audit-skill verify .wcag-audit/runtime.json # servidor de desenvolvimento ainda em execução
verify sai com código diferente de zero se algo permanecer ou se uma correção introduziu um novo achado. Itere até que os achados confirmados sejam resolvidos ou você tenha explicado por que um não pode ser corrigido em código (por exemplo, precisa de conteúdo de legendas do usuário). Execute os próprios testes/lint do projeto.
Fase 5 — Relatório
Escreva .wcag-audit/findings.json em conformidade com assets/report-schema.json e valide-o:
node <skill-dir>/scripts/validate-findings.mjs .wcag-audit/findings.json
Em seguida, escreva .wcag-audit/REPORT.md e dê ao usuário um breve resumo, seguindo references/REPORTING.md: contagens por severidade e veredito, o que foi corrigido, o que precisa da contribuição deles, o que não foi testado.
Severidade
| Severidade | Significado | Exemplos |
|---|---|---|
| crítica | Bloqueia completamente uma tarefa para alguns usuários | campo de formulário sem rótulo, <div onClick> como única forma de enviar, armadilha de teclado, zoom desabilitado |
| grave | Dificuldade maior ou informação faltando | texto de corpo com baixo contraste, idioma da página ausente, link sem nome |
| moderada | Atrito, estrutura confusa | níveis de cabeçalho pulados, texto de link redundante ou vago no contexto |
| menor | Polimento, boa prática | texto alternativo vago, autofoco |
A severidade reflete o impacto no usuário nesta interface, não o padrão da regra: uma caixa de pesquisa sem rótulo no rodapé é menos grave do que um campo de senha sem rótulo na página de login.
Antipadrões (não faça)
- Não adicione
aria-labelque duplica ou contradiz o texto visível (viola WCAG 2.5.3). - Não adicione
role="button"+tabindex="0"quando<button>funciona. - Não "corrija" um achado de ordem de cabeçalho alterando o tamanho visual; mude o nível e mantenha o CSS.
- Não defina
alt=""em imagens informativas para silenciar o scanner. - Não suprima achados (
wcag-audit-ignore) sem um motivo escrito ao lado do comentário. - Não reivindique "conformidade" com WCAG — revisão automatizada + agente pode mostrar falhas, não conformidade.
- Não modifique código gerado, fornecido ou em
node_modules; corrija o componente de origem.
Arquivos
- references/RULES.md — todas as regras estáticas e de tempo real, mapeadas para WCAG
- references/STATIC-SCAN.md — revisão manual da Fase 1 por framework
- references/RUNTIME-SCAN.md — Fase 2 páginas, estados, SPAs, autenticação
- references/VERIFICATION.md — procedimento de refutação da Fase 3 por regra
- references/FIX-PATTERNS.md — correções antes/depois da Fase 4
- references/REPORTING.md — formato do relatório da Fase 5
- references/MANUAL-CHECKLIST.md — o que a automação não pode verificar
- assets/report-schema.json — esquema do findings.json
scripts/validate-findings.mjs— validador sem dependências para findings.json