Acessibilidade que vem com o ofício
Acessibilidade não é uma caixa de conformidade adicionada no final; é o piso da qualidade da interface. A maior parte dela é gratuita se você usar a plataforma: elementos nativos vêm com suporte a teclado, rótulos reais se anunciam, e um anel de foco visível é uma regra de CSS. Aplique estes princípios ao construir ou revisar código de UI e corresponda ao sistema de estilos existente do projeto (Tailwind vs. CSS puro vs. CSS-in-JS) ao aplicar correções.
Ao revisar, percorra a interface primeiro como um usuário apenas de teclado (cada fluxo deve ser concluído sem mouse), depois como um usuário de leitor de tela: cada controle anuncia um nome, um papel e seu estado? Quando estiver em dúvida, prefira o padrão da plataforma em vez de uma reconstrução personalizada e remova ARIA em vez de adicioná-la.
A medição de contraste de par renderizado e a correção de cor são cobertas pelo skill better-colors; o dimensionamento visual de texto e o zoom de entrada no iOS pelo better-typography; o layout espacial RTL pelo better-layout.
Referência Rápida
| Categoria | Quando usar |
|---|---|
| Foco e Teclado | Anéis de foco, links de pular, tabindex, armadilha de foco, padrões de teclado APG |
| Semântica e ARIA | Elementos nativos primeiro, botão vs link, marcos, nomes acessíveis, estados desabilitados |
| Formulários | Rótulos, autocomplete, mensagens de erro, tipos de entrada |
| Leitores de Tela | Conteúdo visualmente oculto, regiões ativas, toasts, texto alternativo, SVG |
| Áreas de Toque | Tamanhos de alvo, expansão de áreas de toque, regras de colisão |
| Movimento e Zoom | prefers-reduced-motion, reprodução automática e UI temporizada, zoom de 200%, refluxo, rem vs px |
Princípios Centrais
1. Elementos Nativos Primeiro
A primeira regra do ARIA: não use ARIA quando existir um elemento nativo. <button> para ações, <a href> para navegação (deve suportar clique Cmd/Ctrl/meio), nunca <div onClick>. Nenhum ARIA é melhor que ARIA ruim.
2. Anéis de Foco Visíveis
Estilize :focus-visible, não o simples :focus, para que usuários de teclado recebam um anel e usuários de mouse geralmente não. Prefira o indicador de foco não modificado do navegador. Se o design precisar de um anel personalizado, use um token de foco do projeto ou outra cor explícita e verifique o indicador completo contra cada cor adjacente que ele cruzar; currentColor é aceitável apenas após a mesma verificação. Use pelo menos um perímetro sólido de 2px ou uma área visível equivalente. Nunca use outline: none sem um substituto verificado e preserve as cores do sistema no modo forced-colors.
3. Suporte Completo a Teclado
Cada interação de ponteiro precisa de um caminho de teclado, seguindo os padrões ARIA APG: Escape fecha sobreposições, teclas de seta movem dentro de widgets compostos (abas, menus, listboxes), Tab move entre widgets, Enter e Espaço ativam. Apenas tabindex="0" (junte-se à ordem de tabulação natural) e tabindex="-1" (foco programático), nunca valores positivos, que quebram a ordem natural. Widgets compostos usam tabindex móvel: o item ativo é 0, todos os outros -1.
4. Armadilha e Restauração de Foco
Modais definem inert no conteúdo de fundo, movem o foco para dentro ao abrir e retornam o foco ao gatilho ao fechar. Adicione overscroll-behavior: contain para que o conteúdo de fundo não role.
5. Área de Toque Mínima
A linha de base do Nível AA da WCAG 2.5.8 é um alvo de 24×24 pixels CSS ou uma de suas exceções definidas (espaçamento, controle equivalente, inline, agente do usuário, essencial). Para ativação mais fácil, almeje 44×44px em contextos de toque e 40×40px em interfaces de desktop quando a densidade permitir. Estenda com um pseudoelemento se o elemento visível precisar permanecer menor. Nunca deixe áreas de toque estendidas se sobreporem.
6. Rotule e Digite Cada Controle
Cada entrada recebe um <label for> ou <label> envolvente; um placeholder nunca é um rótulo, e o rótulo e o controle compartilham um alvo de toque: sem zonas mortas entre uma caixa de seleção e seu texto. Adicione autocomplete com um name significativo, e o type e inputmode corretos para o teclado. Nunca bloqueie colar; usuários colam senhas e códigos de uso único.
7. Erros Que Anunciam
Mantenha o envio habilitado até que a solicitação comece, depois desabilite com um spinner enquanto mantém o rótulo original. Valide no envio: marque campos com falha com aria-invalid="true", aponte aria-describedby para o texto de erro inline e foque o primeiro campo inválido. Use disabled nativo quando um controle nativo estiver genuinamente indisponível. Use aria-disabled="true" apenas quando a retenção de focalizabilidade ou descoberta for intencional; então bloqueie o comportamento do ponteiro, teclado e formulário no código e estilize o estado explicitamente.
8. Nomes Acessíveis em Toda Parte
Botões apenas de ícone precisam de um aria-label descritivo. O texto do rótulo visível deve aparecer no nome acessível. Elementos decorativos recebem aria-hidden="true", nunca em um elemento focalizável.
9. Não Dependa Apenas da Cor
O status precisa de uma dica redundante: ícone, texto ou sublinhado junto com a cor. Determine qual requisito de contraste WCAG se aplica a partir do conteúdo e estado, então use better-colors para medir o par de primeiro plano/fundo renderizado. Quando o contraste falhar, relate o par e o requisito que ele perde; não altere as cores do projeto a menos que solicitado.
10. Honre prefers-reduced-motion
Envolva o movimento em @media (prefers-reduced-motion: no-preference) para que seja opt-in. Sob movimento reduzido, substitua slides e escalas por crossfades de opacidade; mate parallax e reprodução automática completamente. Independente da preferência: mídia com reprodução automática precisa de um controle de pausa visível e toasts que carregam ações ou erros permanecem até serem descartados.
11. Anuncie Conteúdo Dinâmico
Use aria-describedby para validação específica de campo, uma região ativa educada (role="status") para atualizações não urgentes não vinculadas a um controle, como toasts ou contagens de resultados, e role="alert" apenas para erros urgentes não vinculados a um controle. Para anúncios educados repetidos confiáveis, renderize uma região vazia estável antes de atualizar seu texto; alertas inseridos dinamicamente têm suporte diferente e devem ser testados com os leitores de tela alvo.
12. Texto Alternativo por Propósito
Imagens decorativas recebem alt="", imagens informativas descrevem o significado, imagens funcionais descrevem a ação: um botão de ícone de pesquisa é alt="Pesquisar", não alt="lupa".
13. Estrutura é Navegação
Use cabeçalhos que descrevam suas seções e formem um esboço coerente; um <h1> no nível da página e níveis aninhados adequadamente são o padrão recomendado, não regras isoladas de aprovação/reprovação WCAG. Exponha um marco <main> primário visível. Quando navegação repetida ou chrome o preceder, faça um link "Pular para o conteúdo" ser o primeiro elemento focalizável. Cabeçalhos ancorados recebem scroll-margin-top.
14. Sobreviva ao Zoom e Redimensionamento de Texto
A página deve funcionar com zoom de 200% e refluxo a 320px de largura sem rolagem horizontal. Use min-height em vez de height fixa em contêineres de texto, prefira breakpoints rem onde se encaixarem nas convenções do código-base e mantenha a meta da viewport de não limitar o quão longe o leitor pode ampliar.
Erros Comuns
| Erro | Correção |
|---|---|
outline: none para remover o anel de foco | Estilize :focus-visible; cliques de mouse não o mostrarão |
| Cor de foco personalizada presumida funcionar em toda parte | Verifique o indicador completo contra cada cor adjacente e no modo forced-colors |
<div onClick> para um botão ou link | <button> para ações, <a href> para navegação |
| Placeholder usado como o único rótulo | Adicione um <label for> visível; placeholders desaparecem na digitação |
tabindex positivo para corrigir ordem de foco | Corrija a ordem DOM; use apenas 0 e -1 |
| Atualização educada repetida anunciada inconsistentemente | Mantenha uma região de status vazia estável e atualize seu texto; teste os leitores de tela alvo |
Região ativa assertive para um toast de rotina | Use polite; reserve assertive para erros |
aria-hidden="true" em um elemento focalizável | Remova-o ou torne o elemento não focalizável |
| Alt de ícone funcional descreve a imagem | Descreva a ação: alt="Pesquisar", não alt="lupa" |
| Envio desabilitado até que o formulário seja válido | Mantenha-o habilitado; valide no envio e foque o primeiro erro |
Formato de Saída da Revisão
Use este formato apenas quando o usuário solicitar uma revisão de acessibilidade independente. Quando better-interface orquestrar a revisão, forneça evidências de domínio e descobertas para aquele skill e deixe que seu formato de saída, escala de gravidade, regras de consolidação, limite e veredito tenham precedência.
Apresente a revisão independente em duas partes.
Descobertas
Agrupe todas as descobertas confirmadas por princípio. Use uma tabela markdown com as colunas Gravidade, Localização, Antes, Depois e Porquê. Nunca use linhas separadas "Antes:" / "Depois:".
- Gravidade:
ALTAimpede uma tarefa, oculta conteúdo da tecnologia assistiva ou cria uma falha sistêmica de acessibilidade;MÉDIAtorna uma interação significativamente mais difícil;BAIXAé polimento isolado. - Localização: cite
caminho/para/arquivo:linha. Se o artefato não tiver arquivos de origem, cite a tela e o componente exatos. - Antes / Depois: mostre a implementação atual e uma substituição acionável.
- Porquê: nomeie o princípio violado e seu impacto no usuário.
Consolide um problema sistêmico repetido em uma linha e liste cada localização afetada. Omita princípios sem descobertas.
Exemplo
Nomes acessíveis em toda parte
| Gravidade | Localização | Antes | Depois | Porquê |
|---|---|---|---|---|
| ALTA | src/Dialog.tsx:42 | <button><XIcon /></button> | Adicione aria-label="Fechar"; marque o ícone como aria-hidden="true" | O controle apenas de ícone não tem nome acessível |
| ALTA | src/Nav.tsx:18 | <a href="/settings"><GearIcon /></a> | Adicione aria-label="Configurações" | O destino do link não está disponível para leitores de tela |
Anéis de foco visíveis
| Gravidade | Localização | Antes | Depois | Porquê |
|---|---|---|---|---|
| ALTA | src/button.css:12 | button:focus { outline: none; } | button:focus-visible { outline: 2px solid; outline-offset: 2px; } | Usuários de teclado não conseguem ver o foco |
| ALTA | src/Menu.tsx:31 | focus:outline-none | focus-visible:outline-2 focus-visible:outline-offset-2 | A navegação do menu não tem indicador de foco visível |
Erros que anunciam
| Gravidade | Localização | Antes | Depois | Porquê |
|---|---|---|---|---|
| ALTA | src/EmailField.tsx:27 | Erro mostrado apenas como border-red-500 | Adicione aria-invalid="true" + aria-describedby="email-error" com texto de erro inline | A cor sozinha não explica nem anuncia o erro |
| MÉDIA | src/SignupForm.tsx:64 | Envio desabilitado até que o formulário seja válido | Mantenha o envio habilitado; na falha, foque o primeiro campo inválido | Uma ação desabilitada oculta o que deve ser corrigido |
Área de toque mínima
| Gravidade | Localização | Antes | Depois | Porquê |
|---|---|---|---|---|
| MÉDIA | src/Toolbar.tsx:22 | Botão de ícone size-4 | Estenda a área de toque para 44×44px com after:absolute after:size-11 | O alvo é muito pequeno para entrada por toque confiável |
Verificação e Veredito
Após as descobertas:
- Verificação: liste as verificações exatas executadas e seus resultados observados, incluindo travessia de teclado, inspeção de nome acessível e verificações de leitor de tela ou automatizadas quando aplicável. Se uma verificação não foi executada, indique o que ainda precisa de verificação.
- Veredito:
Bloquearse alguma descobertaALTApermanecer,Precisa de mudançasse apenas descobertasMÉDIAouBAIXApermanecerem, eAprovarapenas quando nenhuma descoberta acionável permanecer.
Quando não houver descobertas, omita as tabelas, diga "Nenhuma descoberta de acessibilidade acionável", relate a verificação e termine com Aprovar.