Pular para o conteúdo

Tokens no Figma

As três camadas em JSON DTCG, para o Tokens Studio e as variáveis do Figma.

/tokens.mdmarkdown cru, para quem lê com agent em vez de olho

Os tokens da biblioteca moram em CSS, e é assim que as peças os leem. Quem desenha não lê CSS: lê variável do Figma, ou um conjunto do Tokens Studio. Esta página é a ponte. As três camadas saem no formato do W3C Design Tokens Community Group, na especificação estável 2025.10, que as duas ferramentas leem sem plugin de conversão no meio.

O que sai

Um arquivo por camada, um por densidade e um por tema, mais o resolver que diz como juntá-los:

Arquivo O que carrega
palette.tokens.json A camada 1: a paleta crua, palette.lima.500, palette.graphite.950
scales.tokens.json Tipografia, altura de linha, empilhamento, foco, raio, espaçamento de letra e movimento
density-comfortable.tokens.json Altura de controle e respiro na densidade confortável
density-compact.tokens.json Os mesmos tokens, na compacta
rivocode-dark.tokens.json A camada 3 do tema escuro: os papéis que as peças pintam
rivocode-light.tokens.json O mesmo, no claro
rivocode.resolver.json O resolver do DTCG: base, densidade e tema, nessa ordem

O papel continua apontando para a paleta. No CSS, --rc-accent é var(--rc-p-lima-500); no JSON, color.accent é {palette.lima.500}. Trocar a lima na paleta muda o acento no tema, no Figma como no código. O papel que tem alfa próprio, como color.accent-subtle, sai com a cor inteira, porque o formato não tem alias com transparência.

Todo token carrega de onde veio, em $extensions:

"accent": {
  "$type": "color",
  "$value": "{palette.lima.500}",
  "$extensions": { "br.com.rivocode": { "css": "--rc-accent" } }
}

É o que liga a variável que o designer escolheu à classe que o código escreve: color.accent é --rc-accent, que é bg-accent.

Onde pegar

Do site, sem instalar nada:

for arquivo in palette scales density-comfortable density-compact rivocode-dark rivocode-light; do
  curl -sO "https://ds.rivocode.com.br/tokens/$arquivo.tokens.json"
done
curl -sO https://ds.rivocode.com.br/tokens/rivocode.resolver.json

Do pacote, na versão que o projeto instalou:

ls node_modules/@rivocode/ui/dist/tokens

Ou pelo comando, que escreve os mesmos arquivos numa pasta sua:

npx rivocode-ui tokens --out tokens

O tema do seu cliente

O comando lê o CSS do tema do mesmo jeito que o check-theme, e exporta o seu tema no lugar dos da casa:

npx rivocode-ui tokens tema-acme.css --out tokens

Saem acme-light.tokens.json e acme-dark.tokens.json, um por seletor [data-rc-theme="..."] do arquivo, com a paleta, a escala e as densidades da casa ao lado. O papel que o seu tema aponta para a paleta da casa vira alias; o que você escreveu com cor própria, em hexadecimal, rgb() ou oklch(), sai convertido para sRGB, com o hex junto. Um arquivo sem nenhum seletor de tema é recusado: exportar a casa no lugar do seu tema seria verde sobre nada.

Tokens Studio

  1. Em Settings, escolha o formato W3C DTCG.
  2. Carregue a pasta inteira. Cada arquivo vira um conjunto.
  3. Ligue sempre palette e scales, uma densidade e um tema. Sem a paleta ligada, todo alias do tema fica sem destino.
  4. Em Themes, crie um tema por combinação: escuro confortável, claro compacto. O rivocode.resolver.json já descreve essas combinações, para a ferramenta que lê o resolver.

Figma

A importação de variáveis do Figma lê o mesmo JSON:

  1. Crie a coleção Paleta e importe palette.tokens.json. Ela vem primeiro, porque é para ela que o tema aponta.
  2. Crie a coleção Tema e importe rivocode-dark.tokens.json e rivocode-light.tokens.json, um em cada modo.
  3. Crie a coleção Densidade do mesmo jeito, com os dois arquivos de densidade como modos.
  4. Importe scales.tokens.json numa coleção de um modo só.

O Figma só tem variável de cor, número, texto e booleano. Cor, medida e número viram variável; sombra, curva e duração não têm tipo de variável lá, e são o que o Tokens Studio transforma em estilo.

O que não cabe no formato

O comando lista, ao terminar, o que ficou de fora e por quê. Nos temas da casa são três ganchos que existem vazios de propósito, --rc-accent-image, --rc-accent-shadow e --rc-overlay-filter: valem none até um tema de cliente usá-los, e none não tem tipo no DTCG. Quando o seu tema der uma sombra ao --rc-accent-shadow, ela sai como sombra.

Dois tokens saem aproximados, com o valor do CSS guardado em $extensions:

  • O espaçamento de letra (tracking.display, tracking.tight) é em no CSS, e o formato só aceita px e rem em medida. Sai como número, que multiplica o tamanho da fonte.
  • O título fluido (text.display, text.hero) é um clamp() que cresce com a tela. Sai com o tamanho máximo, que é o da tela larga que se desenha.

Quando não usar

O JSON é para a ferramenta de design. O código continua lendo o CSS: o preset.css é a fonte, e o JSON é gerado dele a cada versão. Não monte tema a partir do JSON para o navegador; escreva o CSS do tema, como ensina Temas e personalização, e exporte daqui para o Figma.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.