--- title: "Figma Variables: guia completo para design tokens, dark mode e theming" date: 2026-05-22T01:13:28Z modified: 2026-07-29T01:29:09Z permalink: "https://camaraux.com.br/figma-variables/" type: post status: publish excerpt: Como estruturar Figma Variables com primitivas, semânticas e modes para dark mode, theming multi-brand e integração com código. wpid: 8196 categories: - Design Systems tags: - Design Systems - dark mode - Design System - Design Tokens - Figma - figma 2026 - Figma Variables - theming - tokens studio - variable modes rank_math_title: "Figma Variables: design tokens, dark mode e theming" rank_math_description: Aprenda a usar Figma Variables para criar design tokens, configurar dark mode com Variable Modes e escalar theming multi-brand no seu ds. rank_math_focus_keyword: variables,Figma Variables featured_image: /wp-content/uploads/2026/05/Ilustracao-conceitual-de-Figma-Variables.webp featured_image_alt: Painel arqueado com divisórias geométricas coloridas em tons pastéis e plantas em vasos sob céu degradê author: Lucas Camara timestamp: 2026-07-29T01:29:09Z --- O guia apresenta Figma Variables como base para design tokens em design systems, diferenciando variables de styles e explicando tipos, collections, aliases e a organização em camadas de primitivas e tokens semânticos. Também aborda nomes, grupos e o vínculo com padrões de design tokens usados no código. O texto mostra como usar Variable Modes para light/dark mode e múltiplas marcas, além de aplicar number e string variables em spacing e tipografia. Inclui um fluxo de implementação gradual, migração de sistemas existentes e exportação com Tokens Studio para integrar o Figma ao desenvolvimento. Se você trabalha com design system, é bem provável que **Figma Variables** já tenha entrado no seu radar. Desde que a Figma lançou essa funcionalidade, ela mudou estruturalmente como designers organizam tokens, implementam dark mode e gerenciam múltiplos temas dentro de um mesmo arquivo. O problema é que a maioria dos tutoriais disponíveis em português trata o assunto de forma superficial, como se configurar uma collection fosse o suficiente para ter um sistema robusto. Este guia foi escrito para quem já entende o que é um design system e quer ir além: estruturar variables de forma escalável, conectar primitivas com semânticas via alias, configurar Variable Modes para light e dark mode sem retrabalho e integrar tudo isso com o código do time de desenvolvimento. Vamos do conceito à implementação prática. ## O que são Figma Variables e por que isso importa para o seu design system Figma Variables são valores reutilizáveis que podem mudar de acordo com o contexto do design. Pense em uma cor chamada `surface/base`: no modo claro, ela vale `#FAFAFA`; no modo escuro, vale `#0F0F0F`. O componente que usa essa variable não precisa mudar, porque a troca acontece na camada da variable, não no componente em si. Isso é radicalmente diferente de manter dois conjuntos de componentes, um para cada tema. O que torna isso importante para um design system real é a escala. Um produto com centenas de componentes não pode depender de ajustes manuais toda vez que o time decide ajustar uma cor ou lançar um tema para uma marca diferente. Variables resolvem esse problema ao criar um ponto único de controle para os valores que percorrem todo o sistema. Quando você atualiza o valor de uma variable, o Figma propaga a mudança para cada elemento que referencia aquele token, em qualquer arquivo conectado à biblioteca. ### Qual a diferença entre Variables e Styles no Figma? Essa é uma das perguntas mais comuns de quem está migrando o sistema. Styles no Figma armazenam propriedades visuais compostas como um color style que inclui nome e valor de cor, ou um text style com todas as propriedades tipográficas juntas. Variables, por outro lado, armazenam valores individuais e tipados: uma cor, um número, uma string, um booleano. A diferença prática está na flexibilidade e na integração com código. Uma color variable pode ser referenciada por outra variable via alias, formando uma hierarquia de tokens. Um color style, não. Se o seu objetivo é ter um design system que dialogue com código usando design tokens no padrão W3C, variables são o caminho, e styles ficam como uma camada opcional para casos específicos. ### Quais são os quatro tipos de variáveis no Figma? O Figma suporta quatro tipos nativos de variables, cada um com escopos de aplicação específicos. **Color** para valores de cor sólida, aplicados em fills e strokes de qualquer objeto. **Number** para valores numéricos como spacing, border-radius, opacidade e escalas tipográficas. **String** para sequências de texto como nomes de fontes, pesos, labels de componentes e conteúdo localizado. **Boolean** para valores verdadeiro/falso, útil para mostrar e ocultar layers em protótipos ou alternar estados de componentes sem criar variantes adicionais. Cada tipo determina onde a variable pode ser aplicada no painel de design. Uma color variable só aparece como opção quando você está configurando um fill ou stroke. Uma number variable aparece em campos de dimensão, espaçamento e opacidade. Essa restrição por escopo é intencional e evita o caos de aplicar uma variable no lugar errado. ## Como organizar suas collections de variables no Figma A estrutura de collections é onde a maioria dos times erra. A tentação é criar uma única collection gigante com todas as variables do sistema, o que resulta em uma lista impossível de navegar em poucos meses. A abordagem mais sólida é separar as collections por camada semântica: primitivas em uma collection, tokens semânticos em outra, e tokens de componente em uma terceira quando o sistema crescer o suficiente para justificar. Essa separação reflete diretamente a [arquitetura de design tokens recomendada pelo padrão W3C](/design-tokens-arquitetura-w3c/), que organiza tokens em três camadas: opções (os valores brutos), decisões (o que cada valor significa) e uso (onde cada decisão é aplicada). Collections no Figma mapeiam naturalmente para esse modelo, e seguir essa lógica desde o início torna muito mais fácil manter e escalar o sistema ao longo do tempo. ### O que são variáveis primitivas (primitive tokens)? Primitivas são os valores brutos do sistema, sem contexto de uso. Na collection de cores, você teria `blue/500: #3B82F6`, `gray/900: #111827`, `green/400: #4ADE80`. Esses valores existem como referência absoluta, e nenhum componente deve usá-los diretamente. A função da primitiva é apenas ser referenciada por tokens semânticos. O mesmo vale para números. Uma collection de primitivas de spacing pode ter `space/1: 4`, `space/2: 8`, `space/4: 16`, seguindo uma escala definida. Esse valores não aparecem nos componentes diretamente, mas formam a base que os tokens semânticos vão referenciar. Manter primitivas separadas facilita muito quando você precisar ajustar a escala ou trocar o valor de um step sem quebrar o significado dos tokens semânticos. ### O que são variáveis semânticas e por que você precisa delas? Tokens semânticos atribuem significado e intenção às primitivas. Em vez de `blue/500`, você tem `color/action/primary`. Em vez de `space/4`, você tem `spacing/component/padding-md`. Esse nível intermediário é o que permite que o sistema responda a mudanças de tema sem reescrever os componentes. A lógica é simples: `color/action/primary` pode apontar para `blue/500` no modo light e para `blue/300` no modo dark. O componente referencia apenas `color/action/primary` e não precisa saber nada sobre os modos. Quando você troca o modo, o Figma resolve o alias automaticamente. Sem tokens semânticos, cada troca de tema exige edição manual dos componentes, o que destrói qualquer benefício de ter um design system. Para um aprofundamento em como construir essa estrutura dentro do Figma, veja o guia completo sobre [como construir um design system no Figma](/como-construir-um-design-system-no-figma/). ### Como nomear e estruturar grupos dentro de uma collection? Grupos dentro de uma collection funcionam como pastas. Você cria um grupo digitando `/` no nome da variable: `color/surface/primary` e `color/surface/secondary` ficam automaticamente agrupados sob `color/surface`. O painel lateral da collection mostra esses grupos como uma hierarquia navegável, o que facilita muito encontrar uma variable específica em sistemas com centenas de tokens. Uma convenção que funciona bem é seguir o padrão `categoria/variante/estado`. Para cores: `color/text/primary`, `color/text/secondary`, `color/text/disabled`. Para spacing: `spacing/inset/md`, `spacing/stack/sm`. A consistência nos prefixos é o que garante que o time todo use os tokens corretos intuitivamente, sem consultar documentação a cada hora. ## Figma Variables como design tokens: a conexão com o código Variables no Figma não existem em um vácuo. O real valor delas aparece quando você conecta a estrutura do Figma com o código que os desenvolvedores usam. A boa notícia é que o Figma Dev Mode já exibe as variables aplicadas em um componente com seu nome e valor, permitindo que o desenvolvedor copie a referência ao token diretamente. A menos boa é que, por padrão, não existe sincronização automática entre as variables do Figma e o CSS ou JSON do projeto. Esse é o ponto onde a [arquitetura W3C de design tokens](/design-tokens-arquitetura-w3c/) entra como padrão de referência. O formato DTCG (Design Token Community Group) define como os tokens devem ser estruturados em JSON para que ferramentas de build possam transformá-los em CSS custom properties, variáveis Sass, constantes JS ou qualquer outro formato que o time precise. Variables no Figma com nomes bem estruturados mapeiam diretamente para esse formato. ### Como usar aliases para conectar primitivas e semânticas? Um alias é quando uma variable aponta para outra variable em vez de um valor bruto. No painel de edição de uma variable semântica, em vez de digitar um hex diretamente, você clica no ícone de biblioteca e seleciona uma variable da collection de primitivas. Agora `color/action/primary` não tem um valor próprio: ela referencia `blue/500`, que tem o valor `#3B82F6`. O poder do alias fica evidente quando você precisa mudar toda a paleta de brand. Você atualiza `blue/500` de `#3B82F6` para `#2563EB` e todos os tokens semânticos que referenciam essa primitiva atualizam automaticamente, incluindo todos os componentes que usam esses tokens. Uma mudança de valor, propagação instantânea em todo o sistema. Essa é a promessa do [design token com arquitetura em camadas](/design-tokens-arquitetura-w3c/). ### Como exportar tokens do Figma para o código com Tokens Studio? O Tokens Studio (antigamente Figma Tokens) é o plugin mais usado para fazer a ponte entre as variables do Figma e o código. Ele lê a estrutura de variables do arquivo, exporta em formato JSON compatível com o padrão DTCG e pode sincronizar com um repositório Git, garantindo que o time de desenvolvimento sempre tenha acesso à versão mais recente dos tokens. O fluxo funciona assim: designer atualiza o valor de uma variable no Figma, o Tokens Studio sincroniza o JSON com o repositório, o pipeline de build transforma o JSON em CSS custom properties, e o produto em produção recebe os novos valores sem nenhuma edição manual no código. Esse processo é especialmente valioso em contextos de consultoria de design system, onde o objetivo é criar uma infraestrutura que o time consiga manter de forma autônoma após a entrega. ## Dark mode com Figma Variables: como configurar Variable Modes Variable Modes são o mecanismo que transforma uma collection em multi-tema. Cada mode é essencialmente uma coluna adicional na tabela de variables: a mesma variable `color/surface/primary` tem um valor na coluna “Light” e um valor diferente na coluna “Dark”. Quando você aplica um mode a um frame, o Figma usa a coluna correspondente para resolver todas as variables dentro daquele frame. Isso significa que você não precisa de dois conjuntos de componentes para ter light e dark mode. Você tem um único conjunto de componentes, todos usando variáveis semânticas, e a troca de tema acontece em um único clique no painel de aparência do frame. Para times que cuidam de produtos com suporte a múltiplos temas ou que precisam validar acessibilidade de contraste em ambos os modos, isso poupa horas de trabalho toda semana. Para se aprofundar nos critérios de contraste que o dark mode precisa respeitar, veja o artigo sobre [acessibilidade em cores de design system](/acessibilidade-cores-design-system/). ### Como criar um modo Light e Dark na mesma collection? Abra o painel de variables e acesse a collection de tokens semânticos. No canto superior direito da tela de collections, clique em “Edit variable” e depois no ícone de modo para adicionar um novo mode. Por padrão, o Figma cria um único mode chamado “Mode 1”. Renomeie para “Light” e adicione um segundo mode chamado “Dark”. Agora cada variable da collection terá duas colunas: Light e Dark. Na coluna Light, os aliases apontam para as primitivas de paleta clara. Na coluna Dark, os aliases apontam para as primitivas de paleta escura. O token `color/text/primary` pode apontar para `gray/900` no Light e para `gray/50` no Dark. O plano de assinatura do Figma define quantos modes estão disponíveis por collection: o plano Professional suporta até 4 modes, enquanto planos superiores oferecem mais. ### Como aplicar o modo correto nos frames e componentes? Selecione um frame no canvas e, no painel de design à direita, procure a seção “Appearance” (ou “Aparência”). Ali aparece o nome da collection com um dropdown de modes disponíveis. Selecione “Light” ou “Dark” e o frame inteiro, incluindo todos os componentes aninhados, resolve as variables usando o mode escolhido. Você pode aplicar modes em níveis diferentes da hierarquia de layers. Um frame pai pode estar em Light, mas um frame filho específico pode ter um override para Dark, criando uma seção de destaque com tema invertido. Essa flexibilidade é útil para prototipar telas de configuração, banners de destaque ou qualquer elemento que precise de contraste visual com o restante da página. ### Quais erros evitar ao montar dark mode com Variables? O erro mais comum é usar primitivas diretamente nos componentes, pulando a camada semântica. Se um botão referencia `blue/500` diretamente em vez de `color/action/primary`, o modo dark não vai funcionar para esse componente porque a primitiva não tem modo: ela tem apenas um valor fixo. Cada componente precisa referenciar exclusivamente tokens semânticos para que a troca de mode tenha efeito. Outro erro frequente é manter os mesmos valores de saturação para light e dark sem ajuste perceptual. Uma cor de destaque que funciona no fundo claro pode parecer apagada ou excessivamente brilhante no fundo escuro. O azul de ação que você usa como `blue/500` no light provavelmente precisa de uma versão mais clara, como `blue/300` ou `blue/400`, no dark para preservar o mesmo peso visual e passar nos critérios de contraste WCAG. ## Theming multi-brand com Figma Variables O caso de uso de múltiplas marcas em um único arquivo é onde Figma Variables brilham de maneira menos óbvia. Imagine um produto white-label ou um design system que serve duas ou três marcas diferentes dentro do mesmo time. Antes de Variables, a solução comum era duplicar arquivos ou manter conditional components com variantes de marca, o que multiplicava o trabalho de manutenção. Com Variable Modes, você pode ter uma collection de tokens semânticos com um mode por marca: “Marca A”, “Marca B”, “Marca C”. Cada mode aponta os aliases para paletas de primitivas diferentes. O mesmo componente de botão, card ou navbar funciona nas três marcas sem nenhuma variante adicional. Para entender como construir a paleta de cada marca de forma sistemática, o artigo sobre [como criar paleta de cores para design system](/como-criar-paleta-cores-design-system/) é o complemento natural deste guia. ### Como usar Variable Modes para múltiplas marcas no mesmo arquivo? A lógica é a mesma do dark mode, mas o eixo de variação muda de tema visual para identidade de marca. Crie uma collection chamada “Brand Tokens” com um mode para cada marca. Em cada mode, os tokens semânticos de cor (`color/brand/primary`, `color/brand/secondary`, `color/surface/base`) apontam para as primitivas da paleta correspondente. O resultado é que um único arquivo Figma pode demonstrar o mesmo produto em qualquer marca em segundos. Para times de produto que atendem clientes diferentes ou que gerenciam portfólios de marcas, esse fluxo reduz o tempo de demonstração e elimina a necessidade de manter arquivos paralelos constantemente desatualizados entre si. ## Figma Variables e spacing tokens: integrando espaçamento ao sistema Number variables são frequentemente tratadas como coadjuvantes em tutoriais de Variables, mas elas são tão importantes quanto as color variables para um design system realmente coeso. Um sistema de espaçamento baseado em number variables significa que o padding de um botão, a margem de uma card e o gap de um grid podem ser atualizados de um ponto central, garantindo consistência matemática em todo o produto. Para quem já trabalha com [tokens de espaçamento no design system](/espacamento-design-system-tokens/), o mapeamento para number variables no Figma é direto. A escala de espaçamento que você já tem documentada se transforma em uma collection de primitivas numéricas, e os tokens semânticos definem onde cada valor é aplicado: `spacing/component/padding-sm` aponta para `space/2` (8px), `spacing/component/padding-md` aponta para `space/4` (16px), e assim por diante. ### Como criar number variables para spacing e border-radius? Crie uma collection chamada “Primitives Numeric” e adicione variables do tipo Number para cada step da escala de espaçamento. Nomeie como `space/1`, `space/2`, `space/3` com valores 4, 8, 12 respectivamente, ou qualquer escala que o sistema use. Faça o mesmo para border-radius: `radius/sm: 4`, `radius/md: 8`, `radius/lg: 16`, `radius/full: 9999`. Em seguida, na collection semântica, crie tokens como `component/button/padding-x` e aponte o alias para `space/4`. Quando o desenvolvedor abre o Dev Mode, ele vê o nome do token e o valor resolvido. Para o CSS, o token pode ser mapeado diretamente para uma custom property. Esse fluxo fecha o loop entre a intenção do designer e a implementação no código, sem margem para interpretação manual. ## Como escalar variables para tipografia no Figma Tipografia é o aspecto onde Variables ainda têm limitações no Figma em 2026, mas já oferecem valor real para quem trabalha com sistemas complexos. String variables podem ser aplicadas em font-family e font-weight, o que permite criar tokens tipográficos que definem qual família e peso usar em cada contexto. Number variables cobrem font-size, line-height e letter-spacing. A integração com [escalas tipográficas de design system](/escala-tipografica-design-system/) segue a mesma lógica de primitivas e semânticas. Uma collection de primitivas tipográficas armazena os valores brutos: tamanhos, famílias, pesos. A collection semântica cria tokens com intenção: `typography/body/size` referencia `font/size/base`, `typography/heading-1/size` referencia `font/size/4xl`. Quando você precisar ajustar a escala do sistema, atualiza a primitiva e tudo se propaga. ### Quais propriedades tipográficas suportam variables no Figma? Em 2026, Figma suporta variables nas seguintes propriedades de texto: font family (string), font style e font weight (string), font size (number), line height (number), letter spacing (number) e paragraph spacing (number). O que ainda não tem suporte nativo é text decoration e text transform como variables, o que exige workarounds ou aceitar essas propriedades como valores fixos nos componentes. Uma limitação importante: string variables para font family exigem o nome exato da fonte como ela aparece no Figma, incluindo capitalização correta. Se a família for “Inter”, a string variable precisa ter o valor `Inter` exatamente, não `inter` ou `INTER`. Figma é tolerante a hífens e underscores, mas capitalize exatamente como a fonte está registrada para evitar que o valor apareça riscado no painel de design. ## Figma Variables na prática: um fluxo de trabalho para times de produto Depois de entender as peças, o desafio real é encaixar tudo em um fluxo que o time consiga adotar sem abandonar em duas semanas. A tentação de estruturar o sistema perfeito desde o primeiro dia costuma ser o maior obstáculo: times que tentam implementar primitivas, semânticas, modes e exportação de código ao mesmo tempo geralmente travam antes de publicar a biblioteca. A abordagem mais eficaz é iterativa. Comece com color variables semânticas para light mode apenas. Publique a biblioteca, migre os componentes principais para usar os tokens e valide o fluxo com o time de desenvolvimento. Só depois introduza o dark mode como segundo mode na collection. Só depois adicione spacing e tipografia. Cada fase entrega valor real e reduz o risco de ter que refatorar tudo por causa de uma decisão de nomenclatura tomada cedo demais. ### Qual o passo a passo para implementar variables em um design system existente? O processo de migração de um design system existente para Figma Variables segue um caminho previsível quando bem planejado. Primeiro, faça um levantamento de todos os valores hardcoded nos componentes: cores, raios, espaçamentos e tamanhos tipográficos. Segundo, agrupe esses valores em primitivas e defina a escala. Terceiro, crie os tokens semânticos e estabeleça os aliases. Quarto, atualize os componentes substituindo valores fixos por variables, sempre começando pelos componentes mais usados. Quinto, publique a biblioteca e alinhe o time de desenvolvimento sobre a convenção de nomes para que tokens no Figma e no código usem a mesma linguagem. Sexto, configure o Tokens Studio para a exportação automatizada e valide o JSON gerado com o time de engenharia. Esse processo completo, dependendo do tamanho do sistema, leva de duas a seis semanas em um time dedicado. Se o seu time está começando a estruturar o design system agora, vale ler o guia sobre [como construir um design system no Figma](/como-construir-um-design-system-no-figma/) antes de dar o primeiro passo. ## Perguntas frequentes sobre Figma Variables ### Qual a diferença entre Variables e Styles no Figma? Styles armazenam propriedades visuais compostas. Variables armazenam valores individuais e tipados: cor, número, string ou booleano. Variables podem se referenciar via alias, formando a hierarquia de design tokens necessária para dark mode e theming. Styles não permitem esse encadeamento. ### Quais são os quatro tipos de variáveis no Figma? Color para valores de cor sólida, Number para valores numéricos como spacing e border-radius, String para font family, font weight e labels de texto, e Boolean para mostrar e ocultar layers em protótipos e alternar estados de componentes. ### Como criar um modo Light e Dark na mesma collection? Abra a collection de tokens semânticos, clique no ícone de modo e adicione um segundo mode. Renomeie os modes para Light e Dark. Em cada mode, configure os aliases dos tokens semânticos para apontar para as primitivas corretas de cada tema. Aplique o mode desejado no painel de Aparência do frame. ### Quais erros evitar ao montar dark mode com Variables? O principal erro é usar primitivas diretamente nos componentes, pulando os tokens semânticos. Primitivas não têm modes: apenas tokens semânticos respondem à troca de mode. Outro erro é manter os mesmos valores de saturação para ambos os modos sem ajuste perceptual, o que quebra contraste e acessibilidade. ## Conclusão Figma Variables não são uma feature isolada: são a infraestrutura que conecta todos os outros elementos de um design system maduro. Collections bem estruturadas com primitivas e semânticas criam a base. Variable Modes transformam essa base em um sistema multi-tema capaz de responder a dark mode, theming de marca e localização sem retrabalho nos componentes. A integração com código fecha o ciclo e transforma o design system em uma fonte de verdade real para o produto. A diferença entre um design system que o time usa de fato e um que fica desatualizado em seis meses costuma estar exatamente aqui: na infraestrutura de tokens bem estruturada, com Variables, aliases e modes configurados desde o início. Se o seu time está nesse processo ou se você quer avaliar onde o sistema atual tem gaps, a CamaraUX pode ajudar com uma consultoria de design system focada em diagnóstico e implementação prática. [Entre em contato](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/page/contato.md) e veja como estruturar isso de forma que o time consiga manter de forma autônoma. ## Topics **Categorias:** [Design Systems](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/category/design-systems.md) **Tags:** [dark mode](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/dark-mode.md), [Design System](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-system.md), [Design Tokens](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/design-tokens.md), [Figma](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/figma.md), [figma 2026](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/figma-2026.md), [Figma Variables](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/figma-variables.md), [theming](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/theming.md), [tokens studio](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/tokens-studio.md), [variable modes](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/post_tag/variable-modes.md)