Design Token Export voor AI Agents — Van Figma Variables naar tokens.json

Designtokens zijn het gedeelde vocabulaire tussen ontwerpers en ontwikkelaars. Ze bestaan al in verschillende vormen sinds het Salesforce Lightning-tijdperk — Style Dictionary, Theo, het W3C Design Token Community Group-conceptspecificatie. Wat recentelijk is veranderd, is dat ze nu ook het gedeelde vocabulaire zijn tussen uw codebasis en AI-coderingsagents.

Een agent die weet dat color.accent = #d96a3a zal die waarde gebruiken. Een agent die een screenshot krijgt zal "warm oranje" raden en iets dichtbij maar fout produceren. Het verschil compoundeert over tientallen componenten.

figmascope exporteert een tokens.json als onderdeel van elke contextbundel. Dit artikel legt het formaat in detail uit, hoe figmascope tokens bronnen uit Figma, de frequentie-inferentie fallback voor bestanden zonder Figma Variables, en hoe de uitvoer te integreren in veelgebruikte frameworks. Zie de uitleg van hoe tokens passen in de volledige exportworkflow op de figmascope app of lees Figma naar Cursor en Figma naar Claude Code.

Het tokens.json-formaat

figmascope gebruikt een W3C Design Token Community Group-geïnspireerd formaat. Elk token is een object met $value- en $type-velden, genest onder semantische categoriesleutels:

{
  "color": {
    "surface":      { "$value": "#f6f2ea", "$type": "color" },
    "surface-2":    { "$value": "#efe9dc", "$type": "color" },
    "ink":          { "$value": "#1f1d1a", "$type": "color" },
    "ink-muted":    { "$value": "#4a4641", "$type": "color" },
    "accent":       { "$value": "#d96a3a", "$type": "color" },
    "accent-soft":  { "$value": "#f2c7a8", "$type": "color" },
    "good":         { "$value": "#6a8f5a", "$type": "color" },
    "warn":         { "$value": "#c89a3a", "$type": "color" },
    "bad":          { "$value": "#b8553a", "$type": "color" }
  },
  "spacing": {
    "1":  { "$value": "4px",   "$type": "dimension" },
    "2":  { "$value": "8px",   "$type": "dimension" },
    "3":  { "$value": "12px",  "$type": "dimension" },
    "4":  { "$value": "16px",  "$type": "dimension" },
    "6":  { "$value": "24px",  "$type": "dimension" },
    "8":  { "$value": "32px",  "$type": "dimension" },
    "12": { "$value": "48px",  "$type": "dimension" },
    "16": { "$value": "64px",  "$type": "dimension" }
  },
  "radius": {
    "sm":   { "$value": "4px",  "$type": "dimension" },
    "md":   { "$value": "8px",  "$type": "dimension" },
    "lg":   { "$value": "16px", "$type": "dimension" },
    "full": { "$value": "9999px", "$type": "dimension" }
  },
  "typography": {
    "body": {
      "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
      "fontSize":   { "$value": "14px",   "$type": "dimension" },
      "fontWeight": { "$value": 400,       "$type": "number" },
      "lineHeight": { "$value": 1.45,     "$type": "number" }
    },
    "heading": {
      "sm": {
        "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
        "fontSize":   { "$value": "18px",   "$type": "dimension" },
        "fontWeight": { "$value": 600,       "$type": "number" },
        "lineHeight": { "$value": 1.25,     "$type": "number" }
      }
    },
    "mono": {
      "fontFamily": { "$value": "JetBrains Mono", "$type": "fontFamily" },
      "fontSize":   { "$value": "13px",   "$type": "dimension" },
      "fontWeight": { "$value": 400,       "$type": "number" }
    }
  }
}

Waarom W3C-achtig en niet precies de specificatie?

De W3C Design Token Community Group-specificatie is nog steeds een concept. figmascope volgt de kernconventies ($value, $type, geneste groepen) maar implementeert niet alle randgevallen zoals samengestelde typen en aliasresolutieketens. De uitvoer is stabiel genoeg om te worden gebruikt door Style Dictionary, directe JSON-doorloop, of een taalmodel — wat de primaire gebruiker is.

Tokentypen in gebruik

$type	Categorie	$value-formaat	Voorbeeld
`color`	kleur	hex-tekenreeks	`"#d96a3a"`
`dimension`	spatiëring, radius	CSS-tekenreeks met eenheid	`"16px"`
`fontFamily`	typografie	lettertypenaam-tekenreeks	`"Inter"`
`number`	typografie	getal zonder eenheid	`400`, `1.45`

Kleuren worden altijd uitgevoerd als hex-tekenreeksen. Als de Figma-bron RGBA gebruikt met niet-volledige dekking, wordt het alfakanaal bewaard in 8-cijferige hex (#d96a3a80).

Hoe figmascope tokens bronnen

figmascope gebruikt een tweelagige bronsstrategie. Figma Variables zijn de voorkeursbron; frequentie-inferentie is de fallback.

Laag 1: Figma Variables

Als het Figma-bestand Variables heeft gedefinieerd (Figma's eigen tokensysteem, beschikbaar op Professional- en Organization-abonnementen), leest figmascope ze via het /v1/files/:key/variables/local-eindpunt van de REST API. Variabelenamen worden gebruikt als tokensleutels, gesaniteerd naar kebab-case. Modi worden samengevouwen naar de standaardmodus, tenzij het bestand één modus heeft, in welk geval de waarden van die modus direct worden gebruikt.

Variabelecollecties worden toegewezen aan de sleutels van de hoogste categorie in tokens.json. Een collectie met de naam "Color" produceert tokens.color.*; "Spacing" produceert tokens.spacing.*. Als uw Figma-bestand niet-standaard collectienamen gebruikt, probeert figmascope de categorie af te leiden van het opgeloste type van de variabele.

Laag 2: Frequentie-inferentie

Veel Figma-bestanden — met name oudere bestanden of bestanden van klanten die Variables nog niet hebben geadopteerd — hebben geen variabledefinities. figmascope verwerkt dit door de volledige knooppuntenboom te doorlopen en frequentiehistogrammen te bouwen van vulkleuren, spatiëringswaarden, hoekradii en typografie-eigenschappen.

Waarden die boven een frequentiedrempel verschijnen worden kandidaat-tokens. Ze worden benoemd op basis van hun categorie en een opeenvolgend index (color.0, color.1...) tenzij een voor mensen leesbare naam kan worden afgeleid van hoe de waarde wordt gebruikt (bijv. een kleur die alleen op achtergronden wordt gebruikt over meerdere frames wordt color.surface).

Het _meta.json-manifest registreert tokensSource als ofwel "variables" of "inferred", zodat uw agentprompt kan noteren wanneer inferentie werd gebruikt:

// _meta.json — inferred fallback
{
  "tokensSource": "inferred",
  "warnings": [
    {
      "code": "tokens-inferred",
      "message": "No Figma Variables found. Tokens were inferred from usage frequency."
    }
  ]
}

Afgeleide tokens zijn nuttig maar niet gezaghebbend. Behandel ze als een startpunt, niet als een designsysteemspecificatie.

Tokenreferenties in de indelings-IR

De per-scherm IR-bestanden (screens/*.json) verwijzen naar tokens per pad met $ref-tekenreeksen in plaats van ruwe waarden in te sluiten. Dit houdt de IR compact en zorgt ervoor dat de agent altijd waarden oplost vanuit één enkele bron van waarheid:

{
  "kind": "stack",
  "name": "PrimaryButton",
  "direction": "horizontal",
  "gap": { "$ref": "spacing.2" },
  "padding": {
    "top": 10, "right": 16, "bottom": 10, "left": 16
  },
  "background": { "$ref": "color.accent" },
  "radius": { "$ref": "radius.sm" },
  "children": [
    {
      "kind": "leaf",
      "name": "ButtonLabel",
      "type": "text",
      "style": { "$ref": "typography.body" },
      "color": { "$ref": "color.surface" }
    }
  ]
}

Een agent die dit knooppunt verwerkt lost color.accent op naar #d96a3a en spacing.2 naar 8px uit het parallelle tokens.json-bestand. Geen dubbelzinnigheid, geen hallucinatie van waarden.

Zie per-scherm IR uitgelegd voor de volledige knooppuntschema-documentatie.

tokens.json gebruiken met Style Dictionary

De uitvoer van figmascope is compatibel met Style Dictionary met minimale configuratie. Omdat het al de $value/$type-conventie gebruikt, kunt u Style Dictionary rechtstreeks naar tokens.json wijzen:

// style-dictionary.config.js
module.exports = {
  source: ['design/tokens.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      prefix: 'fs',
      buildPath: 'src/styles/',
      files: [{ destination: 'tokens.css', format: 'css/variables' }]
    },
    js: {
      transformGroup: 'js',
      buildPath: 'src/',
      files: [{ destination: 'tokens.js', format: 'javascript/es6' }]
    }
  }
};

Het uitvoeren van style-dictionary build produceert CSS-aangepaste eigenschappen en ES-module-exports vanuit hetzelfde bronbestand dat de agent gebruikt.

tokens.json gebruiken met Tailwind

Een klein script converteert tokens.json naar een Tailwind-thema-extensie. De structuur is plat genoeg om zonder recursie te doorlopen voor de gewone gevallen:

// scripts/tokens-to-tailwind.js
const fs = require('fs');
const tokens = JSON.parse(fs.readFileSync('design/tokens.json', 'utf8'));

function flattenGroup(group) {
  return Object.fromEntries(
    Object.entries(group).map(([k, v]) => [k, v.$value])
  );
}

const extend = {
  colors:      flattenGroup(tokens.color),
  spacing:     flattenGroup(tokens.spacing),
  borderRadius: flattenGroup(tokens.radius),
};

console.log(JSON.stringify(extend, null, 2));

node scripts/tokens-to-tailwind.js > design/tailwind-extend.json

Dan in tailwind.config.ts:

import extend from './design/tailwind-extend.json';

export default {
  content: ['./src/**/*.{ts,tsx}'],
  theme: { extend },
};

tokens.json gebruiken met Jetpack Compose

Voor Android-projecten wordt de tokenstructuur eenvoudig toegewezen aan een Kotlin-object. U kunt het programmatisch genereren of Claude Code vragen dat te doen. Voor kleurenstokens:

// Generated from design/tokens.json
object DesignTokens {
  object Color {
    val surface    = Color(0xFFF6F2EA)
    val ink        = Color(0xFF1F1D1A)
    val accent     = Color(0xFFD96A3A)
    val accentSoft = Color(0xFFF2C7A8)
  }
  object Spacing {
    val s1 = 4.dp
    val s2 = 8.dp
    val s4 = 16.dp
    val s8 = 32.dp
  }
}

Zie Jetpack Compose vanuit Figma voor een complete gids inclusief MaterialTheme-integratie.

Wat tokens.json niet bevat

Het kennen van de bereikgrenzen helpt juiste verwachtingen in te stellen:

Schaduwen — figmascope exporteert momenteel geen slagschaduw- of binnenste-schaduw-tokens. Schaduwwaarden verschijnen inline op knooppunten in de IR waar aanwezig.
Verlopen — verloopvullingen worden geëxporteerd zoals ze zijn op bladknooppunten in de IR, niet als benoemde tokens.
Animatie — timing, vereenvoudiging en overgangswaarden vallen buiten het bereik. Figma's animatieondersteuning zit in de Prototype-modus, die figmascope niet leest.
Breekpunten — responsieve beperkingen zijn geen Figma-concept op variabeleniveau; ze vereisen afzonderlijke ontwerp beslissingen.

De warnings-array in _meta.json zal alle waarden noteren die niet schoon konden worden geëxporteerd. Bekijk het voordat u de bundel aan een agent overhandigt.

Hoe tokennamen worden afgeleid

Wanneer figmascope Figma Variables leest, wordt de naam van de variabele in Figma de tokensleutel. Een variabele genaamd Colors/Surface/Primary in een collectie genaamd Color wordt tokens.color.surface.primary in tokens.json — het padscheidingsteken is / in Figma, . in geneste JSON-sleutels.

Figma staat variabelenamen toe met spaties, hoofdletters en speciale tekens. figmascope normaliseert deze:

Spaties worden koppeltekens: Primary Surface → primary-surface
Hoofdletters worden kleine letters: AccentOrange → accent-orange
Besturingstekenreeksen en Unicode-bidi-markeringen worden verwijderd via sanitizeName
Cyrillisch en andere niet-Latijnse scripts worden getranslitereerd voor slug-compatibiliteit

De transliteratiestap is belangrijk voor internationale teams. Een Oekraïens designteam dat Cyrillische variabelenamen gebruikt zoals Фон (achtergrond) krijgt een stabiele ASCII-sleutel (fon) in de uitvoer, die bruikbaar is in CSS-klassenamen en JSON zonder coderingsproblemen. De oorspronkelijke naam wordt bewaard als een $description-veld indien aanwezig in de Figma Variable-metadata.

Tokendekking controleren vóór codegen

Voordat u de bundel aan een agent overhandigt, is het de moeite waard om te verifiëren dat de tokendekking redelijk lijkt. Een snel Node-script dat controleert of alle kleurwaarden waarnaar wordt verwezen in de scherm-IR's worden opgelost naar vermeldingen in tokens.json:

// scripts/check-token-coverage.js
const fs = require('fs');
const glob = require('glob');

const tokens = JSON.parse(fs.readFileSync('design/tokens.json', 'utf8'));
const screenFiles = glob.sync('design/screens/*.json');

function getRef(obj) {
  const refs = [];
  if (obj && typeof obj === 'object') {
    if (obj.$ref) refs.push(obj.$ref);
    for (const v of Object.values(obj)) refs.push(...getRef(v));
  }
  return refs;
}

function resolveRef(ref, tokens) {
  return ref.split('.').reduce((o, k) => o?.[k], tokens);
}

let missing = 0;
for (const file of screenFiles) {
  const screen = JSON.parse(fs.readFileSync(file, 'utf8'));
  for (const ref of getRef(screen)) {
    if (!resolveRef(ref, tokens)) {
      console.error(`Missing token: ${ref} (in ${file})`);
      missing++;
    }
  }
}
if (missing === 0) console.log('All token refs resolve.');
else console.error(`${missing} unresolved token refs.`);

Nul ontbrekende refs betekent dat de agent elke $ref in de indelings-IR kan oplossen zonder waarden te verzinnen. Als er ontbrekende refs zijn, betekent dit meestal dat het Figma-bestand is gewijzigd nadat de bundel werd geëxporteerd — voer figmascope opnieuw uit voor een verse export. U kunt ook de figmascope blog raadplegen voor meer tips over het handhaven van tokendekking over designiteraties.