Uma Introdução Simples a Design Tokens

Se você já atualizou uma cor de marca e passou a próxima hora caçando cada #3B82F6 hardcoded espalhado pela sua folha de estilos, você já entende o problema que os design tokens resolvem. Este artigo explica o que são design tokens, como eles diferem de simples variáveis CSS e como começar a usá-los no seu fluxo de trabalho de estilização frontend.

O Que São Design Tokens?

Design tokens são valores nomeados e reutilizáveis que representam suas decisões de design — coisas como cores, espaçamento, tipografia, raios de borda e sombras. Em vez de escrever padding: 16px diretamente em um componente, você referencia um token como space-4 que armazena esse valor.

Em sua essência, todo design token é apenas um nome associado a um valor. Mas, como metodologia, eles vão além disso. O Design Tokens Community Group (DTCG), um Community Group do W3C trabalhando em direção a uma especificação compartilhada, os descreve como uma forma de expressar decisões de design em um formato agnóstico de plataforma, para que possam ser compartilhadas entre diferentes disciplinas, ferramentas e tecnologias.

Essa parte do “agnóstico de plataforma” é importante. As mesmas definições de tokens podem ser transformadas em CSS custom properties para a web, constantes Swift para iOS ou valores XML para Android — tudo a partir de uma única fonte de verdade.

Categorias Comuns de Design Tokens

A maioria dos design systems organiza os tokens nestas categorias:

• Cor — paleta da marca, cores de texto, fundos, bordas
• Espaçamento — valores de padding, margin e gap
• Tipografia — família de fonte, tamanho, peso, altura da linha
• Border radius — arredondamento de cantos para componentes
• Sombra — efeitos de elevação e profundidade

Tokens Primitivos vs. Tokens Semânticos

Essa distinção é um dos conceitos mais úteis ao trabalhar com tokens de design system.

Tokens primitivos (também chamados de tokens base ou globais) são valores brutos sem uso implícito:

{
  "color-blue-500": { "$value": "#3B82F6", "$type": "color" },
  "space-4": { "$value": "16px", "$type": "dimension" }
}

Tokens semânticos referenciam primitivos e adicionam intenção. Eles dizem onde usar um valor, não apenas o que ele é:

{
  "color-action-primary": { "$value": "{color-blue-500}", "$type": "color" },
  "spacing-component-padding": { "$value": "{space-4}", "$type": "dimension" }
}

Quando você altera color-blue-500, todo token semântico que aponta para ele é atualizado automaticamente. Esse é o real poder do sistema.

Design Tokens vs. Variáveis CSS

Variáveis CSS e design tokens são relacionados, mas não são a mesma coisa.

Design tokens são a fonte. Variáveis CSS frequentemente são a saída. Uma ferramenta como o Style Dictionary pega suas definições de tokens e as transforma em qualquer formato que cada plataforma precise.

Um Exemplo Prático Simples

Aqui está um pequeno conjunto de tokens definidos usando a sintaxe no estilo DTCG:

{
  "color-blue-500": { "$value": "#3B82F6", "$type": "color" },
  "color-text-primary": { "$value": "{color-blue-500}", "$type": "color" },
  "space-4": { "$value": "16px", "$type": "dimension" }
}

Após processá-los pelo Style Dictionary, sua saída CSS fica assim:

:root {
  --color-blue-500: #3B82F6;
  --color-text-primary: var(--color-blue-500);
  --space-4: 16px;
}

Agora seus componentes usam var(--color-text-primary) em vez de um valor hexadecimal hardcoded. Altere o token uma vez e atualize em todos os lugares.

No lado do design, as variáveis do Figma seguem o mesmo padrão de primitivo para semântico, tornando mais fácil manter design e código alinhados.

Comece Pequeno, Escale Intencionalmente

Você não precisa de um sistema completo de tokens no primeiro dia. Comece com primitivos de cor e espaçamento, adicione uma camada semântica conforme os padrões emergem e introduza ferramentas quando o processo manual se tornar um gargalo.

Conclusão

Design tokens não são apenas uma forma de organizar CSS — eles são uma linguagem compartilhada entre designers e desenvolvedores. Uma vez que essa linguagem esteja estabelecida, a consistência em todo o seu produto deixa de ser algo que você impõe manualmente e passa a ser algo que seu sistema gerencia por você.

Perguntas Frequentes

Truly understand users experience

See every user interaction, feel every frustration and track all hesitations with OpenReplay — the open-source digital experience platform. It can be self-hosted in minutes, giving you complete control over your customer data. . Check our GitHub repo and join the thousands of developers in our community..