Framework · Design systems · 3 min de leitura
Modelo de tokens em três níveis
Tokens primitivos guardam valores brutos, tokens semânticos dizem para que um valor serve, tokens de componente nomeiam um espaço em um componente, e aliases ligam os três em uma só direção. Assim um modo, um rebrand ou uma segunda marca mudam um elo, e não todos os componentes.
Um valor bruto com nome neutro. Diz o que é, não para que serve.
color.blue.600 = #1F5FAEUm propósito que aponta para um primitivo. Modos e marcas mudam este elo.
color.action.primaryUm espaço em um componente. Crie só se ele puder mudar.
button.primary.backgroundbutton.primary.background → color.action.primary → color.blue.600
Use quando
- Você está montando os tokens de um sistema novo, ou levando uma biblioteca de estilos para variáveis.
- Modo escuro, uma segunda marca ou um ajuste de densidade estão no roadmap, e hoje os componentes usam cores brutas.
- A lista de tokens passou de mil nomes e ninguém sabe quais usar.
Como usar
- Liste os valores brutos como primitivos. Cores por matiz e degrau, espaço e raio como escalas. Dê nomes neutros que digam o que o valor é, nunca para que serve. Resultado: o conjunto de primitivos, por exemplo
color.blue.600 = #1F5FAE,space.4 = 16px. - Nomeie as decisões como tokens semânticos. Para cada propósito da interface (a ação principal, o texto do corpo, uma superfície discreta, perigo), crie um token que aponta para um primitivo. Resultado: o conjunto semântico, por exemplo
color.action.primary → color.blue.600. - Aponte os componentes para os semânticos. Toda cor que um componente usa lê um token semântico. Procure na biblioteca do Figma e no código cores primitivas usadas direto, e troque. Resultado: nenhum componente lê uma cor primitiva.
- Crie tokens de componente só onde o espaço pode mudar. Pergunte: "Esse componente vai precisar algum dia de um valor diferente do semântico para o qual aponta?" Se sim, crie
button.primary.background → color.action.primary. Se não, pule. Resultado: uma lista curta de tokens de componente, cada um com um motivo. - Coloque os modos no nível semântico. Modo escuro, marcas e densidade mudam para onde os tokens semânticos apontam. Os primitivos mantêm seus valores e os tokens de componente mantêm seus elos. Resultado: uma coluna semântica por modo.
- Confira a direção de cada alias. Componente aponta para semântico, semântico aponta para primitivo. Um primitivo nunca aponta para nada. Resultado: uma corrente que você lê de qualquer componente até um valor bruto.
Exemplo prático
O Harbour, design system da empresa de balsas Tidewater, tem um botão principal. O token do fundo é button.primary.background, que aponta para color.action.primary, que aponta para color.blue.600 no modo claro e color.blue.400 no modo escuro.
| Nível | Modo claro | Modo escuro |
|---|---|---|
Componente: button.primary.background |
→ color.action.primary |
→ color.action.primary |
Semântico: color.action.primary |
→ color.blue.600 |
→ color.blue.400 |
Primitivo: color.blue.600 |
#1F5FAE |
#1F5FAE |
Quando o modo escuro saiu, só a linha semântica mudou. O token e o código do botão ficaram iguais. Os cards não ganham token de componente para o padding: eles leem space.inset.md direto, porque ninguém vai tematizar o padding do card sozinho.
Cuidado com
- Componentes lendo primitivos.
button.background → color.blue.600funciona até o primeiro modo. Aí cada componente precisa de mudança no código. - Nomes semânticos que descrevem aparência.
color.blue-buttoné um primitivo disfarçado. No modo escuro ele já não é aquele azul. - Um token de componente para cada propriedade. Milhares de tokens em que ninguém se acha. Crie um só quando o espaço puder mudar.
- Consertar um uso mudando um primitivo. Mudar
color.blue.600para corrigir uma tela muda todo token que aponta para ele.
Modelo
Preencha uma linha por token que você criar e guarde a tabela junto do arquivo de tokens.
Nível | Nome | Aponta para / valor | Por que existe
------------|-----------------------------|------------------------|------------------------------
Primitivo | color.blue.600 | #1F5FAE | degrau da paleta
Semântico | color.action.primary | {color.blue.600} | a ação principal, todos os produtos
Semântico | modo escuro | {color.blue.400} | contraste em superfícies escuras
Componente | button.primary.background | {color.action.primary} | pode mudar por marca no futuro
Conferir: nenhum componente lê uma cor primitiva? sim / não
Conferir: todo alias aponta um nível para baixo? sim / não
- Expressive Design SystemsYesenia Perez-CruzLivro · 2019 (Amazon)
- Design SystemsAlla KholmatovaLivro · 2017 (Amazon)
- Design Tokens Format Module 2025.10DTCG (site externo)
- Overview of variables, collections, and modesFigma Help (site externo)
Os links "Ver na Amazon" são de afiliado: como associado, recebo por compras qualificadas, sem custo a mais para você.