Marcus Andrey Estudo
Read in English Biblioteca

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.

1Primitivo

Um valor bruto com nome neutro. Diz o que é, não para que serve.

color.blue.600 = #1F5FAE
2Semântico

Um propósito que aponta para um primitivo. Modos e marcas mudam este elo.

color.action.primary
3Componente

Um espaço em um componente. Crie só se ele puder mudar.

button.primary.background

button.primary.background → color.action.primary → color.blue.600

Três níveis, do valor bruto ao componente, ligados por aliases que sempre apontam um nível para baixo.

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.600 funciona 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.600 para 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
Fonte
Sintaxe de alias: W3C Design Tokens Community Group, Format Module 2025.10. Os nomes dos níveis variam por sistema (primitivo, semântico, componente é o conjunto mais comum).
Onde encontrar
Design systems na prática: Níveis de tokens › Três níveis, uma corrente

Os links "Ver na Amazon" são de afiliado: como associado, recebo por compras qualificadas, sem custo a mais para você.

Salvo só neste dispositivo.

↑ ↓ para mover · Enter para abrir · Esc para fechar