Elke export van figmascope bevat tokens.json. Het is de brug tussen de visuele waarden van Figma en de getypte constanten die je code nodig heeft. Dit bericht behandelt het schema, hoe sleutels worden benoemd, wat er gebeurt wanneer een Figma-bestand geen Variables heeft, en waar het tokensysteem eerlijk tekortschiet.

Het schema

De structuur op het hoogste niveau heeft vier secties:

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

Het formaat is W3C Design Tokens Community Group-achtig: elk token is een object met $value en $type. Het is geen strikte W3C DTCG-implementatie — figmascope dateert van vóór de definitieve publicatie van de spec en implementeert geen samengestelde typen zoals fontFamily — maar het is dicht genoeg dat DTCG-bewuste tooling het kan parseren met kleine aanpassing.

Het lege typography-object is geen bug. Het wordt hieronder behandeld.

Waarde-afgeleide sleutelbenoembaarheid

Wanneer een Figma-bestand Variables heeft, komen tokensleutels van de variabelenamen die de ontwerper heeft ingesteld. spacing.md, color.brand.primary, wat het ontwerpsysteem ook gebruikt.

Wanneer een Figma-bestand geen Variables heeft — wat de meerderheid van echte Figma-bestanden is — valt figmascope terug op waarde-afgeleide benoembaarheid. Een spatiëeringswaarde van 16 wordt spacing.16. Een kleur #7f5cfe wordt color.7f5cfe. Een hoekstraal van 4 wordt radius.4.

Dit is een bewuste afweging. Waarde-afgeleide namen zijn lelijk maar stabiel. Ze zijn afgeleid van de werkelijke waarde, zodat twee verschillende runs van hetzelfde Figma-bestand dezelfde sleutel produceren. spacing.16 betekent altijd 16dp. De agent kan erop vertrouwen.

Het alternatief zouden positionele namen zijn zoals spacing.1, spacing.2 enz. Die zijn broos — voeg een kleinere spatiëeringswaarde toe en alles verschuift. Waarde-afgeleide namen verschuiven niet.

Waarde-afgeleide namen zijn een terugval voor bestanden die Variables zouden moeten hebben maar dat niet doen. Als je ontwerpsysteem 40 spatiëeringswaarden heeft die allemaal semantische namen nodig hebben, zet de ontwerper dan aan om Variables in te stellen. De inferentieterugval bestaat voor echte bestanden, niet als vervanging voor een echt tokensysteem. Je kunt figmascope op je eigen bestand uitvoeren om te zien welk bronningspad het neemt.

Het tokensSource-veld en wat het betekent

_meta.json bevat een tokensSource-veld dat je vertelt hoe de tokens zijn afgeleid:

WaardeBetekenis
"figma-variables" Het Figma-bestand heeft Variables en ze zijn direct gebruikt. Tokennamen zijn door de ontwerper toegewezen. Volledige dekking.
"inferred-from-frequency" Geen Variables. figmascope heeft alle knooppunten gescand, frequent terugkerende waarden gevonden en ze gepromoot tot tokens. Dekking hangt af van de consistentie van het ontwerp.
"none" Geen Variables en inferentie heeft niets nuttigs opgeleverd. tokens.json heeft lege of bijna-lege secties.

De waarschuwing "tokens-inferred-from-frequency" in _meta.json weerspiegelt dit. Als je die ziet, is de tokendekking best-effort.

Wanneer tokensSource "inferred-from-frequency" is, werkt het inferentie-algoritme als volgt: vind alle dimensiewaarden die voorkomen in de opvulling, gap of cornerRadius-velden van drie of meer knooppunten. Promoot die respectievelijk naar spatiëerings- of straltokens. Doe hetzelfde voor vul-kleuren. Waarden die slechts één of twee keer voorkomen, worden behandeld als eenmalig en worden niet gepromoot.

Dit werkt goed voor intern consistente ontwerpen. Het werkt slecht voor verkennende ontwerpen waarbij spatiëring vrij varieert. De _meta.json-waarschuwingen bestaan precies zodat de agent weet in welke situatie het zich bevindt.

Waarom typografie vaak leeg is

Typografietokens vereisen Figma Variables met type FLOAT of STRING om betrouwbaar te worden geëxtraheerd. Tekststijlen bestaan in Figma als gedeelde stijlen, niet als Variables, en het API-oppervlak voor stijlen verschilt van de Variables-API.

figmascope v0.4 extraheert typografie wanneer Variables het dekken. Het probeert geen frequentiegebaseerde inferentie voor typografie omdat de nuttige typografietokens — lettertypefamilie, regelafstand, letterspatiëring, gewichtscombinaties — geen voor de hand liggende waarde-afgeleide namen hebben zoals spacing.16 dat doet. Een fontSize.14-sleutel is veel minder nuttig dan typography.body.small, en een slechte naam genereren is erger dan geen naam genereren.

Dus het resultaat is eerlijk: als je Figma-bestand typografie Variables heeft, krijg je typografietokens. Zo niet, dan krijg je een leeg object en wordt de agent via CONTEXT.md verteld dat de typografiedekking mogelijk gedeeltelijk is.

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

De agent ziet dit en weet conservatief te zijn met typografietokenreferenties. Het genereert terugvalcode met expliciete waarden en een TODO-opmerking in plaats van een tokennaam te verzinnen.

Hoe de agent tokens.json gebruikt

De CONTEXT.md-beperking is: "Codeer nooit dp-waarden hard als er een token bestaat binnen ±2dp." De ±2dp-tolerantie verwerkt afronden. Als een knooppunt paddingLeft: 15 heeft en spacing.16 bestaat, gebruikt de agent spacing.16. Als het dichtstbijzijnde token spacing.24 is, geen overeenkomst — de agent gebruikt de letterlijke waarde.

Voor kleuren is het matchen exact op de hexwaarde na normalisatie naar 6-cijferige kleine letters. #7F5CFE komt overeen met color.7f5cfe.

Voor hoekstraal, dezelfde ±2dp-regel als spatiëering.

De praktische uitvoer voor een Jetpack Compose-doel ziet er als volgt uit:

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

// Met inferred-from-frequency tokensSource (zelfde visuele uitvoer, zelfde tokenreferenties)
Surface(
    shape = RoundedCornerShape(Radius.radius8),
    color = Color.color7f5cfe
) { ... }

De waarde-afgeleide namen zijn minder leesbaar. Ze zijn nog steeds beter dan hardgecodeerde waarden.

Vergelijking met andere tokenextractiebenaderingen

Het native "Inspect"-paneel van Figma toont waarden per knooppunt. Er is geen geëxporteerd tokenbestand. Je zou er handmatig een moeten maken of een plugin zoals Tokens Studio gebruiken. Beide vereisen inspanning van de ontwerper en voortdurend onderhoud.

figmascope extraheert tokens automatisch bij elke export. Als het bestand verandert, exporteer je opnieuw en weerspiegelen de tokens de huidige staat. De afweging is dat zonder Variables de namen waarde-afgeleid zijn in plaats van semantisch — maar je krijgt elke keer een tokenbestand, zonder een plugin of extra workflowstap.

Tokens Studio (voorheen Style Dictionary-integratie) vereist dat de ontwerper de plugin instelt, een JSON-bestand in het Figma-bestand onderhoudt en het synchroniseert. Dat is de juiste oplossing voor een volwassen ontwerpsysteem. De aanpak van figmascope is de juiste oplossing voor bestanden die er nog niet zijn, wat de meeste bestanden zijn.

De tokenextractie is een best-effort snapshot van wat er in het bestand bestaat. Het is geen vervanging voor een token-eerst ontwerpsysteem. Het is de oplossing die je gebruikt terwijl je naar één toe bouwt.

tokens.json koppelen aan je codebase

De JSON-structuur is plat genoeg dat het genereren van een Kotlin-object of TypeScript-module ervan eenvoudig is. Een eenvoudig script:

// tokens.json → Kotlin object (vereenvoudigd)
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

Als je al een design-tokenpijplijn gebruikt, is het W3C-achtige formaat dicht genoeg om in Style Dictionary te laten vallen met een aangepaste transformator voor de $value/$type-sleutels.

De rest van hoe tokens interageren met de IR wordt behandeld in Per-scherm IR. Voor hoe tokens interageren met de bredere agentcontext, zie Anatomie van CONTEXT.md. Voor de end-to-end workflow voor design-tokenexport, zie Design Token Export. Om tokens uit je eigen Figma-bestand te exporteren, ga naar figmascope.dev.