Nomear componentes, cores e tokens certo evita retrabalho e acelera onboarding

Por que ninguém concorda sobre o nome de um botão

Quem já sentou numa reunião de design system↳Design system5 conteúdosComo desenvolvemos o novo Design System do AsaasProduto & UX · jul 2024UX e Código: Por que designers que conhecem programação têm uma vantagem estratégicaProduto & UX · abr 2025A importância do HTML e CSS para quem trabalha com UI Design e Design SystemProduto & UX · dez 2024Ver tudo em Produto & UX → conhece a cena: a discussão sobre chamar um componente de Button, Btn ou ActionTrigger consome mais tempo do que deveria. Não é bikeshedding gratuito. Um guia publicado neste mês pelo Smashing Magazine, assinado por Vitaly Friedman, reúne referências práticas para nomear componentes de UI, cores, design tokens e features, partindo de um diagnóstico simples: a linguagem que o time usa molda como ele pensa sobre o produto.

Um dos pontos centrais do material, e o que mais interessa a quem escreve código, é que nome genérico demais esconde intenção (fica difícil entender exatamente o que é), enquanto nome específico demais trava reuso, deixando pouca flexibilidade. Entre esses dois extremos mora boa parte do débito técnico que aparece anos depois, quando ninguém mais lembra por que uma classe, variável ou componente foi batizado daquele jeito.

Onde buscar nome para componente e classe

Para quem está sem repertório na hora de batizar uma função, uma classe HTML↳HTML45 conteúdosA importância do HTML e CSS para quem trabalha com UI Design e Design SystemProduto & UX · dez 2024Como hostear seu site HTML gratuitamente com GitHub PagesDev (Back & Front) · jun 2025SQL Server – Como criar um versionamento de código das suas Stored Procedures em HTML e com comentários da alteraçãoData · nov 2020Ver tudo em Dev (Back & Front) → ou uma propriedade CSS, o guia aponta o Classnames, um catálogo de palavras agrupadas por tema (comportamento, semelhança, ordem, agrupamento), incluindo campos que normalmente não vêm à cabeça de quem programa, como arquitetura, moda e publicação editorial. É uma lista, não uma convenção: o valor está em tirar o dev do vocabulário óbvio (item, box, wrapper) antes que ele vire prefixo de meia base de código.

Para nomear de forma consistente entre camadas (layer, grupo, componente), a referência é o material de Javier Cuello sobre boas práticas de nomenclatura em arquivos de design. Os critérios que ele lista valem tanto para quem desenha no Figma quanto para quem organiza componentes no código:

• Estrutura lógica e previsível, sem variação caso a caso
• Nome curto, mas que não force quem lê a adivinhar o que ele descreve
• Vocabulário compartilhado por todo o time, não só por quem criou
• Independência de propriedade visual (nome não descreve cor, tamanho ou posição)

Esse último ponto é o que mais gera retrabalho em produção: nomear algo como blue-button funciona até o dia em que o botão muda de cor no redesign e ninguém quer sair caçando toda ocorrência da classe no repositório.

Cor tem nome, e são 30 mil deles

Para cores especificamente, o guia cita o repositório mantido por David Aerne, que reúne 30.355 nomes únicos de cor vindos de referências diversas e de milhares de contribuições de usuários. A ferramenta associada, Color Parrot, devolve um nome legível para qualquer valor hexadecimal digitado na URL. Não substitui um token semântico (color-brand-primary), mas ajuda a dar um rótulo memorável a uma paleta antes de ela virar variável de sistema, o que facilita a comunicação entre design e código na hora de documentar o porquê de cada escolha.

Design tokens: da teoria ao caso real da Intuit e da Vodafone

A parte mais densa do material, e a que mais interessa quem lida com arquitetura de front-end em escala, é a seção sobre taxonomia de design tokens. A Intuit, dona de produtos como Mailchimp, QuickBooks e TurboTax, precisava de um sistema de tokens flexível o bastante para servir marcas diferentes sem reescrever a base a cada produto novo. Nate Baldwin documentou o processo num estudo de caso que detalha os problemas da taxonomia antiga, os critérios definidos para a nova e como ela foi construída, com os trade-offs explicados em cada decisão.

O time de design system da Vodafone UK foi por um caminho complementar, construindo em cima do trabalho de Nathan Curtis sobre nomenclatura de tokens. O resultado, batizado de Variables Taxonomy Map, organiza os tokens em quatro camadas conectadas entre si (brand, primitives, semantics e pages), permitindo que qualquer pessoa do time entenda onde um token é usado e o que ele representa só pelo nome.

A vantagem prática dessa separação em camadas aparece quando o produto precisa de um rebranding: muda-se o valor na camada de marca, sem precisar tocar nas camadas que o código efetivamente consome. É o mesmo raciocínio por trás de qualquer sistema de design tokens bem-feito (Style Dictionary, Tokens Studio e afins): separar o que muda com frequência do que muda raramente.

Para quem quer montar essa estrutura do zero sem copiar um sistema de outra empresa, o guia ainda recomenda duas ferramentas abertas: o Design Token Naming Guide + Builder, de Romina Kavcic, que ajuda a configurar categorias, estados e papéis antes de bater o martelo na convenção; e uma planilha de inventário com quatro níveis para mapear todos os tokens existentes sem perder o controle quando o número de temas e modos cresce.

Feature com nome ruim é feature que ninguém usa

Um ponto que foge do CSS e da arquitetura de token, mas que afeta diretamente quem decide o texto de um release notes ou o rótulo de uma flag de feature, é a seção sobre nomear funcionalidades novas. Erin Gannon argumenta que baixa adoção de uma feature costuma ser, em parte, problema de nome: antes de ser usada, a feature precisa ser descoberta, entendida e só depois testada e incorporada ao fluxo de trabalho de quem usa o produto.

A recomendação prática é testável por qualquer time: peça para um usuário explicar a feature com as próprias palavras, e use essas palavras no nome, não o termo técnico que nasceu na reunião de planejamento. Isso tem implicação direta em código também, porque o nome que aparece na interface raramente é igual ao nome interno da flag (feature_flag_v2_beta), e manter os dois registrados em algum lugar documentado evita a arqueologia de três meses depois, quando alguém perguntar o que aquele flag realmente controla.

O que o nome quebra quando está errado (e o que isso tem a ver com acessibilidade)

O material do Smashing Magazine não entra em acessibilidade diretamente, mas a conexão é direta para quem trabalha com HTML semântico e ARIA. Um componente chamado de forma inconsistente no design system tende a ter aria-label inconsistente na implementação: se o Figma chama de "card de produto" e o código chama de "item-tile", é comum que o texto alternativo lido por leitor de tela também varie entre telas do mesmo fluxo, confundindo quem depende de tecnologia assistiva para navegar.

Em resumo: nomenclatura consistente entre design e código não é estética, é o contrato que garante que o rótulo que a pessoa com deficiência visual ouve seja o mesmo em toda a jornada, porque ele vem do mesmo token semântico em vez de ser reescrito a cada tela por quem implementou.

Quando não vale a pena formalizar tudo

Nem todo projeto precisa de uma Variables Taxonomy Map em quatro camadas. Para um time pequeno ou um produto no início, o custo de manter essa estrutura pode superar o ganho, e vale mais investir em um glossário simples, uma página no Notion ou no README do design system listando os termos acordados.

O risco de pular essa etapa, de qualquer tamanho de time, é o mesmo que o guia descreve: gente falando da mesma coisa em dialetos diferentes (o do design, o de quem programa, o de produto), até que a confusão vire conflito de nome dentro do próprio repositório, e aí sim vira item de backlog que ninguém prioriza.

O guia completo, com a lista de recursos e links diretos para cada ferramenta citada, está disponível no Smashing Magazine.

Fonte: Smashing Magazine