--- title: O que são Design Tokens? Exemplos, tipos e padrão DTCG date: 2026-04-30T17:14:42Z modified: 2026-10-15T02:30:31Z permalink: "https://camaraux.com.br/design-tokens-arquitetura-w3c/" type: post status: publish excerpt: Entenda o que são Design Tokens, diferenças entre primitivos e semânticos e como usar JSON DTCG 2025.10, Figma Variables e CSS. wpid: 5442 categories: - Design Systems tags: - Design Systems - arquitetura de sistemas - automação de design - design ops - design systems - Design Tokens - design tokens community group - escalabilidade de design - front-end architecture - nomenclatura de tokens - taxonomia de design - tokens agnósticos - tokens semânticos - ui engineering - ux design sênior - w3c design tokens rank_math_title: O que são Design Tokens? Da taxonomia à especificação W3C rank_math_description: Aprenda a estruturar Design Tokens escaláveis usando arquitetura em camadas, taxonomia eficiente e as normas da especificação W3C. Confira! rank_math_focus_keyword: Design Tokens featured_image: /wp-content/uploads/2026/04/O-que-sao-Design-Tokens-Da-taxonomia-a-especificacao-W3C.webp featured_image_alt: Pessoa observando edifício estilizado com arcos e formas geométricas em primeiro plano author: Lucas Camara timestamp: 2026-10-15T02:30:31Z --- **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. | ![Design Tokens](https://camaraux.com.br/wp-content/uploads/2026/04/Design-Tokens.gif "Camaraux, consultoria em UX design, projetos centrados no usuário") ## 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](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/como-criar-paleta-cores-design-system.md). ### 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)](https://www.w3.org/community/design-tokens) 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](https://www.designtokens.org/tr/2025.10/color/) 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](https://www.designtokens.org/faq/) 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](https://www.designtokens.org/tr/2025.10/format/), `$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](https://www.styledictionary.org/info/tokens/) 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](https://help.figma.com/hc/pt-br/articles/15339657135383-Guia-de-vari%C3%A1veis-no-Figma) 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. ![Design Tokens](https://camaraux.com.br/wp-content/uploads/2026/04/Design-Tokens-aplicando-figma-variables.png "Camaraux, consultoria em UX design, projetos centrados no usuário") 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](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/figma-variables.md). 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](https://www.w3.org/TR/WCAG22/) 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](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-system-guia-escalabilidade-roi.md) reúne componentes, padrões e governança; tokens são uma parte dessa estrutura. Já [DESIGN.md](https://camaraux.com.br/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](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-md-vs-design-tokens.md). ## 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](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-system-guia-escalabilidade-roi.md). Se a equipe precisa identificar inconsistências e priorizar a evolução do produto, conheça a [consultoria de UX](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/page/consultoria-de-ux.md). ## Fontes e referências - [Design Tokens Community Group — Format Module 2025.10](https://www.designtokens.org/tr/2025.10/format/) (JSON, tipos e referências). - [Design Tokens Community Group — Color Module 2025.10](https://www.designtokens.org/tr/2025.10/color/) (valores cromáticos). - [Design Tokens Community Group — FAQ](https://www.designtokens.org/faq/) (status da especificação). - [W3C Community — Design Tokens](https://www.w3.org/community/design-tokens) (grupo e publicações). - [Figma Learn — Guia de variáveis](https://help.figma.com/hc/pt-br/articles/15339657135383-Guia-de-vari%C3%A1veis-no-Figma) (Variables, aliases e modos). - [Style Dictionary — Design Tokens](https://www.styledictionary.org/info/tokens/) (transformação para plataformas). - [W3C — WCAG 2.2](https://www.w3.org/TR/WCAG22/) (requisitos para interfaces finais). ## Topics **Categorias:** [Design Systems](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/category/design-systems.md) **Tags:** [arquitetura de sistemas](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/arquitetura-de-sistemas.md), [automação de design](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/automacao-de-design.md), [design ops](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-ops.md), [design systems](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-systems.md), [Design Tokens](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-tokens.md), [design tokens community group](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-tokens-community-group.md), [escalabilidade de design](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/escalabilidade-de-design.md), [front-end architecture](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/front-end-architecture.md), [nomenclatura de tokens](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/nomenclatura-de-tokens.md), [taxonomia de design](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/taxonomia-de-design.md), [tokens agnósticos](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/tokens-agnosticos.md), [tokens semânticos](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/tokens-semanticos.md), [ui engineering](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/ui-engineering.md), [ux design sênior](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/ux-design-senior.md), [w3c design tokens](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/w3c-design-tokens.md)