Adotar um componente compartilhado revelou um bug que o componente não tinha

No começo desta semana encontrei uma lacuna real: a biblioteca de consentimento deste site não tinha como linkar uma política de privacidade a partir do prompt de consentimento, e não existia nenhuma página de privacidade para linkar de qualquer forma. A correção já existia, só não estava aqui ainda: o @vdaluz/astro-opt-in-analytics tinha lançado um componente PrivacyExplainer na v0.4.0, e o vdaluz.com já tinha uma página /privacy funcionando construída em cima dele. Adotar isso devia ser a parte fácil do dia: subir uma versão, configurar algo, copiar uma estrutura de página que já funciona em outro lugar.

E foi fácil, até o momento em que a checagem de acessibilidade discordou.

Tudo o mais dizia que estava tudo bem

astro check: zero erros. Build de produção: limpo, as rotas em inglês e em espanhol geradas corretamente. Snapshot no navegador: cada string no lugar certo, os dois trackers listados em “as ferramentas por trás disso”, o botão de reabrir preferências funcionando, a página igualzinha à sua implementação de referência. Até tirei um screenshot: verde neon sobre preto, exatamente a estética do site, nada visualmente errado a olho nu.

Aí rodei o npm run a11y, porque uma mudança de interface passa por essa checagem independente de quão confiante tudo o mais parece. 12 das 14 URLs passaram. As duas páginas novas não: o axe sinalizou três links como “não distinguíveis do texto ao redor por nenhum outro meio além da cor”.

O sublinhado que estava lá e não estava

Os links em questão tinham class="text-accent underline hover:text-accent-strong", um sublinhado permanente, não um que só aparece no hover. Isso deveria satisfazer a regra de cara. Então por que o axe estava reclamando?

Checei o estilo computado de verdade no navegador em vez de confiar no markup. text-decoration-line: none. A classe estava bem ali no HTML, sem fazer nada.

A causa era uma lacuna sobre a qual eu já tinha lido um aviso mais cedo nessa mesma sessão, sem conectar com o que estava por vir: as próprias notas de agente deste repositório já documentam que o array content do Tailwind precisa listar explicitamente qualquer pacote @vdaluz/* cujos componentes usem classes utilitárias do Tailwind, ou essas classes nunca são geradas, presentes no HTML, ausentes do CSS compilado, nenhum erro de build em lugar nenhum. A config só listava o astro-blog. Os componentes de consent-gate do astro-opt-in-analytics sempre usaram uma folha de estilos com escopo próprio em vez de classes do Tailwind, então isso nunca tinha aparecido antes. O PrivacyExplainer é o primeiro componente desse pacote a usar classes utilitárias puras, e caiu direto numa lacuna que ninguém tinha precisado fechar até então.

O que realmente pegou isso

Nada no checador de tipos, no build ou num screenshot visual teria pegado isso. A classe existia. A página renderizava. As cores estavam certas. A única coisa checando se o sublinhado era de fato estrutural para alguém que não consegue distinguir texto azul-esverdeado de texto cinza foi uma varredura automatizada de acessibilidade, rodando regras reais do axe contra o DOM real renderizado.

Uma linha resolveu isso: adicionar o caminho que faltava ao content. A parte mais difícil foi perceber que “renderiza corretamente aos meus olhos” e “renderiza corretamente, ponto final” não são a mesma afirmação, e só uma delas tem uma checagem que de fato verifica isso.