Nomenclatura de design tokens: o sistema de três níveis e onde ele falha

A convenção é quase universal, o que torna fácil adotar a estrutura sem o raciocínio. Cada nível responde a uma pergunta diferente, e saber qual é a pergunta evita que você coloque as coisas no lugar errado.

A regra que faz isso funcionar, e a que é mais frequentemente quebrada: nada fora do nível semântico pode referenciar um primitivo. No momento em que um componente usa blue-600 diretamente, o nível primitivo torna-se uma API pública e você não pode mais alterar um valor sem auditar todo o código — que era justamente o motivo de ter níveis.

:root {
  /* Tier 1: primitives. Values only. Nobody uses these directly. */
  --blue-600: #2563eb;
  --red-600:  #dc2626;
  --gray-500: #6b7280;

  /* Tier 2: semantic. Roles. This is the public API. */
  --color-primary:   var(--blue-600);
  --color-danger:    var(--red-600);
  --text-muted:      var(--gray-500);

  /* Tier 3: component. Only where a component truly deviates. */
  --button-danger-bg: var(--color-danger);
}

/* ✅ product code */
.alert { color: var(--color-danger); }

/* ❌ reaches past the semantic layer */
.alert { color: var(--red-600); }

Leia da esquerda para a direita, do geral para o específico: categoria, função, variante, estado. Nem todo token precisa dos quatro, e aqueles que precisam geralmente são interativos.

A consistência importa muito mais do que o padrão escolhido. Uma base de código onde metade dos tokens se chama text-color-muted e a outra metade color-text-muted obriga todos a fazerem uma consulta manual toda vez, para sempre. Escolha uma ordem, documente-a e exija-a no code review.

Aqui está o padrão aplicado, em vez de apenas descrito. Leia os nomes das funções, não as cores — a pergunta que cada um responde é "para que serve isso", e um nome que responde apenas "qual é a cor" falhou no nível em que se encontra.

Uma única pergunta resolve a maioria das discussões sobre nomenclatura em segundos:

Aplique isso a casos reais e as respostas serão inequívocas:

O caso do --shadow-card é sutil e merece atenção. Nomear um token com base na sua implementação trava essa implementação. Quando cada card no código diz box-shadow: var(--shadow-card), mudar para uma elevação baseada em bordas torna-se um refactor em vez de uma simples alteração de token — que é exatamente o acoplamento que os tokens deveriam eliminar.

A maioria dos sistemas de tokens que falham, falham aqui. A camada de componentes começa pequena e legítima, depois absorve tudo e, eventualmente, você tem quatrocentos tokens, metade dos quais possui apenas um consumidor.

O mecanismo é sempre o mesmo. Alguém precisa de um fundo de botão que não seja exatamente o --color-primary. Adicionar --button-primary-bg leva trinta segundos, mas adicioná-lo à camada semântica exige uma conversa. Então, o token de componente entra, a próxima pessoa faz o mesmo, e a camada semântica deixa de ser a fonte da verdade sem que ninguém tenha decidido isso.

Uma auditoria útil: conte os tokens de camada de componente com exatamente um consumidor. Se esse número for alto, a camada está sendo usada como uma válvula de escape, e a correção deve ser feita na origem.

Estes se repetem em quase todo design system de tokens que deixa de ser utilizado. Cada um tem uma correção barata se detectada cedo e uma cara se não for.

1. 1

   Escalas numeradas sem âncora

   De color-1 a color-12 não diz nada a ninguém, e os números adquirem significado apenas através do folclore. Escalas numeradas são aceitáveis na camada primitiva, onde o número rastreia uma dimensão real, como a luminosidade. Elas nunca são aceitáveis na camada semântica, porque o objetivo dessa camada é dizer para que algo serve.

2. 2

   Codificar o tema no nome

   Ter --light-bg e --dark-bg como tokens separados significa que cada componente referencia ambos e cria ramificações. Um nome, dois valores, alternados pelo tema — é para isso que serve a camada de tokens. Se você encontrar if (theme === 'dark') no código do componente, os tokens estão nomeados incorretamente.

   Copy

   /* ❌ */  --light-bg: #fff;  --dark-bg: #0a0a0a;
   /* ✅ */  --surface-base: #fff;
            [data-theme="dark"] { --surface-base: #0a0a0a; }

3. 3

   Tamanhos nomeados com base em onde são usados hoje

   --text-hero funciona bem até que o tamanho hero apareça em uma tabela de preços. --text-4xl ou --font-scale-7 nomeia o passo, não o site, e sobrevive ao ser reutilizado. Nomeie pela posição em uma escala, não pelo primeiro cliente.

4. 4

   Cores de status servindo também como cores de marca

   A forma mais comum de um sistema se tornar incapaz de exibir estados. Se o verde da marca e o verde de sucesso forem o mesmo token, você não poderá reestilizar a marca sem alterar a aparência do sucesso, e não conseguirá distinguir uma linha saudável de uma com marca. Mantenha o conjunto de status reservado e especifique isso em um comentário.

5. 5

   Abreviações que apenas uma pessoa consegue decifrar

   --clr-bg-scndry economiza onze caracteres e custa a cada leitor uma etapa de decodificação para sempre, incluindo um modelo que precisa adivinhar se scndry é secondary ou um erro de digitação. O autocomplete torna o comprimento quase irrelevante. Escreva as palavras.

Tokens precisam viajar cada vez mais: de uma ferramenta de design para o CSS, para um tema Tailwind, para uma plataforma nativa, para um item de registro do shadcn/ui, para um DESIGN.md que um agente lê. Isso impõe uma restrição aos nomes que a maioria das equipes não considera até que o primeiro export quebre.

A regra prática: escolha nomes que sejam simultaneamente uma propriedade customizada CSS válida, uma chave JSON válida e uma frase em inglês legível. O formato achatado, em minúsculas e com hífens satisfaz os três, e os grupos aninhados do formato de token DTCG/W3C podem ser gerados de um conjunto achatado muito mais facilmente do que o inverso.

A decisão de nomenclatura com maior alavancagem não é o padrão. É se os nomes na sua ferramenta de design são idênticos aos nomes no código.

O SLDS da Salesforce é o exemplo publicado mais claro: sua biblioteca no Figma usa os mesmos nomes de hooks semânticos que o CSS — seus próprios exemplos são radius-border-4 e font-scale-4 — assim, os designs mapeiam um para um com o código real. O objetivo declarado deles é um vocabulário compartilhado que faz a ponte entre design e desenvolvimento.

O efeito prático é que toda uma classe de bugs de handoff deixa de existir. Quando um designer diz font-scale-4 e um desenvolvedor digita font-scale-4, não há etapa de tradução e, portanto, nenhum lugar para a perda de significado. Compare isso com um estilo do Figma chamado "Heading / Large" mapeado para uma variável CSS chamada --text-2xl, onde cada handoff é uma busca e cada busca é uma chance de errar a interpretação.

A nomeação de tokens costumava ser uma questão de ergonomia humana — autocomplete, legibilidade, onboarding. Cada vez mais, o leitor mais pesado do seu arquivo de tokens é um agente de código, e isso muda quais falhas importam.

Um humano que não sabe qual de dois cinzas usar perguntará, ou escolherá um e será corrigido em uma revisão. Um modelo escolherá um, silenciosamente, em cada arquivo que tocar, e a inconsistência chegará mais rápido do que a revisão pode detectar. A ambiguidade no nível semântico é um defeito muito mais caro do que costumava ser.

Amostramos 299 arquivos DESIGN.md publicados para leitura de agentes e descobrimos que 86% especificam cores como valores hex puramente, sem nenhum papel semântico atribuído. Não são tokens mal nomeados — são a ausência de tokens. Um modelo ao qual é fornecido #6b7280 e dito que faz parte da paleta o usará onde quer que um cinza médio seja plausível: texto de corpo, bordas, ícones, placeholders, estados desabilitados. Cinco funções diferentes, um valor, sem forma de alterar qualquer uma delas de forma independente depois.

A segunda versão custa três linhas extras e garante a capacidade de escurecer suas bordas sem escurecer suas legendas — uma mudança que você desejará e que a primeira versão torna impossível sem uma auditoria em todo o codebase.

Se você está nomeando um sistema do zero, este é um mínimo justificável. É pequeno propositalmente — um sistema que ninguém consegue manter na cabeça acaba sendo ignorado.

/* Surfaces — what things sit on */
--surface-base        /* the page */
--surface-raised      /* cards, panels */
--surface-overlay     /* modals, popovers */
--surface-sunken      /* wells, inset areas */

/* Text — by emphasis, never by colour */
--text-primary
--text-secondary
--text-muted
--text-disabled
--text-on-accent      /* text sitting on the accent colour */

/* Borders — by weight of presence */
--border-subtle
--border-strong
--border-focus

/* Action — the interactive colour and its states */
--action-primary
--action-primary-hover
--action-primary-active

/* Status — reserved. Nothing decorative uses these. */
--status-success
--status-warning
--status-danger
--status-info

Duas observações sobre esse conjunto. Os tokens de texto são nomeados por ênfase em vez de cor, para que permaneçam precisos no modo escuro. Tokens de status possuem um comentário de reserva, pois a maneira mais comum de um sistema de status falhar é um designer usar o verde de sucesso como um acento decorativo, tornando impossível distinguir uma linha saudável de uma linha com a cor da marca.