Convenções de nomenclatura de tokens

Nomes inconsistentes de tokens tornam impossível prever o que um token faz sem ler seu valor. Uma convenção de nomenclatura clara e previsível é fundamental para um sistema de tokens escalável.

Um padrão comum: [category]-[property]-[variant]. Exemplos: color-text-primary, color-text-secondary, spacing-inset-sm. Cada segmento restringe progressivamente o significado.

Evite nomes de paleta, como blue-500, nos componentes. Use nomes semânticos: color-action-default, color-feedback-error. Nomes semânticos resistem a alterações na cor da marca sem exigir atualizações nos componentes.

Acrescente o estado ao final: color-button-bg-default, color-button-bg-hover, color-button-bg-disabled. Sufixos de estado consistentes tornam os conjuntos de tokens previsíveis e completos.

Use tamanhos de camiseta (xs, sm, md, lg, xl) ou escalas numéricas (100, 200...900) de forma consistente. As escalas numéricas permitem inserir valores intermediários; os tamanhos de camiseta são mais fáceis de entender em conjuntos pequenos.

Para sistemas com várias marcas ou produtos, acrescente um espaço de nomes aos tokens: brand-a-color-primary versus brand-b-color-primary. Os espaços de nomes evitam colisões ao mesclar conjuntos de tokens.

O kebab-case é convertido diretamente em propriedades personalizadas de CSS: color-text-primary torna-se --color-text-primary. Tokens em camelCase precisam de transformação; tokens em kebab-case não.

Bons nomes são autoexplicativos: spacing-stack-md (espaçamento vertical entre elementos empilhados, médio) comunica a intenção sem um comentário. Nomes ruins, como s3, exigem documentação externa para serem compreendidos.

Depois que os tokens estão em uso, renomeá-los é uma alteração incompatível. Use aliases de descontinuação: mantenha o nome antigo, mas faça com que ele faça referência ao novo token. Dê aos consumidores um período de migração antes de remover os tokens descontinuados.

Analise estaticamente os nomes dos tokens com regras personalizadas no Style Dictionary ou em um script de CI. Rejeite tokens que não correspondam ao padrão de nomenclatura. A validação automatizada evita a deriva da nomenclatura à medida que o sistema cresce.

Publique um guia de nomenclatura com exemplos de nomes corretos e incorretos. Faça um breve workshop para que as equipes de design e engenharia concordem com as convenções antes que o sistema cresça. A consistência exige entendimento compartilhado, não apenas documentação.

Por que os tokens de componentes devem usar nomes semânticos em vez de nomes de paleta, como "blue-500"?

Uma convenção consistente de nomenclatura de tokens, usando padrões de categoria-propriedade-variante, nomes semânticos, sufixos de estado e prefixos de namespace, torna os sistemas de tokens previsíveis, autoexplicativos e resilientes a alterações de marca sem quebrar o código dos componentes.