a11y-audit

name	a11y-audit
description	Skill de auditoria de acessibilidade para escanear, corrigir e verificar a conformidade WCAG 2.2 Nível A e AA em codebases React, Next.js, Vue, Angular, Svelte e HTML puro. Use ao auditar acessibilidade, corrigir violações de a11y, verificar contraste de cores, gerar relatórios de conformidade ou integrar verificações de acessibilidade em pipelines CI/CD.
agents	["claude-code"]

Auditoria de Acessibilidade

Skill de Auditoria e Remediação de Acessibilidade WCAG 2.2

Descrição

A skill a11y-audit fornece um pipeline completo de auditoria de acessibilidade para aplicações web modernas. Implementa um fluxo de trabalho em três fases — Escanear, Corrigir, Verificar — que identifica violações WCAG 2.2 Nível A e AA, gera código de correção preciso por framework e produz relatórios de conformidade prontos para partes interessadas.

Para cada violação encontrada, fornece o código de correção preciso antes/depois, adaptado ao seu framework (React, Next.js, Vue, Angular, Svelte ou HTML puro).

O que esta skill faz:

1. Escaneia seu codebase em busca de todas as violações WCAG 2.2 Nível A e AA, categorizadas por severidade (Crítica, Maior, Menor)
2. Corrige cada violação com padrões de código antes/depois específicos para o framework
3. Verifica que as correções resolvem as violações originais e não introduzem regressões
4. Reporta os resultados em formato estruturado adequado para desenvolvedores, PMs e partes interessadas em conformidade
5. Integra em pipelines CI/CD para prevenir regressões de acessibilidade

Funcionalidades

Funcionalidade	Descrição
Escaneamento WCAG 2.2 Completo	Verifica todos os critérios de sucesso Nível A e AA em seu codebase
Detecção de Framework	Detecta automaticamente React, Next.js, Vue, Angular, Svelte ou HTML puro
Classificação de Severidade	Categoriza cada violação como Crítica, Maior ou Menor
Geração de Código de Correção	Produz diffs de código antes/depois para cada problema
Verificador de Contraste de Cores	Valida pares de cores de primeiro e segundo plano contra as proporções AA e AAA
Relatórios de Conformidade	Gera relatórios para partes interessadas com resumos de aprovação/reprovação
Integração CI/CD	Configurações de pipeline para GitHub Actions, GitLab CI, Azure DevOps
Auditoria de Navegação por Teclado	Detecta gerenciamento de foco ausente e problemas de ordem de tabulação
Validação ARIA	Verifica atributos ARIA incorretos, redundantes ou ausentes

Definições de Severidade

Severidade	Definição	Exemplo	SLA
Crítica	Bloqueia o acesso para grupos inteiros de usuários	Texto alternativo ausente, sem acesso por teclado à navegação	Corrigir antes do lançamento
Maior	Barreira significativa que degrada a experiência	Contraste de cores insuficiente, rótulos de formulário ausentes	Corrigir dentro do sprint atual
Menor	Problema de usabilidade que causa atrito	Funções ARIA redundantes, hierarquia de cabeçalhos subótima	Corrigir nos próximos 2 sprints

Uso

Início Rápido

# Escanear projeto inteiro
python scripts/a11y_scanner.py /path/to/project

# Escanear com saída JSON para ferramentas
python scripts/a11y_scanner.py /path/to/project --json

# Verificar contraste de cores para valores específicos
python scripts/contrast_checker.py --fg "#777777" --bg "#ffffff"

# Verificar contraste em um arquivo CSS/Tailwind
python scripts/contrast_checker.py --file /path/to/styles.css

Slash Command

/a11y-audit                    # Auditar o projeto atual
/a11y-audit --scope src/       # Auditar diretório específico
/a11y-audit --fix              # Auditar e aplicar correções automaticamente
/a11y-audit --report           # Gerar relatório para partes interessadas
/a11y-audit --ci               # Saída de resultados compatível com CI

Fluxo de Trabalho em Três Fases

Fase 1: Escanear — Percorrer a árvore de código-fonte, detectar framework, aplicar conjunto de regras.

python scripts/a11y_scanner.py /path/to/project --format table

Fase 2: Corrigir — Aplicar correções específicas para o framework em cada violação.

Veja references/framework-a11y-patterns.md para o catálogo completo de padrões de correção.

Fase 3: Verificar — Executar novamente o scanner para confirmar as correções e verificar regressões.

python scripts/a11y_scanner.py /path/to/project --baseline audit-baseline.json

Exemplo: Auditoria de Componente React

// ANTES: src/components/ProductCard.tsx
function ProductCard({ product }) {
  return (
    <div onClick={() => navigate(`/product/${product.id}`)}>
      <img src={product.image} />
      <div style={{ color: '#aaa', fontSize: '12px' }}>{product.name}</div>
      <span style={{ color: '#999' }}>${product.price}</span>
    </div>
  );
}

#	WCAG	Severidade	Problema
1	1.1.1	Crítica	<img> sem atributo alt
2	2.1.1	Crítica	<div onClick> não acessível por teclado
3	1.4.3	Maior	Cor #aaa no branco falha no contraste (2.32:1, necessita 4.5:1)
4	1.4.3	Maior	Cor #999 no branco falha no contraste (2.85:1, necessita 4.5:1)
5	4.1.2	Maior	Elemento interativo sem role e nome acessível

// DEPOIS: src/components/ProductCard.tsx
function ProductCard({ product }) {
  return (
    <a href={`/product/${product.id}`} className="product-card"
       aria-label={`View ${product.name} - $${product.price}`}>
      <img src={product.image} alt={product.imageAlt || product.name} />
      <div style={{ color: '#595959', fontSize: '12px' }}>{product.name}</div>
      <span style={{ color: '#767676' }}>${product.price}</span>
    </a>
  );
}

Veja references/examples-by-framework.md para exemplos em Vue, Angular, Next.js e Svelte.

Referência de Ferramentas

a11y_scanner.py

Uso: python scripts/a11y_scanner.py <caminho> [opções]

Opções:
  --json                  Saída dos resultados como JSON
  --format {table,csv}    Formato de saída (padrão: table)
  --severity {critical,major,minor}  Filtrar por severidade mínima
  --framework {react,vue,angular,svelte,html,auto}  Forçar framework (padrão: auto)
  --baseline FILE         Comparar com resultados de escaneamento anteriores
  --report                Gerar relatório para partes interessadas
  --output FILE           Escrever resultados em arquivo
  --quiet                 Suprimir saída, apenas código de saída
  --ci                    Modo CI: saída não-zero em problemas críticos

contrast_checker.py

Uso: python scripts/contrast_checker.py [opções]

Opções:
  --fg COLOR              Cor de primeiro plano (hex)
  --bg COLOR              Cor de segundo plano (hex)
  --file FILE             Escanear arquivo CSS para pares de cores
  --tailwind DIR          Escanear diretório para classes de cores Tailwind
  --json                  Saída dos resultados como JSON
  --suggest               Sugerir alternativas acessíveis para falhas
  --level {aa,aaa}        Nível de conformidade alvo (padrão: aa)

Armadilhas Comuns

Armadilha	Abordagem Correta
role="button" em um <div>	Use <button> nativo — inclui tratamento de teclado gratuitamente
tabindex="0" em tudo	Apenas elementos interativos precisam de foco; use elementos nativos
aria-label em elementos não-interativos	Use aria-labelledby apontando para texto visível
display: none para ocultar de leitores de tela	Use a classe .sr-only
Cor apenas para transmitir significado	Adicione ícones, rótulos de texto ou padrões junto com a cor
Placeholder como único rótulo	Sempre forneça um <label> visível
outline: none sem substituição	Sempre forneça um indicador de foco visível via focus-visible
alt="" vazio em imagens informacionais	Imagens informacionais precisam de texto alternativo descritivo
Pular níveis de cabeçalho (h1 -> h3)	Níveis de cabeçalho devem ser sequenciais
onClick sem onKeyDown	Adicione suporte a teclado ou prefira elementos nativos
Ignorar prefers-reduced-motion	Envolva animações em @media (prefers-reduced-motion: no-preference)

Skills Relacionadas

Skill	Relação
senior-frontend	Padrões de frontend usados em correções de a11y
code-reviewer	Incluir verificações de a11y em fluxos de trabalho de revisão de código
senior-qa	Integração de testes de a11y em processos de QA
playwright-pro	Testes automatizados de navegador com asserções de acessibilidade
epic-design	Animações e scroll storytelling em conformidade com WCAG 2.1 AA
tdd-guide	Padrões de desenvolvimento orientado a testes para casos de teste de a11y

Documentação de Referência

Referência	Descrição
wcag-quick-ref.md	Referência rápida dos critérios WCAG 2.2 Nível A e AA
wcag-22-new-criteria.md	Novos critérios de sucesso WCAG 2.2 (Aparência de Foco, Tamanho Meta, etc.)
aria-patterns.md	Padrões ARIA, interação por teclado e regiões ao vivo
framework-a11y-patterns.md	Padrões de correção específicos por framework (React, Vue, Angular, Svelte, HTML)
color-contrast-guide.md	Detalhes do verificador de contraste de cores, mapeamento de paleta Tailwind, classe sr-only
ci-cd-integration.md	Configurações de GitHub Actions, GitLab CI, Azure DevOps, pre-commit hook
audit-report-template.md	Modelo de relatório de auditoria pronto para partes interessadas
testing-checklist.md	Lista de verificação de testes manuais (teclado, leitor de tela, visual, formulários)
examples-by-framework.md	Exemplos completos de auditoria para Vue, Angular, Next.js e Svelte

Recursos

• WCAG 2.2 Specification
• WAI-ARIA Autoring Practices 1.2
• Deque axe-core Rules
• eslint-plugin-jsx-a11y