tokens.json förklarat — Typade designtokens för AI-kodgenerering

Varje figmascope-export inkluderar tokens.json. Det är bryggan mellan Figmas visuella värden och de typade konstanter din kod behöver. Det här inlägget täcker schemat, hur nycklar namnges, vad som händer när en Figma-fil saknar Variables, och var tokensystemet ärligt talat faller kort.

Schemat

Toppnivåstrukturen har fyra sektioner:

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

Formatet är W3C Design Tokens Community Group-liknande: varje token är ett objekt med $value och $type. Det är inte en strikt W3C DTCG-implementation — figmascope är äldre än det slutliga spec-publiceringen och implementerar inte sammansatta typer som fontFamily — men det är tillräckligt nära för att DTCG-medveten verktygsuppsättning ska kunna tolka det med mindre anpassning.

Det tomma typography-objektet är inte ett fel. Det täcks nedan.

Värdebaserad nyckelnamnsgivning

När en Figma-fil har Variables kommer tokennycklarna från de variabelnamn designern angett. spacing.md, color.brand.primary, vad designsystemet nu använder.

När en Figma-fil saknar Variables — vilket är majoriteten av verkliga Figma-filer — faller figmascope tillbaka på värdebaserad namnsgivning. Ett mellanrumsvärde på 16 blir spacing.16. En färg #7f5cfe blir color.7f5cfe. En hörnradie på 4 blir radius.4.

Det här är en medveten avvägning. Värdebaserade namn är fula men stabila. De härleds från det faktiska värdet, så två olika körningar av samma Figma-fil producerar samma nyckel. spacing.16 betyder alltid 16dp. Agenten kan lita på det.

Alternativet vore positionsbaserade namn som spacing.1, spacing.2 osv. De är bräckliga — lägg till ett mindre mellanrumsvärde och allt skiftar. Värdebaserade namn skiftar inte.

Värdebaserade namn är en fallback för filer som borde ha Variables men inte har det. Om ditt designsystem har 40 mellanrumsvärden som alla behöver semantiska namn, pressa designern att sätta upp Variables. Slutledningsfallbacken finns för verkliga filer, inte som ett substitut för ett riktigt tokensystem. Du kan köra figmascope på din egen fil för att se vilken källväg den tar.

Fältet tokensSource och vad det betyder

_meta.json inkluderar ett tokensSource-fält som berättar hur tokens härletts:

Varningen "tokens-inferred-from-frequency" i _meta.json speglar detta. Om du ser den är tokentäckningen bästa-ansträngning.

När tokensSource är "inferred-from-frequency" är slutledningsalgoritmen: hitta alla dimensionsvärden som förekommer i tre eller fler noders utfyllnads-, gap- eller cornerRadius-fält. Befordra dem till mellanrums- eller radietokens respektive. Gör detsamma för fyllningsfärger. Värden som bara förekommer en eller två gånger behandlas som engångsvärden, befordras inte.

Det här fungerar bra för designs som är internt konsekventa. Det fungerar dåligt för utforskande designs där mellanrummet varierar fritt. Varningarna i _meta.json finns just för att agenten vet vilken situation den befinner sig i.

Varför typografi ofta är tomt

Typografitokens kräver Figma Variables med typen FLOAT eller STRING för att kunna extraheras på ett tillförlitligt sätt. Textstilar finns i Figma som delade stilar, inte Variables, och API-ytan för stilar skiljer sig från Variables API.

figmascope v0.4 extraherar typografi när Variables täcker den. Det försöker inte frekvensbaserad slutledning för typografi eftersom de användbara typografitokens — typsnittsfamilj, radhöjd, bokstavsavstånd, viktkombinationer — inte har uppenbara värdebaserade namn på samma sätt som spacing.16 gör. En fontSize.14-nyckel är mycket mindre användbar än typography.body.small, och att generera ett dåligt namn är värre än att inte generera något namn.

Resultatet är alltså ärligt: om din Figma-fil har typografi-Variables får du typografitokens. Om inte får du ett tomt objekt och agenten informeras via CONTEXT.md att typografitäckningen kan vara partiell.

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

Agenten ser det här och vet att vara försiktig med typografitokenreferenser. Den genererar reservkod med explicita värden och en TODO-kommentar snarare än att uppfinna ett tokennamn.

Hur agenten använder tokens.json

CONTEXT.md-begränsningen är: "Hårdkoda aldrig dp-värden om ett token finns inom ±2dp." ±2dp-toleransen hanterar avrundning. Om en nod har paddingLeft: 15 och spacing.16 finns används spacing.16. Om det närmaste tokenet är spacing.24 ingen matchning — agenten använder det literala värdet.

För färger är matchningen exakt på hex-värdet efter normalisering till 6-siffrig gemener. #7F5CFE matchar color.7f5cfe.

För hörnradie, samma ±2dp-regel som för mellanrum.

Den praktiska utdatan för ett Jetpack Compose-mål ser ut så här:

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

// Med inferred-from-frequency tokensSource (samma visuella utdata, samma tokenreferenser)
Surface(
    shape = RoundedCornerShape(Radius.radius8),
    color = Color.color7f5cfe
) { ... }

De värdebaserade namnen är mindre läsbara. De är ändå bättre än hårdkodade värden.

Jämförelse med andra tokenextraktionsmetoder

Figmas inbyggda "Inspect"-panel visar värden per nod. Det finns ingen exporterad tokenfil. Du måste skapa en manuellt eller använda ett plugin som Tokens Studio. Båda kräver designeransträngning och kontinuerligt underhåll.

figmascope extraherar tokens automatiskt vid varje export. Om filen ändras, exportera om och tokens återspeglar det aktuella tillståndet. Avvägningen är att utan Variables är namnen värdebaserade snarare än semantiska — men du får en tokenfil varje gång, utan ett plugin eller extra arbetsflödessteg.

Tokens Studio (tidigare Style Dictionary-integration) kräver att designern sätter upp pluginet, underhåller en JSON-fil i Figma-filen och synkar den. Det är rätt lösning för ett moget designsystem. figmascopes metod är rätt lösning för filer som inte är där ännu, vilket är de flesta filer.

Tokenextraktionen är en bästa-ansträngning-ögonblicksbild av vad som finns i filen. Det är inte ett substitut för ett token-first-designsystem. Det är det du använder medan du bygger mot ett.

Koppla tokens.json till din kodbas

JSON-strukturen är platt nog för att generera ett Kotlin-objekt eller TypeScript-modul från det på ett enkelt sätt. Ett enkelt skript:

// tokens.json → Kotlin-objekt (förenklat)
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

Om du redan använder en designtokenpipeline är det W3C-liknande formatet tillräckligt nära för att släppas in i Style Dictionary med en anpassad transformer för $value/$type-nycklarna.

Resten av hur tokens samverkar med IR täcks i Per-skärm IR. För hur tokens samverkar med den bredare agentkontexten, se CONTEXT.md-anatomin. För designtokenexportarbetsflödet från start till slut, se Designtokenexport. För att exportera tokens från din egen Figma-fil, gå till figmascope.dev.