Auditor de Acessibilidade
Audita aplicações web quanto à conformidade com requisitos de acessibilidade (WCAG 2.1 Nível AA) e sugere melhorias.
Quando Usar
- Ao construir ou revisar componentes de UI
- Quando o usuário solicitar melhorias de acessibilidade
- Ao se preparar para uma auditoria de acessibilidade
- Quando o usuário mencionar "acessibilidade", "a11y", "WCAG", "leitor de tela" ou "navegação por teclado"
Instruções
1. Verificação de HTML Semântico
Use elementos HTML adequados:
<!-- Ruim -->
<div onclick="submit()">Enviar</div>
<!-- Bom -->
<button onclick="submit()">Enviar</button>
Estrutura semântica:
<header>,<nav>,<main>,<footer><article>,<section>,<aside><h1>a<h6>em hierarquia adequada<button>para ações,<a>para navegação
2. Atributos ARIA
Quando usar ARIA:
- Widgets personalizados (abas, accordions, modais)
- Atualizações de conteúdo dinâmico
- Interações complexas
- Quando o HTML semântico não é suficiente
Atributos ARIA comuns:
<!-- Funções de referência (landmark) -->
<nav role="navigation" aria-label="Principal">
<!-- Funções de widget -->
<div role="button" tabindex="0" aria-pressed="false">
<!-- Regiões ativas -->
<div role="alert" aria-live="assertive">Ocorreu um erro</div>
<!-- Rótulos e descrições -->
<button aria-label="Fechar diálogo">×</button>
<input aria-describedby="ajuda-senha" />
Primeira regra do ARIA: Não use ARIA se o HTML semântico funcionar
3. Navegação por Teclado
Todos os elementos interativos devem ser acessíveis por teclado:
// Adicionar suporte de teclado a elementos personalizados
element.addEventListener('keydown', (e) => {
if (e.key === 'Enter' || e.key === ' ') {
executarAcao();
}
});
Ordem de tabulação:
- Use
tabindex="0"para elementos interativos personalizados - Evite
tabindex > 0(cria ordem confusa) - Use
tabindex="-1"apenas para foco programático
Gerenciamento de foco:
- Indicadores de foco visíveis
- Foco preso dentro de modais
- Retorno de foco ao fechar diálogos
- Links de salto para o conteúdo principal
4. Texto Alternativo e Imagens
Imagens informativas:
<img src="grafico.png" alt="As vendas aumentaram 25% no 3º trimestre" />
Imagens decorativas:
<img src="decoracao.png" alt="" />
<!-- ou -->
<img src="decoracao.png" role="presentation" />
Imagens complexas:
<figure>
<img src="grafico-complexo.png" alt="Gráfico de vendas trimestrais" />
<figcaption>
Descrição detalhada dos dados do gráfico...
</figcaption>
</figure>
5. Cor e Contraste
Taxas de contraste (WCAG AA):
- Texto normal: mínimo 4,5:1
- Texto grande (18pt+): mínimo 3:1
- Componentes de UI: mínimo 3:1
Não dependa apenas de cor:
<!-- Ruim: Apenas cor -->
<span style="color: red;">Erro</span>
<!-- Bom: Ícone + cor -->
<span style="color: red;">
<svg aria-hidden="true"><!-- ícone de erro --></svg>
<span class="sr-only">Erro: </span>
Entrada inválida
</span>
6. Formulários e Rótulos
Cada entrada precisa de um rótulo:
<!-- Rótulo explícito -->
<label for="email">Email</label>
<input id="email" type="email" />
<!-- Rótulo implícito -->
<label>
Email
<input type="email" />
</label>
<!-- aria-label para botões de ícone -->
<button aria-label="Pesquisar">
<svg><!-- ícone de pesquisa --></svg>
</button>
Mensagens de erro:
<input
id="senha"
aria-invalid="true"
aria-describedby="erro-senha"
/>
<div id="erro-senha" role="alert">
A senha deve ter pelo menos 8 caracteres
</div>
7. Títulos e Estrutura do Documento
Hierarquia adequada de títulos:
<h1>Título da Página</h1>
<h2>Seção 1</h2>
<h3>Subseção 1.1</h3>
<h3>Subseção 1.2</h3>
<h2>Seção 2</h2>
Não pule níveis: h1 → h2 → h3 (não h1 → h3)
8. Conteúdo Dinâmico
Anuncie atualizações aos leitores de tela:
<!-- Polido: aguardar pausa do usuário -->
<div role="status" aria-live="polite">
5 novas mensagens
</div>
<!-- Assertivo: interromper imediatamente -->
<div role="alert" aria-live="assertive">
Sua sessão expirará em 1 minuto
</div>
Estados de carregamento:
<button aria-busy="true" aria-label="Carregando...">
<span aria-hidden="true">Carregando</span>
</button>
9. Teste com Leitor de Tela
Texto somente para leitor de tela:
.sr-only {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border-width: 0;
}
Ocultar elementos decorativos:
<svg aria-hidden="true"><!-- ícone --></svg>
10. Problemas Comuns a Verificar
Ausentes:
- Texto alternativo em imagens
- Rótulos em campos de formulário
- Hierarquia adequada de títulos
- Indicadores de foco por teclado
- Rótulos ARIA em botões de ícone
Inadequados:
- Texto com baixo contraste
- Marcação não semântica (divs como botões)
- Gerenciamento de foco ausente em modais
- Armadilhas de teclado
- Mídia com reprodução automática
Testes:
- Navegação apenas por teclado
- Leitor de tela (NVDA, JAWS, VoiceOver)
- Simulação de daltonismo
- Zoom para 200%
- Ferramentas automatizadas (axe, Lighthouse)
11. Testes Automatizados
Ferramentas:
# Lighthouse
npx lighthouse https://example.com --only-categories=accessibility
# axe-core
npm install --save-dev @axe-core/cli
npx axe https://example.com
# pa11y
npm install --save-dev pa11y
npx pa11y https://example.com
Em testes:
import { axe } from 'jest-axe';
test('não deve ter violações de acessibilidade', async () => {
const { container } = render(<MeuComponente />);
const results = await axe(container);
expect(results).toHaveNoViolations();
});
12. Checklist WCAG 2.1 Nível AA
Perceptível:
- Alternativas textuais para conteúdo não textual
- Legendas para áudio/vídeo
- Conteúdo adaptável (marcação semântica)
- Contraste de cores suficiente
Operável:
- Acessível por teclado
- Sem armadilhas de teclado
- Limites de tempo adequados (ajustáveis)
- Sem flashes que induzam convulsões
- Links de salto para navegação
- Títulos de página descritivos
- Ordem de foco faz sentido
- Propósito do link claro pelo contexto
Compreensível:
- Idioma da página especificado (
<html lang="pt">) - Navegação previsível
- Assistência de entrada (rótulos, instruções, mensagens de erro)
Robusto:
- HTML válido
- Nome, função, valor para widgets personalizados
- Compatível com tecnologias assistivas
Melhores Práticas
- Incorpore acessibilidade desde o início
- Teste com tecnologias assistivas reais
- Use HTML semântico primeiro, ARIA depois
- Mantenha estrutura documental lógica
- Forneça múltiplas formas de acessar conteúdo
- Teste a navegação por teclado minuciosamente
- Não desabilite o zoom
- Use marcos de referência e títulos
Arquivos de Apoio
reference/wcag-checklist.md: Checklist completo WCAG 2.1 AAreference/aria-patterns.md: Padrões comuns de widgets ARIA


