Design Tokens no Figma com Variables: do primitivo à entrega para o front

Design Tokens no Figma↳Figma3 conteúdosFigma Dev Mode funciona mesmo? Testando na práticaDev (Back & Front) · mar 2025Claude Design: nova aposta da Anthropic contra Figma e MicrosoftProduto & UX · abr 2026A importância do HTML e CSS para quem trabalha com UI Design e Design SystemProduto & UX · dez 2024Ver tudo em Produto & UX → com Variables: do primitivo à entrega para o front

Como estruturei tokens primitivos, semânticos e de componente com modos de tema e plataforma, e exportei de um jeito que o front consome sem redigitar valor.

O problema não é criar cor bonita no Figma. É que o time de front recebe um #0A84FF solto no inspect, decide o nome da variável na mão, e três sprints depois ninguém sabe se blue-primary 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) → é o mesmo Primary da tela de checkout. Design token existe pra matar essa tradução perdida. Vou mostrar a estrutura que montei do zero, com múltiplos modos (tema e plataforma) e a exportação que o front realmente consome.

Usei Figma na versão web (dez/2025). Um ponto de plano importa antes de começar: segundo o guia oficial de Variables, publicar variáveis em bibliotecas de time está disponível no plano de educação e em qualquer plano pago. Editar e criar variáveis, porém, funciona para quem tem acesso de edição ao arquivo; e quem tem acesso ao arquivo pode usar as variáveis dele nos próprios designs. Para a parte de exportação, usei um token pessoal da REST API e Node 20.

As três camadas de tokens (e por que separar)

A regra que sigo: nunca aplique um valor bruto num componente. A hierarquia tem três níveis, cada um numa coleção de Variables separada.

1. Primitivos (a paleta crua). São os valores literais, sem significado de uso. Crio uma coleção Primitives com um único modo. Aqui vivem color/blue/500 = #0A84FF, color/gray/900 = #1C1C1E, space/4 = 8, radius/md = 12. Ninguém consome primitivo direto na tela. Ele é matéria-prima.

2. Semânticos (a intenção). Coleção Semantic, e é aqui que os modos entram. Uma variável como bg/surface não guarda um hex: ela referencia um primitivo. No modo Light, bg/surface aponta para color/gray/50; no modo Dark, para color/gray/900. Faço isso com alias: ao definir o valor da variável, em vez de digitar cor, clico no ícone de variável e escolho o primitivo. É esse encadeamento que faz o dark mode funcionar trocando um modo só.

3. Componente (o acoplamento local). Coleção Component, para tokens que só um componente usa, tipo button/primary/bg. Referencia o semântico (action/primary), não o primitivo. Nem todo projeto precisa dessa camada; em design system pequeno eu paro no semântico. Mas em time grande ela isola mudanças: mexer no botão não vaza pro resto.

A cadeia fica: button/primary/bg → action/primary → color/blue/500 → #0A84FF. Trocar a marca inteira é editar um primitivo.

Modos para tema E plataforma ao mesmo tempo

Aqui está o pulo do gato que muita gente erra: não empilhe tema e plataforma na mesma coleção. Se você criar modos Light-Web, Dark-Web, Light-Mobile, Dark-Mobile numa coleção só, a combinação explode e vira ininteligível.

Separei em duas dimensões:

• Coleção Semantic com modos Light e Dark (dimensão tema).
• Coleção Scale com modos Web e Mobile (dimensão plataforma), guardando espaçamentos e tamanhos de fonte. Ex.: space/gutter = 16 no Web e 24 no Mobile.

O recurso que sustenta isso é o de modos por variável, descrito na documentação como criar múltiplas definições para uma mesma variável, cada uma associada a um modo, para trocar rapidamente o contexto do design. Cada frame pode aplicar um modo por coleção. Seleciono a tela, no painel direito escolho Light para tema e Mobile para escala. As duas dimensões se combinam sem multiplicar variáveis. Verifiquei que funcionou trocando só o modo de tema na tela de login: fundo, texto e bordas viraram dark de uma vez, e os espaçamentos não se mexeram, porque vêm de outra coleção.

O tropeço: scoping e nomes que quebram na exportação

Dois problemas me custaram tempo.

Primeiro, scoping. Por padrão, uma variável de cor aparece em qualquer campo de cor. Isso poluiu o autocomplete: ao aplicar cor de texto, apareciam primitivos que não deviam ser usados diretamente. A documentação trata scoping como parte de criar e gerenciar variáveis, definindo quais variáveis podem ser usadas em quais designs. Resolvi indo em cada primitivo, aba de scoping, e desabilitando os escopos desnecessários, ou escondendo a coleção Primitives da publicação de biblioteca. Assim o designer só enxerga tokens semânticos ao trabalhar. Primitivo é infraestrutura, não deve estar no menu do dia a dia.

Segundo, nomes com barra viram grupo, mas espaço vira dor. O Figma usa / para agrupar visualmente (color/blue/500 cria a pasta color > blue). Isso é ótimo. Mas usei espaço e maiúscula em alguns nomes no começo (Action Primary) e na hora de exportar virou Action Primary na chave JSON, que quebrou o parser do lado do front. Refiz tudo em kebab-case e minúsculo. Regra que fixei: nome de token é nome de variável CSS, então trate como código desde o Figma.

Exportando pro front sem reescrever em CSS

O objetivo é o front consumir os tokens sem redigitar valor nenhum. A documentação confirma que Variables têm suporte na REST API, com endpoints para consultar, criar, atualizar e deletar variáveis. Uso a consulta para puxar coleções, modos e valores. O path exato, o formato da resposta e como cada tipo de valor (incluindo referências entre camadas) é representado ficam nos Developer docs da REST API, que a própria página de Variables lista como referência, é lá que você confere o contrato antes de escrever o script.

Nota da redação: o bloco de código Node mostrado a seguir é ilustrativo, não funcional. Ele exibe apenas o nome de uma função (toCssVar) e comentários descrevendo a intenção do script, mas não implementa de fato a chamada à REST API do Figma (fetch, token, headers), o parsing da resposta de variáveis e modos, nem a lógica de resolução da cadeia de referências entre camadas. A partir só desse trecho, o leitor não consegue reproduzir o CSS de saída exibido abaixo; é preciso escrever essa lógica completa por conta própria. Além disso, o texto não deixa claro que operações de escrita (criar, atualizar, deletar) na API de Variables exigem plano Enterprise/Org com escopo apropriado; a leitura de variáveis, que é o que este tutorial usa, funciona com um token pessoal comum.

Com a resposta em mãos, escrevi um script Node que resolve a cadeia de referências entre as camadas e emite CSS custom properties com escopo por modo:

// resolve referência -> valor final e gera :root e [data-theme="dark"]
const toCssVar = (name) => `--${name.replaceAll('/', '-')}`;
// para cada modo semântico, emitir um bloco de custom properties
// Light -> :root  |  Dark -> [data-theme="dark"]

O output vira algo assim, que o front importa direto:

:root {
  --bg-surface: #FAFAFA;
  --action-primary: #0A84FF;
}
[data-theme="dark"] {
  --bg-surface: #1C1C1E;
  --action-primary: #0A84FF;
}

Para não rodar o script na mão, o próprio Figma mantém um exemplo de GitHub Action para sincronizar Variables com o codebase. A documentação descreve um tutorial de como usar esse repositório de exemplo de Variables GitHub Action para manter Figma e código em sincronia, além de um arquivo de comunidade sobre montar workflows automatizados de sincronização usando a Variables REST API. É esse tipo de fluxo que faz o token deixar de ser figurinha no inspect e virar fonte única de verdade versionada.

Como sei que deu certo (definição de pronto)

O token só está pronto quando três coisas acontecem.

Primeiro: trocar o modo Dark numa tela vira o tema inteiro sem editar camada nenhuma. Como os semânticos são aliases de primitivos, a troca de modo propaga sozinha.

Segundo: o Dev Mode mostra o nome do token, não o hex, ao inspecionar. A documentação registra que Variables aparecem no Dev Mode com detalhes da variável, sugestões e a tabela de coleções locais, o que é exatamente o que o front vê no inspect nativo, sem depender de você passar o valor por fora.

Terceiro, e é aqui que a acessibilidade entra como parte da definição de pronto: o contraste precisa passar nos dois temas. Isso não é conhecimento da fonte do Figma, é critério de UX que eu não terceirizo. Com os semânticos definidos, testo cada par texto/fundo nos modos Light e Dark. Dark mode costuma reprovar em cinzas que pareciam ok no light. Se text/secondary sobre bg/surface falha no Dark, o token está errado, e como é semântico, corrijo num lugar só, e todos os componentes que herdam dele são corrigidos junto.

Contraste que reprova não é detalhe de QA no fim: é o token semântico mal calibrado. Por isso a checagem de acessibilidade mora na camada semântica, antes de qualquer componente herdar o valor.

Fonte: Figma Help Center — Guide to variables in Figma