Arquitetura de Variáveis do Figma: Como Construir um Sistema de Tokens que Sobrevive à Produção

A maioria dos times que usa variáveis do Figma está construindo em cima de um modelo mental de estilos, e esse é o problema. Variáveis sem arquitetura são só estilos com mais cliques.

Os times que acertam tratam as variáveis do Figma como uma camada real de design tokens: estruturada, com aliases, com escopo e exportável. Os times que erram estão a um pedido de dark mode de uma reconstrução completa. Esta é a arquitetura que sobrevive à produção.

Variáveis não são estilos, elas são a camada de tokens

Estilos do Figma são presets. Você define uma cor, um estilo de texto, um efeito e aplica direto em uma camada. Isso funciona para um arquivo com uma única marca, um único modo e sem requisitos de handoff para dev. Para de funcionar no momento em que qualquer coisa muda.

Variáveis do Figma são tokens. Uma variável guarda um valor, mas também pode guardar uma referência a outra variável. Essa cadeia de referências, e a capacidade de trocar conjuntos inteiros de valores resolvidos via modos, é o que torna as variáveis arquiteturalmente diferentes dos estilos. A distinção não é cosmética. É a diferença entre um sistema de presets e um sistema de tokens.

A arquitetura de tokens em três camadas

Primitivos, semânticos, componente. Todo sistema de variáveis que funciona tem essas três camadas. Pular a camada semântica é o erro arquitetural mais comum nos arquivos do Figma hoje.

As três camadas correspondem a três trabalhos: primitivos guardam valores brutos, tokens semânticos carregam significado e tokens de componente têm escopo em uma única família de componentes. Cada camada conversa apenas com a camada abaixo dela. Sem pular, sem atalhos.

As três camadas não são opcionais conforme o tamanho do projeto. Um sistema pequeno com cinco componentes ainda precisa das três camadas, ou o primeiro pedido de tema o explode.

Camada um: primitivos

Primitivos são os valores brutos. blue-500, gray-900, space-4, radius-md. Eles são a paleta, a escala, a fundação. Nunca são aplicados direto em uma camada de componente.

O trabalho de um primitivo é existir, receber aliases de cima e ficar fora do caminho. Se um designer está pegando blue-500 para aplicar em um botão, a arquitetura já está quebrada. Primitivos pertencem à coleção de primitivos e a mais nenhum lugar.

A convenção de nomes importa aqui. Primitivos devem ser baseados em escala ou paleta, nunca semânticos. blue-500 está correto. button-blue como primitivo é um erro de categoria que dói em escala.

Camada dois: semântica

Tokens semânticos carregam significado. surface, surface-elevated, text-primary, text-muted, border-default, border-focus. Eles respondem "para que serve essa cor?" em vez de "que cor é essa?"

Tokens semânticos fazem alias para primitivos. Essa é a única relação que eles têm. Alias de semântico para semântico cria ambiguidade sobre onde o valor vive e torna os overrides de modo pouco confiáveis.

Essa camada é onde vivem os seus modos light, dark e de marca. Um token semântico resolve para um primitivo diferente dependendo do modo ativo, que é como o theming realmente funciona. O primitivo blue-500 não muda. O token semântico text-link muda para o que ele resolve conforme o modo.

Camada três: componente

Tokens de componente têm escopo em uma única família de componentes. button-bg, button-text, button-border, card-surface, card-border, input-bg. Eles fazem alias para tokens semânticos, nunca para primitivos.

O trabalho de um token de componente é ter especificidade sem acoplamento. button-bg resolve para surface-action, que resolve para blue-500. Quando a marca muda, você atualiza a camada semântica e o botão atualiza junto. O token de componente fica intocado.

Uma objeção comum é que isso parece token extra sem motivo. O motivo é que button-bg e surface-action podem divergir. Em algum momento, uma decisão de produto vai exigir que o botão use uma superfície ligeiramente diferente. Tokens de componente dão o ponto de override sem mexer no sistema semântico.

Modos versus coleções: a árvore de decisão

Modos trocam valores dentro de uma coleção. Coleções separam responsabilidades. Essas duas coisas não são a mesma, e confundi-las é a origem da maior parte da confusão arquitetural nas configurações de variáveis do Figma.

A regra é: uma coleção por responsabilidade, modos para variantes da mesma responsabilidade. Cor é uma responsabilidade. Espaçamento é uma responsabilidade. Light e dark não são responsabilidades separadas. São modos da mesma responsabilidade de cor.

Quando usar um modo vs. uma nova coleção:

• Valor diferente da mesma coisa? Modo.
• Coisa completamente diferente? Coleção.
• Alternar entre light e dark? Modo dentro da coleção de cor.
• Alternar entre espaçamento compacto e confortável? Modo dentro da coleção de espaçamento.
• Adicionar uma marca? Modo dentro da camada semântica, não uma nova coleção.

As quatro regras de escopo

O escopo de variáveis controla onde uma variável pode ser aplicada no Figma. Errar isso significa que designers podem pegar primitivos por engano em vez de tokens semânticos, e a disciplina arquitetural desmorona no ponto de uso.

As quatro regras são inegociáveis:

1. Dê escopo nenhum aos primitivos. Primitivos não devem ser aplicáveis em lugar nenhum. São valores internos, não tokens voltados ao consumidor. Esconda-os do dropdown de aplicação por completo.
2. Dê aos tokens semânticos o escopo do seu tipo. Um token semântico de cor recebe escopo para fills e strokes. Um token de espaçamento recebe escopo para gap, padding e campos de tamanho. Mantenha o escopo justo.
3. Dê aos tokens de componente o escopo da sua família. Um token de botão não deve ser aplicável a um card. Se o escopo é amplo demais, a fronteira do componente não significa nada.
4. Nunca exponha primitivos aos consumidores. Se um designer ou desenvolvedor está aplicando um primitivo em uma camada, o sistema falhou na camada de escopo. Isso é uma falha de processo, não uma falha do usuário.

A cadeia de aliases que torna os temas possíveis

Um tema que funciona é uma cadeia de aliases: o componente faz alias para o semântico, o semântico faz alias para o primitivo, o primitivo guarda o valor. O tamanho da cadeia é três, sempre três.

Uma cadeia de dois (componente para primitivo) pula a camada de tradução e torna os modos impossíveis sem overrides manuais em cada token de componente. Uma cadeia de quatro cria ambiguidade sobre qual camada semântica carrega o modo, e auditá-la vira um exercício de debug em vez de uma consulta.

button-bg → surface-action → blue-500 → #0066FF

Copy

Essa cadeia sobrevive ao dark mode atualizando surface-action para apontar para blue-300 no modo dark da coleção semântica. O token button-bg atualiza automaticamente. O primitivo blue-500 continua resolvendo para #0066FF. Nada mais precisa mudar.

Modos light, dark e de marca

Os três modos de que a maioria dos sistemas de variáveis precisa são light, dark e de marca. Só a camada semântica os carrega. Nunca a camada de primitivos.

Aplicar modos a primitivos é um erro de categoria. blue-500 é sempre #0066FF. É um primitivo. Não tem variante light ou dark porque não carrega significado. O token semântico text-link tem variante light e dark porque carrega um significado que se resolve de forma diferente em contextos diferentes.

Modos de marca funcionam do mesmo jeito. Uma segunda marca não precisa de uma segunda paleta de primitivos, a menos que a marca use valores brutos genuinamente diferentes. Na maioria das vezes, um modo de marca na camada semântica apontando para um subconjunto diferente dos primitivos existentes é a decisão certa. Duas coleções completas de primitivos para duas marcas costuma ser exagero. Para entender como as decisões de cor a montante moldam isso, vale ler o texto sobre sistema de cores para dark mode antes de fixar a estrutura da sua camada semântica.

Variáveis de número, string e booleano

Variáveis do Figma não são só cores. Variáveis de número controlam espaçamento, tamanho e raio. Variáveis de string controlam o texto dentro dos arquivos de design. Variáveis booleanas controlam a visibilidade de camadas, o que mapeia direto para props de componente.

Essa é a parte do sistema de variáveis que a maioria dos times não está usando, e é a que fecha a distância entre design e código de forma mais dramática. Uma escala de espaçamento definida como variáveis de número e aplicada aos gaps do auto-layout significa que uma mudança de espaçamento na variável atualiza todo componente que usa aquele token. É isso que um sistema de tokens de verdade faz.

Variáveis de string com modos de locale permitem que designers troquem um arquivo entre inglês e árabe e vejam o layout quebrar em tempo real. Variáveis booleanas que mapeiam para props de componente significam que o componente do Figma e o componente de código têm uma relação de props um para um, o que torna o handoff para dev revisável em vez de interpretável.

Handoff para o código: o padrão que funciona

Um sistema de variáveis é tão bom quanto a sua exportação. O padrão de handoff que funciona é o Tokens Studio ou a REST API de Variables do Figma, mais um pipeline de transformação, mais um script de importação no lado do código.

O Tokens Studio exporta coleções de variáveis para um formato JSON estruturado compatível com o Style Dictionary. O Style Dictionary transforma esse JSON em qualquer saída que o codebase precisar: propriedades customizadas CSS, color sets do Swift, arquivos de recursos do Kotlin, config do Tailwind. A etapa de transformação é onde as convenções de nomes são normalizadas e qualquer nomenclatura específica do Figma que não mapeia para convenções de código é limpa.

O pipeline deve rodar a cada atualização de variável, não manualmente. Uma GitHub Action disparada por um push do Tokens Studio ou um webhook do Figma que dispara em mudanças de variáveis mantém os tokens do lado do código em sincronia sem que ninguém precise lembrar de exportar. Esse é o padrão que Stripe e Atlassian rodam em escala, e é viável em qualquer codebase que tenha uma etapa de build. Para as decisões de formato dos tokens de cor nessa saída, vale ler sobre cor OKLCH antes de fixar os valores das propriedades customizadas CSS.

---

Quer um sistema de variáveis do Figma que sobreviva a modos, marcas e handoff para dev sem reescritas? A Brainy projeta arquiteturas de tokens de produção no Figma com o modelo de três camadas, a cadeia de aliases e o pipeline de exportação que encaixa direto no seu codebase. Contrate a Brainy

---

Sete erros comuns que quebram sistemas de variáveis

A maioria desses erros tem a mesma causa raiz: tratar o painel de variáveis como um painel de estilos melhorado em vez de uma camada arquitetural. A mudança de modelo mental é a correção. Todo o resto decorre dela.

A auditoria do sistema de variáveis

Rode esta auditoria em qualquer sistema de variáveis do Figma e você vai pegar a dívida arquitetural antes de ela ir para produção.

Estrutura

• Três coleções no mínimo: primitivos, semântico, componente (ou nomenclatura equivalente)
• Cada coleção tem uma única responsabilidade clara
• Nenhuma coleção mistura tipos (cor e espaçamento na mesma coleção é uma falha)

Cadeia de aliases

• Todo token de componente faz alias para um token semântico, não para um primitivo
• Todo token semântico faz alias para um primitivo, não para outro token semântico
• Nenhum token guarda um valor bruto, exceto os primitivos
• O tamanho da cadeia de aliases é exatamente três para todos os tokens de cor

Modos

• Light e dark são modos na coleção semântica, não coleções separadas
• Variantes de marca são modos na coleção semântica, não arquivos separados
• A coleção de primitivos não tem modos

Escopo

• Variáveis primitivas têm escopo nenhum (não aplicáveis em lugar nenhum)
• Variáveis semânticas têm escopo do seu tipo (cor para fills/strokes, espaçamento para campos de layout)
• Variáveis de componente têm escopo da sua família de componentes

Handoff

• As variáveis são exportáveis via Tokens Studio ou REST API
• Existe um pipeline de transformação e ele é automatizado
• Os tokens do lado do código seguem a convenção de nomes das variáveis do Figma, com exceções documentadas

Se mais de três desses itens falharem, o sistema precisa de uma reconstrução, não de um remendo. Uma paleta de cores da marca cobre as decisões de cor a montante que alimentam a camada de primitivos, caso seja ali que a auditoria revele mais dívida.

FAQ

Qual é a diferença entre variáveis do Figma e estilos do Figma?

Estilos são presets aplicados direto em camadas. Variáveis são tokens que podem referenciar umas às outras e trocar valores via modos. Variáveis fazem tudo o que estilos fazem, além de theming e de handoff para dev via exportação. Para um novo design system, variáveis são a escolha certa. Para um arquivo existente com um sistema de estilos maduro, vale escrever um plano de migração antes de trocar.

Quantas coleções um sistema de variáveis do Figma deve ter?

De três a cinco na maioria dos sistemas: primitivos, semântico, componente e, opcionalmente, coleções separadas de espaçamento e tipografia se essas escalas forem complexas o bastante para justificar regras de escopo próprias. Mais de cinco coleções costuma ser sinal de que as responsabilidades não estão sendo agrupadas corretamente.

As variáveis do Figma podem substituir o Tokens Studio?

Para criação e edição dentro do Figma, sim. O painel nativo de variáveis cobre a maior parte do que o Tokens Studio fazia antes de a API de variáveis chegar. Para exportação e transformação, o Tokens Studio ainda agrega valor porque tem um pipeline maduro até o Style Dictionary e lida com casos de borda que a exportação nativa não cobre. As duas ferramentas são complementares agora, não concorrentes.

O que acontece se eu fizer alias de um token semântico para outro token semântico?

A resolução de modos fica ambígua. Se text-secondary faz alias para text-primary e você troca para o modo dark, o Figma resolve a cadeia e pode não aplicar o override do dark mode onde você espera. Alias de semântico para semântico também torna a auditoria do sistema quase impossível em escala. A regra é rígida: tokens semânticos fazem alias apenas para primitivos.

Como lidar com uma terceira marca sem reconstruir o sistema?

Adicione um terceiro modo à coleção semântica. A coleção de primitivos é compartilhada entre as marcas, a menos que elas usem valores brutos genuinamente diferentes. Um modo de marca na camada semântica que aponta para um subconjunto diferente de primitivos é a arquitetura certa. Se as marcas são tão diferentes que suas paletas de primitivos não se sobrepõem, duas coleções de primitivos com uma estrutura semântica compartilhada é o plano B.

O modelo de três camadas é necessário para projetos pequenos?

Sim, mas o tamanho de cada camada diminui. Um projeto pequeno pode ter quinze primitivos, oito tokens semânticos e dois tokens de componente por componente. A arquitetura continua sendo de três camadas. A tentação de pular a camada semântica em projetos pequenos é o motivo de tantos projetos pequenos virarem dívida arquitetural no instante em que aparece um segundo designer ou um pedido de dark mode. Para ver como a arquitetura de tokens se encaixa na decisão mais ampla de stack, o texto sobre Framer vs Webflow vs Next.js traz contexto.

A mudança que as variáveis do Figma realmente destravam

Um sistema de variáveis de verdade no Figma é o mais perto que design e dev já chegaram de uma única fonte de verdade. Não é um documento de handoff. Não é um link do Zeplin. É uma camada de tokens viva, exportável e estruturada, que os dois lados leem das mesmas definições.

Os times que tratam variáveis como arquitetura estão cortando a dívida do design system pela metade, não porque variáveis sejam mágicas, mas porque a disciplina arquitetural que um bom sistema de variáveis exige também força as decisões que os design systems vinham adiando. O que esse token significa? Para o que ele pode fazer alias? Quem é dono do primitivo? Essas perguntas agora têm respostas, e as respostas vivem no arquivo.

Variáveis sem arquitetura são só estilos com mais cliques. Variáveis com o modelo de três camadas, a cadeia de aliases, as regras de escopo e o pipeline de exportação formam um design system que sobrevive a uma segunda marca, a um dark mode e a um desenvolvedor que nunca abriu o Figma.

Construa a arquitetura, não só os tokens.