accessibility

name	accessibility
description	Use ao projetar telas (ux-designer), implementar componentes (dev-frontend), ou revisar código de UI (code-reviewer). Define o padrão de acessibilidade adotado pelo projeto (WCAG 2.2 AA) com regras práticas e verificáveis — não teoria abstrata.

Acessibilidade: WCAG 2.2 Level AA

Por que WCAG 2.2 AA (e não outra versão ou nível)

WCAG 2.2 foi lançado em outubro de 2023 e é o padrão global atual. Se você está construindo um novo site hoje, projetar para 2.2 é simplesmente a abordagem mais inteligente e preparada para o futuro. O nível AA é o alvo padrão — é o nível exigido pela maioria das leis e regulações internacionais (ADA, European Accessibility Act, Lei Brasileira de Inclusão). Nível AA oferece acesso mais amplo do que o Nível A, especialmente para usuários de tecnologias assistivas.

WCAG 2.2 e WAI-ARIA — complementares, não concorrentes

WCAG 2.2 é o padrão (define o "o quê" — ex: "foco de teclado deve ser visível", "contraste mínimo de 4.5:1").

WAI-ARIA é uma técnica de implementação (define o "como" para componentes dinâmicos — role, aria-label, aria-live, aria-expanded, etc.). WAI-ARIA é mencionado como uma das técnicas no documento "Técnicas para WCAG 2".

Na prática: você segue o WCAG 2.2 como meta; usa WAI-ARIA quando HTML semântico puro não é suficiente para transmitir semântica a tecnologias assistivas. Só use ARIA quando absolutamente necessário — na maioria dos casos, HTML combinado com boas práticas de UX permite acessibilidade sem WAI-ARIA.

Para projetos do setor público brasileiro, vale adicionalmente o eMAG (Modelo de Acessibilidade em Governo Eletrônico), que segue o WCAG com adaptações para o contexto brasileiro.

---

Os 4 princípios do WCAG — POUR

Princípio	Pergunta central	Exemplos práticos
Perceptível	O usuário consegue perceber o conteúdo?	Alt text em imagens, contraste suficiente, legenda em vídeo
Operável	O usuário consegue interagir?	Teclado funciona, foco visível, sem armadilha de teclado
Compreensível	O usuário entende?	Labels claros, mensagens de erro descritivas, comportamento previsível
Robusto	Funciona em tecnologias assistivas?	HTML semântico, ARIA correto, compatível com screen readers

---

Regras práticas por categoria (WCAG 2.2 AA — o que fazer de fato)

1. Contraste de cor (Perceptível — 1.4.3 / 1.4.11)

• Texto normal: razão mínima de 4.5:1 entre texto e fundo.
• Texto grande (≥18pt ou ≥14pt negrito): mínimo 3:1.
• Componentes de UI e estado de foco: mínimo 3:1 contra cores adjacentes.
• shadcn/ui + Tailwind: usar as variáveis CSS de tema (--foreground, --background, etc.) em vez de cores hardcoded — elas já são calibradas para contraste. Não sobrescrever com cinza claro em fundo branco sem verificar.
• Ferramentas de verificação: Chrome DevTools (inspetor de acessibilidade), extensão axe, whocanuse.com.

2. Foco de teclado visível (Operável — 2.4.7 / 2.4.11 — novo em 2.2)

• Todo elemento interativo (botão, link, campo, checkbox) deve ter foco de teclado visível e com contraste mínimo de 3:1 contra o entorno.
• shadcn/ui: o Radix por baixo já gerencia foco corretamente. Não remover outline via CSS global (* { outline: none } é um anti-padrão — nunca fazer isso).
• Em modo escuro, confirmar que o anel de foco ainda é visível — o Tailwind focus-visible:ring usa variáveis que podem precisar de ajuste no tema escuro.
• Novidade do WCAG 2.2 (2.4.12): ao receber foco, o componente não pode estar completamente oculto por outro elemento (ex: header fixo cobrindo o campo focado).

3. Área de clique/toque (Operável — 2.5.8 — novo em 2.2)

• Alvo mínimo: 24x24 CSS pixels (AA). Recomendado: 44x44px para evitar erros em mobile.
• Botões de ícone sem texto (ex: fechar modal, editar linha) precisam de área de clique suficiente — usar p-3 no mínimo em torno do ícone.
• Em grids com botões de ação por linha (editar/excluir): garantir espaçamento entre eles — evitar dois botões de 16px colados.

4. Semântica HTML e ARIA (Robusto — 4.1.2)

• Use elementos HTML nativos antes de ARIA: <button> em vez de <div onClick>, <nav> em vez de <div role="navigation"> — o navegador já entrega ARIA correto para elementos semânticos.
• shadcn/ui/Radix: não adicionar role, aria-* extras nos componentes Radix — eles já gerenciam ARIA internamente. Adicionar ARIA por cima pode criar conflito e piorar a experiência de screen reader.
• Quando usar ARIA: apenas quando HTML semântico não for suficiente (ex: aria-live para anúncio dinâmico, aria-expanded para accordion customizado).
• role="presentation" e aria-hidden="true" para elementos puramente decorativos (ícones acompanhados de texto).

5. Labels e formulários (Compreensível — 1.3.5 / 3.3.1 / 3.3.2)

• Todo campo de formulário tem <label> associado programaticamente — nunca depender só de placeholder como label (placeholder some quando o usuário começa a digitar).
• Campos de erro: a mensagem de erro é associada ao campo via aria-describedby — não apenas visualmente próxima.
• Campos obrigatórios: marcados via aria-required="true" (ou atributo required) E visualmente (asterisco com legenda explicando o símbolo).
• shadcn/ui <FormField> já gerencia a associação label/campo/erro quando usado corretamente com react-hook-form — usar o padrão do shadcn, não criar <input> solto.

6. Mensagens de status dinâmicas (Robusto — 4.1.3)

• Resultados de busca que atualizam sem recarregar a página precisam ser anunciados para screen readers via aria-live.
• Mensagens de sucesso/erro de formulário que aparecem após submit precisam de role="status" ou role="alert".
• Nunca usar apenas cor para indicar estado (ex: campo de erro só com borda vermelha — precisa também de ícone ou texto descritivo).

7. Autenticação acessível (Compreensível — 3.3.8 — novo em 2.2)

• Formulários de login não podem exigir que o usuário resolva teste cognitivo (CAPTCHA de texto distorcido, puzzle) sem oferecer alternativa.
• Sempre permitir que o gerenciador de senhas preencha o campo (autocomplete="current-password", nunca autocomplete="off" em campo de senha).
• Não bloquear paste em campos de senha — impossibilita uso de gerenciadores de senhas.

8. Navegação por teclado (Operável — 2.1.1)

• Toda funcionalidade acessível pelo mouse deve ser acessível pelo teclado.
• Ordem de tabulação deve ser lógica e seguir a ordem visual da tela.
• Modais e dialogs capturar o foco ao abrir e devolvê-lo ao elemento que o abriu ao fechar (Radix/shadcn já faz isso — não quebrar esse comportamento).
• Escape deve fechar modais, dropdowns e tooltips.

9. Textos alternativos (Perceptível — 1.1.1)

• Imagens informativas: alt descritivo do conteúdo ou função.
• Imagens decorativas: alt="" (string vazia) — screen reader ignora.
• Ícones com texto ao lado: aria-hidden="true" no ícone (o texto já comunica a função).
• Ícones sem texto: aria-label descritivo no botão ou <title> no SVG.

10. Sem armadilha de teclado (Operável — 2.1.2)

• Modais e dropdowns retornam o foco quando fechados. Radix gerencia isso — não interferir.
• Iframes ou embeds não prendem o foco indefinidamente.

---

Novidades específicas do WCAG 2.2 (vs. 2.1)

Critério	Nível	O que mudou
2.4.11 Focus Not Obscured (Minimum)	AA	Foco não pode ficar completamente oculto por header fixo ou cookie banner
2.4.12 Focus Not Obscured (Enhanced)	AAA	Foco visível sem qualquer ocultação parcial
2.5.7 Dragging Movements	AA	Toda ação de drag-and-drop tem alternativa acessível (ex: botões para mover)
2.5.8 Target Size (Minimum)	AA	Alvo mínimo de 24x24px
3.2.6 Consistent Help	AA	Ajuda no mesmo lugar em todas as páginas
3.3.7 Redundant Entry	AA	Não pedir a mesma informação duas vezes no mesmo fluxo
3.3.8 Accessible Authentication	AA	Sem testes cognitivos em autenticação sem alternativa

---

shadcn/ui + Radix: o que já vem pronto e o que você precisa fazer

Já vem pronto pelo Radix	Você ainda precisa garantir
ARIA roles em componentes interativos	Labels dos campos de formulário
Gerenciamento de foco em Dialog/Modal	Contraste de cor do seu tema
Escape fecha dropdown/dialog	alt descritivo em imagens
aria-expanded em Accordion/Collapsible	aria-live em resultados dinâmicos
Navegação por teclado em Menu/Select	Área de toque mínima em botões de ícone

---

Ferramentas de verificação (integrar ao fluxo de desenvolvimento)

• axe DevTools (extensão Chrome gratuita) — verifica automaticamente os critérios verificáveis; rodar antes de qualquer PR de UI.
• WAVE (extensão Chrome) — visualização mais didática dos erros.
• Chrome DevTools → Painel Lighthouse → aba Accessibility — integra ao CI com threshold mínimo de 90.
• Verificação manual obrigatória (o que as ferramentas automáticas não pegam):
  • Navegar pela tela só com teclado (sem mouse) e verificar ordem de foco e acesso a todas as ações.
  • Testar com VoiceOver (Mac/iOS) ou NVDA (Windows, gratuito) pelo menos nos fluxos principais.
  • Verificar em zoom de 200% — conteúdo não pode sumir ou sobrepor.

---

No contexto do setor público brasileiro

O eMAG (Modelo de Acessibilidade em Governo Eletrônico) é a referência oficial do governo brasileiro. Ele segue o WCAG e adiciona:

• Barra de acessibilidade padrão com atalhos de teclado (ex: alt+1 para conteúdo, alt+2 para menu).
• Teclas de atalho documentadas e não conflitantes com os do sistema operacional.
• Compatibilidade explícita com leitores de tela em português (NVDA com eSpeak PT-BR, Orca no Linux).

Para aplicações governamentais voltadas ao público externo, a conformidade com eMAG é obrigatória, não opcional.

---

Motion e animações — prefers-reduced-motion obrigatório

Todo projeto com animações CSS ou JavaScript deve respeitar a preferência do usuário por movimento reduzido. Usuários com epilepsia, vertigem ou sensibilidade a movimento podem ser prejudicados por animações.

/* Adicionar em globals.css ou styles.scss — obrigatório */
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration:        0.01ms !important;
    animation-iteration-count: 1      !important;
    transition-duration:       0.01ms !important;
    scroll-behavior:           auto   !important;
  }
}

Regra de design de motion (princípio de Emil Kowalski): A primeira pergunta sobre qualquer animação é "isso deveria animar?". Só animar quando há propósito — comunicar estado, guiar atenção ou dar feedback de ação. Para sistemas de produtividade (DSGOV, dashboards), duração máxima 300ms e sem bounce/spring em ações utilitárias.

Ver ux-designer.md para a lista completa de anti-padrões de motion gerado por IA (stagger-spam, hover-scale-on-everything, etc.).