AI Agents के लिए Design Token Export — Figma Variables से tokens.json तक

Design tokens designers और developers के बीच shared vocabulary हैं। ये Salesforce Lightning के ज़माने से विभिन्न रूपों में exist करते हैं — Style Dictionary, Theo, W3C Design Token Community Group spec draft। हाल ही में जो बदला है वो यह है कि अब ये आपके codebase और AI coding agents के बीच भी shared vocabulary हैं।

एक agent जो जानता है कि color.accent = #d96a3a वो उस value को use करेगा। एक agent जिसे screenshot मिलती है वो "warm orange" guess करेगा और कुछ close लेकिन गलत produce करेगा। यह अंतर दर्जनों components में बढ़ता जाता है।

figmascope हर context bundle के हिस्से के रूप में एक tokens.json export करता है। यह article format को detail में explain करता है, figmascope Figma से tokens कैसे source करता है, Figma Variables के बिना files के लिए frequency-inference fallback, और output को common frameworks में कैसे wire करें। यह देखने के लिए कि tokens पूरे export workflow में कैसे fit होते हैं, figmascope app देखें या Figma से Cursor और Figma से Claude Code पढ़ें।

tokens.json format

figmascope W3C Design Token Community Group-inspired format use करता है। हर token एक object है जिसमें $value और $type fields हैं, semantic category keys के नीचे nested:

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

W3C-ish क्यों, exact spec नहीं?

W3C Design Token Community Group spec अभी भी draft है। figmascope core conventions follow करता है ($value, $type, nested groups) लेकिन सभी edge cases implement नहीं करता जैसे composite types और alias resolution chains। Output Style Dictionary, direct JSON traversal, या एक language model — जो primary consumer है — द्वारा consume करने के लिए stable है।

Use में token types

$type	Category	$value format	उदाहरण
`color`	color	hex string	`"#d96a3a"`
`dimension`	spacing, radius	unit के साथ CSS string	`"16px"`
`fontFamily`	typography	font name string	`"Inter"`
`number`	typography	unitless number	`400`, `1.45`

Colors हमेशा hex strings के रूप में output होते हैं। अगर Figma source non-full opacity के साथ RGBA use करता है, तो alpha channel 8-digit hex में preserved होता है (#d96a3a80)।

figmascope tokens कैसे source करता है

figmascope two-tier sourcing strategy use करता है। Figma Variables preferred source हैं; frequency inference fallback है।

Tier 1: Figma Variables

अगर Figma file में Variables defined हैं (Figma का native token system, Professional और Organization plans पर available), तो figmascope इन्हें REST API के /v1/files/:key/variables/local endpoint के ज़रिए पढ़ता है। Variable names token keys के रूप में use होते हैं, kebab-case में sanitize किए जाते हैं। Modes को default mode पर collapse किया जाता है जब तक कि file में single mode न हो, ऐसे में उस mode के values directly use होते हैं।

Variable collections tokens.json में top-level category keys से map होती हैं। "Color" नाम की collection tokens.color.* produce करती है; "Spacing" tokens.spacing.* produce करती है। अगर आपकी Figma file non-standard collection names use करती है, तो figmascope variable के resolved type से category infer करने की कोशिश करता है।

Tier 2: Frequency inference

कई Figma files — खासकर पुरानी या उन clients की जिन्होंने Variables adopt नहीं की हैं — में कोई variable definitions नहीं होती। figmascope इसे पूरे node tree को walk करके और fill colors, spacing values, corner radii, और typography properties के frequency histograms बनाकर handle करता है।

एक frequency threshold से ऊपर appear होने वाले values candidate tokens बनते हैं। इन्हें उनकी category और एक sequential index से name किया जाता है (color.0, color.1...) जब तक कि value के use से एक human-readable name infer नहीं किया जा सके (जैसे, एक color जो multiple frames में सिर्फ backgrounds पर use होती है color.surface बन जाती है)।

_meta.json manifest tokensSource को या तो "variables" या "inferred" के रूप में record करता है, ताकि आपका agent prompt note कर सके जब inference use हुई:

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

Inferred tokens useful हैं लेकिन authoritative नहीं। इन्हें starting point मानें, design system specification नहीं।

Layout IR में token references

Per-screen IR files (screens/*.json) raw values embed करने के बजाय $ref strings use करके tokens को path से reference करती हैं। यह IR को compact रखता है और ensure करता है कि agent हमेशा single source of truth से values resolve करे:

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

इस node को process करने वाला agent parallel tokens.json file से color.accent को #d96a3a और spacing.2 को 8px resolve करता है। कोई ambiguity नहीं, values का कोई hallucination नहीं।

Full node schema documentation के लिए per-screen IR explained देखें।

Style Dictionary के साथ tokens.json use करना

figmascope का output minimal configuration के साथ Style Dictionary के साथ compatible है। चूंकि यह पहले से $value / $type convention use करता है, आप Style Dictionary को directly tokens.json की तरफ point कर सकते हैं:

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

style-dictionary build चलाने पर उसी source file से CSS custom properties और ES module exports produce होंगे जो agent use करता है।

Tailwind के साथ tokens.json use करना

एक छोटा script tokens.json को Tailwind theme extension में convert करता है। Common cases के लिए structure recursion के बिना traverse करने के लिए काफी flat है:

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

फिर tailwind.config.ts में:

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

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

Jetpack Compose के साथ tokens.json use करना

Android projects के लिए, token structure cleanly एक Kotlin object से map होती है। आप इसे programmatically generate कर सकते हैं या Claude Code से करवा सकते हैं। Color 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
  }
}

MaterialTheme integration सहित complete guide के लिए Jetpack Compose from Figma देखें।

tokens.json में क्या नहीं है

Scope limits जानने से सही expectations set होती हैं:

Shadows — figmascope currently drop-shadow या inner-shadow tokens export नहीं करता। Shadow values IR में nodes पर inline appear होते हैं जहां present हों।
Gradients — gradient fills IR में leaf nodes पर as-is export होते हैं, named tokens के रूप में नहीं।
Animation — timing, easing, और transition values out of scope हैं। Figma का animation support Prototype mode में है, जो figmascope नहीं पढ़ता।
Breakpoints — responsive constraints variable level पर Figma concept नहीं हैं; इनके लिए separate design decisions चाहिए।

_meta.json में warnings array किसी भी ऐसे value को note करेगी जो cleanly export नहीं हो सकी। Bundle को agent को देने से पहले इसे review करें।

Token names कैसे derive होते हैं

जब figmascope Figma Variables पढ़ता है, तो Figma में variable का name token key बन जाता है। Color नाम की collection में Colors/Surface/Primary नाम का variable tokens.json में tokens.color.surface.primary बनता है — path separator Figma में / है, JSON nested keys में .।

Figma spaces, uppercase letters, और special characters के साथ variable names allow करता है। figmascope इन्हें normalize करता है:

Spaces hyphens बन जाते हैं: Primary Surface → primary-surface
Uppercase lowercase हो जाता है: AccentOrange → accent-orange
Control characters और Unicode bidi marks sanitizeName से strip हो जाते हैं
Cyrillic और अन्य non-Latin scripts slug compatibility के लिए transliterate होते हैं

Transliteration step international teams के लिए matter करती है। एक Ukrainian design team जो Cyrillic variable names जैसे Фон (background) use करती है, output में एक stable ASCII key (fon) पाती है, जो encoding issues के बिना CSS class names और JSON में usable है। Original name $description field के रूप में preserved रहता है अगर Figma Variable metadata में present हो।

Codegen से पहले token coverage check करना

Bundle को agent को देने से पहले, यह verify करना worth है कि token coverage reasonable लगती है। एक quick Node script जो check करता है कि screen IRs में referenced सभी color values tokens.json में entries को resolve करती हैं या नहीं:

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

Zero missing refs का मतलब है agent layout IR में हर $ref को values बनाए बिना resolve कर सकेगा। अगर missing refs हैं, तो इसका आमतौर पर मतलब है कि Figma file bundle export होने के बाद change हुई — fresh export के लिए figmascope फिर चलाएं। Design iterations में token coverage maintain करने के अधिक tips के लिए figmascope blog भी check करें।