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
colorcategoria: que tipo de valorfeedbackconceito: a funçãodangervariante: qual delas
buttoncomponenteprimaryvariantepadding-inlinepropriedade
| Sistema | Um nome de token real | A ordem das partes |
|---|---|---|
| Harbour | color. | categoria, conceito, variante |
| Atlassian | color. | fundamento, propriedade, modificador |
| Adobe Spectrum | negative-content-color-default | conceito, propriedade, categoria, estado |
| IBM Carbon | $text-primary | propriedade, ênfase; o tema define o valor |
| Material Web | --md-sys-color-primary | namespace, nível, categoria, papel |
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.1aspace.8para 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 doxxxl.
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.subtleao lado desubtle.border.color. - Sinônimos:
danger,errorecriticalpara 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)
- Anote cinco nomes de cor que você já viu num arquivo ou num código de verdade.
- Marque cada um: descreve o valor, a função, ou os dois?
- 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
- Atlassian: Design tokens
- Adobe Spectrum: Design tokens
- GOV.UK Design System: Colour
- Design Tokens Community Group: Format Module 2025.10, nomes e grupos
- Figma Help: Create and manage variables, nomes de código
Livros, cursos e vídeos para ir mais fundo
- Design SystemsAlla KholmatovaLivro · Smashing Media, 2017 · sobre nomes como linguagem compartilhada (Amazon)
- Expressive Design SystemsYesenia Perez-CruzLivro · A Book Apart, 2019 (Amazon)
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