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 interface funcionando por teclado, leitor de tela e contraste suficiente, sem depender do mouse nem de enxergar bem. A lei já cobra isso no Brasil, na Europa e nos Estados Unidos, e o alvo técnico deste curso é a WCAG 2.2 no nível AA.

No Brasil, a ABNT NBR 17225 é a norma técnica de acessibilidade digital, publicada em 11 de março de 2025. Ela se apoia na WCAG, a norma internacional usada em auditoria e em ação judicial.

Na União Europeia, a obrigação de aplicar a diretiva de acessibilidade começou em 28 de junho de 2025, para comércio eletrônico, banco ao consumidor e livro digital.

Essa diretiva ainda tem transições correndo. O serviço pode manter até 28 de junho de 2030 os produtos que já usava legalmente, e a microempresa de serviço está dispensada dos requisitos. Nenhuma das duas exceções alcança o site novo que você publica agora.

O Ministério Público Federal ajuizou ação civil pública citando o Tribunal de Contas da União: entre 366 sites públicos federais verificados, 88,5% foram classificados como ruins em acessibilidade. Uma liminar de 7 de julho de 2026 deu 180 dias à União, sob multa diária de dez mil reais, decisão provisória e recorrível.

A regra do Departamento de Justiça dos Estados Unidos, publicada em 24 de abril de 2024, usa a WCAG 2.1 no nível AA para governos estaduais e locais. Agências federais seguem a Section 508, alinhada à WCAG 2.0 AA desde 18 de janeiro de 2018.

A WCAG 3.0 segue em rascunho de trabalho, sem status 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, e as duas se corrigem na raiz. O piso é 4,5:1 no texto normal e 3:1 no texto grande. Corrija pela cor guardada com nome nos tokens do site, porque o ajuste se propaga a todos os componentes irmãos.

O axe é o verificador que roda no navegador e aponta o elemento exato e a regra quebrada. Instale a extensão axe DevTools, aperte F12 e rode a análise nos dois temas, com menu e diálogo abertos. O verificador 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; se numa parada você não sabe onde está, 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. Abrir o filtro só com Enter e fechá-lo só com Esc, sem tocar no mouse, 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 testa a tela como um usuário, serve de portão na esteira de publicação.

A cobertura tem dois números que costumam ser confundidos. O teste automatizado alcança de 30% a 40% dos critérios de sucesso da norma. Os 57% que a Deque publica medem outra coisa: o volume de problemas encontrados.

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

O axe-core é também o motor do relatório de acessibilidade 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 tem 24 px de piso 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.

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. Eles precisam de uma camada paralela em HTML com atributos ARIA, os rótulos que descrevem cada elemento, e o agente só a escreve se você pedir.

A skill frontend-design, publicada pela Anthropic no repositório anthropics/skills, fixa um piso de qualidade que o agente entrega sem anunciar. O piso tem cinco itens: tela responsiva até o celular, foco de teclado visível, menos movimento respeitado, contraste correto e paleta harmoniosa.

Com a skill carregada, as checagens desta aula viram ponto de partida do trabalho do agente, e a sua revisão confere em vez de ensinar. Ela se instala uma vez por máquina e vale para todo projeto.

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 inteira só com Tab, Shift+Tab, Enter e Esc. Libere a publicação apenas com o axe-core no Playwright como portão da esteira.

Meça o contraste degrau a degrau, nos dois temas

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. Esse degrau nunca recebe texto e serve só de fundo decorativo ou de traço.

Razão de contraste é o número que compara a tinta com o fundo, e o piso do texto normal é 4,5:1. A escala completa, 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.

A 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. Ela chegou ao estágio Baseline Newly Available em 10 de abril de 2026, no Chrome e no Edge 147, no Firefox 146 e no Safari 26.

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, mas não escolhe entre as tintas quase pretas e quase brancas da marca. Mesmo aprovada na razão de contraste, ela pode deixar texto pequeno difícil de ler. Confira tamanho, peso e cor de 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, e esse é o item mais esquecido no design system da casa.

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.

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.