Tokens de design: a base que mantém a interface consistente entre produtos

A mesma cor em doze tons diferentes

Tokens de design são valores de design com nome, como uma cor, um espaçamento ou um raio de borda, guardados em um único lugar em vez de repetidos em cada tela. Design e código leem o mesmo valor. A mesma cor deixa de aparecer em tons ligeiramente diferentes, e trocar uma decisão visual não exige procurar valor por valor.

"Doze tons" é uma imagem, não uma contagem. O que importa é o padrão: o laranja do botão, o do ícone e o do destaque do relatório deveriam ser o mesmo laranja, e quase nunca são.

Como a divergência nasce

Ninguém decide criar doze tons. Eles se acumulam.

Alguém copia a cor do arquivo de design com um conversor e perde uma casa. Outra pessoa ajusta o valor "só nesta tela" porque o fundo estava diferente. Um módulo novo nasce a partir de um antigo, com o CSS que já estava lá. O arquivo de design também envelhece: a cor muda nele, e o código continua com a anterior.

Cada passo é razoável sozinho. A soma é um produto em que o mesmo elemento parece um pouco diferente conforme a tela.

O que ela custa

O custo aparece em três lugares.

• Na aparência. O usuário não sabe apontar o problema, mas percebe que o sistema parece feito por várias mãos.
• Na manutenção. Mudar a cor principal vira uma busca por valores espalhados, sempre com a dúvida de ter esquecido algum.
• Na acessibilidade. Uma cor corrigida em uma tela continua errada nas outras, porque ninguém sabe onde mais ela foi escrita.

O que é um token e o que ele não é

Um token é a menor unidade de uma decisão visual com nome. Em vez de escrever o valor em cada lugar, o código escreve o nome, e o valor mora em um só ponto.

Valor com nome, em vez de valor solto

Veja um exemplo ilustrativo, com valores neutros, em CSS:

/* Exemplo ilustrativo */
:root {
  --cor-destaque: #1a5fb4;
  --espaco-medio: 16px;
  --raio-borda: 4px;
}

.botao {
  background: var(--cor-destaque);
  padding: var(--espaco-medio);
  border-radius: var(--raio-borda);
}

Se a decisão mudar, o valor muda uma vez, na definição. Todo elemento que usa o nome acompanha.

O nome também carrega intenção. --cor-destaque diz mais para quem lê o código do que um código hexadecimal solto.

Token não é componente nem biblioteca

Token é a matéria-prima. Componente é a peça montada com ela: um botão, um campo, um menu. Uma biblioteca é o conjunto de peças reunido para ser reutilizado.

Dá para ter tokens sem biblioteca, e é um bom começo. O contrário é frágil: componentes que escrevem cor e espaçamento à mão não têm token por baixo, só a aparência de sistema.

Tokens de base e tokens por função, como opção

Muitas equipes separam dois níveis. Os tokens de base guardam a paleta e as escalas, como um azul ou um espaçamento de 16 pixels. Os tokens por função dizem para que o valor serve, como "cor do texto principal" ou "fundo de alerta", e apontam para um token de base.

É uma opção de organização, não uma norma. Um produto pequeno pode viver bem com um nível só. A separação ajuda quando surge a necessidade de trocar o papel de uma cor sem mexer na paleta, como acontece quando o produto ganha um segundo tema.

Tokens e contraste acessível

Contraste é um dos pontos em que a divergência de cor mais machuca, e onde o token mais ajuda. Vale entender antes o que a norma pede.

Contraste é decisão de par de cores

Contraste não é propriedade de uma cor, e sim da relação entre duas: texto e fundo, ícone e superfície, borda e vizinhança. Por isso a decisão é sobre pares.

A WCAG 2.2, recomendação do W3C de 12 de dezembro de 2024 (versão consultada em 29 de outubro de 2026), trata disso em dois critérios de nível AA:

• o critério 1.4.3, Contrast (Minimum), pede razão de contraste de pelo menos 4,5:1 para texto, e de pelo menos 3:1 para texto grande, com exceções previstas, como logotipos e elementos inativos;
• o critério 1.4.11, Non-text Contrast, pede pelo menos 3:1 contra as cores adjacentes para componentes de interface e objetos gráficos necessários para entender o conteúdo, também com exceções.

Os dois dizem respeito a combinações de cor. Um token isolado não passa nem reprova.

Corrigir no token em vez de tela a tela

Quando as cores estão escritas à mão, corrigir um contraste ruim é uma caçada: achar cada ocorrência, trocar, conferir de novo. Sempre sobra uma tela que ninguém lembrou.

Com token, o par problemático tem um nome. Ajusta-se o valor na definição, e todo lugar que usa o nome recebe a correção. Também fica mais fácil nomear os pares aprovados, como "texto principal sobre fundo da página", para que a equipe use combinações já verificadas em vez de improvisar.

O que o token não garante

Token não garante acessibilidade. Ele organiza onde o valor está, mas não diz se o valor é bom.

Um token pode guardar uma cor com contraste insuficiente e espalhá-la com perfeição por todo o produto. Além disso, contraste é só uma parte do que a WCAG cobre: foco visível, texto alternativo, navegação por teclado e leitor de tela continuam pedindo teste. Para o que isso exige em sistemas públicos, veja o que é o eMAG.

Do arquivo de design ao código

O ganho maior dos tokens é mais organizacional do que técnico: designers e desenvolvedores passam a falar com o mesmo vocabulário.

Uma fonte, dois consumidores

No arranjo ideal, o valor é definido uma vez e consumido por dois lados. O arquivo de design usa o nome para montar as telas, e o código usa o mesmo nome para estilizá-las. Quando a decisão muda, muda na fonte, e os dois lados podem receber a atualização.

Isso depende de uma regra de convivência: ninguém escreve valor solto em nenhum dos lados. Basta uma exceção "rápida" para a divergência voltar. É esse acordo, mais do que qualquer ferramenta, que sustenta o sistema.

Organizar esse acordo, junto com as peças que usam os tokens, é o trabalho de um design system.

Temas e identidade visual em código

Com os valores centralizados, o tema deixa de ser um retrabalho. Um tema escuro, uma variação para outro órgão ou uma atualização da identidade visual passam a ser, em boa parte, um novo conjunto de valores para os mesmos nomes.

A condição é que o código use os nomes de ponta a ponta. Cor escrita à mão fica de fora da troca e aparece no meio da tela como uma peça fora do lugar. Também vale conferir o contraste de cada tema, porque um par aprovado em um deles não está aprovado no outro.

Por onde começar num produto que já existe

Quase ninguém parte do zero. O caminho mais seguro costuma ser gradual:

1. Levante os valores que existem. Liste as cores, os espaçamentos e as fontes realmente usados no código. O resultado costuma surpreender.
2. Reduza a lista. Decida quais valores ficam, agrupando os quase iguais, e dê nome a eles.
3. Troque primeiro o que mais se repete. A cor principal e o espaçamento-base rendem mais.
4. Combine a regra. A partir daqui, valor novo entra como token, e não como número solto.

Esse trabalho mexe na estrutura do código, e é o tipo de decisão tratada na frente de arquitetura de front-end. Para ver como os tokens se encaixam em um padrão oficial de governo, leia sobre o Padrão Digital de Governo.

Se a mesma cor aparece em tons diferentes no seu produto, vale começar pelo levantamento. A Evo Tech trabalha com design systems e arquitetura de front-end. Fale com o nosso time e descreva o seu produto.