Marcus Andrey Estudo
Read in English Biblioteca

Design systems · Passo 2 · 7 min de leitura

Como nomear tokens

O nome de um token é um pedacinho de documentação que as pessoas leem centenas de vezes por dia. Como montar nomes do geral para o específico, nomear primitivos pelo que eles são e semânticos pelo que fazem, escolher uma escala que cresce, e manter um nome só entre Figma, JSON, CSS e código nativo.

O nome é a interface de um token. Ninguém lê o valor de um token; as pessoas leem o nome, num seletor do Figma, no autocompletar, numa revisão de código. Um bom nome diz quando usar sem precisar abrir a documentação. Um nome ruim é usado onde quer que a cor pareça certa, e aí o sistema não quer dizer mais nada. Nomear é o lugar mais barato para acertar um design system, e o mais caro para corrigir depois.

O que você vai conseguir fazer depois de ler:

  • Montar o nome de um token do geral para o específico, numa ordem fixa
  • Nomear primitivos pelo que eles são e semânticos pelo que eles fazem
  • Escolher uma escala que cresce sem precisar renomear
  • Manter um nome só entre as ferramentas de design e as plataformas

1. Um nome é uma frase

  1. colorcategoria: que tipo de valor
  2. feedbackconceito: a função
  3. dangervariante: qual delas
  1. buttoncomponente
  2. primaryvariante
  3. padding-inlinepropriedade
SistemaUm nome de token realA ordem das partes
Harbourcolor.feedback.dangercategoria, conceito, variante
Atlassiancolor.icon.successfundamento, propriedade, modificador
Adobe Spectrumnegative-content-color-defaultconceito, propriedade, categoria, estado
IBM Carbon$text-primarypropriedade, ênfase; o tema define o valor
Material Web--md-sys-color-primarynamespace, nível, categoria, papel
O nome de um token é uma frase curta, lida do geral para o específico. Cada grande sistema ordena as partes do seu jeito; o que importa é que um sistema use uma ordem só, sempre.Nomes tirados da documentação pública de cada sistema, com links na lição. Diagrama: Marcus Andrey, CC BY 4.0.

Leia color.feedback.danger da esquerda para a direita: é uma cor, de feedback, do tipo perigo. Cada parte afunila a anterior. Essa é a regra principal: do geral para o específico, sempre na mesma ordem.

A Atlassian descreve os nomes dela do mesmo jeito, em três partes: um fundamento ("such as color, elevation, or space", como cor, elevação ou espaço), uma propriedade ("the UI element the token is being applied to, such as a border, background, shadow", o elemento em que o token é aplicado, como borda, fundo ou sombra) e um modificador opcional ("its color role, emphasis, or interaction state", o papel da cor, a ênfase ou o estado de interação). Ela também avisa que "not every token has a modifier. For example, color.text is our default body text color" (nem todo token tem modificador; color.text, por exemplo, é a cor padrão do texto) (Atlassian, Design tokens).

A figura mostra que os grandes sistemas escolhem ordens diferentes. O Spectrum põe o conceito primeiro (negative-content-color-default); a Atlassian e o Harbour põem a categoria primeiro. As duas funcionam. O que não funciona é misturar ordens dentro de um mesmo sistema.


2. Primitivos: o que eles são

Os nomes primitivos descrevem o valor, de forma neutra, para nunca ficarem errados:

  • Cor: matiz e degrau. color.blue.600, color.sand.50, color.coral.600. Números maiores são mais escuros. Os intervalos (50, 100 … 900) deixam espaço para acrescentar um degrau depois sem renomear.
  • Espaço: uma escala numerada. O Harbour usa de space.1 a space.8 para 4 a 64 px.
  • Raio, tamanho de fonte: conjuntos pequenos, com nome ou número. radius.sm, radius.md; font.size.300.

Nunca coloque uma função num nome primitivo (color.brand-blue): no dia em que a marca mudar, o nome mente. E nunca coloque um valor (space.16px): no dia em que o valor mudar, ele mente para o outro lado.


3. Semânticos: para que servem

Os nomes semânticos descrevem a função, nunca a aparência:

Em vez de Use Por quê
color.blue-button color.action.primary No modo escuro não é o mesmo azul
color.red-text color.feedback.danger Uma nova marca pode deixar o perigo coral ou laranja
color.light-grey-bg color.surface.subtle "Light" (claro) está errado no modo escuro
space.16 space.inset.md O valor pode mudar com a densidade

O GOV.UK diz o mesmo sobre as cores dele: use govuk-functional-colour("brand") "rather than #1d70b8" (em vez de #1d70b8), e "only use the variables in the context they're designed for" (só use as variáveis no contexto para o qual elas foram feitas) (GOV.UK Design System, Colour). Um nome de função usado para a função errada continua sendo divergência, só que mais bem disfarçada.

Partes úteis para nomes semânticos, na ordem do Harbour:

  • Categoria: color, space, radius, font
  • Conceito: action, text, surface, border, feedback, inset, stack
  • Variante: primary, subtle, danger, success, ou um tamanho: sm, md, lg
  • Estado, por último e só quando precisar: hover, pressed, disabled

Então: color.action.primary.hover, color.text.subtle, color.border.focus, space.stack.lg.

Os nomes ficam em inglês, mesmo num time que fala português: é a língua do código, das ferramentas e dos sistemas públicos, e um nome só evita duas traduções.


4. Escalas que crescem

Dois tipos de nome de escala são comuns, e os dois funcionam se você escolher uma vez:

  • Números (space.1 … space.8, font.size.100 … 600): fáceis de estender no topo, difíceis de encaixar um degrau no meio, a não ser que você deixe intervalos (100, 200, 300).
  • Tamanhos de camiseta (sm, md, lg, xl): fáceis de ler, e bons para tokens semânticos com poucos degraus (space.inset.sm/md/lg). Ficam estranhos depois do xxxl.

O Harbour usa números para os primitivos e tamanhos de camiseta para os semânticos, então space.inset.md → space.4 se lê com naturalidade.


5. Um nome, várias sintaxes

Um token é escrito de um jeito em cada lugar, mas deve ser o mesmo nome:

Onde O color.action.primary do Harbour
Arquivo de tokens (JSON DTCG) grupos color › action › primary; referenciado como {color.action.primary}
Variável do Figma primary dentro dos grupos color › action, numa coleção Semantic
CSS --hb-color-action-primary
Swift ou Kotlin colorActionPrimary

O formato DTCG não aceita ., { nem } dentro de um nome, porque o ponto é como se escrevem grupos e referências (DTCG, Format Module 2025.10). Então os pontos de color.action.primary são um caminho pelos grupos, não parte de um nome comprido. O prefixo hb- no CSS é um namespace: ele impede que as propriedades do Harbour batam com as de qualquer outro código na página.

O Figma deixa você definir um nome de código por plataforma para cada variável, que o Dev Mode mostra nos trechos de código; cabem até três, para Web, Android e iOS (Figma Help, Create and manage variables). Preencha, para que designers e desenvolvedores vejam o mesmo token.


6. Erros comuns

  • Aparência em nomes semânticos: blue, light, big.
  • Função em nomes primitivos: brand-blue, error-red.
  • Duas ordens no mesmo sistema: color.text.subtle ao lado de subtle.border.color.
  • Sinônimos: danger, error e critical para a mesma coisa.
  • Renomear tokens com frequência. Cada renomeação é uma mudança que quebra para alguém (veja Descontinuação e breaking changes).

7. Vocabulário

Termo Significado
Categoria O tipo de valor: cor, espaço, raio, fonte
Conceito A função que um token semântico cumpre: ação, texto, superfície, feedback
Variante Qual delas dentro do conceito: primary, subtle, danger, md
Estado Uma condição de interação: hover, pressed, disabled
Namespace Um prefixo que marca os nomes de um sistema, como hb-
Caminho Os grupos em que um token está, escritos com pontos

8. Experimente (sem ferramentas)

  1. Anote cinco nomes de cor que você já viu num arquivo ou num código de verdade.
  2. Marque cada um: descreve o valor, a função, ou os dois?
  3. Renomeie os que misturam as duas coisas, usando categoria, conceito, variante, estado.

Perguntas para refletir: Quais dos seus nomes novos continuariam certos depois de uma nova marca? E depois do modo escuro?


9. Se você já pratica

  • Escreva a sua gramática de nomes como um padrão de uma linha, tipo category.concept.variant.state, com as palavras permitidas em cada parte. Cada token novo é conferido contra ele.
  • Mantenha uma lista de sinônimos proibidos. "Error não é variante; use danger."
  • Antes de renomear, crie o nome novo como alias do antigo e descontinue o antigo ao longo de um release, para ninguém quebrar da noite para o dia.

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

Níveis de tokens · Cor, tipografia e espaçamento como tokens · Tokens do Figma ao código · Descontinuação e breaking changes · Tokens de movimento · Fórmula de nomes de tokens

Salvo só neste dispositivo.

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