Regras de nomenclatura e taxonomia para escalabilidade do sistema

Regras de nomenclatura e taxonomia são o “sistema de endereçamento” do seu Design System: elas determinam como pessoas e ferramentas encontram, entendem e reutilizam componentes, estilos e tokens com consistência. Quando a nomenclatura é previsível, a biblioteca escala sem virar um labirinto; quando é improvisada, cada novo componente aumenta a entropia e o retrabalho no handoff.

Neste capítulo, você vai definir um vocabulário comum (taxonomia), um padrão de escrita (nomenclatura) e um conjunto de regras operacionais (governança leve) para manter a escalabilidade. O foco é prático: como nomear componentes, variantes, propriedades, tokens e estilos para que o sistema seja pesquisável, legível e automatizável.

Conceitos essenciais: nomenclatura, taxonomia e semântica

Nomenclatura: o padrão de escrita

Nomenclatura é como você escreve os nomes: separadores, ordem das palavras, singular/plural, idioma, uso de maiúsculas, abreviações e símbolos. Um bom padrão reduz ambiguidades e facilita busca e filtros. Exemplo: decidir entre “Button / Primary” vs “button-primary” vs “Button.Primary”.

Taxonomia: a estrutura de classificação

Taxonomia é como você organiza o “mapa” do sistema: categorias, subcategorias e relações. Ela responde: “isso pertence a qual família?” e “qual é o nível de abstração?”. Exemplo: “Inputs” como categoria, “Text field” como componente, “State” como dimensão de variação.

Semântica: o significado por trás do nome

Semântica é o que o nome quer dizer no produto, não como ele parece. Em Design Systems escaláveis, você prefere nomes semânticos (ex.: “text/default”, “surface/raised”) a nomes puramente visuais (ex.: “gray-700”, “shadow-2”), porque o visual muda; a intenção tende a permanecer.

Continue em nosso aplicativo

Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.

ou continue lendo abaixo...

Baixar o aplicativo

Princípios para uma nomenclatura que escala

1) Previsibilidade acima de criatividade

Se duas pessoas nomeariam a mesma coisa de formas diferentes, o padrão está fraco. O objetivo é que o nome “certo” seja óbvio. Isso reduz duplicação (ex.: “Card/Default” e “Cards/Base” coexistindo sem necessidade).

2) Um nome deve responder “o que é” e “como varia”

Para componentes, o nome base deve dizer o que é (ex.: “Button”). As variações devem ser expressas por propriedades/variantes (ex.: “variant=primary”, “size=md”, “state=disabled”). Evite codificar variações no nome do componente quando elas podem ser variantes.

3) Preferir semântica para tokens e estilos

Tokens e estilos são a ponte para desenvolvimento e temas. Nomes semânticos facilitam troca de tema, acessibilidade e refatoração. Exemplo: “color.text.muted” é mais resiliente do que “color.gray.600”.

4) Consistência de idioma e forma gramatical

Escolha um idioma para nomes internos (PT ou EN) e mantenha. Misturar “Botão/Primary” com “Button/Secundary” cria ruído na busca e na comunicação. Também defina singular/plural: “Button” (singular) costuma funcionar melhor para componentes.

5) Evitar abreviações não padronizadas

Abreviações aceleram, mas custam entendimento. Se usar, documente e limite a um glossário. Exemplo: “md” para “medium” pode ser aceitável se for padrão do sistema; “med” e “m” ao mesmo tempo não.

Modelo de taxonomia recomendado (camadas de decisão)

Uma taxonomia útil separa o que é “tipo de coisa” do que é “variação”. Um modelo prático para Design Systems no Figma é pensar em camadas:

• Categoria: família ampla (ex.: Actions, Inputs, Navigation, Feedback, Data display, Layout).
• Componente: unidade reutilizável (ex.: Button, Text field, Tabs, Toast, Table).
• Subcomponente/parte (quando necessário): elementos internos reutilizáveis (ex.: Button/Icon, Field/Label).
• Propriedades: dimensões de variação (ex.: variant, size, state, icon, density).
• Valores: opções de cada propriedade (ex.: variant=primary|secondary|ghost).

Essa separação ajuda a evitar explosão de componentes. Em vez de criar “Button/Primary/Small/Disabled” como um item separado, você mantém um único componente “Button” com propriedades bem definidas.

Padrão de nomenclatura para componentes

Estrutura base: Categoria / Componente

Uma convenção comum e fácil de buscar é usar “Categoria / Componente”. Isso agrupa naturalmente no painel de Assets e melhora a descoberta.

Actions / Button
Inputs / Text field
Navigation / Tabs
Feedback / Toast
Data display / Badge

Se você não quiser expor a categoria no nome (por preferir agrupar por outra forma), mantenha ao menos um prefixo consistente. O importante é que a regra seja única e aplicada sempre.

Quando usar subcomponentes no nome

Use subcomponentes quando você realmente precisa publicar uma parte para reutilização em outros contextos (ex.: um “Icon button” que é uma variação de Button pode ser propriedade; mas um “Tabs/Tab item” pode ser uma peça interna reutilizável em composições).

Navigation / Tabs
Navigation / Tabs / Tab item
Inputs / Select
Inputs / Select / Option

Evite criar níveis profundos sem necessidade. Se você precisa de “/ / / /”, provavelmente está modelando estrutura interna que deveria ser resolvida com propriedades e slots.

Regras para nomes de componentes (checklist)

• Nome em singular (Button, Card, Tooltip).
• Evitar termos vagos: “Base”, “Default”, “New” (a menos que tenham definição formal).
• Evitar codificar estado no nome (ex.: “Button Disabled”). Estado deve ser propriedade.
• Evitar codificar cor no nome (ex.: “Button Blue”). Cor deve ser propriedade/estilo/token.
• Usar termos do produto (ex.: “Top bar” vs “Header”) conforme o vocabulário do time, mas padronizar.

Propriedades e variantes: taxonomia de variação

Variantes são onde a escalabilidade ganha ou perde. O segredo é definir propriedades com nomes consistentes e valores controlados. Pense em propriedades como “eixos” e valores como “pontos” nesses eixos.

Propriedades recomendadas (padrões comuns)

• variant: intenção/estilo (primary, secondary, ghost, danger).
• size: escala (xs, sm, md, lg).
• state: comportamento (default, hover, pressed, focus, disabled, loading).
• icon: presença/posição (none, leading, trailing, only).
• density: espaçamento (comfortable, compact) quando aplicável.
• tone: semântica de feedback (info, success, warning, critical) para componentes de status.

Nem todo componente precisa de todas. O ponto é: se “state” existe em um componente interativo, tente manter o mesmo nome e valores em outros componentes interativos.

Valores: controle de vocabulário

Defina valores curtos e consistentes. Evite sinônimos (“small” e “sm” misturados). Um padrão prático é usar abreviações apenas para tamanhos (xs/sm/md/lg) e palavras completas para o resto.

size = xs | sm | md | lg
state = default | hover | pressed | focus | disabled | loading
variant = primary | secondary | ghost | danger

Ordem e prioridade das propriedades

Mesmo que o Figma não exija uma ordem “visual”, o time precisa de uma ordem mental para discutir e revisar. Uma regra simples:

• Primeiro: variant (intenção)
• Depois: size (escala)
• Depois: state (interação)
• Depois: opcionais (icon, density, tone etc.)

Isso ajuda a revisar se um componente está “completo”: você confere eixos principais antes de detalhes.

Passo a passo prático: definindo a taxonomia do sistema

Passo 1 — Liste famílias de componentes por intenção de uso

Crie uma lista curta (5 a 8 categorias) baseada no que o produto realmente usa. Exemplo de ponto de partida:

• Actions
• Inputs
• Navigation
• Feedback
• Data display
• Layout
• Overlays

Valide com o time: cada componente deve encaixar em uma categoria sem debate longo. Se houver debate frequente, ajuste nomes das categorias.

Passo 2 — Defina um glossário de termos do sistema

Antes de nomear, alinhe vocabulário. Exemplo: “Text field” vs “Input”, “Top bar” vs “App bar”, “Modal” vs “Dialog”. Escolha um termo preferencial e registre sinônimos proibidos.

Preferir: Text field
Evitar: Input, Campo de texto (se o sistema estiver em EN)
Preferir: Dialog
Evitar: Modal (se “Dialog” for o termo oficial)

Passo 3 — Padronize separadores e capitalização

Escolha um formato e aplique em tudo. Um padrão comum para nomes de componentes é Title Case com separador “ / ” para hierarquia. Para tokens, é comum usar minúsculas com pontos.

• Componentes: Title Case + “ / ” (ex.: “Inputs / Text field”)
• Propriedades: lowercase (ex.: “state”, “size”)
• Valores: lowercase (ex.: “disabled”, “md”)
• Tokens: lowercase com “.” (ex.: “color.text.default”)

Passo 4 — Modele 3 componentes críticos e extraia padrões

Escolha componentes que costumam gerar variações: Button, Text field, Badge (ou equivalentes). Modele propriedades e valores. Em seguida, compare: os eixos fazem sentido e são reutilizáveis? Ajuste antes de expandir para o resto.

Exemplo (Button):

Actions / Button
Properties:
- variant: primary | secondary | ghost | danger
- size: sm | md | lg
- state: default | hover | pressed | focus | disabled | loading
- icon: none | leading | trailing | only

Exemplo (Text field):

Inputs / Text field
Properties:
- size: sm | md | lg
- state: default | hover | focus | disabled | error
- leadingIcon: true | false
- trailingIcon: true | false
- helperText: true | false

Note que “error” pode ser parte de “state” ou uma propriedade separada (ex.: “validation=none|error|success”). A escolha deve ser consistente entre componentes de formulário.

Passo 5 — Defina regras para “booleanos” e presença de elementos

Propriedades booleanas (true/false) são úteis, mas podem virar bagunça se cada componente inventar um nome. Padronize:

• Use hasX para presença: hasIcon, hasAvatar, hasDivider.
• Use showX para visibilidade condicional: showLabel, showHelper.
• Use leading/trailing quando posição importa: iconPosition=leading|trailing.

Evite misturar “icon=true” em um componente e “hasIcon=true” em outro. Escolha um padrão e aplique.

Nomenclatura para tokens: do global ao semântico

Tokens precisam ser fáceis de mapear para código e fáceis de manter quando temas mudam. Uma taxonomia de tokens geralmente tem níveis:

• Primitivos (base): valores brutos (cores, espaçamentos, fontes).
• Semânticos: intenção de uso (texto, superfície, borda, feedback).
• Component tokens (opcional): ajustes específicos por componente (ex.: button.background.primary).

Mesmo que você não publique todos os níveis, nomear com essa lógica evita acoplamento ao visual.

Padrão de nome com pontos

Use um esquema previsível: categoria.subcategoria.função.estado (nem todos os níveis são obrigatórios, mas a ordem deve ser estável).

color.text.default
color.text.muted
color.text.inverse
color.surface.default
color.surface.raised
color.border.default
color.border.focus
color.feedback.success
color.feedback.warning
space.100
space.200
radius.sm
radius.md

Regras práticas para tokens

• Evite nomes baseados em cor (“blue500”) como token final de uso; se existirem, trate como primitivo.
• Evite misturar separadores (ponto e hífen) no mesmo nível.
• Use números para escalas quando fizer sentido (space.100, space.200), mas documente a progressão.
• Inclua estado quando o token muda por interação (ex.: color.border.focus).

Nomenclatura para estilos (texto, cores, efeitos)

Estilos no Figma (Text Styles, Color Styles, Effect Styles) também precisam de taxonomia. A regra geral: nomes devem refletir intenção e hierarquia tipográfica, não o tamanho exato.

Text styles: hierarquia e função

Um padrão comum:

type.heading.h1
type.heading.h2
type.body.md
type.body.sm
type.label.md
type.caption

Se o produto tem variações por plataforma (web/mobile) ou densidade, inclua um nível:

type.web.body.md
type.mobile.body.md

Evite “Roboto 16 Regular” como nome: isso impede refatoração e não comunica uso.

Color styles: semântica por papel

color.text.default
color.text.muted
color.icon.default
color.surface.default
color.surface.overlay
color.border.default
color.border.subtle

Se você precisa de variações por tema (claro/escuro), mantenha o mesmo nome semântico e troque o valor por modo/tema, em vez de duplicar nomes com “Light/Dark” no final, quando possível.

Regras para estados e interações (sem poluir nomes)

Estados são uma fonte comum de inconsistência: “active” pode significar “selecionado” em um lugar e “pressionado” em outro. Defina um vocabulário de estados e aplique em todos os componentes interativos.

Vocabulário sugerido

• default: repouso
• hover: ponteiro sobre
• pressed: clique pressionado (momentâneo)
• focus: foco visível (teclado/acessibilidade)
• disabled: indisponível
• selected: selecionado (persistente)
• active: usar com cuidado; se possível, substituir por pressed/selected conforme o caso

Regra prática: se o estado é momentâneo, use “pressed”; se é persistente, use “selected”. Isso reduz discussões e melhora o mapeamento para código.

Anti-padrões comuns e como corrigir

Anti-padrão 1: “Default” como muleta

“Default” aparece quando não há clareza de variação. Se existe apenas uma opção, não nomeie como default; apenas não crie a propriedade. Se existem várias opções, “default” deve ter definição (ex.: “variant=default” significa “neutro”, diferente de primary/secondary?).

Anti-padrão 2: nomes que misturam intenção e implementação

Exemplo ruim: “Button / Primary Blue”. Mistura intenção (primary) com implementação (blue). Se amanhã o primary virar verde, o nome vira mentira. Prefira “variant=primary” e deixe a cor vir de tokens.

Anti-padrão 3: sinônimos competindo

“Toast” e “Snackbar” coexistindo sem regra. Solução: escolha um termo oficial e crie um glossário. Se precisar manter ambos por legado, defina um plano de migração e marque o termo antigo como “deprecated” em documentação interna (sem precisar poluir o nome do componente, se possível).

Anti-padrão 4: profundidade excessiva na hierarquia

Exemplo: “Inputs / Text field / With icon / With helper / Error”. Isso é sinal de que variantes estão sendo codificadas como pastas. Solução: reduzir para “Inputs / Text field” e mover diferenças para propriedades (leadingIcon, helperText, validation).

Passo a passo prático: criando um guia de nomenclatura (1 página)

Para manter consistência, crie um guia curto e operacional. Ele deve caber em uma página e responder “como nomear” sem debate.

Passo 1 — Defina o formato de nomes por tipo de item

• Componentes: “Categoria / Componente”
• Subcomponentes: “Categoria / Componente / Parte”
• Propriedades: lowercase (variant, size, state)
• Valores: lowercase (primary, md, disabled)
• Tokens/estilos: lowercase com pontos (color.text.default)

Passo 2 — Liste propriedades padrão e valores permitidos

Crie uma tabela simples (mesmo que fora do Figma) com propriedades canônicas e valores. Exemplo:

variant: primary | secondary | ghost | danger
size: xs | sm | md | lg
state: default | hover | pressed | focus | disabled | loading
validation: none | error | success
iconPosition: leading | trailing

Regra: se um componente precisar de um novo valor (ex.: size=xl), ele deve ser adicionado ao vocabulário e avaliado para outros componentes.

Passo 3 — Defina regras para nomes “proibidos”

Liste termos que não devem aparecer por serem ambíguos:

• Base
• New
• Temp
• Final
• Old
• Test

Se precisar sinalizar algo em transição, faça isso por processo (ex.: revisão/etiqueta) e não no nome do componente, para não eternizar dívida.

Passo 4 — Crie exemplos canônicos

Inclua 5 a 10 exemplos “perfeitos” para o time copiar. Exemplo:

Actions / Button
Navigation / Tabs
Inputs / Checkbox
Feedback / Alert
Overlays / Dialog
color.text.default
type.body.md

Governança leve: como manter a taxonomia saudável

Mesmo com regras boas, a biblioteca muda. Para evitar degradação, adote rotinas simples.

Checklist de revisão antes de publicar um componente

• O componente está na categoria correta?
• O nome segue o padrão (separadores, capitalização, singular)?
• As propriedades usam nomes canônicos (variant/size/state)?
• Os valores não criam sinônimos (sm vs small)?
• Existe alguma variação codificada no nome que deveria ser propriedade?
• Tokens/estilos usados são semânticos (quando aplicável)?

Política de mudança de nomes (para evitar quebra de busca e handoff)

Renomear itens afeta quem já usa a biblioteca. Defina regras:

• Renomear apenas quando houver ganho claro de consistência ou correção de conceito.
• Evitar renomes frequentes; agrupar mudanças em janelas.
• Quando um termo muda (ex.: “Dialog” substitui “Modal”), planejar migração e comunicar ao time.

Exemplo completo: taxonomia aplicada a um conjunto de componentes

A seguir, um exemplo de como a taxonomia e a nomenclatura se combinam em um sistema coerente:

Actions / Button
- variant: primary | secondary | ghost | danger
- size: sm | md | lg
- state: default | hover | pressed | focus | disabled | loading
- icon: none | leading | trailing | only

Inputs / Text field
- size: sm | md | lg
- state: default | hover | focus | disabled
- validation: none | error | success
- hasLeadingIcon: true | false
- hasTrailingIcon: true | false
- showHelperText: true | false

Feedback / Alert
- tone: info | success | warning | critical
- variant: filled | subtle | outline
- hasIcon: true | false
- hasAction: true | false

Navigation / Tabs
- size: sm | md | lg
- state: default | hover | selected | disabled
- align: start | center

Overlays / Dialog
- size: sm | md | lg
- hasHeader: true | false
- hasFooter: true | false

Observe que “tone” aparece em componentes de feedback e pode ser reutilizado em Badge/Tag/Toast. “validation” aparece em componentes de formulário. “state” mantém vocabulário coerente, com “selected” onde faz sentido.

Passo a passo prático: auditoria e refatoração de nomes existentes

Passo 1 — Extraia uma lista de itens e identifique padrões divergentes

Faça uma varredura dos nomes atuais e marque:

• Sinônimos (Dialog/Modal, Text field/Input)
• Separadores diferentes (“-” vs “/”)
• Pluralização inconsistente (Buttons vs Button)
• Variações no nome que deveriam ser propriedades (Primary/Secondary no nome)

Passo 2 — Defina o “padrão alvo” e mapeie conversões

Crie um mapeamento simples “antes → depois”. Exemplo:

Buttons/Primary  → Actions / Button (variant=primary)
Buttons/Secondary → Actions / Button (variant=secondary)
Modal/Default → Overlays / Dialog

Passo 3 — Refatore começando pelos itens mais reutilizados

Priorize componentes com maior impacto (Button, Text field, Icon, Typography). Ajustar esses primeiro reduz a chance de novos componentes nascerem com padrões antigos.

Passo 4 — Normalize propriedades e valores

Se você encontrar “size=small|medium|large” em um componente e “size=sm|md|lg” em outro, escolha um padrão e migre. O mesmo vale para state (active vs selected vs pressed).

Passo 5 — Crie uma lista de “decisões finais” (para evitar regressão)

Registre decisões como:

• Usamos “Dialog” (não “Modal”).
• Usamos “Text field” (não “Input”).
• Tamanhos são xs/sm/md/lg.
• Estados momentâneos usam “pressed”; persistentes usam “selected”.

Esse registro é o que impede que a taxonomia se fragmente novamente quando o time crescer.