Forma / FRM.003Explicado

Design tokens: como uma decisão de design vira código

Valores com nome que guardam as decisões visuais de uma marca. Entenda as camadas, como funciona um arquivo de tokens no formato estável do W3C e como começar.

Quantas vezes o mesmo verde aparece no seu produto com códigos ligeiramente diferentes? Em uma tela é #BBFF3D, em outra alguém digitou #BCFF40, e no aplicativo móvel ninguém sabe de onde veio a cor. Design tokens existem para resolver esse tipo de desencontro. Ou seja, são valores com nome que guardam as decisões visuais de uma marca (cores, fontes, espaçamentos, tempos de animação) em um lugar só, para que design e código usem a mesma fonte.

Neste explicado, você vai entender o que são design tokens, como eles se organizam em camadas, como um arquivo de tokens funciona na prática e o que mudou depois que o grupo de trabalho do W3C publicou um formato estável, em outubro de 2025.

O que são design tokens

Um design token é um par de nome e valor. O nome descreve a intenção, enquanto o valor é o dado concreto. cor.fundo.pagina pode valer #F2F1ED. espaco.secao pode valer 112px. A comunidade que mantém a especificação define os tokens como “a fonte única de verdade para cores, tipografia, espaçamento e outras decisões de design”, segundo o anúncio do W3C.

Por que dar nome a um número? Porque o nome sobrevive à mudança. Assim, se a marca decidir escurecer o fundo, você altera o valor em um ponto e todas as telas, componentes e plataformas acompanham. Sem tokens, por outro lado, a mesma alteração vira uma caça ao código hexadecimal espalhado por arquivos de design, folhas de estilo e aplicativos.

Design tokens são uma parte de algo maior. Se você leu o que é um design system, pode pensar nos tokens como o vocabulário básico desse sistema: os componentes são as frases, e os tokens são as palavras que eles usam.

As três camadas de uma decisão visual

Muitas equipes organizam os tokens em níveis. A especificação não impõe essa divisão, mas ela ajuda a entender por que os tokens são mais do que uma paleta com apelidos.

  1. Primitivos (ou de base): descrevem o valor bruto. Exemplo: verde.400 = #BBFF3D. Eles dizem o que existe, não onde usar.
  2. Semânticos: descrevem a função. Exemplo: cor.destaque = {verde.400}. Aqui entra a intenção: esse verde serve para destacar.
  3. De componente: descrevem um uso específico. Exemplo: botao.fundo-hover = {cor.destaque}.
Diagrama em camadas dos design tokens: um valor bruto, o verde #BBFF3D, vira um token primitivo, depois um token semântico de destaque, depois o token do botão em hover, e por fim é exportado para web, iOS e Android.
Cada camada aponta para a anterior. Quando o valor muda na base, a mudança desce até os componentes e as plataformas.

Entre as três, a camada semântica é a que mais protege o produto, porque separa o uso do valor. Por exemplo, se amanhã o destaque deixar de ser verde, você troca a referência de cor.destaque e não precisa revisar cada botão. Além disso, essa organização cria uma regra de leitura: quem desenha consulta a intenção, não o código da cor.

Como funciona um arquivo de design tokens

Em 28 de outubro de 2025, o Design Tokens Community Group, um grupo de comunidade do W3C, publicou a versão 2025.10 do formato. É um relatório final de grupo de comunidade, não um padrão oficial do W3C, mas o próprio documento o declara estável. O formato usa JSON e recomenda as extensões .tokens ou .tokens.json.

As regras principais são poucas:

  • Todo token é um objeto com a propriedade obrigatória $value.
  • $type informa o tipo (color, dimension, fontFamily, duration e outros). Ele pode ser herdado do grupo.
  • Grupos são objetos sem $value, usados para organizar tokens.
  • Um token pode apontar para outro com chaves: {grupo.token}. Essas referências não podem ser circulares.

Veja um exemplo com as cores do próprio Sistemativo:

{
  "verde": {
    "$type": "color",
    "400": { "$value": "#BBFF3D" }
  },
  "cor": {
    "$type": "color",
    "destaque": { "$value": "{verde.400}" },
    "fundo": { "$value": "#F2F1ED" }
  }
}
Esquema de um arquivo de tokens: o token primitivo verde 400 com o valor #BBFF3D e o token semântico cor.destaque apontando para ele por meio da referência entre chaves; ao lado, dois temas, claro e escuro, que trocam o valor do fundo sem duplicar o arquivo.
A referência entre chaves liga o uso ao valor. Temas trocam valores sem copiar a estrutura inteira.

Além dos tipos simples, o formato prevê tipos compostos, como typography, border, shadow e transition. Um token de tipografia, por exemplo, reúne família, tamanho, peso e entrelinha em um só nome.

Por que um formato comum faz diferença

Até pouco tempo atrás, cada ferramenta tinha seu jeito de guardar tokens. Por isso, exportar do arquivo de design para o código exigia conversões, plugins e ajustes manuais. Um formato neutro muda essa lógica, já que o mesmo arquivo pode alimentar ferramentas diferentes.

Segundo o anúncio do W3C, Style Dictionary, Tokens Studio e Terrazzo são implementações de referência, e Penpot, Figma, Sketch, Framer, Knapsack, Supernova e zeroheight tinham suporte em andamento na data da publicação. O texto também destaca suporte a espaços de cor modernos, como Display P3 e Oklch, e temas (claro, escuro, alto contraste) sem arquivos duplicados.

Vale um cuidado: “suporte em andamento” não é o mesmo que suporte completo. Portanto, antes de escolher uma ferramenta, confira na documentação dela qual versão do formato é lida e exportada.

Como começar com design tokens no seu projeto

Você não precisa de um sistema grande para tirar proveito dos tokens. Um caminho possível, em etapas:

  1. Faça o inventário. Liste as cores, tamanhos de fonte e espaçamentos que realmente aparecem nas telas. Geralmente, as duplicatas quase iguais aparecem aqui.
  2. Nomeie pela função. Troque “verde claro” por “destaque” e “cinza 2” por “texto de apoio”. Se você não consegue dizer para que um valor serve, talvez ele não precise existir.
  3. Centralize em um arquivo. Comece pelas cores. Assim, um único .tokens.json no repositório já evita boa parte dos desencontros.
  4. Gere o código a partir dele. Ferramentas como o Style Dictionary transformam o arquivo em variáveis CSS ou em código para aplicativos móveis.
  5. Combine a regra de alteração. Mudou uma decisão? Ela muda no arquivo de tokens, não direto na tela.

No Sistemativo, as cores e fontes da marca ficam nas configurações globais do Elementor e são reaproveitadas em todas as páginas. É uma versão simples do mesmo princípio: uma decisão, um nome, vários usos.

O que um arquivo de tokens não resolve

Tokens organizam decisões, mas não tomam decisões por você. Por exemplo, um arquivo impecável com uma paleta sem contraste suficiente continua gerando telas difíceis de ler. Da mesma forma, tokens não garantem identidade. Como discutimos em por que os produtos digitais estão começando a parecer iguais, padronizar a base é útil, mas a personalidade de uma marca nasce das escolhas que vêm antes do arquivo.

O ganho real está na conversa entre áreas. Quando design e desenvolvimento usam os mesmos nomes, uma pergunta como “esse verde é o destaque ou é decoração?” passa a ter resposta registrada. E isso vale mais do que qualquer ferramenta.

/ Conexões

Próximas conexões

Autor

Glécia Dias

Ver todos os artigos

Sistemativo / Brief

Gostou dessa ideia?

A cada duas semanas, ideias, ferramentas, referências e movimentos que valem alguns minutos da sua atenção.

Brief (formulário compacto)

Você poderá sair da lista quando quiser. Sem spam.