Design Tokens são valores nomeados e reutilizáveis que representam decisões de design, como cores, espaçamento e tipografia. Em vez de repetir um HEX em dez componentes, a equipe pode manter um token para a cor e outros tokens que indiquem em quais funções ela deve ser usada.
Eles ajudam a aproximar o que designers definem no Figma daquilo que desenvolvedores implementam. Mas tokens não são apenas variáveis CSS: podem ser descritos em arquivos interoperáveis, referenciados por aliases e transformados para diferentes tecnologias. Neste guia você aprenderá o que são tokens primitivos e semânticos, como escrever um arquivo JSON DTCG e como lidar com temas e governança.
O que são Design Tokens e para que servem?
Design Tokens traduzem decisões visuais para uma linguagem organizada, que pode ser interpretada por ferramentas e pessoas. Eles são especialmente úteis em produtos com múltiplos componentes, marcas ou equipes. Um token não é uma promessa de sincronização automática: cada etapa entre o design e o código exige integração e verificação.
Uma cor da marca, por exemplo, pode ser registrada como color.brand.500, enquanto um botão usa color.action.primary. Quando a função é expressa separadamente do valor, fica mais fácil adaptar o componente a novos temas sem trocar HEXs em cada lugar.
| Sem sistema de tokens | Com arquitetura e referências |
|---|---|
| HEX e medidas repetidos sem relação explícita. | Valores padronizados e nomeados por papel. |
| Cada componente decide como uma cor é utilizada. | O token semântico expressa a intenção do uso. |
| Mudanças exigem inspeção de vários arquivos. | Integrações permitem propagar referências com revisão. |
| Temas claros e escuros são configurados isoladamente. | Papéis podem ser associados a valores específicos por tema. |
Tipos de Design Tokens: primitivos, semânticos e componentes
Um modelo comum de arquitetura organiza os tokens em três camadas. Essa é uma decisão de arquitetura adotada por muitas equipes, e não uma exigência formal de três níveis pela especificação DTCG. Dependendo do produto, um nível pode não ser necessário.
Tokens primitivos: inventário de valores
Primitivos descrevem os valores disponíveis: color.brand.500, space.md ou font.weight.bold. Nomes como esses indicam o que existe no sistema, mas não necessariamente onde usar cada escolha. Os valores podem mudar em uma revisão de marca ou de acessibilidade; não são imutáveis.
Uma escala de 50 a 950 pode ajudar a organizar a paleta, mas os números não garantem contraste nem devem ser usados automaticamente como nomes de funções. Para projetar as famílias cromáticas, veja paleta de cores para Design System.
Tokens semânticos: papéis no produto
Tokens semânticos descrevem o papel de um valor, como color.text.default, color.surface.page ou color.action.primary. Eles permitem diferenciar a intenção do componente do valor escolhido no momento. O token semântico pode mudar a cor utilizada em um tema escuro e continuar representando a mesma função.
Um alias é uma referência técnica a outro token. Isso não é exatamente o mesmo que “semântica”: aliases podem existir em diferentes níveis, enquanto a nomeação semântica representa uma decisão de arquitetura e linguagem.
Tokens de componente: exceções e necessidades específicas
Alguns Design Systems usam button.primary.background ou input.border.focus para detalhar decisões de componentes. Essa camada deve existir quando oferece benefício prático, e não apenas para duplicar cada propriedade de cada variante. Evite construir um catálogo tão profundo que ninguém consiga encontrar a decisão certa.
| Camada | Exemplo | Função |
|---|---|---|
| Primitiva | color.brand.500 | Representar um valor de cor. |
| Semântica | color.action.primary | Representar uma ação primária. |
| Componente | button.primary.background | Aplicar uma decisão ao botão, se a camada for necessária. |
Como nomear Design Tokens
Uma boa taxonomia torna decisões encontráveis e coerentes. Prefira um padrão que diferencie categoria, função, variação e estado, sem obrigar cada token a conter todos esses elementos. O formato do nome só é útil se as equipes conseguirem localizar e usar as referências certas.
- Primitivos: nomes que representam inventários de valores sem antecipar o uso final.
- Semânticos: nomes que comunicam papel, como fundo, texto, ação ou borda.
- Estados: variações documentadas para foco, hover, erro ou seleção quando necessárias.
- Consistência: separadores, pluralização e convenções devem ser uniformes dentro do sistema.
- Governança: registre nomes descontinuados, responsáveis, revisões e orientações de migração.
Especificação DTCG 2025.10: o que foi padronizado?
O Design Tokens Community Group (DTCG) publicou, em 28 de outubro de 2025, sua primeira especificação estável para compartilhamento de tokens. Ela fornece um formato de intercâmbio com grupos, tipos, valores e referências. O conjunto também inclui módulos específicos para cores e mecanismos de resolução relacionados a temas.
Atenção à terminologia: a versão DTCG 2025.10 é um Final Community Group Report estável, não uma W3C Recommendation. O FAQ oficial do DTCG explica que ela não pertence ao W3C Standards Track. Assim, dizer que é “uma norma W3C obrigatória” seria incorreto.
O que significam $value, $type e aliases?
No Format Module 2025.10, $value guarda o conteúdo de um token. A propriedade $type define o tipo, como color ou dimension, e também pode ser herdada de grupos válidos. Sem um tipo que possa ser resolvido, o token não é considerado válido. Referências como {color.brand.500} permitem apontar para valores existentes.
O tipo determina a estrutura esperada. Cores podem usar colorSpace e components; dimensões expressam número e unidade. Escrever qualquer string em JSON não basta para garantir compatibilidade com o formato estável.
Exemplo de Design Tokens em JSON DTCG 2025.10
O exemplo a seguir é didático. A cor-base usa sRGB, o token de ação faz uma referência e o espaçamento registra um valor em pixels. Os exemplos não são dados de um cliente ou exportações automáticas de um plugin.
{
"color": {
"brand": {
"500": {
"$type": "color",
"$value": {
"colorSpace": "srgb",
"components": [
0,
0.4,
0.8
],
"hex": "#0066cc"
}
}
},
"action": {
"primary": {
"$type": "color",
"$value": "{color.brand.500}"
}
}
},
"space": {
"md": {
"$type": "dimension",
"$value": {
"value": 16,
"unit": "px"
}
}
}
}A cor primitiva color.brand.500 contém o valor; color.action.primary aponta para ela. É possível alterar o valor do primitivo preservando a referência, desde que as ferramentas resolvam os aliases corretamente. O token space.md demonstra o tipo de dimensão com seu número e unidade.
Como gerar variáveis CSS a partir dos tokens
Ferramentas como o Style Dictionary podem consumir valores e produzir saídas para diferentes plataformas. O CSS abaixo é apenas uma representação possível dos tokens anteriores; a saída real depende das regras de transformação e da configuração da equipe.
:root {
--color-brand-500: #0066cc;
--color-action-primary: var(--color-brand-500);
--space-md: 16px;
}
.button-primary {
background: var(--color-action-primary);
padding-inline: var(--space-md);
}Compartilhar nomes reduz divergências, mas não garante que a variável do Figma e a implementação estejam sincronizadas. Para fechar esse ciclo, defina responsáveis, fonte de verdade, processo de publicação, revisão e testes.
Design Tokens e Figma Variables: qual a relação?
As Figma Variables armazenam valores reutilizáveis e suportam referências e modos em contextos compatíveis. Elas podem representar decisões da arquitetura de tokens, mas não são, por si só, um arquivo interoperável DTCG. O fluxo entre Figma, um repositório e código depende das ferramentas e permissões disponíveis.
Para aprender sobre coleções, aliases, modes e operação dentro do editor, consulte o artigo especializado Figma Variables: design tokens, dark mode e theming. Aqui o assunto principal é a arquitetura dos tokens e como suas representações se relacionam.
Como usar Design Tokens em modo claro e escuro
O ideal é preservar papéis como color.surface.page ou color.text.default ao variar o tema. Os valores associados podem mudar para conservar legibilidade e hierarquia. A resolução de temas tem regras próprias; um JSON de tokens não transforma automaticamente a interface quando o usuário ativa o modo escuro.
| Token semântico | Modo claro | Modo escuro |
|---|---|---|
color.surface.page | Superfície clara aprovada | Superfície escura aprovada |
color.text.default | Texto escuro sobre superfície clara | Texto claro sobre superfície escura |
color.action.primary | Tom escolhido e testado para esse contexto | Tom escolhido e testado para o tema escuro |
O mapeamento precisa ser validado no produto. WCAG 2.2 e outros requisitos aplicáveis devem ser avaliados nos pares reais de cores e controles. A existência de tokens não garante conformidade com acessibilidade.
Design Tokens, Design System e DESIGN.md não são sinônimos
Um Design System reúne componentes, padrões e governança; tokens são uma parte dessa estrutura. Já DESIGN.md documenta instruções de design em determinados fluxos com agentes e ferramentas de IA. Ele não substitui por padrão um sistema de tokens tipados. A comparação específica está em DESIGN.md versus Design Tokens.
Como criar Design Tokens em seis etapas
Antes de criar dezenas de tokens, identifique quais decisões realmente precisam ser compartilhadas entre produtos e plataformas. Use este roteiro como referência e adapte a documentação ao grau de maturidade e ao número de equipes envolvidas.
Como organizar Design Tokens em seis etapas, da auditoria de valores à governança.
Mapeie as decisões repetidas
Levante cores, espaços, tipografia e componentes usados no produto e identifique divergências.
Defina nomes e papéis
Separe valores primitivos dos tokens que representam funções, temas e estados.
Modele e valide o formato
Crie tokens tipados com valores e referências compatíveis com o formato adotado.
Integre Figma e código
Documente a origem dos valores, os transformadores utilizados e a forma de atualizar a implementação.
Teste interfaces e temas
Verifique acessibilidade, contraste, estados e diferentes condições de uso.
Governança e versionamento
Defina revisores, regras de mudança, depreciações e critérios de qualidade para lançamentos.
Como medir a eficiência dos Design Tokens
Evite afirmar que o uso de tokens reduz custos ou prazos por uma porcentagem fixa sem medições específicas. O objetivo é melhorar a consistência e reduzir esforço de manutenção, mas as consequências dependem da arquitetura, da equipe e das ferramentas. Registre indicadores e compare tarefas equivalentes.
| Indicador | Como usar | Limitação |
|---|---|---|
| Referências quebradas | Identificar aliases ou tipos inconsistentes. | Validação técnica não garante boa semântica. |
| Valores fora da biblioteca | Verificar repetições de HEXs, tamanhos ou espaços. | Exceções locais podem ser legítimas. |
| Mudanças propagadas | Conferir versões adotadas em produtos e apps. | Atualização não substitui testes de regressão. |
| Tempo de manutenção | Observar o esforço para revisar uma decisão compartilhada. | Compare cenários de complexidade semelhante. |
Erros frequentes na implementação
- Confundir tokens com apenas cores: espaçamentos, tipografia e outras decisões podem ser modelados.
- Tratar DTCG como recomendação formal do W3C: o status correto é relatório estável de grupo comunitário.
- Impor três camadas para qualquer projeto: uma arquitetura simples também pode ser suficiente.
- Presumir sincronia automática: nomes iguais não são uma integração real entre Figma e código.
- Dispensar acessibilidade: é indispensável testar resultados no produto e em cada tema.
- Prometer ROI sem dados: a melhoria precisa ser medida, não apenas presumida.
Perguntas frequentes sobre Design Tokens
O que são Design Tokens?
São representações nomeadas de decisões de design, incluindo cores, espaçamento e tipografia. Podem ser compartilhadas entre componentes, ferramentas e plataformas por formatos e transformações compatíveis.
O que são tokens primitivos e semânticos?
Primitivos representam valores disponíveis, por exemplo color.brand.500. Semânticos nomeiam funções, por exemplo color.action.primary, e podem referenciar primitivas.
O DTCG é uma recomendação oficial do W3C?
Não. A versão 2025.10 é um Final Community Group Report estável criado no contexto de um grupo da comunidade W3C, mas não uma W3C Recommendation.
O que significam $value e $type?
No DTCG, $value armazena o valor do token e $type identifica um tipo válido como color ou dimension. O tipo também pode ser herdado de grupos ou referências adequadas.
Figma Variables são Design Tokens?
Variables podem representar decisões de design e suas referências no Figma. Porém, o formato de Variables e o formato interoperável DTCG não são a mesma coisa; sincronizá-los pode exigir integrações.
Tokens garantem contraste e acessibilidade?
Não. Tokens permitem organizar decisões, mas os pares de cor, estados e comportamento da interface final precisam ser testados conforme os critérios aplicáveis das WCAG.
Conclusão
Design Tokens transformam decisões repetidas em referências que podem ser auditadas, transformadas e reutilizadas. Um bom sistema combina nomes compreensíveis, tipos corretos, aliases válidos, integração e governança. A especificação DTCG 2025.10 contribui para esse objetivo, mas não dispensa decisões de design e validação das interfaces.
Para organizar componentes e processos em torno dessas decisões, veja o guia de Design Systems. Se a equipe precisa identificar inconsistências e priorizar a evolução do produto, conheça a consultoria de UX.
Fontes e referências
- Design Tokens Community Group — Format Module 2025.10 (JSON, tipos e referências).
- Design Tokens Community Group — Color Module 2025.10 (valores cromáticos).
- Design Tokens Community Group — FAQ (status da especificação).
- W3C Community — Design Tokens (grupo e publicações).
- Figma Learn — Guia de variáveis (Variables, aliases e modos).
- Style Dictionary — Design Tokens (transformação para plataformas).
- W3C — WCAG 2.2 (requisitos para interfaces finais).
