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 cor é esta" 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.

Esses erros recorrem em quase todo sistema 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 por meio de 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 nomeiam o degrau da escala, não o site, e sobrevivem ao reuso. Nomeie pela posição na escala, não pelo primeiro cliente.

4. 4

   Cores de status duplicando como cores de marca

   A maneira 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á estilizar a marca sem alterar a aparência do sucesso, e não conseguirá distinguir uma linha saudável de uma linha da 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 terá que adivinhar se scndry é 'secondary' ou um erro de digitação. O autocomplete torna a extensão do nome quase irrelevante. Escreva as palavras completas.

Os tokens precisam viajar cada vez mais: de uma ferramenta de design para o CSS, para um tema do Tailwind, para uma plataforma nativa, para um item de registro do shadcn, 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 a primeira exportação falhe.

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

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

O SLDS 2 da Salesforce é o exemplo publicado mais claro: sua biblioteca do Figma usa os mesmos nomes de hooks semânticos que o CSS (exemplos deles são radius-border-4 e font-scale-4), portanto, os designs mapeiam um para um com o código real. O objetivo declarado deles é um vocabulário compartilhado que une 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, não há lugar para 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 nomenclatura de tokens costumava ser uma questão de ergonomia humana: autocomplete, legibilidade, onboarding. Cada vez mais, o leitor mais frequente do seu arquivo de tokens é um agente de código, e isso muda quais falhas são críticas.

Um humano que não sabe qual de dois cinzas usar irá perguntar, ou escolherá um e será corrigido na revisão. Um modelo escolherá um, silenciosamente, em cada arquivo que tocar, e a inconsistência surgirá mais rápido do que a revisão consegue detectar. A ambiguidade na camada semântica é 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 hexadecimais puros, sem nenhum papel semântico atribuído. Não tokens mal nomeados: nenhum token. Um modelo que recebe #6b7280 e é informado que faz parte da paleta o usará onde quer que um cinza médio seja plausível: texto do corpo, bordas, ícones, placeholders, estados desativados. Cinco funções diferentes, um valor, sem maneira de alterar qualquer um deles independentemente 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 defensá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.