Auditar acessibilidade e contraste nos dois temas

Um tribunal francês condenou o Carrefour a corrigir site e aplicativo em seis meses, sob multa de 500 euros por dia de atraso. A defesa alegou 71% de conformidade com a norma de acessibilidade, e o tribunal respondeu que conformidade parcial não conta como conformidade.

Acessibilidade é a tela funcionando por teclado, com contraste suficiente entre tinta e fundo. Vale também para o leitor de tela, ou seja, o programa que lê a página em voz alta para quem não enxerga. Quem não enxerga bem desiste da compra quando o texto some no fundo, e o prejuízo chega antes do processo.

A WCAG é a norma internacional que descreve essas exigências, e o alvo técnico deste curso é a versão 2.2 no nível AA. A lei já cobra esse nível no Brasil, na Europa e nos Estados Unidos.

No Brasil, a ABNT NBR 17225 é a norma técnica de acessibilidade digital. Ela se apoia na WCAG, a mesma régua usada em auditoria e em ação judicial.

Na União Europeia, a obrigação de aplicar a diretiva de acessibilidade já começou para comércio eletrônico, banco ao consumidor e livro digital. Há transições correndo: o serviço mantém até 2030 os produtos que já usava legalmente, e a microempresa de serviço está dispensada. Nenhuma das duas exceções alcança o site novo que você publica agora.

O tamanho do problema aparece na conta pública: entre 366 sites federais verificados, 88,5% foram classificados como ruins em acessibilidade. Uma liminar deu 180 dias à União, sob multa diária de dez mil reais, em decisão provisória e recorrível.

Nos Estados Unidos, a regra do Departamento de Justiça usa a WCAG 2.1 no nível AA para governos estaduais e locais. As agências federais seguem a Section 508, alinhada à versão 2.0 AA.

A WCAG 3.0 segue em rascunho, sem valor normativo e sem jurisdição que a exija. Ela vai coexistir com a 2.2 por anos, e pedir ao agente conformidade com a versão 3 cobra uma promessa que nenhum auditor consegue conferir.

Contraste e teclado são as duas falhas que mais reprovam uma tela. Contraste é a razão entre a tinta e o fundo, com piso de 4,5:1 no texto normal e 3:1 no texto grande. Corrija pelo token, ou seja, a cor guardada com nome, porque o ajuste se propaga a todos os componentes irmãos.

O axe é o verificador que roda no navegador e aponta o elemento e a regra quebrada, como um fiscal que já entrega a multa com o endereço. Instale a extensão axe DevTools, aperte F12 e rode a análise nos dois temas, com menu e diálogo abertos. Ele só enxerga o que está no ar naquele instante.

Teclado falha pelo mesmo motivo: o componente foi construído olhando só para o mouse. Percorra a tela inteira com Tab, Shift+Tab, Enter e Esc, e quando numa parada você não sabe onde está, então o foco sumiu. Menu que ignora o Enter e diálogo que não fecha no Esc estão quebrados.

Numa imobiliária com filtro de bairro que só abre no clique do mouse, metade dos anúncios some para quem navega por teclado. A lista chega vazia, e a visita se perde sem que ninguém descubra o motivo. Abrir o filtro só com Enter e fechá-lo só com Esc expõe a falha em menos de um minuto.

Uma varredura com nota máxima não autoriza declarar a tela pronta. O axe-core dentro do Playwright, a ferramenta que abre o navegador sozinha e clica como um visitante, vira portão da esteira de publicação. Ele barra a entrega que reprova.

A cobertura tem dois números que se confundem. O teste automatizado alcança de 30% a 40% dos critérios da norma, e os 57% da Deque medem outra coisa: o volume de problemas encontrados.

O resto é revisão humana, porque ordem de foco quebrada e rótulo errado passam batido na máquina. O Pa11y faz varredura parecida por linha de comando, útil quando são dezenas de páginas.

Também é o axe-core o motor do Lighthouse e do painel do Chrome DevTools. Ferramentas que parecem independentes convergem porque leem a mesma régua, e três notas iguais não valem como três confirmações.

Três regras de norma dispensam ferramenta. Alvo de toque é a área que o dedo acerta. O piso é 24 px no nível AA, 44 px no AAA e nas diretrizes da Apple, e 48 dp no Android. Todo modal fecha por um botão visível e tocável, porque quem não consegue fechar a janela abandona o site.

Gráfico que sustenta uma decisão ganha tabela alternativa, e a checagem Chartability serve de auditoria, com a sonificação como canal complementar.

Canvas e WebGL entregam ao leitor de tela uma imagem muda, e o cliente cego escuta silêncio no lugar do preço. Eles precisam de uma camada paralela em HTML com atributos ARIA, ou seja, rótulos que dizem o que cada elemento é. O agente só escreve essa camada se você pedir.

A skill frontend-design, publicada pela Anthropic, fixa um piso de qualidade que o agente entrega sem anunciar. São cinco itens: tela que funciona no celular, foco de teclado visível, menos movimento respeitado, contraste correto e paleta harmoniosa.

Com ela carregada, as checagens desta aula viram ponto de partida do trabalho do agente, e a sua revisão passa a conferir em vez de ensinar.

Antes de aprovar qualquer fluxo que fatura, comprar, agendar ou cadastrar, rode o axe nos dois temas, com menu e diálogo abertos. Depois percorra a tela só com Tab, Shift+Tab, Enter e Esc, e conserte o que travar. Deu certo quando o axe não aponta falha e o axe-core no Playwright segura sozinho a publicação que reprova.

Conferir se cada cor da sua escala tem contraste suficiente

A auditoria automática aponta onde o contraste falha, e a escala de cor ainda precisa ser medida degrau a degrau, nos dois temas, antes de virar token.

No degrau 500 de uma escala de cor, nem o texto branco nem o quase-preto passam no piso de contraste. O branco fica em 3,96:1 e o quase-preto em 4,49:1, contra o piso de 4,5:1, por isso esse degrau serve só de fundo decorativo ou de traço.

Razão de contraste é o número que compara a tinta com o fundo, como a diferença entre giz branco no quadro-negro e o mesmo giz na parede clara. Texto que se aproxima do fundo cansa o olho do cliente, e quem não enxerga bem desiste da compra antes de achar o botão.

A escala inteira, de 50 a 950, precisa da razão medida degrau a degrau, nos dois temas, com uma regra de corte escrita para o agente obedecer.

Essa escala nasce em OKLCH (o jeito de escrever cor por claridade, intensidade e matiz, como afinar um instrumento por altura, volume e timbre). Nela a claridade cresce em linha reta: cada degrau de 50 a 950 escurece o mesmo tanto para o olho, o que o código hexadecimal não garante.

Com color-mix(in oklch, ...) o agente deriva o tema inteiro de uma cor só, no lugar de dezenas de valores fixos. Medir cada degrau contra branco e contra o texto quase-preto revela onde nenhuma das duas tintas passa. No meio da escala, no 500, os dois reprovam.

A função contrast-color() escolhe sozinha entre preto e branco contra a cor que você passa, e poupa a decisão manual em cada botão. Ela chegou ao estágio Baseline Newly Available em 10 de abril de 2026.

Newly Available quer dizer que os navegadores atuais já trazem o recurso e os antigos ainda não. Por isso ela vai atrás de uma consulta de suporte, com a tinta fixa como reserva, e o fallback entra junto, nunca depois.

A função compara preto puro e branco puro, e não escolhe entre as tintas quase pretas e quase brancas da marca. Mesmo aprovada na razão, ela pode deixar texto pequeno difícil de ler. Confira tamanho, peso e fundo além da medida, e ajuste o token quando a leitura continuar ruim.

Outra função, light-dark(), guarda dois valores numa declaração só, um para cada tema, e exige color-scheme declarado no bloco. Sem essa declaração ela é ignorada em silêncio, e o cartão fica com a cor do tema errado.

O tema escuro troca o papel dos tokens (o valor de cor guardado com nome, como a etiqueta na lata de tinta). O que era fundo vira tinta, a razão muda junto, e a medição se repete nos dois temas.

Sobre fundo escuro, texto claro parece mais fino que o mesmo texto escuro sobre claro, e o peso da fonte sobe um degrau para compensar.

Três linhas resumem a regra da casa para qualquer figura que o agente desenhe. Tinta e fundo ficam fortemente contrastantes nos dois temas, e a fonte tem 14 px ou mais no viewBox do SVG. Todo texto leva fill próprio, porque ele não herda a cor do site, e o auditor de contraste do navegador é conferido antes de concluir.

A régua de corte cabe numa linha. Texto sobre cor vai no degrau 600 ou mais escuro, com tinta branca, ou no 300 ou mais claro, com tinta quase-preta. O 400 passa com quase-preto em 6,67:1 e o 600 passa com branco em 5,51:1; entre eles fica o 500, reservado a fundo decorativo e traço.

Esse piso de 4,5:1 vale para texto. Componente de interface e elemento gráfico essencial exigem 3:1, pelo critério 1.4.11 da WCAG. A borda do campo e a linha do gráfico entram nessa conta. Esse é o item mais esquecido no design system, ou seja, o conjunto de peças e cores reaproveitadas no site inteiro.

Numa clínica com portal do paciente, a cor da marca no degrau 500 vira fundo do botão de agendar, com texto branco. Esse par fica em 3,96:1 e reprova o piso, então o paciente idoso não acha o botão e liga para a recepção.

Baixar o fundo para o degrau 600, que passa em 5,51:1 com texto branco, devolve legibilidade sem mudar a identidade. O mesmo botão é medido de novo no tema escuro, porque o fundo da página mudou de papel.

Peça ao agente a escala de 50 a 950 em OKLCH, com a razão de contraste de cada degrau medida nos dois temas. A medida vale contra branco e contra o texto escuro, e o degrau do meio fica proibido para texto, mesmo com contrast-color().

Só aprove a tela quando o auditor de contraste do navegador não apontar par abaixo de 4,5:1 em nenhum dos dois temas.

Guia prático: auditoria técnica com nota antes de corrigir

Corrigir contraste tela por tela, conforme alguém reclama, nunca termina. O comando audit da skill Impeccable inverte a ordem: primeiro um relatório do que é mensurável no código, com nota, e só depois a correção pela gravidade. Ele não altera nenhum arquivo.

A nota soma cinco dimensões, cada uma de 0 a 4: acessibilidade, desempenho, tema, responsividade e integridade da implementação. A última roda o detector de antipadrões e confere cada achado em contexto. O total vai até 20. De 18 a 20 a tela pede só acabamento; de 14 a 17 há dimensões fracas a tratar; de 10 a 13 o trabalho é significativo; de 6 a 9 a tela pede reforma ampla; de 0 a 5 o estado é crítico.

Cada problema recebe uma gravidade de P0 a P3. P0 impede a pessoa de concluir a tarefa e é corrigido na hora. P1 causa dificuldade séria ou descumpre o nível AA das diretrizes de acessibilidade da web (WCAG), e é corrigido antes de publicar. P2 incomoda e tem contorno, e fica para a próxima rodada. P3 é acabamento sem impacto real, e entra se sobrar tempo. O roteiro avisa contra o excesso de P3: uma lista longa de detalhes esconde os dois problemas que importam.

Guia prático: testar a página com o movimento reduzido ligado

Pedir acessibilidade ao agente não garante acessibilidade. Na biblioteca de 1.451 componentes de interface estudada em 07/10/2026, o pedido de cada componente exige respeitar a preferência por menos movimento. Nos 815 exemplos de uso que vêm preenchidos, essa preferência aparece em zero. Foco visível aparece em 8 e texto para leitor de tela em 4.

Os templates de site repetem o quadro. Só 14 dos 51 tratam a preferência por menos movimento, e nenhum dos 12 que usam WebGL ou cena 3D faz isso. Outros sinais medidos: 25 tiram o contorno de foco sem pôr outro no lugar, 26 usam rótulos de 9 a 11 px e 29 têm algum atributo aria.

A preferência existe no sistema de todo aparelho: no Windows 11 é desligar os efeitos de animação em Acessibilidade, no iPhone é ligar Reduzir Movimento, no Android é remover animações. Quem sente tontura com movimento liga essa opção e espera que o site respeite. A lição: confie no teste, não na promessa do pedido. Ligue a opção no seu aparelho uma vez por entrega e deixe um teste automático repetir a checagem.

Aplicar os recursos ao projeto