Pular para o conteúdo principal

N1-04 · Tokens no Figma — workflow do dia a dia

Contexto​

Você sabe o que são tokens e para que servem. Agora você precisa usá-los no Figma — o seu ambiente de trabalho diário.

Este tutorial mostra o fluxo completo: como os tokens chegam ao Figma, como aplicá-los em fills, paddings e texto, e o que fazer quando o token certo parece não existir.

Como os tokens chegam ao Figma​

Os tokens não são criados no Figma. Eles são gerados pelo engine e entregues ao Figma em formato JSON. O plugin Tokens Studio lê esses arquivos e os transforma em Variáveis nativas do Figma.

O fluxo é sempre neste sentido — nunca o contrário:

engine (config) → arquivos JSON → Tokens Studio → Variáveis do Figma

Quando um token muda no sistema (por exemplo, a cor primária da marca), o arquivo JSON é regenerado. O Tokens Studio atualiza as Variáveis. Todos os componentes que usam aquele token atualizam automaticamente.

Parte 1 — Carregando os tokens​

O que você precisa​

  • Figma com o arquivo de design aberto
  • Plugin Tokens Studio for Figma instalado
  • Acesso ao arquivo JSON do tema (fornecido pelo time de DS ou pelo System Designer)

1.1 — Abrindo o Tokens Studio​

Abra o plugin pelo menu Plugins → Tokens Studio for Figma.

[PRINT N1-04-01]
Menu Plugins do Figma aberto, com "Tokens Studio for Figma" em destaque.

1.2 — Carregando o arquivo JSON​

Na tela inicial do Tokens Studio, clique em Settings (ícone de engrenagem) → Add New Storage → Local/URL.

Cole o caminho ou URL do arquivo JSON do tema — por exemplo, aplica_joy-light-positive.json.

[PRINT N1-04-02]
Painel Tokens Studio aberto na aba Settings, com o campo de configuração de storage preenchido.

1.3 — Sincronizando as variáveis nativas do Figma​

Após carregar o JSON:

  1. Na aba Sets, selecione o conjunto do tema (ex: aplica_joy-light-positive)
  2. Clique no ícone de Figma Variables (ícone de losango com setas)
  3. Selecione Create/Update Variables

O plugin vai criar coleções de Variáveis organizadas por camada. O processo leva alguns segundos.

[PRINT N1-04-03]
Tokens Studio com conjunto selecionado e ação "Create/Update Variables" em destaque.

1.4 — Confirmando as coleções criadas​

Após a sincronização, abra Figma Variables pelo painel Assets (ícone de losango na barra lateral direita). Você verá coleções criadas automaticamente.

As coleções principais são:

  • semantic — todos os tokens de interface (a camada que você vai usar)
  • foundation — os atalhos curtos (bg.primary, txt.body)
  • brand, mode, surface — camadas internas (não usar em componentes diretamente)

[PRINT N1-04-04]
Painel Figma Variables com as coleções criadas pelo Tokens Studio. Coleção "foundation" expandida mostrando alguns aliases.

Parte 2 — Aplicando tokens em cor​

2.1 — Aplicando um token de cor em um fill​

Crie um retângulo. No painel de propriedades à direita, clique na cor do fill (o quadrado colorido).

Na janela de cor, troque para a aba Libraries ou clique no ícone de losango (Variables) — a interface varia levemente dependendo da versão do Figma.

[PRINT N1-04-05]
Janela de seleção de cor com o ícone de Variables destacado, antes de abrir o seletor de variáveis.

Clique no ícone de Variables. Aparece o seletor de variáveis. Navegue até a coleção foundation → bg para ver os aliases de fundo.

[PRINT N1-04-06]
Seletor de variáveis mostrando a coleção foundation → bg, com as opções de fundo disponíveis.

Após selecionar foundation.bg.primary, o fill do retângulo assume a cor do token. O ícone de losango aparece ao lado do valor de cor no painel, indicando que está vinculado a uma variável.

[PRINT N1-04-07]
Retângulo com fill vinculado a variável — ícone de losango e nome do token visíveis no painel de Fill.

2.2 — Usando tokens de cor para texto (o par txtOn)​

Crie um texto sobre o retângulo. O token de cor do texto deve ser o par correspondente ao fundo.

Regra: se o fundo usa foundation.bg.primary, o texto deve usar foundation.txt.on-primary — não foundation.txt.body.

[PRINT N1-04-08]
Seletor de variáveis aberto para o fill de texto, coleção foundation → txt, com "on-primary" destacado como a escolha correta para texto sobre bg.primary.

Parte 3 — Aplicando tokens em espaçamento​

3.1 — Padding via Auto Layout​

Selecione um frame com Auto Layout. No painel de propriedades, clique no ícone de losango ao lado do campo de padding horizontal ou vertical.

[PRINT N1-04-09]
Frame com Auto Layout selecionado, painel de propriedades mostrando os campos de padding com o ícone de variável em destaque.

Clique no losango. O seletor de variáveis abre. Navegue até foundation → spacing (ou semantic → dimension dependendo de como o tema foi configurado).

[PRINT N1-04-10]
Seletor de variáveis para padding com coleção foundation → spacing expandida e opções de tamanho visíveis.

Após vincular, o campo de padding exibe o ícone de losango e o valor correspondente ao token.

[PRINT N1-04-11]
Frame com padding vinculado a variável — ícone de losango e nome do token visíveis no painel de Auto Layout.

Parte 4 — Aplicando estilos de tipografia​

Estilos tipográficos compostos são aplicados de forma diferente — não como variáveis individuais, mas como Text Styles do Figma.

Selecione um elemento de texto. No painel de propriedades, clique no nome do estilo atual (onde aparece o nome da fonte) para abrir o seletor de estilos.

[PRINT N1-04-12]
Seletor de Text Styles aberto com os grupos de estilos do sistema visíveis: Heading, Display, Content, Action, Code.

Após selecionar o estilo, a tipografia do elemento assume automaticamente a família, tamanho, peso e entrelinha corretos.

Parte 5 — Trocando de modo (light/dark)​

Com variáveis vinculadas, a troca entre light e dark é instantânea.

Selecione o frame ou a página que contém o componente. No painel de propriedades, localize a seção Layer ou Frame. Clique em Change variable mode (botão com ícone de losango/seta).

[PRINT N1-04-13]
Seletor de Variable Mode no painel de propriedades, com as opções Light e Dark visíveis.

[PRINT N1-04-14]
O mesmo componente exibido em Light Mode (esquerda) e Dark Mode (direita) — layout idêntico, cores adaptadas automaticamente.

Parte 6 — O que fazer quando o token certo não existe​

Às vezes você procura um token e não encontra exatamente o que precisa. Há uma ordem certa para resolver isso:

Passo 1 — Procure na Foundation antes do Semantic​

A Foundation tem aliases simples (bg.primary, txt.body). Antes de ir ao Semantic, verifique se o atalho já existe.

Passo 2 — Se não existe na Foundation, procure no Semantic​

O Semantic tem todos os tokens. Use o seletor de variáveis e navegue pela coleção semantic. O nome do token descreve seu propósito: semantic.color.interface.function.primary.normal.background.

Passo 3 — Se não existe no Semantic, fale com o System Designer​

O token que você precisa pode não existir ainda. Isso é uma informação valiosa — significa que o sistema precisa crescer naquele ponto.

Nunca faça isso:

  • Usar um hex solto no lugar do token ausente
  • Criar uma variável no Figma manualmente
  • Usar um token de outra camada (Brand, Mode ou Surface) diretamente

Criar um hex solto ou uma variável manual é o equivalente a furar o contrato do sistema. Na próxima atualização, esse valor vai ficar para trás enquanto tudo ao redor muda.

[PRINT N1-04-15]
Comparação no painel Fill: à esquerda, hex solto sem vínculo (errado); à direita, variável vinculada com nome do token (correto).

Agora você tenta​

Você precisa criar um banner informativo simples no Figma:

┌─────────────────────────────────────────────┐
│  ℹ  Sua solicitação está em análise.        │
└─────────────────────────────────────────────┘

Usando apenas o que aprendeu neste tutorial:

  1. Crie um frame com Auto Layout
  2. Aplique o token de fundo correto para um banner informativo (dica: feedback.info)
  3. Aplique o token de texto correto para texto sobre aquele fundo
  4. Defina o padding horizontal e vertical com tokens de espaçamento
  5. Aplique o estilo de tipografia correto para o texto (não é Heading nem Display)
  6. Troque para Dark Mode — o banner deve adaptar sem nenhuma edição

Resultado esperado:

  • Fundo: semantic.color.interface.feedback.info.default.background ou foundation.bg.feedback.info
  • Texto: o txtOn correspondente ao nível de fundo usado
  • Padding: spacing.small (24px) horizontal, spacing.micro (8px) vertical
  • Tipografia: estilo do grupo Content (ex: body_small ou label)
  • Dark mode: ambas as cores trocam automaticamente sem edição manual

Checkpoint​

Ao fim deste tutorial você deve saber:

  • Como os tokens chegam ao Figma (engine → JSON → Tokens Studio → Variáveis)
  • Como abrir o seletor de variáveis a partir de um campo de cor ou espaçamento
  • A diferença entre a coleção Foundation (atalhos) e Semantic (completo)
  • Como usar o par bg + txtOn corretamente
  • Como vincular tokens de espaçamento em campos de padding no Auto Layout
  • Como aplicar estilos de tipografia compostos
  • Como trocar entre Light e Dark Mode usando Variable Modes
  • O que fazer (e o que nunca fazer) quando o token certo não existe

Próximo passo​

N1-05 · Acessibilidade por construção

Você agora aplica tokens no Figma com confiança. O próximo tutorial explica por que essa prática de usar o par correto de tokens não é só consistência — é o que garante acessibilidade automática para qualquer usuário.

Lista consolidada de prints necessários​

IDOnde apareceO que capturarPrioridade
N1-04-01Parte 1.1Menu Plugins → Tokens Studio em destaqueAlta
N1-04-02Parte 1.2Tokens Studio → Settings → Add New StorageAlta
N1-04-03Parte 1.3Tokens Studio → aba Sets → ação Create/Update VariablesAlta
N1-04-04Parte 1.4Figma Variables com coleções criadas, foundation expandidaAlta
N1-04-05Parte 2.1Janela de cor com ícone Variables em destaqueAlta
N1-04-06Parte 2.1Seletor de variáveis, foundation → bg expandidaAlta
N1-04-07Parte 2.1Painel Fill com ícone de losango + nome do tokenAlta
N1-04-08Parte 2.2Seletor de variáveis para texto, foundation → txt, on-primary destacadoAlta
N1-04-09Parte 3.1Frame Auto Layout, campo padding com ícone de variávelMédia
N1-04-10Parte 3.1Seletor de variáveis, foundation → spacing expandidaMédia
N1-04-11Parte 3.1Painel Auto Layout com padding vinculado a variávelMédia
N1-04-12Parte 4Seletor de Text Styles com grupos Heading/Display/Content/Action/CodeAlta
N1-04-13Parte 5Seletor de Variable Mode com opções Light/DarkAlta
N1-04-14Parte 5Componente lado a lado em Light e Dark ModeAlta
N1-04-15Parte 6Comparação hex solto vs variável vinculada no painel FillAlta

Total: 15 prints. 12 de alta prioridade, 3 de média.

Referências​