Figma Variables pro AI codegen — Proč záleží a co dělat bez nich

Figma Variables přistály v roce 2023 jako dlouho odkládaná odpověď platformy na design tokeny. Funkce je mocná: pojmenované kolekce primitivních hodnot — barvy, čísla, řetězce, booleany — které lze svázat s jakoukoli vlastností jakékoli komponenty. Změňte proměnnou, každá instance se aktualizuje. Přidejte kolekci tmavého režimu, každá vazba proměnné se automaticky přepne.

Pro AI codegen nejsou Variables jen užitečné. Jsou mechanismem, který přeměňuje Figma soubor z pixelově přesného mockupu na specifikaci, kterou váš agent dokáže správně implementovat. Když má barva jméno — color/brand/primary, ne #7F5CFE — agent ji může namapovat na token kódu, správně implementovat tmavý režim a produkovat výstup, který se účastní vašeho skutečného design systému.

Zde je problém: většina Figma souborů v aktivním použití dnes Variables nastavené nemá. figmascope oba případy zvládá. Tento příspěvek vysvětluje jak.

Co Variables vlastně jsou

Figma Variable je pojmenovaný skalár svázaný s kolekcí. Kolekce organizují proměnné podle režimu — "Light" a "Dark" jsou kanonický příklad. Každá proměnná v kolekci může mít různé hodnoty podle režimu: color/surface/background je #FFFFFF ve světlém a #0D0D0D v tmavém. Vazba se šíří: každá výplň odkazující na color/surface/background se aktualizuje při přepnutí režimů.

Variables mohou být barvy, čísla, řetězce nebo booleany. V praxi jsou nejdůležitější barvy a čísla — které pokrývají většinu plochy tokenů v typickém design systému: barevná paleta, škála mezer, poloměry ohraničení, velikosti písma, hodnoty výšky.

Figma zpřístupňuje Variables přes REST API jako kolekci localVariables. Každá proměnná má ID, jméno, typ a hodnoty-podle-režimu. Vlastnosti komponent, které odkazují na proměnné, nesou pole boundVariables s ID proměnné. Jsou to strukturovaná data, která čistě procházejí extrakčním pipeline.

Šťastná cesta: Variables jsou přítomny

Když má Figma soubor Variables, figmascope je čte z API a sestavuje tokens.json podle struktury kompatibilní s W3C Design Tokens Community Group. Každý token má $value a $type. Barevné tokeny dostávají hex hodnoty s volitelnou průhledností. Tokeny mezer dostávají numerické hodnoty s nápovědou k jednotce px. Název tokenu sleduje cestu kolekce a názvu proměnné:

{
  "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" }
  }
}

Když se sestavuje IR pro každou obrazovku, každá výplň, která měla referenci boundVariables, dostane název tokenu místo rozlišeného hexu. Uzel nese:

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

Ne #7F5CFE. Název tokenu. Agent to čte a generuje background-color: var(--color-brand-primary) nebo Color.brandPrimary nebo cokoli, co je vzor konzumace tokenů cílového frameworku. To je výstup, který chcete: kód propojený s vaším design systémem, ne kód, který se rozbije v okamžiku, kdy designér aktualizuje barvu.

Sémantické pojmenování je rozdíl mezi kódem, který dobře stárne, a kódem, který se odchyluje. Hex hodnota ve zdroji je závazek; reference tokenu je smlouva. Variables jsou to, co dělá Figma soubory schopnými vyjadřovat smlouvy, ne jen pixely.

Realita: většina souborů Variables nemá

Variables vyžadují plán Figma Professional nebo vyšší. Vyžadují designéra, který je nastavil — což znamená vytvoření kolekcí, pojmenování proměnných a ruční svázání s každou vlastností komponenty. Ve zralém, dobře udržovaném souboru design systému je to hotovo. V produktovém Figma startupu, souboru klienta freelancera nebo jakémkoli souboru, který předchází funkci Variables, to typicky není.

figmascope byl navržen tak, aby byl užitečný i pro tyto soubory. Degraduje gracefully: když Variables chybí, přepne se na inferenci tokenů na základě frekvence.

Záložní cesta: inferred-from-frequency

Algoritmus inference funguje takto:

Projde každý listový uzel v každém exportovaném rámci.
Sbírá všechny barvy výplní, hodnoty mezer a poloměry ohraničení.
Počítá výskyty každé jedinečné hodnoty.
Hodnoty, které se objevují nad prahem frekvence, jsou povýšeny na odvozené tokeny.
Každý token dostane jméno odvozené z hodnoty: color.7f5cfe, spacing.16, radius.8.

Výstupní tokens.json vypadá strukturálně podobně jako cesta Variables, ale názvy jsou odvozeny z hodnot, ne sémantické:

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

V IR dostávají uzly, které tyto hodnoty používají, reference tokenů: "tokenRef": "color.7f5cfe". Ne hardkódované literály. Reference — jen na odvozené tokeny, ne pojmenované.

Agent stále generuje kód odkazující na tokeny. var(--color-7f5cfe) není tak čitelné jako var(--color-brand-primary), ale stále je to token — můžete ho najít a nahradit, přejmenovat, auditovat jeho použití. Je to pojmenované handle na hodnotu, ne magické číslo.

Pole tokensSource

Každý balíček figmascope obsahuje _meta.json, který dokumentuje, co je v balíčku a jak byl vytvořen. Pole tokensSource má tři možné hodnoty:

figma-variables — Variables byly přítomny a použity. Názvy tokenů jsou sémantické.
inferred-from-frequency — Variables nenalezeny. Tokeny byly odvozeny z frekvence hodnot. Názvy jsou odvozeny z hodnot.
none — Žádné tokeny nebylo možné extrahovat ani odvodit. IR používá přímo rozlišené hodnoty.

To záleží, protože říká konzumujícímu agentovi (a vývojáři čtoucímu balíček), nakolik věřit názvům tokenů. Balíček figma-variables je zdrojem pravdy pro váš design systém. Balíček inferred-from-frequency je užitečný strukturální scaffold, který potřebuje designérskou kontrolu pojmenování, než bude kanonický. Balíček none je výchozí bod s hardkódovanými hodnotami, které je třeba tokenizovat později.

Poctivá metadata jsou podceňována. Nástroje, které tiše odvozují bez označení toho jako inference, vytvářejí falešnou důvěru. figmascope zpřístupňuje inference chain explicitně, abyste věděli, s čím pracujete.

Proč je inference z frekvence lepší než nic

Alternativou k inferenci z frekvence je výstup rozlišených literálních hodnot všude — #7F5CFE v každém uzlu výplně, který tuto barvu používá. To produkuje kód, který je obtížnější refaktorovat, obtížnější auditovat a obtížnější propojit s design systémem, když je nakonec přidán.

Inference z frekvence minimálně extrahuje sadu hodnot, které návrh skutečně používá. Pokud se #7F5CFE objevuje 47krát napříč návrhem, je to signál: toto je primární barva, ne akcent. Název tokenu to neví — je to jen color.7f5cfe — ale data o frekvenci příběh vypráví. Agent dostávající odvozené tokeny může přiměřeně hádat, které hodnoty jsou primární a které jsou jednorázové.

Praktičtěji: inference z frekvence vám dává tokens.json, který lze diffovat napříč verzemi. Pokud exportujete stejný soubor dvakrát poté, co designér změnil opakující se barvu, diff ukáže, že se hodnota tokenu změnila. Bez inference byste pronásledovali každou jednotlivou doslovenou změnu roztroušenou napříč více IR soubory.

Co by designéři přesto měli dělat

Inference z frekvence je kompatibilní vrstva, ne náhrada za Variables. Správná cesta je, aby designéři přijali Variables pro všechny hodnoty, které se účastní design systému: barvy značky, neutrální škála, škála mezer, poloměry ohraničení, výška, typografie. Jakmile jsou na místě, balíček figmascope přechází z tokenů kvality scaffoldu na tokeny produkční kvality.

Variables také odemykají tématiku v balíčku: více hodnot režimu na token. Soubor se světlými/tmavými režimy produkuje tokens.json s hodnotami podle režimu, které se přímo napájí do CSS vlastních vlastností s přepisy media query nebo objektů témat specifických pro platformu. To nelze odvodit z jediného snapshot návrhu — vyžaduje to explicitní záměr designéra vyjádřený prostřednictvím Variables.

Upgrade cesta je postupná. Tým může začít s tokeny kvality inference dnes, postupně přijímat Variables jak design systém dozrává, a automaticky dostávat lepší balíčky. Pole tokensSource sleduje, kde v tomto postupu jste.

Celý pipeline tokenů

Aby bylo konkrétní, zde je celý pořadí rozlišení, které figmascope používá pro každou výplň v IR:

Má uzel referenci boundVariables.fills? Pokud ano, rozlište na název proměnné a hodnotu nultého režimu. Zdroj tokenu: figma-variables.
Je rozlišená hodnota přítomna v odvozených frekvenčních tokenech (nad prahem)? Pokud ano, namapujte na odvozený název tokenu. Zdroj tokenu: inferred-from-frequency.
Jinak: použijte přímo rozlišenou hex hodnotu. Žádná reference tokenu. Zdroj tokenu: none.

Kroky jsou zkoušeny v pořadí. Vyhraje zdroj nejvyšší kvality. Pole tokensSource v _meta.json odráží dominantní cestu pro celý balíček.

To znamená, že soubor s částečnými Variables — kde některé komponenty mají vazby a jiné ne — produkuje smíšený balíček. Pojmenované tokeny kde existují, odvozené tokeny kde ne. To je správné chování: použijte každý kousek strukturovaných informací, který je k dispozici, gracefully se vraťte tam kde chybí, a buďte upřímní ohledně toho, jakou cestou každá hodnota šla.

Exportujte svůj balíček z aplikace figmascope, abyste viděli, jaký tokensSource váš soubor produkuje. Poté použijte balíček s Claude Code nebo Cursor pro přesné generování kódu odkazujícího na tokeny.