Arquitetura de token de design semântico: tokens globais, semânticos e de componentes
Como estruturar tokens de design em três níveis, suportar temas e múltiplas marcas e enviá-los para a web, iOS e Android usando o formato W3C DTCG.
Ponto principal
A maioria dos sistemas de design maduros usa três níveis de tokens: global (valores brutos como blue-600), semântico (propósito, como color.action.primary) e componente (usos específicos, como button.background). Os componentes fazem referência a tokens semânticos, os tokens semânticos fazem referência aos globais e os temas ou marcas trocam apenas a camada semântica. Armazene-os no formato W3C DTCG e gere o código da plataforma com uma ferramenta de construção.
Os três níveis
Material Design descreve três classes de tokens: referência, sistema e componente. Muitas equipes os chamam de globais, semânticos e componentes. Os nomes diferem, mas a ideia é a mesma: separar os valores brutos das decisões sobre como eles são usados.
- Global (referência): todos os valores brutos do sistema, como azul-600, espaço-4, tamanho da fonte-16, primavera-suave.
- Semântica (sistema): para que serve um valor, como color.text.primary, color.action.primary, motion.enter.
- Componente: como um componente usa o sistema, como button.background ou dialog.motion.open.
Por que os tokens semânticos são importantes
Se um botão usa blue-600 diretamente, cada mudança de tema significa editar cada componente. Se usar color.action.primary, modo escuro, alto contraste ou uma nova marca, altere apenas o que color.action.primary aponta. O material observa que os tokens tornam possível aplicar uma paleta de alto contraste ou alterar a escala de tipo em todo o sistema exatamente dessa maneira.
Temas e múltiplas marcas
Para produtos multimarcas ou de marca branca, mantenha um conjunto de tokens semânticos e de componentes e uma paleta global por marca. Cada tema é um mapeamento de tokens semânticos para valores globais. A primeira versão estável da especificação W3C Design Tokens (2025.10), lançada em outubro de 2025, adicionou temas e suporte multimarcas, espaços de cores modernos, como Display P3 e OKLCH, além de aliases e referências em nível de componente.
Os tokens de movimento também pertencem aqui
Durações, curvas de atenuação e molas seguem os mesmos níveis. Um token global pode ser suave com sua rigidez e amortecimento; um token semântico motion.enter aponta para ele; um token de componente sheet.motion.open aponta para motion.enter. Adicione um tema de movimento reduzido que remapeia tokens de movimento para fades curtos.
Envio de tokens para todas as plataformas
Mantenha os tokens em um repositório como DTCG JSON, a única fonte da verdade. Uma ferramenta de construção como Style Dictionary os transforma em variáveis CSS, Swift, Kotlin, Flutter ou outros formatos. As ferramentas de design que leem o mesmo formato podem permanecer sincronizadas e as ferramentas de codificação de IA podem ler o JSON diretamente.
- Fonte da verdade: DTCG JSON no Git, revisado como código
- Construir: transforme-se em cada plataforma a cada mudança
- Sincronização da ferramenta de design: importação ou plugin, valores nunca copiados manualmente
- Linting: proíbe valores brutos em componentes
Princípios-chave para lembrar
- Três níveis: global (valores), semântico (propósito), componente (uso)
- Os componentes fazem referência a tokens semânticos, nunca a valores brutos
- Temas e marcas remapeiam a camada semântica
- O formato W3C DTCG atingiu sua primeira versão estável (2025.10) em outubro de 2025
- Inclui tokens de movimento e um tema de movimento reduzido
Perguntas frequentes
Fontes
- Design tokens overview — Material Design 3
- Design Tokens specification reaches first stable version — Grupo comunitário de tokens de design W3C
- Design Tokens Community Group — designtokens.org
- Style Dictionary — styledictionary.com