AA vs AAA: o que esses níveis realmente significam e por que seu botão desabilitado está falhando nos dois terminou com uma instrução específica: quando uma cor falha AAA num contexto, documente a exceção no próprio token, não ao redor dele. Essa instrução assume que a cor que chega na tela já é um token, algo como var(--color-accent) que o navegador consegue resolver, e não uma string hex digitada uma vez numa folha de estilo e copiada em todo lugar que precisou dela depois. A maioria dos design systems não chega nessa premissa com segurança. Um arquivo de tokens é criado, alguns componentes são construídos contra ele, e o resto do código continua entregando valores literais que coincidem com os tokens, não que referenciam eles. Esta é a auditoria pra encontrar exatamente onde está essa brecha, e a configuração que impede que ela reabra.

01

O que é um design token

Um design token é uma variável nomeada que guarda uma decisão de design uma única vez, pra que toda plataforma que precisa dessa decisão leia de uma única fonte em vez de reimplementá-la. O termo tem uma origem específica: Jina Anne o cunhou em 2014 enquanto construía o Salesforce Lightning Design System, onde os mesmos valores de cor, espaçamento e tipografia precisavam chegar a CSS, iOS e Android, cada um com sua própria sintaxe pra variável. Numa entrevista de 2019, ela fez um ponto que vale manter em mente pra qualquer time adotando o padrão: design tokens são uma metodologia, não um formato de arquivo. Chamá-los de "só variáveis" é como chamar design responsivo de "só media queries", e isso ignora a disciplina real por trás dos dois.

Essa disciplina agora tem um formato de troca compartilhado por trás dela. O Design Tokens Community Group do W3C publicou a primeira versão estável do seu Design Tokens Format Module em outubro de 2025, dando a ferramentas que antes falavam formatos de token proprietários próprios um formato de arquivo comum pra ler e escrever. Nada dessa infraestrutura faz diferença sozinha se os valores que ela produz nunca chegam na folha de estilo que o navegador realmente carrega. Essa brecha, entre um token existir e um token ser usado em todo lugar onde a decisão de design que ele representa aparece, é o assunto do resto deste artigo.

02

Onde valores hardcoded se escondem, mesmo com um arquivo de tokens

2.1 Copiado direto do painel de inspeção

A fonte mais comum não tem nada a ver com disciplina de engenharia. Alguém abre o painel de inspeção num componente, copia uma string hex, e ela vai pra folha de estilo exatamente como foi copiada: #f3b02e em vez de var(--y). Renderiza de forma idêntica à versão que usa o token. Nada no resultado visual conta pra ninguém que aquilo não é o token, e é exatamente por isso que sobrevive à revisão.

2.2 Estilos inline e embeds de terceiros

Um atributo style="" escrito à mão pula a camada de tokens inteira, e o mesmo vale pra um escrito por JavaScript em tempo de execução, que é o que a maioria dos widgets de terceiros faz: um formulário de newsletter, um chat, um embed de agenda. Eles renderizam em páginas com a cor da marca enquanto leem zero dos tokens dessa marca, porque o script que os construiu não tem acesso às custom properties CSS da página hospedeira a menos que alguém conecte isso explicitamente.

2.3 CSS legado transportado

Um redesign raramente começa do zero. Regras antigas são carregadas pra nova folha de estilo por completo durante a migração, valores hex inclusos, porque reescrever cada declaração à mão na mesma semana de um rebranding não é realista. A intenção é sempre voltar e substituir depois. A auditoria da seção 3 é o que transforma essa intenção em algo verificável em vez de apenas aspiracional.

2.4 Arquivos SVG de origem

Um ícone exportado com fill="#f3b02e" embutido no próprio path carrega um valor hardcoded que vive fora do arquivo CSS que o resto da auditoria verifica. fill="currentColor", ou uma custom property CSS definida na tag <svg>, permite que o ícone herde qualquer contexto de cor ao redor dele. Um fill hardcoded não permite isso, e continua invisível pra quem está varrendo só arquivos .css atrás do problema.

03

A auditoria de cinco comandos

Nenhuma das quatro fontes acima aparece ao inspecionar um componente renderizado, todas parecem corretas no navegador. Elas aparecem ao buscar direto no código-fonte. Os cinco comandos abaixo são a mesma auditoria que este projeto roda em todo código antes de qualquer coisa ir ao ar, adaptada pra qualquer projeto com um bloco de tokens em :root e uma separação entre .css, .html e .svg.

  1. grep -rn 'style="' --include=*.html .

    Encontra: todo atributo de estilo inline, incluindo os adicionados pra "só resolver logo" num prazo apertado.

  2. grep -rnE '#[0-9a-fA-F]{3,8}\b' --include=*.css assets/css/ | grep -v ':root'

    Encontra: valores hex crus vivendo fora do bloco de definição de tokens, os que o navegador resolve direto em vez de por uma custom property.

  3. grep -rnE 'fill="#|stroke="#' --include=*.svg assets/img/

    Encontra: cor hardcoded embutida em arquivos de origem de ícones, o ponto cego da seção 2.4.

  4. grep -rn 'rgba(' assets/css/ | grep -v 'var(--'

    Encontra: valores de transparência inventados na hora em vez de referenciar um token existente como --accent-dim.

  5. grep -rnE '\b[0-9]{2,}px\b' assets/css/ | grep -v 'var(--'

    Encontra: valores de pixel fora da escala de espaçamento e raio. Esse aqui precisa de uma checagem humana, nem todo resultado é um erro (uma borda de 1-2px é CSS legítimo), então trate como uma lista curta pra revisão, não uma reprovação automática.

Cinco comandos, cinco lugares diferentes onde o mesmo problema se esconde. Sem linter, sem build step, sem plugin. Os cinco rodam num terminal em menos de trinta segundos.

04

Transformando isso num bloqueio, não numa limpeza pontual

Uma auditoria grep rodada uma vez resolve a dívida de hoje e não diz nada sobre o pull request de amanhã. Duas ferramentas transformam os mesmos padrões acima em algo que reprova um build em vez de esperar ser lembrado.

A regra color-no-hex do Stylelint rejeita qualquer valor de cor em hex no momento do lint, os mesmos valores que o comando 2 acima encontra manualmente. declaration-property-value-disallowed-list vai além e permite que um time proíba padrões específicos de propriedade e valor em todo o projeto, por exemplo bloqueando qualquer declaração de color ou background que combine com /^#/ fora do próprio arquivo de tokens. Conectada ao CI, qualquer uma das duas regras transforma um valor hardcoded num pull request reprovado em vez de um comentário de revisão esquecido.

A outra metade do problema, o mesmo valor precisando chegar em CSS, iOS e Android a partir de uma única definição, é pra isso que o Style Dictionary foi construído. A Amazon abriu o código dele em 2017 como um sistema de build que pega um único arquivo de origem de tokens e gera saídas no formato que a folha de estilo de cada plataforma realmente precisa. Um token que só existe no painel de exportação de uma ferramenta de design não está distribuído, está documentado. Um build step como o Style Dictionary é o que faz "um valor, em todo lugar" ser verdade além do site, não só verdade em princípio.

05

Tokens sem hierarquia são hex renomeado

Passar na auditoria da seção 3 responde se um valor é um token. Não responde se o sistema de tokens está construído corretamente. O detalhamento de arquitetura de tokens de Nathan Curtis, de 2016, na EightShapes, estabeleceu a hierarquia que a maioria dos sistemas ainda usa hoje: um token primitivo guarda um valor cru, um token semântico nomeia a função que esse valor cumpre, e um componente só lê a camada semântica, nunca o primitivo diretamente.

Valor cru

#f3b02e

Token primitivo

--y: #f3b02e;

Token semântico

--accent: var(--y);

Componente

.btn-primary { background: var(--accent); }

Quatro camadas, um valor. Um componente só lê a camada semântica. Ele nunca precisa saber que o valor cru embaixo dela existe.

Pule essa hierarquia e um sistema de tokens vira uma ferramenta de buscar-e-substituir vestida de design system. Uma lista plana de tokens nomeados pelo próprio valor, um hex cru renomeado numa variável mas ainda descrevendo cor em vez de função, significa que um rebranding continua sendo uma passada manual por todo arquivo que o usou. Nada no nome conta pra ninguém qual dos quarenta tokens de cor é seguro repontar e qual outra coisa depende silenciosamente dele.

O arquivo de tokens deste site deixa essa costura visível de propósito. O globals.css define primitivos como --y: #f3b02e e um bloco de aliases semânticos logo abaixo, --accent: var(--y), --text-primary: var(--t1), então um componente estilizado contra .btn-primary { background: var(--accent) } nunca precisa saber ou se importar que o valor cru é âmbar. Essa indireção é o ponto inteiro: mude pra onde --accent aponta uma vez, e todo componente que o lê muda junto, sem um único arquivo de componente ser tocado.

O swatch abaixo é a mesma ideia, ao vivo. Uma caixa lê um token, a outra lê o literal que atualmente coincide com ele. Clique num botão e só uma delas se move.

Lê var(--demo-accent)

token

Lê #f3b02e

literal hardcoded

As duas caixas renderizam a cor idêntica agora. Essa semelhança é exatamente o que torna um valor hardcoded invisível numa revisão, até o accent da marca mudar e só uma caixa responder.

06

O teste de dois minutos

Sem linter, sem build step, só um editor de texto e um navegador antes de um componente ir ao ar.

  1. Busque # no arquivo. Qualquer coisa fora do bloco :root não é um token, não importa qual cor ele coincida.

  2. Abra o dev tools, selecione o elemento, e verifique a origem do valor computado. Um valor rastreável até uma custom property CSS é um token. Um valor que simplesmente está lá, sem nenhuma custom property associada, não é.

  3. Verifique todo <svg> no arquivo. fill e stroke devem ler currentColor ou um var(--...), nunca um hex literal.

  4. Se o mesmo valor cru aparece três vezes num arquivo sem nada conectando as instâncias, esse é o sinal de que deveria ter sido um token desde a primeira linha, não a partir da terceira colada.

Fontes