CSS Variables vs Figma Variables: Como Sincronizar Design Tokens sem Retrabalho

Manter a consistência entre o que é projetado no Figma e o que é implementado no código sempre foi um dos maiores desafios de design systems. A chegada das Figma Variables trouxe a promessa de aproximar essas duas pontas. No entanto, as variáveis do Figma e as propriedades personalizadas do CSS (CSS Custom Properties) funcionam sob lógicas internas distintas.

Para evitar o retrabalho de atualizar cores, espaçamentos e raios manualmente em dois lugares, é preciso entender como mapear essas estruturas e automatizar o fluxo.

Qual a Diferença Estrutural entre Figma e CSS Variables?

No CSS, as variáveis são dinâmicas por padrão, herdam valores do escopo do DOM e aceitam expressões lógicas complexas (como cálculos através de calc()). No Figma, as variáveis possuem tipagem estática (Color, Number, String, Boolean) e são organizadas em modos (como Light Mode e Dark Mode) e coleções.

A principal divergência está na forma como lidam com aliases (referências a outras variáveis):

• No Figma: Uma variável aponta diretamente para outra variável em uma coleção base (ex: color.brand.primary aponta para primitive.blue.500). O Figma valida essas referências nativamente para evitar links quebrados.
• No CSS: Uma variável referencia outra usando a sintaxe var(), como background: var(--color-brand-primary, var(--primitive-blue-500)). A resolução ocorre em tempo de execução no navegador, sem compilação prévia.

Como Estruturar Design Tokens de Forma Automatizada

Para criar uma ponte confiável e sem intervenção manual contínua, a melhor prática do mercado é adotar uma ferramenta de tradução de tokens, como o Style Dictionary da Amazon, integrado à API do Figma.

O fluxo de sincronização recomendado segue três etapas básicas:

/* 1. Variáveis Primitivas (Fila base de valores absolutos) */
:root {
  --blue-500: #0070f3;
  --spacing-8: 8px;
}

/* 2. Variáveis Semânticas (Onde o design toma significado) */
:root {
  --action-primary-default: var(--blue-500);
  --padding-card: var(--spacing-8);
}

1. Exportação do Figma: Use plugins como o Variables Export ou a API oficial de desenvolvedores do Figma para extrair as variáveis em formato JSON.
2. Tradução com Style Dictionary: O script lê o JSON gerado e compila os arquivos formatados para múltiplos destinos (CSS, Sass, Tailwind CSS ou código nativo mobile).
3. Entrega Contínua (CI/CD): Integre o script ao GitHub Actions para que, sempre que o time de design publicar uma atualização na biblioteca do Figma, um Pull Request seja aberto automaticamente com os novos tokens atualizados no código.

Cuidados ao Sincronizar Modos Escuro e Claro

Ao mapear coleções multimodo do Figma para o CSS, evite criar variáveis duplicadas como --light-bg e --dark-bg. Em vez disso, use escopos de classe ou atributos HTML para redefinir os valores das variáveis semânticas correspondentes:

/* Escopo padrão: Light Mode */
:root {
  --bg-page: #ffffff;
  --text-primary: #111111;
}

/* Redefinição de valores: Dark Mode */
@media (prefers-color-scheme: dark) {
  :root {
    --bg-page: #121212;
    --text-primary: #eeeeee;
  }
}

Esta abordagem garante que o código HTML permaneça limpo e reutilizável, dependendo apenas da alteração do contexto CSS para mudar o tema de toda a aplicação sem hacks de JavaScript.