O Figma Variables chegou em 2023 como a resposta há muito aguardada da plataforma para design tokens. O recurso é poderoso: coleções nomeadas de valores primitivos — cores, números, strings, booleanos — que você pode vincular a qualquer propriedade em qualquer componente. Mude a variável e cada instância atualiza. Adicione uma coleção de modo escuro e cada vínculo de variável troca automaticamente.

Para AI codegen, Variables não são apenas úteis. São o mecanismo que converte um arquivo do Figma de um mockup pixel-perfect em uma spec que seu agente pode implementar corretamente. Quando uma cor tem um nome — color/brand/primary, não #7F5CFE — o agente pode mapeá-la para um token de código, implementar o modo escuro corretamente e produzir output que participa do seu design system real.

O problema: a maioria dos arquivos do Figma em uso ativo hoje não tem Variables configuradas. O figmascope lida com os dois casos. Este post explica como.

O que são Variables na prática

Uma Figma Variable é um escalar nomeado vinculado a uma coleção. As coleções organizam variáveis por modo — "Claro" e "Escuro" são o exemplo canônico. Cada variável em uma coleção pode ter valores diferentes por modo: color/surface/background é #FFFFFF no modo Claro e #0D0D0D no modo Escuro. O vínculo se propaga: cada preenchimento que referencia color/surface/background atualiza quando você muda de modo.

Variables podem ser cores, números, strings ou booleanos. Na prática, as mais impactantes são cores e números — o que cobre a maior parte da superfície de tokens em um design system típico: paleta de cores, escala de espaçamento, border radii, tamanhos de fonte, valores de elevação.

O Figma expõe Variables via sua API REST como uma coleção localVariables. Cada variável tem um ID, um nome, um tipo e valores por modo. Propriedades de componentes que referenciam variáveis carregam um campo boundVariables com o ID da variável. Esses são dados estruturados que viajam limpos pelo pipeline de extração.

O caminho feliz: Variables estão presentes

Quando um arquivo do Figma tem Variables, o figmascope as lê da API e constrói um tokens.json seguindo uma estrutura compatível com o W3C Design Tokens Community Group. Cada token tem um $value e um $type. Tokens de cor recebem valores hex com alfa opcional. Tokens de espaçamento recebem valores numéricos com uma dica de unidade px. O nome do token segue o caminho de coleção e nome da variável:

{
  "color": {
    "brand": {
      "primary": { "$value": "#7F5CFE", "$type": "color" }
    },
    "surface": {
      "background": { "$value": "#FFFFFF", "$type": "color" }
    }
  },
  "spacing": {
    "4": { "$value": 4, "$type": "number" },
    "8": { "$value": 8, "$type": "number" },
    "16": { "$value": 16, "$type": "number" }
  }
}

Quando a IR por tela é construída, cada preenchimento que tinha uma referência boundVariables recebe o nome do token em vez do hex resolvido. O nó carrega:

"fills": [{ "type": "SOLID", "tokenRef": "color/brand/primary" }]

Não #7F5CFE. O nome do token. O agente lê isso e gera background-color: var(--color-brand-primary) ou Color.brandPrimary ou qualquer que seja o padrão de consumo de token do framework alvo. Esse é o output que você quer: código conectado ao seu design system, não código que vai quebrar no momento em que um designer atualizar uma cor.

A nomenclatura semântica é a diferença entre código que envelhece bem e código que deriva. Um valor hex no código-fonte é um passivo; uma referência a um token é um contrato. Variables são o que tornam os arquivos do Figma capazes de expressar contratos, não apenas pixels.

A realidade: a maioria dos arquivos não tem Variables

Variables requerem o plano Professional do Figma ou superior. Requerem um designer que as tenha configurado — o que significa criar coleções, nomear variáveis e vinculá-las manualmente a cada propriedade de componente. Em um arquivo de design system maduro e bem mantido, isso está feito. No arquivo do Figma de produto de uma startup, em um arquivo de cliente de freelancer ou em qualquer arquivo que seja anterior ao recurso Variables, tipicamente não está.

O figmascope foi projetado para ser útil também para esses arquivos. Ele degrada graciosamente: quando Variables estão ausentes, ele cai para inferência de tokens baseada em frequência.

O fallback: inferred-from-frequency

O algoritmo de inferência funciona assim:

  1. Percorra cada nó folha em cada frame exportado.
  2. Colete todas as cores de preenchimento, valores de espaçamento e border radii.
  3. Conte as ocorrências de cada valor único.
  4. Valores que aparecem acima de um threshold de frequência são promovidos a tokens inferidos.
  5. Cada token recebe um nome derivado do valor: color.7f5cfe, spacing.16, radius.8.

O tokens.json de output parece estruturalmente similar ao caminho de Variables, mas os nomes são derivados de valor em vez de semânticos:

{
  "color": {
    "7f5cfe": { "$value": "#7F5CFE", "$type": "color" },
    "f6f2ea": { "$value": "#F6F2EA", "$type": "color" }
  },
  "spacing": {
    "16": { "$value": 16, "$type": "number" },
    "8": { "$value": 8, "$type": "number" }
  }
}

Na IR, nós que usam esses valores recebem referências de tokens: "tokenRef": "color.7f5cfe". Não literais hardcoded. Referências — apenas para tokens inferidos em vez de nomeados.

O agente ainda gera código referenciado por token. var(--color-7f5cfe) não é tão legível quanto var(--color-brand-primary), mas ainda é um token — você pode fazer find-and-replace, renomeá-lo, auditar seu uso. É um identificador nomeado de um valor, não um número mágico.

O campo tokensSource

Todo bundle do figmascope inclui um _meta.json que documenta o que há no bundle e como foi produzido. O campo tokensSource tem três valores possíveis:

Isso importa porque informa ao agente consumidor (e ao desenvolvedor lendo o bundle) exatamente quanto confiar nos nomes dos tokens. Um bundle figma-variables é fonte de verdade para o seu design system. Um bundle inferred-from-frequency é um scaffold estrutural útil que precisa de revisão de nomenclatura pelo designer antes de ser canônico. Um bundle none é um ponto de partida com valores hardcoded que precisam ser tokenizados depois.

Metadados honestos são subestimados. Ferramentas que inferem silenciosamente sem sinalizar a inferência criam falsa confiança. O figmascope expõe a cadeia de inferência explicitamente para que você saiba com o que está trabalhando.

Por que a inferência por frequência é melhor do que nada

A alternativa à inferência por frequência é produzir valores literais resolvidos em todo lugar — #7F5CFE em cada nó de preenchimento que usa essa cor. Isso produz código mais difícil de refatorar, mais difícil de auditar e mais difícil de conectar a um design system quando um for eventualmente adicionado.

A inferência por frequência extrai no mínimo o conjunto de valores que o design realmente usa. Se #7F5CFE aparece 47 vezes no design, isso é um sinal: é uma cor primária, não um acento. O nome do token não sabe disso — é apenas color.7f5cfe — mas os dados de frequência contam a história. Um agente com os tokens inferidos pode fazer suposições razoáveis sobre quais valores são primários e quais são únicos.

Mais praticamente: a inferência por frequência fornece um tokens.json que pode ser comparado (diff) entre versões. Se você exportar o mesmo arquivo duas vezes depois que um designer mudou uma cor recorrente, o diff mostra que o valor do token mudou. Sem inferência, você estaria rastreando cada mudança de literal individual espalhada por múltiplos arquivos de IR.

O que os designers ainda devem fazer

A inferência por frequência é uma camada de compatibilidade, não um substituto para Variables. O caminho correto é para os designers adotarem Variables para todos os valores que participam de um design system: cores de marca, escala neutra, escala de espaçamento, border radii, elevação, tipografia. Uma vez que estejam no lugar, o bundle do figmascope vai de tokens de qualidade de scaffold para tokens de qualidade de produção.

Variables também desbloqueiam temas no bundle: múltiplos valores de modo por token. Um arquivo com modos Claro/Escuro produz um tokens.json com valores por modo que alimentam diretamente propriedades customizadas CSS com substituições de media query, ou objetos de tema específicos da plataforma. Isso é impossível de inferir a partir de um único snapshot de design — requer intenção explícita do designer, expressa através de Variables.

O caminho de upgrade é incremental. Uma equipe pode começar com tokens de qualidade de inferência hoje, adotar Variables gradualmente conforme o design system amadurece e obter bundles melhores automaticamente à medida que fazem isso. O campo tokensSource rastreia onde você está nessa progressão.

O pipeline de tokens completo

Para ser concreto, aqui está a ordem completa de resolução que o figmascope usa para cada preenchimento na IR:

  1. O nó tem uma referência boundVariables.fills? Se sim, resolva para o nome da variável e o valor do modo zero. Fonte do token: figma-variables.
  2. O valor resolvido está presente nos tokens de frequência inferidos (acima do threshold)? Se sim, mapeie para o nome do token inferido. Fonte do token: inferred-from-frequency.
  3. Caso contrário: use o valor hex resolvido diretamente. Sem referência de token. Fonte do token: none.

Os passos são tentados em ordem. A fonte de maior qualidade vence. O campo tokensSource em _meta.json reflete o caminho dominante para o bundle como um todo.

Isso significa que um arquivo parcialmente coberto por Variables — onde alguns componentes têm vínculos e outros não — produz um bundle misto. Tokens nomeados onde existem, tokens inferidos onde não. Esse é o comportamento correto: use cada fragmento de informação estruturada disponível, faça fallback graciosamente onde estiver ausente e seja honesto sobre qual caminho cada valor tomou.

Exporte seu bundle do app figmascope para ver qual tokensSource seu arquivo produz. Depois use o bundle com Claude Code ou Cursor para geração de código precisa e referenciada por tokens.