Design systems · Passo 2 · 9 min de leitura
Tokens do Figma ao código
Tokens só servem se o design e o código lerem os mesmos. Onde deve morar a fonte da verdade, como as variáveis do Figma, os arquivos de tokens DTCG e uma ferramenta de build como o Style Dictionary se encaixam, como é um arquivo de tokens do Harbour, e o que já está estável no padrão hoje.
Um token que mora em dois lugares são dois tokens, e eles vão divergir. O Figma tem variáveis, o código tem custom properties, e no dia em que alguém muda um à mão o outro fica desatualizado. A solução não é disciplina. É um pipeline: uma fonte da verdade, uma direção, e uma máquina fazendo as cópias. Esta lição é sobre montar esse pipeline, pequeno o bastante para um time de três pessoas dar conta.
O que você vai conseguir fazer depois de ler:
- Escolher onde mora a fonte da verdade dos seus tokens
- Acompanhar os tokens das variáveis do Figma até o CSS e o código nativo
- Ler e escrever um arquivo de tokens no formato DTCG
- Saber o que já está estável no padrão e o que ainda está mudando
1. O pipeline
- Variáveis do FigmaColeções
PrimitiveseSemantic; modos Light, Dark e Compact. Aliases ligam o semântico ao primitivo. - ExportaçãoUm plugin ou a REST API do Figma lê as variáveis, com os modos e os aliases.
- Arquivos de tokens
harbour.no formato DTCG, guardado no repositório do código e revisado como código.tokens. json - BuildUma ferramenta como o Style Dictionary transforma uma fonte única no formato de cada plataforma.
- CSS
- iOS
- Android
- ComponentesO código lê
var(--hb-color-action-primary), nunca um hexadecimal. O Dev Mode mostra o mesmo nome.
Cinco passos, e o único manual é o primeiro: uma pessoa decide um valor. Tudo depois disso é cópia, e cópia é trabalho de máquina.
A figura começa no Figma, mas isso é uma escolha, não uma regra. A decisão principal é onde mora a fonte da verdade:
- Primeiro o Figma. Os designers editam as variáveis; uma exportação transforma tudo em arquivos de tokens. Bom quando os designers são donos das decisões e mudam com frequência.
- Primeiro o código. Os arquivos de tokens ficam no repositório e são editados em pull requests; uma sincronização leva tudo para o Figma. Bom quando você precisa de revisão, histórico e releases para cada mudança, o que a maioria dos sistemas acaba querendo.
De um jeito ou de outro, escolha um e deixe o outro só para leitura. Editar dos dois lados é como se chega a duas verdades.
2. Variáveis do Figma
As variáveis do Figma são os tokens do Harbour do lado do design. Alguns fatos que definem como montá-las (Figma Help, Overview of variables, collections, and modes):
- Existem seis tipos: cor, número, string, booleano, tempo e easing.
- Uma coleção é "a set of variables and modes" (um conjunto de variáveis e modos). O Harbour usa uma para os Primitives, uma para a cor Semantic (modos Light e Dark) e uma para a Density (Comfortable e Compact).
- Uma variável pode referenciar outra do mesmo tipo, o que o Figma diz que "is also called aliasing" (também se chama aliasing). É a corrente de níveis de Níveis de tokens.
Duas configurações importam para o pipeline (Figma Help, Create and manage variables):
- O escopo limita onde uma variável pode ser usada, então
space.inset.mdsó aparece nos seletores de padding e de gap, e os primitivos de cor podem ficar fora dos seletores de preenchimento. - O nome de código dá a cada variável o nome dela no código, para até três plataformas. O Dev Mode mostra esse nome nos trechos de código, que "are supported in CSS, SwiftUI, and Compose" (funcionam em CSS, SwiftUI e Compose). Defina o de Web como
var(--hb-color-action-primary)e o desenvolvedor vê o token de verdade, não um hexadecimal. É o lado dos tokens de Handoff para desenvolvedores.
3. Tirando os tokens do Figma
As variáveis precisam sair do Figma como arquivos. Dois caminhos:
- A REST API. Ela tem "endpoints for querying, creating, updating, and deleting variables" (endpoints para consultar, criar, atualizar e apagar variáveis), pensados para "sync design system source of truth to and from Figma" (sincronizar a fonte da verdade do design system com o Figma, nos dois sentidos). Ela exige um assento Full numa organização Enterprise (Figma Developers, Variables).
- Um plugin. Nos outros planos, um plugin consegue ler e escrever variáveis; o Figma indica um exemplo de importação e exportação (Figma Help, Guide to variables).
O que quer que exporte deve escrever no formato DTCG, para qualquer ferramenta do caminho conseguir ler o arquivo.
4. O arquivo de tokens
O Design Tokens Community Group publicou a primeira versão estável da especificação, a 2025.10, em 28 de outubro de 2025: um módulo Format, um módulo Color e um módulo Resolver para os modos (designtokens.org, Technical reports · módulos da 2025.10). É um relatório de Community Group, "not a W3C Standard nor is it on the W3C Standards Track" (não é um padrão do W3C nem está no caminho para ser um), e ele se declara estável e pronto para ser implementado (DTCG, Format Module 2025.10). O anúncio lista suporte ou trabalho em andamento em ferramentas como Style Dictionary, Tokens Studio, Terrazzo, Penpot, Figma, Sketch, Framer e zeroheight (W3C, anúncio do DTCG, 2025).
Esta é uma parte do arquivo principal do Harbour, harbour.tokens.json:
{
"color": {
"$type": "color",
"blue": {
"600": {
"$value": { "colorSpace": "srgb", "components": [0.1216, 0.3725, 0.6824], "hex": "#1f5fae" }
}
},
"action": {
"primary": {
"$value": "{color.blue.600}",
"$description": "Main action on a screen. Use on color.surface.default: 6.0:1 light, 5.3:1 dark."
}
}
},
"space": {
"$type": "dimension",
"4": { "$value": { "value": 16, "unit": "px" } },
"inset": {
"md": { "$value": "{space.4}" }
}
}
}
Como ler, regra por regra, a partir da especificação:
- Um objeto com
$valueé um token; todo o resto é grupo.color.action.primaryé o caminho pelos grupos. $typepode ficar num grupo e vale para todos os tokens dentro dele. As ferramentas "must not attempt to guess the type" (não devem tentar adivinhar o tipo) pelo valor.- Aliases usam chaves:
"{color.blue.600}". - Cores são objetos com um
colorSpaceecomponents, e umhexopcional de reserva (DTCG, Color Module 2025.10). Os componentes aqui são 31, 95 e 174 divididos por 255. - Dimensões são um número e uma unidade,
pxourem. $descriptioné onde vai o contraste medido de Cor, tipografia e espaçamento como tokens, para ele viajar junto com o token. No Harbour, as descrições ficam em inglês, como os nomes.- Os arquivos usam
.tokensou.tokens.json.
O modo escuro e a densidade compacta moram em arquivos extras pequenos, mode/dark.tokens.json e density/compact.tokens.json, que só reapontam tokens semânticos. O módulo Resolver diz como combiná-los: um modifier mode com os contextos light e dark, um modifier density com comfortable e compact, combinados em ordem (DTCG, Resolver Module 2025.10). É o CSS de Temas e modos, em forma de dados.
5. Do arquivo para cada plataforma
Uma ferramenta de build lê o arquivo de tokens e escreve o formato de cada plataforma. O Style Dictionary é a ferramenta open source mais conhecida: exporta "to any platform" (para qualquer plataforma), incluindo CSS, iOS e Android. A documentação dele diz que "as of version 4, Style Dictionary has first-class support for the DTCG format" (desde a versão 4, o Style Dictionary tem suporte completo ao formato DTCG), e também, com honestidade, que a 2025.10 "does not have full support yet" (ainda não tem suporte completo), sendo esse suporte "a work in progress in v5" (um trabalho em andamento na v5) (Style Dictionary, DTCG). Confira as notas da sua ferramenta antes de depender de uma parte mais nova da especificação, como o resolver.
No Harbour, o resultado é um arquivo CSS com as custom properties que você viu na demo, mais constantes em Swift e Kotlin para futuros apps nativos. Ninguém edita esses arquivos à mão; eles são gerados de novo a cada mudança e publicados como um pacote com número de versão (veja Versões e releases).
6. Erros comuns
- Duas fontes da verdade, editadas nos dois lugares.
- Exportar só os hexadecimais já resolvidos, perdendo os aliases, e o modo escuro não pode mais ser reconstruído.
- Variáveis sem nome de código, então o Dev Mode mostra hexadecimais e os desenvolvedores copiam.
- Arquivos gerados editados à mão, sobrescritos no build seguinte.
- Montar o pipeline antes de existir tokens que valham a pena. Um conjunto pequeno e correto num arquivo só vale mais do que um pipeline perfeito para um conjunto bagunçado.
7. Vocabulário
| Termo | Significado |
|---|---|
| Fonte da verdade | O único lugar onde um token é editado; todo o resto é gerado |
| Formato DTCG | O formato JSON do Design Tokens Community Group para tokens, estável desde a 2025.10 |
| Coleção | Um conjunto de variáveis do Figma que dividem os mesmos modos |
| Escopo | O limite das propriedades em que uma variável do Figma pode ser aplicada |
| Nome de código | O nome de uma variável do Figma no código, mostrado no Dev Mode |
| Ferramenta de build | Um programa, como o Style Dictionary, que transforma arquivos de tokens em código de cada plataforma |
8. Experimente (sem ferramentas)
- Pegue três tokens do Harbour:
color.blue.600,color.action.primaryespace.inset.md. - Escreva cada um como ele apareceria no arquivo DTCG, no Figma (coleção, grupo, nome) e no CSS.
- Marque qual mudaria no modo escuro, e em qual arquivo.
Perguntas para refletir: Quem no seu time deveria poder mudar o valor de um token? Onde a pessoa faria isso, e quem revisaria?
9. Se você já pratica
- Coloque os arquivos de tokens no controle de versão com um changelog, e trate um token renomeado como uma mudança que quebra.
- Valide os arquivos de tokens na integração contínua: todo alias resolve, todo
$typeestá definido, todo par de cores documentado continua passando. - Compare o Figma com os arquivos de tokens com uma frequência fixa e relate as diferenças, mesmo que ainda não dê para sincronizar sozinho.
- Ligue os componentes do mesmo jeito que os tokens: isso é Code Connect e a ponte entre design e código.
Checklist
Para saber mais
- Design Tokens Community Group: designtokens.org · Format Module 2025.10 · Color Module 2025.10 · Resolver Module 2025.10 · anúncio no W3C (2025)
- Figma: Overview of variables, collections, and modes · Create and manage variables · Variables REST API
- Style Dictionary · as notas sobre o DTCG
Livros, cursos e vídeos para ir mais fundo
- Guide to variables in FigmaFigma Helpgrátis, artigos e tutoriais, em inglês (site externo)
- Design SystemsAlla KholmatovaLivro · Smashing Media, 2017 (Amazon)
Os links dos livros são de afiliado da Amazon: como associado, recebo por compras qualificadas, sem custo a mais para você.
Relacionadas
Temas e modos · Como nomear tokens · Níveis de tokens · Handoff para desenvolvedores · Montar uma biblioteca no Figma · Code Connect e a ponte entre design e código · Versões e releases · Monte um conjunto de tokens com modos