Variáveis de Cores no Figma: Um Guia Completo para Sistemas de Design

Os sistemas de design entram em colapso no momento em que os valores de cor divergem entre design e código. Um botão tem um azul no Figma, um azul ligeiramente diferente no componente React e um terceiro azul na configuração do Tailwind. As variáveis de cores do Figma — introduzidas em 2023 e profundamente aprimoradas desde então — são o mecanismo que fecha essa lacuna. Elas transformam códigos hex brutos em tokens nomeados e semânticos que podem ser referenciados em todo um arquivo de design, alternados entre temas com um único clique e exportados diretamente para os formatos que os engenheiros realmente usam.

Este guia abrange o ciclo de vida completo: criar variáveis, organizá-las em coleções, configurar modos claro e escuro e exportar para propriedades CSS personalizadas e configuração do Tailwind.

O Que São Variáveis do Figma?

Uma variável do Figma é um valor nomeado que pode ser referenciado por qualquer propriedade de camada — cor de preenchimento, contorno, raio, espaçamento, opacidade. Quando você altera o valor da variável, cada camada que a referencia é atualizada automaticamente.

As variáveis de cores especificamente armazenam um valor de cor e lhe dão um nome significativo. Em vez de um retângulo ter um preenchimento codificado diretamente de #3B82F6, ele referencia a variável color/brand/primary. Quando você atualiza color/brand/primary para #2563EB, cada instância no arquivo é atualizada instantaneamente.

Isso é fundamentalmente diferente dos Estilos do Figma (o sistema mais antigo). Os estilos só podem ser aplicados a propriedades de estilo completas (como "fill" ou "stroke"), e não suportam modos ou temas. As variáveis suportam modos, tornando-as a ferramenta certa para qualquer sistema de design que precise de temas claro e escuro — ou qualquer outra variante, como um modo de acessibilidade de alto contraste.

Variáveis vs. Estilos

Para novos sistemas de design, as variáveis são a escolha correta. Os estilos continuam sendo úteis para propriedades complexas de texto e efeitos que as variáveis não cobrem.

Criando Variáveis de Cores no Figma

As variáveis de cores ficam no painel de Variáveis, acessível pelo ícone de grade no painel direito ou via Editar → Variáveis no menu.

Configurando uma Coleção

As variáveis são organizadas em coleções. Cada coleção pode ter múltiplos modos (como Claro e Escuro). Antes de criar variáveis individuais, planeje a estrutura da sua coleção.

Um sistema bem organizado usa duas ou três coleções:

1. Primitivos — valores de cor brutos sem significado semântico (red/500, blue/200, neutral/900)
2. Semânticos — tokens orientados por propósito que referenciam primitivos (color/text/primary, color/background/surface)
3. Componentes (opcional) — tokens específicos de componente que referenciam semânticos (button/background/default)

Essa hierarquia garante que as alterações se propaguem corretamente. Se você quiser ajustar o azul da sua marca, você altera um primitivo. Cada token semântico que o referencia é atualizado, o que por sua vez atualiza cada componente que referencia esses semânticos.

Para criar uma coleção: 1. Abra o painel de Variáveis 2. Clique em + (Nova coleção) 3. Nomeie como "Primitivos" (ou o nome de sua preferência)

Criando Variáveis

Dentro de uma coleção, clique no botão + (Nova variável). Para variáveis de cor, selecione Cor como tipo.

Nomeie as variáveis usando notação de barra para criar grupos:

color/brand/primary
color/brand/secondary
color/text/primary
color/text/secondary
color/background/base
color/background/elevated
color/border/default
color/feedback/success
color/feedback/warning
color/feedback/danger

A barra cria uma hierarquia de pastas visual no painel de Variáveis, mantendo centenas de variáveis gerenciáveis.

Inserção de Valores

Para cada variável, clique na amostra de cor e insira o valor hex, ou escolha no seletor de cores. Para a coleção de Primitivos, insira valores hex brutos. Para a coleção de Semânticos, em vez de inserir um código hex, clique no ícone de variável no seletor de cores e selecione uma variável primitiva para criar um alias (referência).

Os aliases são a chave para sistemas de design manuteníveis. Seu token semântico color/background/base deve fazer alias de neutral/50 no modo claro e de neutral/950 no modo escuro — não codificar valores hex diretamente.

Use o Gerador de Paletas para gerar um conjunto completo e harmonioso de cores primitivas a partir de uma única cor de marca antes de começar a criar variáveis. O Gerador de Tonalidades é ideal para criar a escala de 50–950 para neutros e cores de marca que você usará como tokens primitivos.

Modos de Variáveis para Temas Claro e Escuro

Os modos são o recurso mais poderoso das variáveis do Figma. Uma única variável pode conter valores diferentes para contextos diferentes, e você alterna entre eles no nível do frame.

Adicionando um Modo Escuro

1. Abra a coleção Semânticos no painel de Variáveis
2. Clique em + Modo na linha do cabeçalho de modo
3. Nomeie o novo modo como "Escuro"

Agora cada variável semântica tem duas colunas: Claro e Escuro. Para cada variável: - Valor no modo claro: referência ao primitivo claro apropriado (ex.: neutral/50 para fundos, neutral/900 para texto) - Valor no modo escuro: referência ao primitivo escuro apropriado (ex.: neutral/950 para fundos, neutral/50 para texto)

Exemplo de Mapeamento Semântico

Note que color/brand/primary usa uma tonalidade diferente para o modo escuro — o azul base #2563EB pode passar no contraste WCAG AA contra branco, mas falhar contra um fundo escuro. Mudar para a tonalidade 400 blue/400 #60A5FA restaura o contraste adequado em superfícies escuras.

Aplicando Modos a Frames

Selecione qualquer frame no Figma e observe a seção Variáveis no painel direito. Você verá sua coleção com um menu suspenso mostrando o modo atual. Alterne para "Escuro" e o frame inteiro, incluindo todas as camadas filhas que referenciam variáveis semânticas, é imediatamente renderizado no modo escuro.

Este é o equivalente de design de alternar uma classe CSS no elemento raiz — o mesmo mecanismo que faz o modo escuro funcionar em código.

Modos Adicionais

Os modos não se limitam a claro e escuro. Considere: - Alto Contraste — para acessibilidade (conformidade WCAG AAA) - Marca A / Marca B — para produtos white-label de múltiplas marcas - Compacto / Confortável — para variantes de densidade (ao usar variáveis de número para espaçamento)

Cada modo adiciona uma coluna às suas variáveis. O poder escala com o número de componentes que referenciam tokens semânticos.

Sincronizando Variáveis com Código

As variáveis só são úteis se os engenheiros puderem consumi-las sem transcrição manual. Existem dois caminhos principais: exportação baseada em plugin e a API REST nativa do Figma.

Exportação Baseada em Plugin (Recomendado)

O plugin Tokens Studio for Figma (anteriormente Figma Tokens) é o padrão do setor para sincronização bidirecional entre variáveis do Figma e código. Ele pode:

• Exportar todas as variáveis para um arquivo JSON de token (formato W3C Design Token)
• Enviar para GitHub, GitLab ou qualquer repositório
• Integrar com Style Dictionary para transformar tokens em CSS, Tailwind, Sass e outros formatos de saída

Um arquivo de token exportado típico parece assim:

{
  "color": {
    "brand": {
      "primary": {
        "$value": "#2563EB",
        "$type": "color"
      }
    },
    "text": {
      "primary": {
        "$value": "{color.neutral.900}",
        "$type": "color"
      }
    }
  }
}

A sintaxe {color.neutral.900} preserva referências de alias na saída JSON, para que as ferramentas de transformação saibam que o token semântico é derivado de um primitivo — não um valor independente.

API REST do Figma

A API REST do Figma expõe variáveis diretamente no endpoint /v1/files/{file_key}/variables/local. Você pode automatizar a extração como parte de um pipeline CI/CD:

curl -H "X-Figma-Token: YOUR_TOKEN" \
  "https://api.figma.com/v1/files/YOUR_FILE_KEY/variables/local" \
  | jq '.meta.variables'

A resposta inclui IDs de variáveis, nomes, valores resolvidos por modo e relações de alias. Um script Node.js ou Python personalizado pode transformar essa saída no formato que seu codebase precisa.

Exportando para Propriedades CSS Personalizadas

O formato de saída de código mais direto para projetos web são as propriedades CSS personalizadas. Uma configuração do Style Dictionary pode transformar seu JSON de tokens em um arquivo CSS:

// style-dictionary.config.js
module.exports = {
  source: ["tokens/**/*.json"],
  platforms: {
    css: {
      transformGroup: "css",
      prefix: "color",
      buildPath: "src/styles/",
      files: [
        {
          destination: "tokens.css",
          format: "css/variables",
          options: {
            outputReferences: true,
          },
        },
      ],
    },
  },
};

A saída CSS gerada parece assim:

:root {
  /* Primitivos */
  --color-neutral-50: #FAFAFA;
  --color-neutral-100: #F5F5F5;
  --color-neutral-900: #171717;
  --color-neutral-950: #0A0A0A;
  --color-blue-400: #60A5FA;
  --color-blue-600: #2563EB;

  /* Semânticos — modo Claro */
  --color-background-base: var(--color-neutral-50);
  --color-background-elevated: var(--color-neutral-100);
  --color-text-primary: var(--color-neutral-900);
  --color-brand-primary: var(--color-blue-600);
}

[data-theme="dark"] {
  --color-background-base: var(--color-neutral-950);
  --color-background-elevated: var(--color-neutral-900);
  --color-text-primary: var(--color-neutral-50);
  --color-brand-primary: var(--color-blue-400);
}

Os engenheiros consomem --color-brand-primary em seus componentes. Quando [data-theme="dark"] é aplicado ao elemento raiz, a variável resolve para o valor do modo escuro automaticamente — sem necessidade de JavaScript no nível do componente.

Exportando para Configuração do Tailwind

Para projetos Tailwind CSS v3, a saída de tokens é mapeada para o tailwind.config.js:

// tailwind.config.js
const tokens = require('./tokens/resolved.json');

module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          primary: tokens.color.brand.primary.$value,
          secondary: tokens.color.brand.secondary.$value,
        },
        text: {
          primary: 'var(--color-text-primary)',
          secondary: 'var(--color-text-secondary)',
        },
        background: {
          base: 'var(--color-background-base)',
          elevated: 'var(--color-background-elevated)',
        },
      },
    },
  },
};

Para o Tailwind v4, a abordagem é ainda mais limpa. O Tailwind v4 usa CSS diretamente para configuração, o que significa que seu arquivo CSS de tokens pode ser importado e consumido sem nenhuma configuração JavaScript:

/* tailwind.css */
@import "tailwindcss";
@import "./tokens.css";

@theme {
  --color-brand-primary: var(--color-brand-primary);
  --color-text-primary: var(--color-text-primary);
  --color-background-base: var(--color-background-base);
}

Esse padrão significa que a cadeia variável Figma → token JSON → propriedade CSS personalizada → classe utilitária Tailwind é totalmente automatizada. Quando um designer atualiza uma cor no Figma, a mudança flui pelo pipeline para o CSS de produção sem intervenção manual.

Organizando Variáveis em Escala

Para sistemas de design com centenas de variáveis, a organização evita que o painel se torne ingerenciável.

Convenções de Nomenclatura

A nomenclatura consistente permite automação. Um padrão comum:

{categoria}/{subcategoria}/{variante}/{estado}

Exemplos:

color/text/primary
color/text/secondary
color/text/disabled
color/interactive/primary/default
color/interactive/primary/hover
color/interactive/primary/active
color/interactive/primary/disabled

Evite incluir nomes de modo nos nomes de variáveis (color/text/primary-dark é um antipadrão). Os modos são gerenciados pelo próprio sistema de variáveis — o nome da variável permanece o mesmo, o valor muda por modo.

Escopo de Variáveis

O Figma permite que você defina o escopo das variáveis para tipos de propriedades específicos. Uma variável destinada apenas a fundos deve ter o escopo definido para "Fill" — ela não aparecerá no seletor de cores ao definir um contorno ou cor de texto. Isso reduz a desordem e evita uso indevido.

Clique com o botão direito em qualquer variável → Editar variável → Desmarque as opções de escopo para restringir onde ela aparece.

Documentação Dentro do Figma

Adicione descrições a cada variável no painel Editar variável. Boas descrições explicam a intenção:

• color/brand/primary — "Cor primária da marca. Use para CTAs principais, links e ênfase. Não use para fundos."
• color/feedback/danger — "Apenas para estados de erro e ações destrutivas. Não use para avisos gerais."

Essas descrições são incluídas nas respostas da API REST do Figma e podem ser incorporadas automaticamente em comentários de código gerado.

Principais Conclusões

• Variáveis são a base de sistemas de design escaláveis: elas substituem valores hex codificados diretamente por tokens nomeados e semânticos que se atualizam globalmente quando alterados.
• Use uma hierarquia Primitivos → Semânticos: primitivos armazenam valores brutos, semânticos fazem alias de primitivos com nomes significativos. Os componentes referenciam semânticos, nunca primitivos diretamente.
• Os modos permitem a troca de temas sem duplicar componentes: valores claro e escuro vivem na mesma variável, e um único toggle no nível do frame alterna todo o design.
• Exporte via Tokens Studio ou a API REST do Figma: a automação fecha a lacuna design-código para que as variáveis permaneçam sincronizadas entre o Figma e seu codebase.
• Propriedades CSS personalizadas e configuração do Tailwind são os alvos de saída mais comuns. As variáveis CSS são consumidas diretamente; a configuração do Tailwind mapeia nomes de tokens para classes utilitárias.
• Use o Gerador de Paletas para criar sua paleta primitiva inicial e o Gerador de Tonalidades para produzir a escala completa de 50–950 para cada cor antes de inserir valores no Figma.