Design Token Export für KI-Agenten — Von Figma Variables zu tokens.json

Design tokens sind das gemeinsame Vokabular von Designern und Entwicklern. Es gibt sie in verschiedenen Formen seit der Salesforce-Lightning-Ära — Style Dictionary, Theo, der Spezifikationsentwurf der W3C Design Token Community Group. Was sich zuletzt verändert hat: Sie sind nun auch das gemeinsame Vokabular zwischen Ihrer Codebasis und KI-Coding-Agenten.

Ein Agent, der weiß, dass color.accent = #d96a3a ist, verwendet diesen Wert. Ein Agent, der einen Screenshot erhält, errät „warmes Orange" und produziert etwas Ähnliches, aber Falsches. Dieser Unterschied potenziert sich über Dutzende von Komponenten.

figmascope exportiert ein tokens.json als Teil jedes Context-Bundles. Dieser Artikel erläutert das Format im Detail, wie figmascope Tokens aus Figma bezieht, den Häufigkeitsinferenz-Fallback für Dateien ohne Figma Variables sowie die Anbindung der Ausgabe an gängige Frameworks. Den vollständigen Export-Workflow finden Sie in der figmascope-App oder unter Figma zu Cursor und Figma zu Claude Code.

Das tokens.json-Format

figmascope verwendet ein Format, das sich an der W3C Design Token Community Group orientiert. Jedes Token ist ein Objekt mit $value- und $type-Feldern, verschachtelt unter semantischen Kategorieschlüsseln:

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

Warum W3C-ähnlich und nicht die exakte Spezifikation?

Die W3C-Design-Token-Community-Group-Spezifikation ist noch ein Entwurf. figmascope folgt den Kernkonventionen ($value, $type, verschachtelte Gruppen), implementiert aber nicht alle Randfälle wie zusammengesetzte Typen und Alias-Auflösungsketten. Die Ausgabe ist stabil genug, um von Style Dictionary, direktem JSON-Traversal oder einem Sprachmodell konsumiert zu werden — dem primären Verbraucher.

Verwendete Token-Typen

$type	Kategorie	$value-Format	Beispiel
`color`	Farbe	Hex-String	`"#d96a3a"`
`dimension`	Abstände, Radius	CSS-String mit Einheit	`"16px"`
`fontFamily`	Typografie	Schriftname als String	`"Inter"`
`number`	Typografie	Zahl ohne Einheit	`400`, `1.45`

Farben werden immer als Hex-Strings ausgegeben. Verwendet die Figma-Quelle RGBA mit nicht-voller Deckkraft, wird der Alphakanal im 8-stelligen Hex erhalten (#d96a3a80).

Wie figmascope Tokens bezieht

figmascope verwendet eine zweistufige Bezugsstrategie. Figma Variables sind die bevorzugte Quelle; Häufigkeitsinferenz ist der Fallback.

Stufe 1: Figma Variables

Wenn die Figma-Datei Variables definiert hat (Figmas natives Token-System, verfügbar in Professional- und Organization-Plänen), liest figmascope diese über den REST-API-Endpunkt /v1/files/:key/variables/local. Variable-Namen werden als Token-Schlüssel verwendet und in Kebab-Case normalisiert. Modi werden auf den Standardmodus reduziert, es sei denn, die Datei hat nur einen Modus — dann werden dessen Werte direkt verwendet.

Variable-Kollektionen werden den Top-Level-Kategorieschlüsseln in tokens.json zugeordnet. Eine Kollektion namens „Color" ergibt tokens.color.*; „Spacing" ergibt tokens.spacing.*. Bei nicht-standardmäßigen Kollektionsnamen versucht figmascope, die Kategorie aus dem aufgelösten Typ der Variable zu inferieren.

Stufe 2: Häufigkeitsinferenz

Viele Figma-Dateien — insbesondere ältere oder Dateien von Kunden, die Variables noch nicht eingeführt haben — enthalten keine Variable-Definitionen. figmascope löst das, indem es den gesamten Knotenbaum durchläuft und Häufigkeitshistogramme für Füllfarben, Abstandswerte, Eckenradien und Typografieeigenschaften erstellt.

Werte, die einen Häufigkeitsschwellenwert überschreiten, werden zu Token-Kandidaten. Sie werden nach ihrer Kategorie und einem sequenziellen Index benannt (color.0, color.1 …), es sei denn, aus der Verwendungsweise lässt sich ein menschenlesbarer Name ableiten (z. B. wird eine Farbe, die über mehrere Frames hinweg ausschließlich für Hintergründe verwendet wird, zu color.surface).

Das Manifest _meta.json speichert tokensSource entweder als "variables" oder "inferred", damit Ihr Agent-Prompt vermerken kann, wann Inferenz verwendet wurde:

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

Inferierte Tokens sind nützlich, aber nicht autoritativ. Behandeln Sie sie als Ausgangspunkt, nicht als Design-System-Spezifikation.

Token-Referenzen in der Layout-IR

Die bildschirmweisen IR-Dateien (screens/*.json) referenzieren Tokens per Pfad über $ref-Strings, statt rohe Werte einzubetten. Das hält die IR kompakt und stellt sicher, dass der Agent Werte immer aus einer einzigen Quelle der Wahrheit auflöst:

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

Ein Agent, der diesen Knoten verarbeitet, löst color.accent zu #d96a3a und spacing.2 zu 8px aus der parallel vorliegenden tokens.json-Datei auf. Keine Mehrdeutigkeit, keine halluzinierten Werte.

Das vollständige Knotenschema finden Sie unter per-screen IR explained.

tokens.json mit Style Dictionary verwenden

figmascopes Ausgabe ist mit Style Dictionary mit minimaler Konfiguration kompatibel. Da es bereits die $value/$type-Konvention verwendet, können Sie Style Dictionary direkt auf tokens.json zeigen:

// 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' }]
    }
  }
};

Das Ausführen von style-dictionary build erzeugt CSS-Custom-Properties und ES-Modul-Exporte aus derselben Quelldatei, die der Agent verwendet.

tokens.json mit Tailwind verwenden

Ein kleines Skript konvertiert tokens.json in eine Tailwind-Theme-Extension. Die Struktur ist für die gängigen Fälle flach genug, um sie ohne Rekursion zu traversieren:

// 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

Dann in tailwind.config.ts:

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

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

tokens.json mit Jetpack Compose verwenden

Für Android-Projekte lässt sich die Token-Struktur sauber auf ein Kotlin-object abbilden. Sie können es programmatisch generieren oder Claude Code darum bitten. Für Farb-Tokens:

// 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
  }
}

Den vollständigen Leitfaden einschließlich MaterialTheme-Integration finden Sie unter Jetpack Compose from Figma.

Was tokens.json nicht enthält

Die Kenntnis der Umfangsgrenzen hilft, korrekte Erwartungen zu setzen:

Schatten — figmascope exportiert derzeit keine Drop-Shadow- oder Inner-Shadow-Tokens. Schattenwerte erscheinen inline auf Knoten in der IR, sofern vorhanden.
Verläufe — Verlaufsfüllungen werden als solche auf Blattknoten in der IR exportiert, nicht als benannte Tokens.
Animationen — Timing, Easing und Übergangswerte liegen außerhalb des Umfangs. Figmas Animationsunterstützung befindet sich im Prototyping-Modus, den figmascope nicht liest.
Breakpoints — Responsive Constraints sind kein Figma-Konzept auf Variable-Ebene; sie erfordern separate Designentscheidungen.

Das Array warnings in _meta.json vermerkt alle Werte, die nicht sauber exportiert werden konnten. Prüfen Sie es, bevor Sie das Bundle an einen Agenten übergeben.

Wie Token-Namen abgeleitet werden

Wenn figmascope Figma Variables liest, wird der Variable-Name in Figma zum Token-Schlüssel. Eine Variable namens Colors/Surface/Primary in einer Kollektion namens Color wird zu tokens.color.surface.primary in tokens.json — der Pfadtrenner ist / in Figma und . bei verschachtelten JSON-Schlüsseln.

Figma erlaubt Variable-Namen mit Leerzeichen, Großbuchstaben und Sonderzeichen. figmascope normalisiert diese:

Leerzeichen werden zu Bindestrichen: Primary Surface → primary-surface
Großschreibung wird in Kleinschreibung umgewandelt: AccentOrange → accent-orange
Steuerzeichen und Unicode-Bidi-Markierungen werden über sanitizeName entfernt
Kyrillische und andere nicht-lateinische Schriften werden für Slug-Kompatibilität transliteriert

Der Transliterationsschritt ist für internationale Teams relevant. Ein ukrainisches Design-Team, das kyrillische Variable-Namen wie Фон (Hintergrund) verwendet, erhält in der Ausgabe einen stabilen ASCII-Schlüssel (fon), der in CSS-Klassennamen und JSON ohne Codierungsprobleme verwendbar ist. Der Originalname wird als $description-Feld erhalten, sofern er in den Figma-Variable-Metadaten vorhanden ist.

Token-Abdeckung vor der Codegenerierung prüfen

Bevor Sie das Bundle an einen Agenten übergeben, lohnt es sich zu überprüfen, ob die Token-Abdeckung plausibel ist. Ein kurzes Node-Skript, das prüft, ob alle in den Screen-IRs referenzierten Farbwerte in tokens.json aufgelöst werden können:

// 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.`);

Null fehlende Referenzen bedeutet, dass der Agent jeden $ref in der Layout-IR auflösen kann, ohne Werte zu erfinden. Gibt es fehlende Referenzen, hat sich die Figma-Datei nach dem Bundle-Export geändert — führen Sie figmascope erneut aus, um einen aktuellen Export zu erhalten. Im figmascope-Blog finden Sie weitere Tipps zur Pflege der Token-Abdeckung über Design-Iterationen hinweg.