Marcus Andrey Estudo
Read in English Biblioteca

Design systems · Passo 2 · 7 min de leitura

Níveis de tokens

O token primitivo diz o que um valor é, o semântico diz para que ele serve, o de componente diz onde ele entra. Por que a maioria dos sistemas usa esses três níveis, como os aliases ligam um ao outro, como o Material, o Carbon e o Spectrum dão nome à mesma ideia, e quantos níveis um sistema precisa de verdade.

Um leque de sete amostras preso num rebite, cada tira dividida em pastilhas, como um leque de tintas guarda uma escala inteira. Aponte para uma tira: ela ganha o contorno claro e fica no lugar, enquanto as vizinhas giram em volta do rebite para longe dela, as mais próximas primeiro. Este passo é isso: um token é um degrau com nome numa escala que todos compartilham, então as pessoas escolhem um valor em vez de misturar o seu. Este passo tem cinco lições: camadas de tokens, como nomear tokens, cor, tipografia e espaçamento como tokens, temas e modos, e tokens do Figma ao código.Ilustração: Marcus Andrey, desenhada com Hairline (MIT, Lucas Marques).

Um bom sistema de tokens separa o que um valor é daquilo para que ele serve. #1F5FAE é um azul. "A cor da ação principal" é uma decisão. Se os seus botões apontam direto para o azul, você não consegue mudar um sem mudar o outro. Coloque uma decisão com nome no meio e você consegue: modo escuro, uma nova marca, uma segunda marca, tudo mudando uma ligação só. Essa camada do meio é todo o truque dos níveis de tokens.

O que você vai conseguir fazer depois de ler:

  • Explicar os três níveis: primitivo, semântico, de componente
  • Dizer por que os componentes nunca devem ler primitivos direto
  • Reconhecer os mesmos níveis no Material, no Carbon e no Spectrum
  • Decidir quantos níveis o seu sistema precisa

1. Três níveis, uma corrente

color.blue.600 #1F5FAEcolor.action.primarybutton.primary.background
color.blue.400 #5B95DBcolor.action.primary, modo escurobutton.primary.background, sem mudança
color.coral.600 #C2412Dcolor.feedback.dangerbadge.danger.text
space.5 24 pxNão precisa de passo semânticobutton.primary.padding-inline
space.4 16 pxspace.inset.mdUsado direto por cards, diálogos e painéis
radius.md 8 pxradius.controlTodo controle lê este, sem token de componente
Três níveis no Harbour, cada um apontando para o seguinte. O primitivo diz o que o valor é, o semântico diz para que serve, o de componente diz onde entra. No modo escuro só muda a ligação entre o primitivo e o semântico: o token do próprio botão nunca muda. Nem toda linha precisa dos três níveis.Nomes dos níveis como no Adobe Spectrum (primitive, semantic, component-specific); o Material chama de reference, system e component. Diagrama: Marcus Andrey, CC BY 4.0.
  • Tokens primitivos guardam valores crus: color.blue.600 = #1F5FAE, space.4 = 16px, radius.md = 8px. Eles descrevem a paleta e as escalas. Não dizem nada sobre o uso.
  • Tokens semânticos dão nome a uma função e apontam para um primitivo: color.action.primary → color.blue.600, space.inset.md → space.4. É a camada com que os designers mais trabalham.
  • Tokens de componente dão nome a um lugar dentro de um componente e apontam para um semântico (ou, às vezes, para um primitivo): button.primary.background → color.action.primary.

A ligação de um token para outro se chama alias, ou referência. O formato do Design Tokens Community Group do W3C escreve isso com chaves: "$value": "{color.blue.600}" (DTCG, Format Module 2025.10). O Figma usa o mesmo nome: uma variável que referencia outra "is also called aliasing" (também se chama aliasing) (Figma Help, Overview of variables, collections, and modes).


2. Por que o nível do meio importa

Olhe a segunda linha da figura. No modo escuro, color.action.primary aponta para color.blue.400 em vez de color.blue.600. O token do próprio botão não mudou. O código do botão também não. Todo componente que usa color.action.primary muda de uma vez.

Sem o nível semântico você teria duas opções ruins: dar ao botão dois tokens de fundo e ensinar cada componente sobre o modo escuro, ou mudar o próprio color.blue.600 para um azul mais claro no modo escuro, o que transforma o nome numa mentira.

O nível do meio também é onde mora o significado. "Perigo" pode ser coral hoje e vermelho depois de uma nova marca. Um código que diz color.feedback.danger continua certo; um que diz color.coral.600 fica errado.


3. A mesma ideia em sistemas públicos

Os níveis têm nomes diferentes, mas a forma é a mesma:

Sistema Nível 1 Nível 2 Nível 3
Adobe Spectrum Primitive (ou global), ex. blue-800 Semantic, ex. accent-background-color-default Component-specific, ex. tooltip-maximum-width
Material Design 3 Reference, ex. --md-ref-typeface-brand System, ex. --md-sys-color-primary Component, ex. --md-filled-button-container-shape
IBM Carbon Paleta, ex. $blue-60 Tokens de tema, ex. $interactive, $text-primary Tokens de componente, ex. $button-primary
Harbour color.blue.600 color.action.primary button.primary.background

Fontes: Spectrum, Design tokens, Material Web, Theming ("each component token maps to a system token, which has a concrete reference value", cada token de componente aponta para um token de sistema, que tem um valor de referência concreto), Carbon, Themes (no tema White, $interactive "calls the IBM Design Language color palette token $blue-60", chama o token $blue-60 da paleta), Carbon, Color tokens (os tokens de componente "should never be used for anything other than their own component", nunca devem ser usados fora do próprio componente).

O Carbon resume bem a regra: os tokens de tema "are universal and never change across themes" (são universais e nunca mudam entre temas); só os valores deles mudam.


4. Quantos níveis?

Três é comum, não obrigatório. As definições do próprio Spectrum deixam espaço: os tokens semânticos "define how design decisions are used throughout the system" (definem como as decisões de design são usadas no sistema), e os de componente são para decisões "that apply to a specific component" (que valem para um componente específico).

Use este teste para um token de componente: esse componente vai precisar algum dia de um valor diferente do token semântico para o qual ele aponta? Se o fundo do botão vai ser sempre color.action.primary, um token de componente é um seguro barato. Se o espaço interno de um card é sempre space.inset.md e ninguém vai adaptar isso em separado, pule, como a figura faz para os cards e para o radius.control.

E o contrário: button.primary.padding-inline aponta direto para space.5, porque não existe uma função compartilhada que um token semântico acrescentaria. Nem toda linha precisa de todos os níveis.

O que você não deve pular: componentes nunca leem primitivos de cor direto. É essa ligação que torna os modos e as marcas possíveis.


5. Erros comuns

  • Componentes lendo color.blue.600 direto, e o modo escuro passa a exigir mudança de código.
  • Nomes semânticos que são primitivos disfarçados: color.blue-button.
  • Um token de componente para cada propriedade de cada componente: milhares de tokens em que ninguém se acha.
  • Mudar o valor de um primitivo para consertar um uso, e quebrar todos os outros.
  • Aliases apontando para o lado errado: um primitivo apontando para um semântico.

6. Vocabulário

Termo Significado
Token primitivo Um valor cru com um nome neutro: color.blue.600 = #1F5FAE
Token semântico Uma função que aponta para um primitivo: color.action.primary
Token de componente Um lugar dentro de um componente: button.primary.background
Alias Um token cujo valor é outro token
Nível Um degrau da corrente que vai do valor cru até o componente

7. Experimente (sem ferramentas)

  1. Pegue três cores de um produto que você conhece: a do botão principal, a do texto de erro, a do fundo da página.
  2. Para cada uma, escreva um nome primitivo (por matiz e degrau) e um nome semântico (pela função).
  3. Agora imagine o modo escuro. Quais tokens semânticos apontariam para outro lugar? Quais primitivos você precisaria acrescentar?

Perguntas para refletir: Qual das suas cores não tinha uma função clara quando você tentou dar nome a ela? O que isso diz?


8. Se você já pratica

  • Procure níveis pulados: busque no código e na biblioteca do Figma tokens primitivos de cor usados direto nos componentes.
  • Deixe os primitivos privados onde as ferramentas permitirem. O Figma deixa esconder variáveis da publicação, então os outros arquivos só veem o conjunto semântico (Figma Help, Create and manage variables).
  • Revise cada novo token de componente com o teste da seção 4. Apague os que nunca foram diferentes do semântico.

Checklist

Para saber mais

Livros, cursos e vídeos para ir mais fundo

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

Relacionadas

Como nomear tokens · Temas e modos · Cor, tipografia e espaçamento como tokens · Tokens de movimento · O que é um design system · Sistemas multimarca e multiproduto · Modelo de tokens em três níveis

Salvo só neste dispositivo.

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