Contraste e design tokens: uma abordagem sistemática
Garantir contraste acessível em escala requer mais que checar pares individualmente — requer um sistema de tokens com contraste embutido na definição.
O problema de garantir contraste em escala
Verificar contraste par a par — cor de texto vs. cor de fundo — funciona para 10 combinações. Com um design system real (múltiplas superfícies, estados, temas claro/escuro), as combinações explodem para centenas. Checar manualmente não é sustentável.
A solução é embutir o contrato de contraste na própria nomenclatura dos tokens. Um token chamado `--text-on-surface-primary` já comunica seu contexto de uso. Se você sempre usa `--text-on-surface-primary` sobre `--surface-primary`, você precisa validar apenas esse par — e automação garante que o par nunca quebre.
Estrutura de tokens semânticos com contraste garantido
A estrutura de tokens deve ter dois níveis: primitivos (valores raw de cor) e semânticos (papéis de uso). Tokens semânticos são validados em build time para garantir que os pares atendam WCAG AA (4,5:1 para texto normal, 3:1 para texto grande e UI components).
No Tailwind v4, CSS custom properties servem como tokens semânticos. Defina os pares no `src/index.css` e adicione um script de validação que lê as variáveis e calcula o ratio usando a fórmula de contraste relativa de luminância do WCAG.
/* tokens semânticos com par garantido */
@theme {
/* Superfície primária */
--color-surface-primary: #01060d;
--color-text-on-primary: #f8f9fc; /* ratio ~17:1 ✓ */
/* Superfície de card */
--color-surface-card: rgba(255,255,255,0.05);
--color-text-on-card: #c8d4e0; /* ratio ~8.2:1 ✓ */
/* Accent com legibilidade */
--color-accent-cyan: #02c5d3;
--color-text-on-cyan: #01060d; /* ratio ~9.4:1 ✓ */
}Automatizando a validação em CI
Uma biblioteca como `wcag-contrast` ou `culori` calcula o contraste entre duas cores. Crie um script Node.js que importa seus tokens, calcula os ratios de cada par semântico e falha o build se qualquer par cair abaixo de 4,5:1.
Integre esse script como step no GitHub Actions antes do build principal. Assim, qualquer PR que altere tokens de cor passa pela validação automática. Combine com um snapshot visual (Storybook Chromatic ou Percy) para detectar mudanças visuais não intencionais.
Atenção
WCAG 2.2 mantém os ratios de contraste do 2.1. O WCAG 3.0 (ainda em rascunho) propõe o algoritmo APCA, mais preciso para fontes variáveis e pesos diferentes. Monitore a progressão antes de migrar sua base.
Portodev Studio
Consultoria e engenharia digital · Jul 2026
Continue lendo
Acessibilidade7 min de leitura · Ago 2026
Hierarquia semântica de headings em SPAs
SPAs frequentemente quebram a hierarquia de headings durante navegação client-side. Veja como auditar e corrigir sem mudar o design visual.
Ler o artigo
Para quem decide7 min de leitura · Out 2026
Quanto custa um site lento (e como descobrir no seu caso)
Lentidão não aparece no extrato, mas aparece no funil: visita que desiste antes de carregar, formulário que não é enviado, anúncio pago que leva a uma tela em branco. Veja como medir o custo no seu site.
Ler o guia
Para quem decide8 min de leitura · Out 2026
GEO: como fazer sua empresa aparecer nas respostas do ChatGPT
Cada vez mais gente pergunta a um assistente de IA antes de procurar no Google. GEO é o trabalho para sua empresa ser entendida, lembrada e citada nessas respostas. Veja o que já dá para fazer.
Ler o guiaEsses padrões no seu produto.
Em 30 minutos mapeamos como esses conceitos se aplicam ao contexto do seu projeto real.