Designtokens är det delade vokabuläret mellan designers och utvecklare. De har existerat i olika former sedan Salesforce Lightning-eran — Style Dictionary, Theo, W3C Design Token Community Group-specifikationsutkastet. Det som har förändrats nyligen är att de nu också är det delade vokabuläret mellan din kodbas och AI-kodningsagenter.

En agent som vet att color.accent = #d96a3a kommer att använda det värdet. En agent som får en skärmdump gissar "varm orange" och producerar något nära men fel. Skillnaden multipliceras över dussintals komponenter.

figmascope exporterar en tokens.json som en del av varje kontextpaket. Den här artikeln förklarar formatet i detalj, hur figmascope hämtar tokens från Figma, frekvensinfererande reserven för filer utan Figma Variables, och hur man kopplar utdata till vanliga ramverk. För att se hur tokens passar in i det fullständiga exportarbetsflödet, besök figmascope-appen eller läs Figma till Cursor och Figma till Claude Code.

Formatet tokens.json

figmascope använder ett W3C Design Token Community Group-inspirerat format. Varje token är ett objekt med $value- och $type-fält, nästlade under semantiska kategorinycklar:

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

Varför W3C-liknande och inte exakt specen?

W3C Design Token Community Group-specen är fortfarande ett utkast. figmascope följer kärnkonventionerna ($value, $type, nästlade grupper) men implementerar inte alla kantfall som sammansatta typer och aliasupplösningskedjor. Utdata är tillräckligt stabil för att konsumeras av Style Dictionary, direkt JSON-traversal, eller en språkmodell — vilket är den primära konsumenten.

Tokentyper i användning

$type Kategori $value-format Exempel
color färg hex-sträng "#d96a3a"
dimension avstånd, radie CSS-sträng med enhet "16px"
fontFamily typografi teckensnittsnamnssträng "Inter"
number typografi enhetslöst tal 400, 1.45

Färger matas alltid ut som hex-strängar. Om Figma-källan använder RGBA med icke-full opacitet bevaras alfakanalen i 8-siffrig hex (#d96a3a80).

Hur figmascope hämtar tokens

figmascope använder en tvånivåstrategi för hämtning. Figma Variables är den föredragna källan; frekvensinfererande är reserven.

Nivå 1: Figma Variables

Om Figma-filen har Variables definierade (Figmas inbyggda tokensystem, tillgängligt på Professional- och Organization-planer), läser figmascope dem via REST API:ets /v1/files/:key/variables/local-endpoint. Variabelnamn används som tokennycklar, sanerade till kebab-case. Lägen kollapsas till standardläget om inte filen har ett enda läge, i vilket fall det lägets värden används direkt.

Variabelsamlingar mappas till toppnivåkategorinycklarna i tokens.json. En samling kallad "Color" producerar tokens.color.*; "Spacing" producerar tokens.spacing.*. Om din Figma-fil använder icke-standardsamlingsnamn försöker figmascope inferera kategorin från variabelns upplösta typ.

Nivå 2: Frekvensinfererande

Många Figma-filer — särskilt äldre eller filer från kunder som inte har anammat Variables — har inga variabledefinitioner. figmascope hanterar detta genom att gå igenom hela nodträdet och bygga frekvenshistogram av fyllnadsfärger, avståndsvärden, hörnradier och typografiinställningar.

Värden som förekommer över ett frekvenströskel blir kandidattokens. De namnges av sin kategori och ett sekventiellt index (color.0, color.1...) om inte ett mänskligt läsbart namn kan infereras från hur värdet används (t.ex. en färg som bara används på bakgrunder över flera ramar blir color.surface).

Manifestet _meta.json registrerar tokensSource som antingen "variables" eller "inferred", så din agentprompt kan notera när infererande användes:

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

Infererande tokens är användbara men inte auktoritativa. Behandla dem som en startpunkt, inte en designsystemspecifikation.

Tokenreferenser i layout-IR

Per-skärm-IR-filerna (screens/*.json) refererar tokens via sökväg med hjälp av $ref-strängar snarare än att bädda in råvärden. Detta håller IR:en kompakt och säkerställer att agenten alltid löser upp värden från en enda sanningskälla:

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

En agent som bearbetar denna nod löser upp color.accent till #d96a3a och spacing.2 till 8px från den parallella tokens.json-filen. Ingen tvetydighet, ingen hallucination av värden.

Se per-skärm-IR förklarad för fullständig nodschema-dokumentation.

Använda tokens.json med Style Dictionary

figmascopes utdata är kompatibel med Style Dictionary med minimal konfiguration. Eftersom den redan använder $value/$type-konventionen kan du peka Style Dictionary direkt på tokens.json:

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

Att köra style-dictionary build producerar CSS-anpassade egenskaper och ES-modulexporter från samma källfil som agenten använder.

Använda tokens.json med Tailwind

Ett litet skript konverterar tokens.json till ett Tailwind-temaförlängningsblock. Strukturen är tillräckligt platt för att traversera utan rekursion för vanliga fall:

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

Sedan i tailwind.config.ts:

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

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

Använda tokens.json med Jetpack Compose

För Android-projekt mappas tokenstrukturen rent till ett Kotlin object. Du kan generera det programmatiskt eller be Claude Code att göra det. För färgtokens:

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

Se Jetpack Compose från Figma för en komplett guide inklusive MaterialTheme-integration.

Vad tokens.json inte innehåller

Att känna till omfångsbegränsningarna hjälper att sätta korrekta förväntningar:

Arrayen warnings i _meta.json noterar värden som inte kunde exporteras rent. Granska den innan du lämnar över paketet till en agent.

Hur tokennamn härleds

När figmascope läser Figma Variables blir variabelns namn i Figma tokennyckeln. En variabel med namnet Colors/Surface/Primary i en samling kallad Color blir tokens.color.surface.primary i tokens.json — sökvägsseparatorn är / i Figma, . i JSON-nästlade nycklar.

Figma tillåter variabelnamn med mellanslag, versaler och specialtecken. figmascope normaliserar dessa:

Translittereringssteget spelar roll för internationella team. Ett ukrainskt designteam som använder kyrilliska variabelnamn som Фон (bakgrund) får en stabil ASCII-nyckel (fon) i utdata, som kan användas i CSS-klassnamn och JSON utan kodningsproblem. Det ursprungliga namnet bevaras som ett $description-fält om det finns i Figma Variable-metadata.

Kontrollera tokentäckning innan kodgenerering

Innan paketet överlämnas till en agent är det värt att verifiera att tokentäckningen ser rimlig ut. Ett snabbt Node-skript som kontrollerar om alla färgvärden som refereras i skärm-IR:erna löser upp till poster i 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.`);

Noll saknade refs innebär att agenten kan lösa upp varje $ref i layout-IR utan att hitta på värden. Om det finns saknade refs betyder det vanligtvis att Figma-filen ändrades efter att paketet exporterades — kör figmascope igen för en ny export. Du kan också besöka figmascope-bloggen för fler tips om att upprätthålla tokentäckning över designiterationer.