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 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.primary button.primary.background color.blue.400 #5B95DBcolor.action.primary , modo escurobutton.primary.background , sem mudançacolor.coral.600 #C2412Dcolor.feedback.danger badge.danger.text space.5 24 pxNão precisa de passo semânticobutton.primary.padding-inline space.4 16 pxspace.inset.md Usado direto por cards, diálogos e painéisradius.md 8 pxradius.control Todo controle lê este, sem token de componente- 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.600direto, 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)
- 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.
- Para cada uma, escreva um nome primitivo (por matiz e degrau) e um nome semântico (pela função).
- 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
- Adobe Spectrum: Design tokens
- Material Web: Theming · Material Design 3, Design tokens
- IBM Carbon: Themes · Color tokens
- Design Tokens Community Group: Format Module 2025.10
Livros, cursos e vídeos para ir mais fundo
- Expressive Design SystemsYesenia Perez-CruzLivro · A Book Apart, 2019 (Amazon)
- Design SystemsAlla KholmatovaLivro · Smashing Media, 2017 (Amazon)
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