Acessibilidade no Claude Code: o que pedir no prompt e como conferir contraste, foco e leitura de tela

Fala aí, beleza? A IA te entrega exatamente aquilo que você pediu, nem um item a mais

E acessibilidade quase nunca entra sozinha na resposta

O motivo é meio deprimente: o relatório WebAIM Million 2026 analisou 1 milhão de home pages e achou texto com contraste baixo em 83,9% delas, contra 79,1% em 2025

A média foi de 34 ocorrências distintas de texto com contraste baixo por página, 15% a mais que no ano anterior

Ou seja: o padrão da web já é inacessível, e o modelo aprendeu com esse padrão

Se você usa a IA pra criar telas e protótipos, a conta cai no seu colo

Neste post eu te mostro os cinco pontos que precisam entrar no pedido (com número, não com adjetivo) e como conferir cada um depois, sem depender da palavra da IA 🙂

O que ter em mãos antes de pedir

Nada aqui é pago, e nada precisa de PC da Nasa

• Chrome DevTools: você vai usar o seletor de cor (Color Picker) com a seção Contrast ratio, e o painel Lighthouse pra varredura automática. Detalhe importante: a categoria de acessibilidade do Lighthouse roda sobre o motor axe-core
• Firefox DevTools: o Accessibility Inspector tem a caixa Show Tabbing Order, que desenha na página a ordem em que o teclado vai passar. O recurso está disponível desde o Firefox 84
• NVDA: leitor de tela livre e de código aberto para Windows, criado e mantido pela NV Access desde 2006, com sintetizador de voz embutido e suporte a mais de 55 idiomas

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

E o alvo de referência: a WCAG 2.2, publicada como Recomendação do W3C em 05/10/2023, com atualização publicada em 12/12/2024

As versões 2.0 e 2.1 seguem como Recommendation, mas o próprio W3C recomenda usar a 2.2

Como régua prática, mira no nível AA

Um aviso de escopo antes de seguir: nenhuma dessas ferramentas substitui olhar a tela e usar a tela

Elas te dão evidência, não veredito

Como escrever o pedido: 5 exigências para colar no prompt

A lógica é sempre a mesma: adjetivo o modelo interpreta, número ele cumpre

"Use cores acessíveis" é convite pra improviso

"Texto normal com contraste mínimo de 4,5:1" é especificação

1. Contraste de texto: fale o número, não o adjetivo

O critério 1.4.3 no nível AA pede 4,5:1 para texto normal e 3:1 para texto grande

E texto grande tem definição: 18pt ou maior, ou 14pt ou maior se estiver em negrito (negrito aqui é font-weight: 700 ou mais), o que equivale a cerca de 24px e cerca de 18,67px em negrito

Todo texto deve atingir contraste mínimo de 4,5:1 contra o fundo.
Só cai para 3:1 se for texto grande (18pt+, ou 14pt+ em negrito com font-weight 700 ou mais).
Inclua o texto secundário, placeholders e legendas nessa regra.

O erro comum deste passo: aceitar aquele cinza clarinho sobre branco no texto secundário, que "fica elegante" e não passa nem perto

2. Contraste de componente e do anel de foco: 3:1

Botão, campo de formulário, ícone informativo e o próprio indicador de foco não são texto, e caem no critério 1.4.11 Non-text Contrast, nível AA

A régua é 3:1 contra as cores adjacentes

Componentes inativos (desabilitados) ficam isentos, beleza?

Bordas de input, ícones informativos, limites de botão e o anel de foco
devem ter no mínimo 3:1 de contraste contra as cores adjacentes (WCAG 1.4.11).
Componentes desabilitados estão isentos.

O erro comum deste passo: pedir só a cor do texto e terminar com uma borda de input praticamente invisível no fundo claro

3. Ordem de foco e foco visível

Aqui entram dois critérios novos da 2.2 que quase ninguém pede

O 2.4.11 Focus Not Obscured (Minimum), nível AA, diz que ao receber foco pelo teclado, ao menos parte do componente precisa continuar visível

Traduzindo: barra fixa, banner de cookies e rodapé grudado não podem engolir o elemento focado

A versão AAA (2.4.12) é mais dura ainda: nenhuma parte do indicador de foco pode ficar escondida por conteúdo do autor

E tem o 2.4.13 Focus Appearance, também AAA, que exige contraste suficiente entre o estado com e sem foco e tamanho suficiente do indicador

A ordem de tabulação deve seguir a ordem visual e lógica da tela.
Todo elemento focável precisa de indicador de foco visível (nunca outline: none sem substituto).
O elemento focado não pode ficar totalmente escondido atrás de header fixo, banner ou rodapé fixo.

O erro comum deste passo: o clássico outline: none no CSS pra "limpar o visual", sem nada no lugar

4. Alvo de toque: 24 por 24 pixels CSS

O critério 2.5.8 Target Size (Minimum) é novo na WCAG 2.2, nível AA, e pede 24 por 24 pixels CSS, ou espaçamento suficiente em relação aos alvos vizinhos

Se você quiser mirar mais alto, o nível AAA (2.5.5) pede 44 por 44 pixels CSS

Todo alvo clicável ou tocável deve ter no mínimo 24x24 pixels CSS,
ou espaçamento suficiente em relação aos alvos vizinhos (WCAG 2.5.8).
Isso vale para ícones, botões de fechar, paginação e itens de lista com ação.

O erro comum deste passo: o ícone de fechar de 16px no canto do modal, bonito no desktop e impossível no dedo

5. Rótulo, alt e nome acessível

Esse é o passo que mais aparece nas estatísticas de falha

No WebAIM Million 2026, alt text ausente apareceu em 53,1% das home pages, rótulo de campo de formulário ausente em 51%, links vazios em 46,3%, botões vazios em 30,6% e idioma do documento ausente em 13,5%

Seis categorias (essas cinco mais o contraste baixo) concentram 96% dos erros detectados

Todo campo precisa de <label> associado (não só placeholder).
Toda imagem informativa precisa de alt descritivo; imagem decorativa vai com alt="".
Todo link e botão precisa de texto acessível, inclusive os que só têm ícone.
Defina o idioma no elemento raiz: <html lang="pt-BR">.

O erro comum deste passo: botão só com ícone SVG e zero nome acessível, que o leitor de tela anuncia como "botão" e ponto

E fecha o prompt com uma exigência que muda tudo: peça pro modelo devolver os valores usados, não só o código

Ao final, liste em tabela: cada par de cores usado e a razão de contraste calculada,
o tamanho em px de cada alvo clicável e onde o foco fica visível.

Assim você tem o que conferir, item por item

Como conferir cada ponto depois, sem acreditar na resposta

A IA vai dizer que aplicou tudo

Muitas vezes aplicou mesmo, e é justamente por isso que vale conhecer os limites do modelo antes de tratar a resposta como laudo

Bora conferir na mão? Cada checagem aqui espelha uma exigência do bloco anterior

1. Contraste de texto e de componente, no Chrome DevTools

Clique no elemento, abra o seletor de cor ao lado da declaração de cor e expanda a seção Contrast ratio

Ele mostra o resultado para os níveis AA e AAA, e ainda oferece o botão "Use suggested color" pra aplicar uma cor que passa

O erro comum deste passo: conferir só o título e esquecer do texto secundário, que é onde o cinza claro se esconde

2. Varredura geral com o Lighthouse

Abra o DevTools, vá no painel Lighthouse, marque a categoria Accessibility e clique em Generate report

Lembrando: essa categoria roda sobre o axe-core, então é teste automatizado

3. Ordem de foco, no Firefox

Abra o Accessibility Inspector do DevTools do Firefox e marque a caixa Show Tabbing Order

Ele sobrepõe na página um número em cada parada de tabulação, na ordem em que o teclado vai percorrer

O erro comum deste passo: achar que o overlay é dinâmico. Ele é um retrato do momento em que a caixa foi marcada: itens que entram na ordem depois (ao abrir um menu ou um modal, por exemplo) só aparecem relançando o Accessibility Inspector

4. Foco visível e armadilha de teclado: só Tab e Shift+Tab

Esse teste é o mais barato de todos e o mais ignorado

Larga o mouse e percorre a tela inteira só com Tab e Shift+Tab

Você consegue ver onde está o foco em TODO momento? Consegue sair do modal sem mouse? Algum elemento sumiu atrás do header fixo?

5. Leitura de tela com o NVDA

Abra a página com o NVDA rodando e escute

O link anuncia pra onde vai? O botão tem nome ou é só "botão"? O campo diz o que quer?

Se você ouvir "link" seco três vezes seguidas, achou os links vazios

O erro comum de todo este bloco: tratar nota 100 de acessibilidade no Lighthouse como página acessível

Nota 100 significa apenas que a página passou em todas as checagens automatizadas

Armadilha de teclado, alt text com texto realmente significativo e ordem de leitura lógica não entram nessa nota

Quando o pedido genérico falha e o específico salva

Tem situação de vibe coding em que "faça acessível" simplesmente não resolve, porque a decisão que quebra a acessibilidade é uma decisão estética

Se liga em três:

Tela com estado desabilitado e texto secundário em cinza. Sem número no pedido, o modelo escolhe o cinza pela estética, e o texto secundário nasce abaixo de 4,5:1. Aqui o detalhe fino ajuda: componente desabilitado é isento do 3:1, mas texto secundário ativo não é. Se você não separar os dois no prompt, a IA generaliza pro lado errado

Interface com modal ou menu suspenso. A ordem de foco muda depois que o componente abre, e é exatamente o caso que o overlay do Firefox não pega sozinho, porque ele é o retrato do momento. Peça nominalmente: foco vai pro modal ao abrir, volta pro gatilho ao fechar, e não vaza pro conteúdo de trás

Barra de navegação fixa no topo ou banner de consentimento. Tudo funciona no mouse, e aí o usuário tabula até um elemento que fica embaixo da barra. É o 2.4.11 na veia, e é invisível pra quem só testa clicando

E por que essas coisas escapam? Porque teste automatizado não cobre a acessibilidade inteira

Um estudo da Deque com a suíte axe encontrou que, em média, 57% (57,38%) dos problemas foram completamente cobertos por teste automatizado, numa base de mais de 13.000 páginas ou estados de página e quase 300.000 problemas

Ou seja: quase metade só aparece se alguém testar à mão

Próximo passo: transforme isso em instrução fixa

A diferença aqui não está no modelo, está no pedido

Acessibilidade entra quando é exigida com número, e sai calada quando você pede "design bonito e moderno"

Então o próximo passo prático é simples: guarda os cinco pontos como texto padrão do projeto, o mesmo bloco em todo pedido de tela, e para de reescrever isso do zero toda vez

Depois roda a dupla de conferência antes de considerar a tela pronta: Lighthouse pro que é automatizável, Tab e leitor de tela pro resto

Uma última pra deixar registrado: a WCAG 2.2 acrescentou 9 novos critérios de sucesso em relação à 2.1, e vale ler com calma justamente os que tocam foco e alvo de toque, porque são os que mais aparecem em interface gerada por IA

Faça o teste na sua última tela e me conta o que apareceu 😀

até o próximo post!