Marcus Andrey Estudo
Read in English Biblioteca

Framework · Design systems · 3 min de leitura

Fórmula de nomes de tokens

Uma ordem fixa para montar nomes de tokens do geral para o específico (categoria, conceito, variante, estado), com uma lista de palavras permitidas para cada parte. Assim cada nome diz quando usar o token, e os nomes novos continuam coerentes.

1Categoria

O tipo de valor. Sempre primeiro.

color, space, radius
2Conceito

O trabalho do token. Propósito, nunca aparência.

action, text, surface
3Variante

Qual dentro do conceito, ou um tamanho.

primary, danger, md
4Estado

Uma condição de interação. Por último, e só quando precisa.

hover, pressed, disabled

color . action . primary . hover → --hb-color-action-primary-hover

Um nome de token montado do geral para o específico, em uma ordem fixa, com cada parte vinda de uma lista combinada.

Use quando

  • Você está dando nome aos primeiros tokens semânticos de um sistema.
  • A lista de tokens tem sinônimos (danger, error, critical) ou ordens misturadas (color.text.subtle ao lado de subtle.border.color).
  • Designers e devs veem nomes diferentes para o mesmo token no Figma e no código.

Como usar

  1. Escolha as partes e a ordem. A maioria dos sistemas vai do geral para o específico: categoria, conceito, variante, estado. Escreva em uma linha, por exemplo category.concept.variant.state. Resultado: o padrão de nomes.
  2. Liste as palavras permitidas para cada parte. Categorias (color, space, radius, font), conceitos (action, text, surface, border, feedback), variantes (primary, subtle, danger, sm, md), estados (hover, pressed, disabled). Resultado: uma tabela de vocabulário, uma coluna por parte.
  3. Proíba os sinônimos. Para cada conceito, escolha uma palavra e anote as que você não vai usar. "Error não é variante; use danger." Resultado: uma lista curta de palavras proibidas, com a substituta.
  4. Nomeie primitivos e semânticos de jeitos diferentes. Primitivos descrevem o valor (color.blue.600, space.4). Semânticos descrevem o propósito (color.action.primary). Nunca ponha um propósito no nome de um primitivo, nem um valor no nome de um semântico. Resultado: dois conjuntos de nomes bem separados.
  5. Mapeie o nome em cada plataforma. Os pontos são um caminho por grupos no arquivo de tokens. Escreva como o mesmo nome fica no Figma, no CSS (com um prefixo de namespace) e no código nativo. Resultado: uma linha por plataforma para cada token.
  6. Confira os tokens novos contra o padrão. Na revisão, leia o nome da esquerda para a direita. Cada parte deve vir do vocabulário, na ordem, e o estado vem por último e só quando precisa. Resultado: um sim ou não para cada token novo, antes de sair.

Exemplo prático

O Harbour, design system da empresa de balsas Tidewater, escreve seu padrão como category.concept.variant.state, com o namespace de CSS hb-.

Parte Palavras permitidas (trecho) Exemplo
Categoria color, space, radius, font color
Conceito action, text, surface, border, feedback, inset, stack action
Variante primary, subtle, danger, success, sm, md, lg primary
Estado (opcional) hover, pressed, disabled, focus hover

Então a cor de hover da ação principal é color.action.primary.hover. No CSS fica --hb-color-action-primary-hover; em Swift ou Kotlin, colorActionPrimaryHover. Um time pede color.red-error. A revisão recusa por dois motivos: "red" é aparência, e "error" é um sinônimo proibido. O token sai como color.feedback.danger.

Cuidado com

  • Aparência em nomes semânticos. blue, light e big ficam errados no modo escuro ou depois de um rebrand.
  • Duas ordens no mesmo sistema. O autocomplete para de ajudar, e as pessoas criam duplicatas porque não acham o token de que precisam.
  • Renomear toda hora. Cada renomeação é uma breaking change para alguém. Crie o nome novo como alias primeiro e depois descontinue o antigo.
  • Um padrão que só existe na cabeça das pessoas. Se a gramática não está escrita, cada pessoa nova inventa a sua.

Modelo

Copie isto para a documentação do sistema e preencha o vocabulário antes de nomear o próximo token.

Padrão:     category.concept.variant.state   (estado só quando precisa)
Namespace:  prefixo de css "...-"

Categoria:  color | space | radius | font | ...
Conceito:   action | text | surface | border | feedback | ...
Variante:   primary | subtle | danger | sm | md | lg | ...
Estado:     hover | pressed | disabled | focus

Proibidas:  error -> danger · critical -> danger · bg -> surface

Token novo: ....................................
  Partes na ordem, todas das listas?         sim / não
  Sem palavras de aparência (blue, light)?   sim / não
  Figma:  ...   CSS: --...-...   iOS/Android: ...
Fonte
Nathan Curtis, "Naming Tokens in Design Systems" (EightShapes, 2020). Sintaxe de grupos e referências: W3C Design Tokens Community Group, Format Module 2025.10.
Onde encontrar
Design systems na prática: Como nomear tokens › Um nome é uma frase

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