Design tokens na prática: do Figma ao Style Dictionary seguindo a spec do W3C

Design tokens na prática: do Figma ao Style Dictionary seguindo a spec do W3C

Um passo a passo para sair de cores soltas até um design system↳Design system5 conteúdosComo desenvolvemos o novo Design System do AsaasProduto & UX · jul 2024UX e Código: Por que designers que conhecem programação têm uma vantagem estratégicaProduto & UX · abr 2025A importância do HTML e CSS para quem trabalha com UI Design e Design SystemProduto & UX · dez 2024Ver tudo em Produto & UX → com tokens tipados, aliases e temas light/dark, exportados via Style Dictionary e validados contra o formato do W3C.

O problema começa sempre igual: alguém no time abre o Figma, cria uma paleta de cores com nomes tipo Blue/500, e três meses depois ninguém sabe qual azul é o do botão primário, qual é o do link e qual sobrou de um teste. O valor #3366FF está copiado à mão em 40 lugares no CSS↳CSS31 conteúdosArquitetura CSS: CSS FuncionalDev (Back & Front) · set 2019Entendendo posicionamento com CSS de uma vez por todasDev (Back & Front) · jul 2025Sites que combinam estética e usabilidade: reflexos da evolução do CSSDev (Back & Front) · fev 2025Ver tudo em Dev (Back & Front) →. Quando o design pede dark mode, a resposta honesta é: vai doer.

Design token existe para resolver exatamente isso: separar a decisão de design ("a cor de ação primária é este azul") do valor bruto (#3366FF) e do lugar onde é usada (button.background). O que o Design Tokens Format Module, mantido pelo Design Tokens Community Group do W3C, traz de novo é um formato de arquivo JSON padronizado para trocar esses tokens entre ferramentas, em vez de cada uma inventar o próprio export.

Vou mostrar o caminho que eu seguiria para sair de um arquivo de cores soltas até um design system com tokens tipados, aliases e temas, exportado com o Style Dictionary e com o JSON validado. Um aviso importante desde já: a versão que li da spec é um preview draft (2025.10) e o próprio documento diz, em letras garrafais, "do not implement this version". Ou seja, a estrutura conceitual ($value, $type, grupos, aliases) está estável e vale ouro para entender, mas alguns detalhes de sintaxe de cor ainda estão em movimento. Vou usar a forma clássica que as ferramentas já suportam hoje e comentar onde a spec nova diverge.

Nota da redação: a citação acima, "do not implement this version", é uma paráfrase do autor e não uma transcrição literal do documento. O texto original diz "Do not attempt to implement this version of the specification. Do not reference this version as authoritative in any way" e, em outro trecho, "do not implement anything in this document". O sentido do aviso está preservado, mas a formatação como citação direta induzia o leitor a pensar que era transcrição exata, o que não é o caso.

Pré-requisitos

Crie a pasta e instale:

mkdir ds-tokens && cd ds-tokens
npm init -y
npm install --save-dev style-dictionary ajv-cli
mkdir -p tokens build schema

Passo 1: os tokens primitivos (a paleta crua)

A primeira camada não tem semântica nenhuma. São os valores brutos, o equivalente ao seu Blue/500 do Figma. Um objeto vira token quando tem a propriedade $value, e vira grupo quando não tem: essa é a regra central da spec. $value é palavra reservada.

tokens/color.base.json:

{
  "color": {
    "$type": "color",
    "blue": {
      "500": { "$value": "#3366ff" },
      "700": { "$value": "#1a3fcc" }
    },
    "gray": {
      "0":   { "$value": "#ffffff" },
      "900": { "$value": "#111418" }
    }
  }
}

Repare que coloquei $type: "color" no grupo color, não em cada token. A spec diz que o tipo é herdado do grupo pai mais próximo que declarar $type. Isso economiza repetição e é o primeiro ganho concreto sobre o Figma, onde cada valor é uma ilha.

Groups are arbitrary and tools SHOULD NOT use them to infer the type or purpose of design tokens.

Design Tokens Format Module, W3C DTCG

Traduzindo: agrupar por blue é organização humana, não semântica. Quem carrega semântica é o $type e, na próxima camada, o nome.

Passo 2: tokens semânticos com aliases

Aqui mora o pulo do gato. Em vez de button.background apontar direto para #3366ff, ele referencia o token primitivo. A spec chama isso de alias, e a sintaxe é o nome do token entre chaves, separado por ponto: {color.blue.500}. Por isso ponto e chaves são proibidos em nomes de token.

tokens/color.semantic.json:

{
  "action": {
    "$type": "color",
    "primary": {
      "bg":    { "$value": "{color.blue.500}" },
      "bg-hover": { "$value": "{color.blue.700}" },
      "text":  { "$value": "{color.gray.0}" }
    }
  }
}

Quando o $value é uma referência, o $type do token é o tipo resolvido do token referenciado. Não precisa repetir. E o benefício prático: se amanhã o azul da marca mudar, você troca #3366ff em um lugar (color.blue.500) e todo mundo que faz alias acompanha.

Passo 3: temas light e dark

Existem várias formas de modelar tema. A que eu escolheria para começar é a mais legível: dois arquivos de tokens semânticos que sobrescrevem os mesmos nomes com aliases diferentes, e o Style Dictionary gera dois arquivos CSS.

tokens/theme.dark.json:

{
  "action": {
    "$type": "color",
    "primary": {
      "text": { "$value": "{color.gray.900}" }
    }
  }
}

No dark, o texto sobre o botão primário troca. O bg continua o azul, mas o text vira o cinza escuro. Cada tema é uma composição diferente de aliases sobre a mesma paleta primitiva, e é aí que fica claro por que a separação em camadas não é preciosismo: sem ela, dark mode seria copiar e colar hex.

Passo 4: configurar o Style Dictionary

Nota da redação: o código desta seção e da seção de validação com ajv (Passo 6) não foi executado em ambiente real. Valide antes de usar em produção.

O Style Dictionary é citado nominalmente pela spec como translation tool: pega o JSON de tokens e cospe código de plataforma. Como o script usa import/await de topo (sintaxe ES Modules), salve o arquivo como config.mjs (extensão .mjs), assim o Node interpreta o arquivo como módulo sem precisar mexer no package.json gerado pelo npm init -y.

config.mjs:

import StyleDictionary from 'style-dictionary';

const base = ['tokens/color.base.json', 'tokens/color.semantic.json'];

function build(theme, files) {
  const sd = new StyleDictionary({
    source: files,
    platforms: {
      css: {
        transformGroup: 'css',
        buildPath: 'build/',
        files: [{
          destination: `tokens.${theme}.css`,
          format: 'css/variables',
          options: { selector: theme === 'light' ? ':root' : '[data-theme="dark"]' }
        }]
      }
    }
  });
  return sd.buildAllPlatforms();
}

await build('light', base);
await build('dark', [...base, 'tokens/theme.dark.json']);

Rode:

node config.mjs

O build/tokens.light.css sai assim:

:root {
  --color-blue-500: #3366ff;
  --action-primary-bg: #3366ff;
  --action-primary-text: #ffffff;
}

E o tokens.dark.css traz --action-primary-text: #111418; dentro de [data-theme="dark"]. Note que o Style Dictionary resolveu os aliases: no CSS final o alias virou o valor concreto. É o comportamento esperado de uma ferramenta de tradução.

Passo 5: verificar que deu certo

"Compilou" não é o mesmo que "correto". Duas verificações que eu não pularia.

Primeiro, o teste visual burro: um HTML com o botão e um toggle de data-theme. Se o texto do botão muda de cor ao alternar, os aliases estão fluindo.

<link rel="stylesheet" href="build/tokens.light.css">
<link rel="stylesheet" href="build/tokens.dark.css">
<button style="background: var(--action-primary-bg); color: var(--action-primary-text)">
  Enviar
</button>

Segundo, e este é o ponto sensível de acessibilidade: contraste é parte da definição de pronto. Um token de cor que passa no light mode pode reprovar no dark. Antes de dar o token por concluído, jogue o par bg/text de cada tema num verificador de contraste (a meta é 4.5:1 para texto normal, WCAG AA). Token bonito que reprova em contraste é bug, não decisão de design.

Passo 6: validar o JSON contra schema

A spec ainda tem uma editor's note dizendo que o grupo "está explorando adicionar um JSON Schema" ao formato, ou seja, não existe schema oficial publicado dentro da 2025.10. Então a validação honesta aqui é contra um schema que reflita as regras normativas: todo objeto tem $value ou é grupo, nomes não começam com $ nem contêm {, } ou ., e $type é string.

Crie o schema mínimo antes de rodar a validação:

mkdir -p schema
cat > schema/dtcg.schema.json << 'EOF'
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "patternProperties": {
    "^(?!\\$)[^.{}]+$": {
      "type": "object"
    }
  },
  "additionalProperties": true
}
EOF

Ele é deliberadamente simples: checa a regra mais crítica (nomes sem caracteres proibidos) e serve de ponto de partida, não de validação completa da spec. Agora rode o ajv:

npx ajv validate -s schema/dtcg.schema.json -d "tokens/*.json"

Se você tiver um token chamado "my.token" com ponto no nome, ou um objeto que tem $value e filhos ao mesmo tempo (a spec manda tratar isso como erro, porque não dá para ser token e grupo ao mesmo tempo), a validação acusa. Vale automatizar isso num hook de pre-commit: token quebrado não deveria chegar ao build.

Os tropeços que eu esperaria

• Alias que não resolve. Escrever {color.blue.500} mas o token se chamar color.blue.500 dentro de um grupo com $type diferente, ou errar o caminho. O Style Dictionary reclama de referência não encontrada. Confira o caminho completo a partir da raiz do JSON.
• $type esquecido. Sem $type no token nem em nenhum grupo pai, e sem ser alias, a spec manda considerar o token inválido. A ferramenta não deve "adivinhar" olhando o valor. Se algo não exporta, cheque a herança de tipo.
• Nomes que só diferem por caixa. font-size e FONT-SIZE são tokens distintos e válidos pela spec, mas ao exportar para Sass viram a mesma variável e um sobrescreve o outro silenciosamente. Evite.
• Cair na sintaxe nova de cor cedo demais. O preview da spec usa objetos de cor com colorSpace e components ([1, 0, 0]). As ferramentas de produção ainda trabalham majoritariamente com hex string. Como o próprio documento pede para não implementar essa versão, fique no que a sua toolchain suporta hoje e acompanhe as versões estáveis antes de migrar.

O valor real desse exercício não é o CSS gerado, é a estrutura: primitivos que ninguém referencia diretamente, semânticos que dão nome à decisão, temas que recompõem aliases. Com isso, mudar a marca inteira ou adicionar um terceiro tema deixa de ser caça ao hex e vira trocar meia dúzia de referências, com o schema garantindo que ninguém escreveu bobagem no caminho.

Fonte 1: Design Tokens Format Module — W3C Design Tokens Community Group (https://tr.designtokens.org/format/)

Fonte: Design Tokens Format Module — W3C Design Tokens Community Group