tokens.json Vysvětleno — Typované designové tokeny pro AI generování kódu

Každý export figmascope zahrnuje tokens.json. Je to most mezi vizuálními hodnotami Figmy a typovanými konstantami, které váš kód potřebuje. Tento příspěvek pokrývá schéma, jak jsou klíče pojmenovány, co se stane, když soubor Figmy nemá Variables, a kde tokenový systém upřímně zaostává.

Schéma

Struktura nejvyšší úrovně má čtyři sekce:

{
  "spacing": {
    "spacing.4":  { "$value": 4,  "$type": "dimension" },
    "spacing.8":  { "$value": 8,  "$type": "dimension" },
    "spacing.12": { "$value": 12, "$type": "dimension" },
    "spacing.16": { "$value": 16, "$type": "dimension" },
    "spacing.24": { "$value": 24, "$type": "dimension" }
  },
  "radius": {
    "radius.4":  { "$value": 4,  "$type": "dimension" },
    "radius.8":  { "$value": 8,  "$type": "dimension" },
    "radius.12": { "$value": 12, "$type": "dimension" }
  },
  "color": {
    "color.7f5cfe": { "$value": "#7f5cfe", "$type": "color" },
    "color.ffffff": { "$value": "#ffffff", "$type": "color" },
    "color.1a1a2e": { "$value": "#1a1a2e", "$type": "color" }
  },
  "typography": {}
}

Formát je W3C Design Tokens Community Group-ish: každý token je objekt s $value a $type. Není to přísná implementace W3C DTCG — figmascope předchází finální publikaci specifikace a neimplementuje kompozitní typy jako fontFamily — ale je dostatečně blízko, že nástroje aware-of-DTCG ho mohou parsovat s menší adaptací.

Prázdný objekt typography není chyba. Je pokryt níže.

Pojmenování klíčů odvozené z hodnot

Když soubor Figmy má Variables, klíče tokenů pocházejí z názvů Variables, které designer nastavil. spacing.md, color.brand.primary, cokoli designový systém používá.

Když soubor Figmy nemá Variables — což je většina skutečných souborů Figmy — figmascope přejde na pojmenování odvozené z hodnot. Hodnota spacing 16 se stane spacing.16. Barva #7f5cfe se stane color.7f5cfe. Poloměr rohu 4 se stane radius.4.

To je záměrný kompromis. Názvy odvozené z hodnot jsou ošklivé, ale stabilní. Jsou odvozeny od skutečné hodnoty, takže dva různé běhy stejného souboru Figmy produkují stejný klíč. spacing.16 vždy znamená 16dp. Agent se na to může spolehnout.

Alternativou by byly poziční názvy jako spacing.1, spacing.2 atd. Ty jsou křehké — přidejte menší hodnotu mezery a vše se posune. Názvy odvozené z hodnot se neposouvají.

Názvy odvozené z hodnot jsou záložní řešení pro soubory, které by měly mít Variables, ale nemají. Pokud má váš designový systém 40 hodnot mezer, které všechny potřebují sémantická jména, přesvědčte designéra, aby nastavil Variables. Inferenční záložní řešení existuje pro skutečné soubory, nikoli jako náhrada za skutečný systém tokenů. Můžete spustit figmascope na svém vlastním souboru a zjistit, jakou cestu sourcing bere.

Pole tokensSource a co znamená

_meta.json zahrnuje pole tokensSource, které vám říká, jak byly tokeny odvozeny:

Varování "tokens-inferred-from-frequency" v _meta.json to zrcadlí. Pokud ho vidíte, pokrytí tokenů je best-effort.

Když je tokensSource "inferred-from-frequency", inferenční algoritmus je: najděte všechny dimenzionální hodnoty, které se objevují ve třech nebo více polích padding, gap nebo cornerRadius uzlů. Propagujte ty na tokeny mezer nebo poloměru. Totéž pro barvy výplní. Hodnoty, které se objevují pouze jednou nebo dvakrát, jsou považovány za jednorázové a nejsou propagovány.

To funguje dobře pro interně konzistentní designy. Funguje špatně pro exploratorní designy, kde se mezery volně mění. Varování _meta.json existují přesně proto, aby agent věděl, v jaké situaci se nachází.

Proč je typography často prázdná

Typografické tokeny vyžadují Figma Variables s typem FLOAT nebo STRING pro spolehlivou extrakci. Textové styly existují ve Figmě jako sdílené styly, nikoli Variables, a povrch API pro styly se liší od Variables API.

figmascope v0.4 extrahuje typografii, když ji pokrývají Variables. Nepokouší se o inferenci na základě frekvence pro typografii, protože užitečné typografické tokeny — rodina písma, výška řádku, mezery mezi písmeny, kombinace vah — nemají zřejmá jména odvozená z hodnot tak jako spacing.16. Klíč fontSize.14 je mnohem méně užitečný než typography.body.small a generování špatného jména je horší než negenerovat žádné.

Výsledek je tedy upřímný: pokud má váš soubor Figmy typografické Variables, dostanete typografické tokeny. Pokud ne, dostanete prázdný objekt a agent je prostřednictvím CONTEXT.md informován, že pokrytí typografie může být částečné.

// _meta.json
{
  "tokensSource": "inferred-from-frequency",
  "warnings": [
    "tokens-inferred-from-frequency"
  ]
}

Agent to vidí a ví, že má být konzervativní ohledně referencí typografických tokenů. Generuje záložní kód s explicitními hodnotami a komentářem TODO namísto vymýšlení názvu tokenu.

Jak agent používá tokens.json

Omezení CONTEXT.md je: „Nikdy hardkódujte dp hodnoty, pokud token existuje v rozsahu ±2dp." Tolerance ±2dp zpracovává zaokrouhlování. Pokud má uzel paddingLeft: 15 a existuje spacing.16, agent použije spacing.16. Pokud je nejbližší token spacing.24, žádná shoda — agent použije doslovnou hodnotu.

Pro barvy je shoda přesná na hexadecimální hodnotě po normalizaci na 6-číslicový malý formát. #7F5CFE odpovídá color.7f5cfe.

Pro poloměr rohu platí stejné pravidlo ±2dp jako pro mezery.

Praktický výstup pro cíl Jetpack Compose vypadá takto:

// Se zdrojem tokensSource figma-variables
Surface(
    shape = RoundedCornerShape(Radius.radius8),
    color = Color.Brand.Primary
) {
    Column(
        verticalArrangement = Arrangement.spacedBy(Spacing.spacing16),
        modifier = Modifier.padding(horizontal = Spacing.spacing24)
    ) { ... }
}

// Se zdrojem tokensSource inferred-from-frequency (stejný vizuální výstup, stejné reference tokenů)
Surface(
    shape = RoundedCornerShape(Radius.radius8),
    color = Color.color7f5cfe
) { ... }

Názvy odvozené z hodnot jsou méně čitelné. Jsou stále lepší než hardcódované hodnoty.

Srovnání s jinými přístupy k extrakci tokenů

Nativní panel „Inspect" Figmy zobrazuje hodnoty per-uzel. Neexistuje žádný exportovaný soubor tokenů. Museli byste ho vytvořit ručně nebo použít plugin jako Tokens Studio. Obojí vyžaduje úsilí designéra a průběžnou údržbu.

figmascope extrahuje tokeny automaticky při každém exportu. Pokud se soubor změní, re-exportujte a tokeny odrážejí aktuální stav. Kompromisem je, že bez Variables jsou jména odvozena z hodnot spíše než sémantická — ale dostanete soubor tokenů pokaždé, bez pluginu nebo extra kroku pracovního postupu.

Tokens Studio (dříve integrace Style Dictionary) vyžaduje, aby designer nastavil plugin, udržoval JSON soubor v souboru Figmy a synchronizoval ho. To je správné řešení pro vyspělý designový systém. Přístup figmascope je správné řešení pro soubory, které tam ještě nejsou, což je většina souborů.

Extrakce tokenů je best-effort snímek toho, co v souboru existuje. Není to náhrada za tokenový designový systém. Je to věc, kterou používáte při budování k jednomu.

Zapojení tokens.json do vaší codebase

JSON struktura je dostatečně plochá, že generování Kotlin objektu nebo TypeScript modulu z ní je přímočaré. Jednoduchý skript:

// tokens.json → Kotlin object (zjednodušeno)
const tokens = JSON.parse(fs.readFileSync('tokens.json', 'utf-8'));

let output = 'object Spacing {\n';
for (const [key, token] of Object.entries(tokens.spacing)) {
    const name = key.replace('spacing.', 'spacing').replace('.', '_');
    output += `    val ${name} = ${token.$value}.dp\n`;
}
output += '}';
// → val spacing16 = 16.dp

Pokud již používáte pipeline designových tokenů, formát W3C-ish je dostatečně blízko, aby šel vložit do Style Dictionary s vlastním transformátorem pro klíče $value/$type.

Zbytek toho, jak tokeny interagují s IR, je pokryt v IR pro každou obrazovku. Pro to, jak tokeny interagují s širším kontextem agenta, viz Anatomie CONTEXT.md. Pro pracovní postup exportu designových tokenů od začátku do konce viz Export designových tokenů. Pro export tokenů z vlastního souboru Figmy přejděte na figmascope.dev.