Communitygithub.com

wcag-audit

Audita interfaces web para falhas de acessibilidade WCAG 2.2 e as corrige. Executa um procedimento em fases (varredura estática de código-fonte HTML/JSX/TSX/Vue/Svelte/Astro/MDX/Angular/CSS, varredura em tempo real com navegador usando axe-core e verificações de teclado, verificação adversarial de cada achado, correções mínimas com explicações e um relatório legível por máquina).

O que é wcag-audit?

Esta skill capacita agentes de IA a auditar e corrigir problemas de acessibilidade em interfaces web, seguindo as diretrizes WCAG 2.2. Ela é útil para desenvolvedores que precisam garantir conformidade com padrões como WCAG, ADA, Seção 508 ou EN 301 549, melhorando o suporte a leitores de tela, teclado, contraste de cores e rótulos. A skill suporta uma ampla variedade de frameworks modernos (React, Vue, Svelte, Angular, etc.) e opera em um fluxo de cinco fases: varredura estática de código-fonte, varredura em tempo real com navegador (usando axe-core e verificações de teclado), verificação adversarial para eliminar falsos positivos, correções mínimas e comportamentais, e geração de relatórios detalhados. A abordagem é rigorosa: cada achado deve ser confirmado manualmente ou rejeitado, garantindo que apenas problemas reais sejam relatados e corrigidos, com foco em HTML nativo e evitar ARIA desnecessário.

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

Perguntar na sua IA favorita

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

Documentação

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

  1. 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.
  2. HTML nativo primeiro. O melhor ARIA é nenhum ARIA. Corrija <div onClick> transformando-o em um <button>, e não adicionando role, tabindex e manipuladores de teclado.
  3. 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).
  4. 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_validation e pergunte; não escreva alt="image".
  5. 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:

  1. Faça a menor alteração que satisfaça o critério, no idioma do framework (htmlFor no React, :aria-label no Vue, etc.).
  2. Explique em uma ou duas frases: o que estava errado, quem afetou, o que mudou.
  3. 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

SeveridadeSignificadoExemplos
críticaBloqueia completamente uma tarefa para alguns usuárioscampo de formulário sem rótulo, <div onClick> como única forma de enviar, armadilha de teclado, zoom desabilitado
graveDificuldade maior ou informação faltandotexto de corpo com baixo contraste, idioma da página ausente, link sem nome
moderadaAtrito, estrutura confusaníveis de cabeçalho pulados, texto de link redundante ou vago no contexto
menorPolimento, boa práticatexto 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-label que 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

Habilidades Relacionadas