Design Tokens: Como Sistemas de Design Reais Mantêm Consistência
O que são design tokens, o modelo de três camadas usado por sistemas reais (Shopify Polaris, IBM Carbon, GitHub Primer), como nomeá-los, tematização para dark mode e quando tokens são exagero.
Design Tokens: Como Sistemas de Design Reais Mantêm Consistência
Um código hex é um valor. Um token é uma decisão com nome. Sistemas de design são feitos de decisões, não de valores.
Essa distinção é o ponto central. Escreva #0EA5E9 diretamente em catorze componentes do Figma, receba um pedido de dark mode, e você vai passar uma semana fazendo find-and-replace. Nomeie como color-interactive-primary e você muda um valor enquanto todas as superfícies atualizam. Isso não é mágica, apenas decisões nomeadas.
O que é um design token, de verdade
Um design token é uma variável nomeada que armazena uma decisão de design. Pode guardar uma cor, um valor de espaçamento, um tamanho de fonte, um border radius, uma sombra, uma duração. O nome é o contrato. O valor por trás do nome pode mudar sem quebrar nada que use o token.
A abordagem clássica sem tokens começa quando um designer escolhe #1D4ED8 para botões primários, escreve diretamente no componente de botão, depois copia aquele hex para o card, o badge e o link. Seis meses depois, a marca muda. Agora você tem um problema de manutenção que escala com cada componente que você entregou.
Os tokens invertem isso. Você nomeia a decisão (color-action-default), atribui o valor uma vez, e tudo que referencia o token fica sincronizado. O valor é detalhe de implementação. O nome é o sistema.
As três camadas que fazem os tokens funcionarem
Tokens brutos são apenas variáveis. O que torna um sistema de tokens realmente útil é a hierarquia. Todo sistema em produção que vale estudar usa três camadas.
| Camada | Também chamada de | O que armazena | Exemplo |
|---|---|---|---|
| Primitivo | Global, Base | Valores brutos, sem significado | color.blue.500 = #3B82F6 |
| Semântico | Alias, Role | Papéis nomeados mapeados para primitivos | color.interactive.default = color.blue.500 |
| Componente | Específico | Decisões com escopo de componente | button.background.default = color.interactive.default |
Primitivos são sua paleta. Todo azul, cada passo de espaçamento e cada raio vive aqui como um valor nomeado sem opinião sobre onde será usado. Você não consome primitivos diretamente nos componentes.
Tokens semânticos mapeiam papéis para primitivos. O token color-surface-default pode apontar para quase-branco no modo claro e quase-preto no dark mode, e o componente nunca sabe qual valor bruto recebe. Ele só conhece o papel.
Tokens de componente são os mais específicos. Existem quando um componente precisa de uma decisão intencionalmente diferente do padrão semântico. Um botão de perigo aponta seu background para um papel de feedback crítico em vez do papel interativo padrão. A maioria dos componentes não precisa de tokens próprios; consome tokens semânticos diretamente.
Por que tokens superam valores hardcoded
Velocidade de mudança é o argumento óbvio, mas não é o real. O argumento real é precisão.
Quando um designer entrega um arquivo cheio de códigos hex brutos, o desenvolvedor não tem ideia de quais são intencionais e quais são acidentais. Aquele #1A1A2E é o background, ou alguém usou eyedrop na camada errada? Os tokens eliminam a ambiguidade. Um nome de token semântico é documentação que viaja junto com o valor.
Os tokens também são o contrato de handoff entre ferramentas de design e código em 2026. As variáveis do Figma mapeiam diretamente para CSS custom properties. Um token definido em um arquivo do Figma pode ser exportado, commitado e consumido no código sem uma etapa manual sequer. A distância entre design e implementação colapsa quando os dois lados falam os mesmos nomes de token.
Para equipes que trabalham com acessibilidade, os tokens adicionam mais uma camada de segurança. Você audita a paleta semântica em um só lugar e garante que color-text-default sempre passa 4.5:1 de contraste contra color-surface-default, independente do tema ativo.
Como sistemas de design reais estruturam seus tokens
Três sistemas valem a pena conhecer: Shopify Polaris, IBM Carbon e GitHub Primer. Eles lidam com o modelo de três camadas de formas diferentes, e as diferenças são instrutivas.
Shopify Polaris mantém primitivos em uma escala de cores (color-sky-100 até color-sky-900) e os alia a papéis semânticos como --p-color-bg-fill-active. Tokens de componente são escassos, então a maioria dos componentes consome tokens semânticos. A convenção é papel-então-estado, que lê naturalmente no código, já que você sabe para que serve bg-fill-disabled sem contexto extra.
Veja ao vivo em polaris.shopify.com
IBM Carbon vai fundo nas camadas semânticas. Seu conjunto de cores inclui tokens de feedback explícitos como support-error e support-success, tokens de estado interativo e tokens de camada para superfícies aninhadas (um componente em um painel em uma página precisam cada um de um valor de superfície diferente). É mais complexo, mas a IBM entrega software enterprise onde cada estado aninhado importa.
Veja ao vivo em carbondesignsystem.com
GitHub Primer expõe sua camada primitiva como "primitives" e sua camada semântica como "functional tokens", documentados publicamente em primer.style. A tematização do Primer permite ao GitHub entregar temas claro, escuro, claro de alto contraste e escuro atenuado a partir de um único conjunto de componentes. Cada tema é uma atribuição de valores diferente para os mesmos nomes de token.
O padrão comum aos três é consistente: primitivos como escala, tokens semânticos como nomes de papel, e tematização como troca de valores na camada semântica. Os componentes permanecem intocados.
A Brainy ajuda designers a construírem sistemas que escalam, não telas únicas. Veja o que estamos construindo para criadores em /creators.
Como nomear tokens sem enlouquecer
A nomenclatura de tokens quebra equipes. Genérico demais e os nomes não carregam informação. Específico demais e você escreve um novo token para cada componente.
Uma convenção de nomenclatura que funciona nomeia quatro partes: categoria, papel, variante e estado. Você não vai usar todas as quatro sempre, mas a estrutura evita o caos ad-hoc.
| Parte | O que captura | Exemplos |
|---|---|---|
| Categoria | A propriedade de design | color, spacing, radius, shadow, font |
| Papel | O propósito semântico | surface, text, border, interactive, feedback |
| Variante | Sub-papel ou modificador | primary, secondary, danger, subtle |
| Estado | Condição interativa | default, hover, active, disabled, focus |
Exemplos práticos, escritos como CSS custom properties que um desenvolvedor realmente consome:
color-surface-defaultdefine o background padrão da páginacolor-text-subtleé o texto secundário com contraste mais baixocolor-interactive-primary-hoveré o estado hover de uma ação primáriaspacing-component-mdé o padding interno médio para componentesradius-interactiveé o border radius para elementos clicáveis
Duas regras evitam a maioria das discussões. Nunca codifique o valor bruto no nome, porque color-blue-500 não diz nada sobre o papel. Nunca nomeie por componente na camada semântica, porque button-primary-color na camada semântica significa que você pulou a camada semântica por completo.
Para sistemas de tipografia que escalam, a mesma convenção se aplica, e font-size-body-lg supera text-18px sempre.
Um conjunto de tokens, light mode e dark mode
O dark mode é onde os sistemas de tokens se pagam de forma mais visível. Se você nomeou seus tokens por papel, dark mode é uma troca de valores, não um redesenho.
O mecanismo é direto. Seu token semântico color-surface-default aponta para um primitivo que é quase-branco no modo claro e quase-preto no dark mode. O componente que o consome nunca muda. Você troca de tema trocando o mapeamento de valores na camada semântica.
CSS custom properties tornam isso mecânico:
:root {
--color-surface-default: #ffffff;
--color-text-primary: #111827;
}
[data-theme="dark"] {
--color-surface-default: #0f172a;
--color-text-primary: #f8fafc;
}
Todo componente que referencia var(--color-surface-default) agora responde ao atributo de tema com zero código adicional. Shopify Polaris, GitHub Primer e IBM Carbon usam esse padrão em escala de produção.
O erro mais comum é misturar tokens semânticos e primitivos nos componentes. Quando um componente referencia color-blue-600 diretamente em vez de color-interactive-primary, aquele componente para de responder à tematização. Uma referência primitiva descuidada quebra o modelo inteiro. Regras de lint que sinalizam consumo direto de primitivos em código de componente valem o tempo de configuração.
Entender como as escolhas de cor funcionam dá o embasamento conceitual, e os tokens dão a estrutura para agir sobre isso em todos os temas.
Quando design tokens são exagero
Tokens adicionam indireção. Indireção tem custos. Seja honesto sobre quando esses custos valem a pena.
| Situação | Tokens? | Motivo |
|---|---|---|
| Sistema de design servindo 3+ produtos | Sim | Tokens compartilhados se pagam imediatamente |
| Produto único, 5+ designers | Sim | Evita desvio de paleta na equipe |
| Produto único, 1-2 designers, iteração ativa | Talvez | Somente camada semântica, pule tokens de componente |
| Site de marketing, sem biblioteca de componentes | Não | Uma stylesheet é mais rápida de mudar |
| Protótipo ou MVP em menos de 3 meses | Não | Abstraia depois que o design se estabilizar |
| Adicionando dark mode a um sistema existente | Sim | É exatamente para isso que os tokens servem |
Equipes pequenas se movem mais rápido sem tokens. Uma startup de três pessoas buscando product-market fit não precisa de uma hierarquia de três camadas. Quando você muda a direção visual a cada duas semanas, uma única biblioteca de estilos no Figma é suficiente.
O antipadrão a evitar é a nomenclatura semântica prematura. Tokens chamados color-blue e color-gray adicionam indireção sem significado. Ou nomeie por papel com color-surface e color-text, ou fique com primitivos até ter componentes suficientes para saber quais papéis de fato existem.
Nomenclatura ruim de tokens é pior do que nenhum token. Um token chamado button-color-for-the-checkout-page na camada semântica é uma armadilha de manutenção. A disciplina de nomenclatura não é opcional, é a razão pela qual os tokens funcionam.
FAQ
Design tokens substituem os estilos do Figma?
Não, mas os estendem. As variáveis do Figma, lançadas em 2023, são o equivalente nativo mais próximo dentro do Figma, e mapeiam para tokens de código quando você compartilha convenções de nomenclatura entre os dois. Os estilos do Figma lidam com tipografia e preenchimentos de cor, enquanto as variáveis lidam com a hierarquia completa de tokens, incluindo estados e decisões de nível de componente.
Os tokens funcionam sem um sistema de design?
Os tokens são mais valiosos dentro de um sistema de design, mas até um produto único se beneficia de nomenclatura semântica no nível de CSS custom properties. Você não precisa de um sistema formal para parar de hardcodar valores hex.
Qual ferramenta devo usar para gerenciar tokens?
Para equipes pequenas, variáveis do Figma mais uma exportação JSON são suficientes. Para equipes maiores, Style Dictionary (open source, da Amazon) é a ferramenta de build padrão. Ele recebe uma estrutura JSON de tokens e gera CSS custom properties, constantes Swift para iOS e XML para Android. Tokens Studio para Figma é o plugin ponte popular entre Figma e Style Dictionary.
Qual deve ser a granularidade dos tokens de componente?
Apenas a granularidade necessária. A maioria dos componentes pode consumir tokens semânticos diretamente. Tokens específicos de componente fazem sentido quando um componente diverge da camada semântica intencionalmente, como um botão de ação destrutiva ou um banner com uma superfície incomum. Na dúvida, consuma tokens semânticos e crie tokens de componente apenas quando você se pegar escrevendo exceções.
Os tokens funcionam para espaçamento e tipografia, ou só para cores?
Tokens funcionam para qualquer coisa com um valor discreto: cor, espaçamento, tipografia, border radius, box shadow, duração de animação, easing de animação e z-index. Os sistemas mais maduros, como IBM Carbon e Atlassian Design System, têm tokens para todos esses casos. Comece com cor e espaçamento, depois adicione os outros conforme o sistema amadurece.
Pare de hardcodar valores
O caminho prático não é complicado:
- Nomeie seus primitivos como uma escala
- Mapeie esses primitivos para papéis semânticos
- Faça cada componente consumir tokens semânticos, nunca primitivos
- Exporte os valores de tokens de uma fonte única (variáveis do Figma, um arquivo JSON ou um pacote de sistema de design) e deixe as ferramentas de build distribuí-los para CSS, iOS e Android
Você não precisa de uma migração de três meses para começar. Pegue um componente, nomeie suas decisões e sinta a diferença quando você muda um valor uma vez e vê tudo atualizar. Essa experiência é o argumento.
Para mais textos sobre sistemas de design, veja o que a Brainy cobre em /paper.
Brainy helps designers build systems that scale, not one-off screens. See what we are building for creators.
Get Started
