figma-code-agent 1.0.0

package/knowledge/figma-api-variables.md

@@ -0,0 +1,848 @@
+# Figma Variables API Reference
+
+## Purpose
+
+Authoritative reference for the Figma Variables REST API covering access requirements, endpoints, the variable data model (Variable, VariableCollection, modes, scopes), variable resolution mechanics, multi-mode theming patterns, and practical token extraction strategies. This is the design tokens foundation that all token-related modules depend on.
+
+## When to Use
+
+Reference this module when you need to:
+
+- Extract design tokens from Figma files via the Variables API
+- Understand variable collections, modes, and the `valuesByMode` structure
+- Resolve variable aliases and bound variables on nodes
+- Implement multi-mode theming (light/dark, brand variants)
+- Build token dictionaries from Figma Variables for CSS/Tailwind/platform export
+- Determine access requirements for Variables API endpoints
+
+---
+
+## Content
+
+### Access Requirements
+
+The Variables REST API is restricted to **full members of Enterprise organizations**. Guests and members of non-Enterprise plans cannot access these endpoints.
+
+| Requirement | Details |
+|------------|---------|
+| **Figma plan** | Enterprise |
+| **Seat type** | Full member (not guest) |
+| **Read scope** | `file_variables:read` |
+| **Write scope** | `file_variables:write` |
+| **Read permission** | View access to the file |
+| **Write permission** | Edit access to the file |
+
+> **Important:** If your organization is not on an Enterprise plan, you must extract tokens by traversing the file tree and reading style properties from nodes. See `figma-api-rest.md` for file traversal patterns.
+
+---
+
+### Endpoints
+
+#### GET /v1/files/:file_key/variables/local
+
+Retrieves all local variables and collections created in the file, plus any remote variables consumed by the file.
+
+**Scope required:** `file_variables:read`
+**Rate limit tier:** Tier 2
+
+```bash
+curl -H "X-Figma-Token: YOUR_FIGMA_TOKEN" \
+  "https://api.figma.com/v1/files/FILE_KEY/variables/local"
+```
+
+**Response shape:**
+
+```ts
+interface GetLocalVariablesResponse {
+  status: number;
+  error: boolean;
+  meta: {
+    variables: Record<string, Variable>;
+    variableCollections: Record<string, VariableCollection>;
+  };
+}
+```
+
+This endpoint returns:
+- All variables defined locally in the file
+- All remote (external library) variables that are referenced/used in the file
+- All variable collections (local and remote)
+
+Use the `remote` boolean field on each variable/collection to distinguish local from external.
+
+#### GET /v1/files/:file_key/variables/published
+
+Retrieves variables that have been published from the specified file (for library consumers).
+
+**Scope required:** `file_variables:read`
+**Rate limit tier:** Tier 2
+
+```bash
+curl -H "X-Figma-Token: YOUR_FIGMA_TOKEN" \
+  "https://api.figma.com/v1/files/FILE_KEY/variables/published"
+```
+
+**Key differences from `/local`:**
+
+- Returns only published variables (not local-only or unpublished)
+- Each variable and collection includes a `subscribed_id` field for consumer tracking
+- Mode details are omitted from the response
+
+Use this endpoint when building tooling for library consumers who need to reference published tokens.
+
+#### POST /v1/files/:file_key/variables
+
+Bulk create, update, and delete variables, collections, and modes.
+
+**Scope required:** `file_variables:write`
+**Rate limit tier:** Tier 3
+
+```bash
+curl -X POST \
+  -H "X-Figma-Token: YOUR_FIGMA_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{ "variableCollections": [...], "variables": [...] }' \
+  "https://api.figma.com/v1/files/FILE_KEY/variables"
+```
+
+**Request body arrays (processed in order):**
+
+| Array | Purpose |
+|-------|---------|
+| `variableCollections` | Create, update, or delete collections |
+| `variableModes` | Create, update, or delete modes |
+| `variables` | Create, update, or delete variables |
+| `variableModeValues` | Set variable values per mode |
+
+**Constraints:**
+
+| Constraint | Limit |
+|-----------|-------|
+| Max modes per collection | 40 |
+| Max variables per collection | 5,000 |
+| Max request payload | 4 MB |
+| Mode name length | 40 characters |
+| Variable name restrictions | Cannot contain `.`, `{`, `}` |
+| Variable name uniqueness | Must be unique within collection |
+
+**Atomicity:** All changes in a single POST request succeed or fail together. Partial application does not occur.
+
+**Temporary IDs:** When creating new objects, you can use temporary IDs (prefixed with any string) to reference objects created in the same request. For example, create a collection and immediately add variables to it.
+
+> **Important:** Variables created or updated via the REST API must be **published** before they become accessible in other files. The API does not auto-publish.
+
+---
+
+### Variable Data Model
+
+#### Variable
+
+A single design token that defines values for each mode in its parent collection.
+
+```ts
+interface Variable {
+  /** Unique identifier within the file */
+  id: string;
+
+  /** Variable name (e.g., "primary/500", "spacing/md") */
+  name: string;
+
+  /** Stable key for cross-file references */
+  key: string;
+
+  /** Parent collection ID */
+  variableCollectionId: string;
+
+  /** Resolved type of this variable's values */
+  resolvedType: 'BOOLEAN' | 'FLOAT' | 'STRING' | 'COLOR';
+
+  /** Values indexed by mode ID */
+  valuesByMode: Record<string, VariableValue>;
+
+  /** Whether this variable comes from an external library */
+  remote: boolean;
+
+  /** Human-readable description */
+  description: string;
+
+  /** If true, excluded from library publishing */
+  hiddenFromPublishing: boolean;
+
+  /** Controls which UI pickers show this variable */
+  scopes: VariableScope[];
+
+  /** Platform-specific code syntax for Dev Mode */
+  codeSyntax: VariableCodeSyntax;
+
+  /**
+   * True if the variable was deleted but is still referenced
+   * by other variables or nodes in the file
+   */
+  deletedButReferenced?: boolean;
+}
+```
+
+#### VariableCollection
+
+A grouping of related variables that share the same set of modes.
+
+```ts
+interface VariableCollection {
+  /** Unique identifier within the file */
+  id: string;
+
+  /** Collection name (e.g., "Colors", "Spacing", "Typography") */
+  name: string;
+
+  /** Stable key for cross-file references */
+  key: string;
+
+  /** Modes defined in this collection: { modeId: modeName } */
+  modes: Record<string, string>;
+
+  /** The default mode ID (used when no explicit mode is set) */
+  defaultModeId: string;
+
+  /** Whether this collection comes from an external library */
+  remote: boolean;
+
+  /** If true, excluded from library publishing */
+  hiddenFromPublishing: boolean;
+
+  /** Ordered list of variable IDs in this collection */
+  variableIds: string[];
+
+  /** Whether this is an extended (inherited) collection */
+  isExtension?: boolean;
+
+  /** Parent collection ID (for extended collections) */
+  parentVariableCollectionId?: string;
+
+  /** Root collection ID in the extension chain */
+  rootVariableCollectionId?: string;
+
+  /** Variable IDs inherited from parent (extended collections) */
+  inheritedVariableIds?: string[];
+
+  /** Variable IDs created locally (extended collections) */
+  localVariableIds?: string[];
+
+  /** Override values for inherited variables */
+  variableOverrides?: Record<string, any>;
+}
+```
+
+#### VariableValue
+
+A variable's value for a given mode is either a direct value or an alias to another variable.
+
+```ts
+/** Direct values based on resolvedType */
+type VariableValue =
+  | boolean              // BOOLEAN
+  | number               // FLOAT
+  | string               // STRING
+  | RGBA                 // COLOR
+  | VariableAlias;       // Reference to another variable
+
+interface RGBA {
+  r: number;  // 0-1
+  g: number;  // 0-1
+  b: number;  // 0-1
+  a: number;  // 0-1
+}
+
+interface VariableAlias {
+  type: 'VARIABLE_ALIAS';
+  id: string;  // The referenced variable's ID
+}
+```
+
+> **Note:** Color values use 0-1 range, NOT 0-255. Multiply by 255 and round when converting to hex/rgb CSS values.
+
+#### VariableScope
+
+Scopes control which property pickers in the Figma UI show the variable. Scopes do NOT prevent programmatic binding via the API or plugin code.
+
+```ts
+type VariableScope =
+  | 'ALL_SCOPES'          // Shown in all pickers (if set, no other scopes allowed)
+  | 'TEXT_CONTENT'         // String variables: text content
+  | 'CORNER_RADIUS'       // Float variables: border radius
+  | 'WIDTH_HEIGHT'         // Float variables: width/height
+  | 'GAP'                 // Float variables: auto layout gap/spacing
+  | 'ALL_FILLS'           // Color variables: all fill types
+  | 'FRAME_FILL'          // Color variables: frame fills only
+  | 'SHAPE_FILL'          // Color variables: shape fills only
+  | 'TEXT_FILL'           // Color variables: text fills only
+  | 'STROKE_COLOR'        // Color variables: stroke colors
+  | 'EFFECT_COLOR'        // Color variables: effect colors (shadows, etc.)
+  | 'STROKE_FLOAT'        // Float variables: stroke width
+  | 'EFFECT_FLOAT'        // Float variables: effect values (blur, spread)
+  | 'OPACITY'             // Float variables: opacity
+  | 'FONT_FAMILY'         // String variables: font family
+  | 'FONT_STYLE'          // String variables: font style
+  | 'FONT_WEIGHT'         // Float variables: font weight
+  | 'FONT_SIZE'           // Float variables: font size
+  | 'LINE_HEIGHT'         // Float variables: line height
+  | 'LETTER_SPACING'      // Float variables: letter spacing
+  | 'PARAGRAPH_SPACING'   // Float variables: paragraph spacing
+  | 'PARAGRAPH_INDENT'    // Float variables: paragraph indent
+  ;
+```
+
+**Scope validity by resolvedType:**
+
+| resolvedType | Valid Scopes |
+|-------------|-------------|
+| `BOOLEAN` | `ALL_SCOPES` |
+| `FLOAT` | `ALL_SCOPES`, `TEXT_CONTENT`, `CORNER_RADIUS`, `WIDTH_HEIGHT`, `GAP`, `OPACITY`, `STROKE_FLOAT`, `EFFECT_FLOAT`, `FONT_WEIGHT`, `FONT_SIZE`, `LINE_HEIGHT`, `LETTER_SPACING`, `PARAGRAPH_SPACING`, `PARAGRAPH_INDENT` |
+| `STRING` | `ALL_SCOPES`, `TEXT_CONTENT`, `FONT_FAMILY`, `FONT_STYLE` |
+| `COLOR` | `ALL_SCOPES`, `ALL_FILLS`, `FRAME_FILL`, `SHAPE_FILL`, `TEXT_FILL`, `STROKE_COLOR`, `EFFECT_COLOR` |
+
+#### VariableCodeSyntax
+
+Platform-specific code representations displayed in Dev Mode.
+
+```ts
+interface VariableCodeSyntax {
+  WEB?: string;      // e.g., "var(--color-primary)"
+  ANDROID?: string;  // e.g., "@color/primary"
+  iOS?: string;      // e.g., "Color.primary"
+}
+```
+
+---
+
+### Variable Resolution
+
+#### Direct Values vs Aliases
+
+A variable's value for each mode can be either a **direct value** (literal boolean, number, string, or color) or a **variable alias** (reference to another variable).
+
+```ts
+// Direct value example (COLOR type, mode "light"):
+{
+  "valuesByMode": {
+    "mode-light-id": { "r": 0.067, "g": 0.067, "b": 0.067, "a": 1 },
+    "mode-dark-id": { "r": 0.933, "g": 0.933, "b": 0.933, "a": 1 }
+  }
+}
+
+// Alias example (references another variable):
+{
+  "valuesByMode": {
+    "mode-light-id": { "type": "VARIABLE_ALIAS", "id": "VariableID:1234:0" },
+    "mode-dark-id": { "type": "VARIABLE_ALIAS", "id": "VariableID:5678:0" }
+  }
+}
+```
+
+#### Resolving Alias Chains
+
+Aliases can chain: Variable A references Variable B which references Variable C. To resolve to a final value, follow the chain:
+
+```ts
+function resolveVariable(
+  variableId: string,
+  modeId: string,
+  variables: Record<string, Variable>
+): VariableValue {
+  const variable = variables[variableId];
+  if (!variable) throw new Error(`Variable ${variableId} not found`);
+
+  const value = variable.valuesByMode[modeId];
+  if (!value) {
+    // Fall back to default mode
+    const collection = findCollection(variable.variableCollectionId);
+    return variable.valuesByMode[collection.defaultModeId];
+  }
+
+  // If it's an alias, resolve recursively
+  if (typeof value === 'object' && 'type' in value && value.type === 'VARIABLE_ALIAS') {
+    return resolveVariable(value.id, modeId, variables);
+  }
+
+  return value;
+}
+```
+
+> **Note:** Figma prevents alias cycles — a variable cannot reference itself directly or through a chain.
+
+#### Mode Resolution and Fallbacks
+
+Each variable has values indexed by mode ID in its `valuesByMode` map. Resolution order:
+
+1. Look up the value for the **requested mode ID**
+2. If no value exists for that mode, use the **collection's `defaultModeId`**
+3. If the value is an alias, resolve the referenced variable using the **same mode ID**
+
+When an alias references a variable in a **different** collection, the referenced variable resolves using its own collection's modes. Cross-collection mode mapping is not automatic.
+
+#### Bound Variables on Nodes
+
+Nodes in the Figma file tree indicate which variables are bound to their properties via the `boundVariables` field:
+
+```ts
+// Example: a frame with variables bound to fills and corner radius
+{
+  "type": "FRAME",
+  "name": "Card",
+  "boundVariables": {
+    "fills": [
+      {
+        "type": "VARIABLE_ALIAS",
+        "id": "VariableID:1234:0"
+      }
+    ],
+    "topLeftRadius": {
+      "type": "VARIABLE_ALIAS",
+      "id": "VariableID:5678:0"
+    },
+    "topRightRadius": {
+      "type": "VARIABLE_ALIAS",
+      "id": "VariableID:5678:0"
+    },
+    "itemSpacing": {
+      "type": "VARIABLE_ALIAS",
+      "id": "VariableID:9012:0"
+    }
+  }
+}
+```
+
+**Properties that can have bound variables include:** fills, strokes, effects, cornerRadius (and individual corners), itemSpacing, paddingLeft/Right/Top/Bottom, width, height, opacity, fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, and more.
+
+The `boundVariables` map tells you which properties are token-driven vs hard-coded, which is essential for design-to-code token mapping.
+
+---
+
+### Multi-Mode Theming
+
+#### Pattern: Light/Dark Mode
+
+The most common multi-mode pattern is light and dark themes.
+
+**Figma structure:**
+
+```
+Collection: "Theme"
+  Modes: ["Light", "Dark"]
+  Variables:
+    "bg/primary"     → Light: #FFFFFF, Dark: #1A1A1A
+    "bg/secondary"   → Light: #F5F5F5, Dark: #2D2D2D
+    "text/primary"   → Light: #1A1A1A, Dark: #FFFFFF
+    "text/secondary"  → Light: #666666, Dark: #A0A0A0
+    "border/default" → Light: #E0E0E0, Dark: #404040
+```
+
+**CSS output (class-based switching):**
+
+```css
+:root,
+[data-theme="light"] {
+  --bg-primary: #ffffff;
+  --bg-secondary: #f5f5f5;
+  --text-primary: #1a1a1a;
+  --text-secondary: #666666;
+  --border-default: #e0e0e0;
+}
+
+[data-theme="dark"] {
+  --bg-primary: #1a1a1a;
+  --bg-secondary: #2d2d2d;
+  --text-primary: #ffffff;
+  --text-secondary: #a0a0a0;
+  --border-default: #404040;
+}
+```
+
+**CSS output (media query):**
+
+```css
+:root {
+  --bg-primary: #ffffff;
+  --text-primary: #1a1a1a;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg-primary: #1a1a1a;
+    --text-primary: #ffffff;
+  }
+}
+```
+
+#### Pattern: Brand Theming
+
+Multiple brands sharing a common token structure.
+
+**Figma structure:**
+
+```
+Collection: "Brand"
+  Modes: ["Brand A", "Brand B", "Brand C"]
+  Variables:
+    "color/primary"   → A: #0066FF, B: #FF3366, C: #00CC88
+    "color/secondary" → A: #003399, B: #CC0033, C: #009966
+    "font/heading"    → A: "Inter",  B: "Poppins", C: "DM Sans"
+```
+
+**CSS output (class-based):**
+
+```css
+.brand-a {
+  --color-primary: #0066ff;
+  --color-secondary: #003399;
+  --font-heading: 'Inter', sans-serif;
+}
+
+.brand-b {
+  --color-primary: #ff3366;
+  --color-secondary: #cc0033;
+  --font-heading: 'Poppins', sans-serif;
+}
+
+.brand-c {
+  --color-primary: #00cc88;
+  --color-secondary: #009966;
+  --font-heading: 'DM Sans', sans-serif;
+}
+```
+
+#### Pattern: Layered Modes (Theme + Density)
+
+Multiple collections with independent modes that compose together.
+
+**Figma structure:**
+
+```
+Collection: "Theme"
+  Modes: ["Light", "Dark"]
+  Variables: color tokens...
+
+Collection: "Density"
+  Modes: ["Compact", "Default", "Comfortable"]
+  Variables: spacing tokens...
+```
+
+In CSS, these compose naturally because each collection maps to independent custom properties:
+
+```css
+/* Theme layer */
+[data-theme="light"] { --bg: #fff; --text: #1a1a1a; }
+[data-theme="dark"]  { --bg: #1a1a1a; --text: #fff; }
+
+/* Density layer (independent) */
+[data-density="compact"]      { --spacing-md: 8px; --spacing-lg: 12px; }
+[data-density="default"]      { --spacing-md: 16px; --spacing-lg: 24px; }
+[data-density="comfortable"]  { --spacing-md: 24px; --spacing-lg: 32px; }
+```
+
+---
+
+### Practical Patterns
+
+#### Extracting All Color Tokens
+
+```ts
+interface ColorToken {
+  name: string;
+  variableId: string;
+  collection: string;
+  values: Record<string, { hex: string; rgba: RGBA }>;
+}
+
+async function extractColorTokens(fileKey: string): Promise<ColorToken[]> {
+  const res = await fetch(
+    `https://api.figma.com/v1/files/${fileKey}/variables/local`,
+    { headers: { 'X-Figma-Token': process.env.FIGMA_TOKEN! } }
+  );
+  const { meta } = await res.json();
+  const tokens: ColorToken[] = [];
+
+  for (const variable of Object.values(meta.variables) as Variable[]) {
+    if (variable.resolvedType !== 'COLOR') continue;
+    if (variable.remote) continue; // Skip imported variables
+
+    const collection = meta.variableCollections[variable.variableCollectionId];
+
+    const values: Record<string, { hex: string; rgba: RGBA }> = {};
+    for (const [modeId, value] of Object.entries(variable.valuesByMode)) {
+      const resolved = resolveToColor(value as VariableValue, modeId, meta.variables);
+      if (resolved) {
+        const modeName = collection.modes[modeId] || modeId;
+        values[modeName] = {
+          hex: rgbaToHex(resolved),
+          rgba: resolved,
+        };
+      }
+    }
+
+    tokens.push({
+      name: variable.name,
+      variableId: variable.id,
+      collection: collection.name,
+      values,
+    });
+  }
+
+  return tokens;
+}
+
+function rgbaToHex(c: RGBA): string {
+  const toHex = (v: number) => Math.round(v * 255).toString(16).padStart(2, '0');
+  const hex = `#${toHex(c.r)}${toHex(c.g)}${toHex(c.b)}`;
+  return c.a < 1 ? `${hex}${toHex(c.a)}` : hex;
+}
+```
+
+#### Building a Complete Token Dictionary
+
+```ts
+interface TokenDictionary {
+  colors: Record<string, Record<string, string>>;   // name → { modeName: hex }
+  numbers: Record<string, Record<string, number>>;  // name → { modeName: value }
+  strings: Record<string, Record<string, string>>;  // name → { modeName: value }
+  booleans: Record<string, Record<string, boolean>>; // name → { modeName: value }
+}
+
+async function buildTokenDictionary(fileKey: string): Promise<TokenDictionary> {
+  const res = await fetch(
+    `https://api.figma.com/v1/files/${fileKey}/variables/local`,
+    { headers: { 'X-Figma-Token': process.env.FIGMA_TOKEN! } }
+  );
+  const { meta } = await res.json();
+
+  const dict: TokenDictionary = { colors: {}, numbers: {}, strings: {}, booleans: {} };
+
+  for (const variable of Object.values(meta.variables) as Variable[]) {
+    if (variable.remote) continue;
+    if (variable.hiddenFromPublishing) continue;
+
+    const collection = meta.variableCollections[variable.variableCollectionId];
+    const tokenName = `${collection.name}/${variable.name}`;
+
+    for (const [modeId, rawValue] of Object.entries(variable.valuesByMode)) {
+      const modeName = collection.modes[modeId] || modeId;
+      const value = resolveValue(rawValue as VariableValue, modeId, meta.variables);
+
+      switch (variable.resolvedType) {
+        case 'COLOR':
+          dict.colors[tokenName] ??= {};
+          dict.colors[tokenName][modeName] = rgbaToHex(value as RGBA);
+          break;
+        case 'FLOAT':
+          dict.numbers[tokenName] ??= {};
+          dict.numbers[tokenName][modeName] = value as number;
+          break;
+        case 'STRING':
+          dict.strings[tokenName] ??= {};
+          dict.strings[tokenName][modeName] = value as string;
+          break;
+        case 'BOOLEAN':
+          dict.booleans[tokenName] ??= {};
+          dict.booleans[tokenName][modeName] = value as boolean;
+          break;
+      }
+    }
+  }
+
+  return dict;
+}
+```
+
+#### Detecting Which Variables Are Actually Used
+
+Combine file tree traversal with the Variables API to find which tokens are actively bound to design elements:
+
+```ts
+async function findUsedVariables(fileKey: string): Promise<Set<string>> {
+  // 1. Fetch the file tree
+  const fileRes = await fetch(
+    `https://api.figma.com/v1/files/${fileKey}`,
+    { headers: { 'X-Figma-Token': process.env.FIGMA_TOKEN! } }
+  );
+  const file = await fileRes.json();
+
+  // 2. Walk the tree and collect all bound variable IDs
+  const usedIds = new Set<string>();
+
+  function walk(node: any) {
+    if (node.boundVariables) {
+      for (const bindings of Object.values(node.boundVariables)) {
+        if (Array.isArray(bindings)) {
+          for (const b of bindings) {
+            if (b && typeof b === 'object' && b.type === 'VARIABLE_ALIAS') {
+              usedIds.add(b.id);
+            }
+          }
+        } else if (bindings && typeof bindings === 'object') {
+          const b = bindings as any;
+          if (b.type === 'VARIABLE_ALIAS') {
+            usedIds.add(b.id);
+          }
+        }
+      }
+    }
+    if (node.children) {
+      node.children.forEach(walk);
+    }
+  }
+
+  walk(file.document);
+  return usedIds;
+}
+```
+
+#### Generating CSS Custom Properties from Variables
+
+```ts
+async function generateCSSVariables(fileKey: string): Promise<string> {
+  const res = await fetch(
+    `https://api.figma.com/v1/files/${fileKey}/variables/local`,
+    { headers: { 'X-Figma-Token': process.env.FIGMA_TOKEN! } }
+  );
+  const { meta } = await res.json();
+
+  const output: string[] = [];
+
+  // Group variables by collection
+  for (const collection of Object.values(meta.variableCollections) as VariableCollection[]) {
+    if (collection.remote) continue;
+
+    const collectionVars = collection.variableIds
+      .map(id => meta.variables[id])
+      .filter((v): v is Variable => v != null && !v.hiddenFromPublishing);
+
+    // Generate CSS for each mode
+    const modeEntries = Object.entries(collection.modes);
+
+    for (const [modeId, modeName] of modeEntries) {
+      const isDefault = modeId === collection.defaultModeId;
+      const selector = isDefault
+        ? ':root'
+        : `[data-${slugify(collection.name)}="${slugify(modeName)}"]`;
+
+      output.push(`${selector} {`);
+
+      for (const variable of collectionVars) {
+        const value = variable.valuesByMode[modeId];
+        if (!value) continue;
+
+        const resolved = resolveValue(value, modeId, meta.variables);
+        const cssName = `--${tokenToCSSName(variable.name)}`;
+        const cssValue = formatCSSValue(resolved, variable.resolvedType);
+
+        output.push(`  ${cssName}: ${cssValue};`);
+      }
+
+      output.push('}');
+      output.push('');
+    }
+  }
+
+  return output.join('\n');
+}
+
+function tokenToCSSName(name: string): string {
+  return name
+    .replace(/\//g, '-')
+    .replace(/\s+/g, '-')
+    .replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
+    .replace(/^-/, '')
+    .toLowerCase();
+}
+
+function slugify(str: string): string {
+  return str.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
+}
+
+function formatCSSValue(value: any, type: string): string {
+  switch (type) {
+    case 'COLOR': {
+      const c = value as RGBA;
+      if (c.a < 1) {
+        return `rgba(${Math.round(c.r * 255)}, ${Math.round(c.g * 255)}, ${Math.round(c.b * 255)}, ${c.a})`;
+      }
+      return rgbaToHex(c);
+    }
+    case 'FLOAT':
+      return `${value}px`;
+    case 'STRING':
+      return `'${value}'`;
+    case 'BOOLEAN':
+      return value ? '1' : '0';
+    default:
+      return String(value);
+  }
+}
+```
+
+#### Platform-Agnostic Token Export
+
+The `codeSyntax` field on variables provides platform-specific token names for Dev Mode:
+
+```ts
+// Example: use codeSyntax for platform-aware export
+function exportForPlatform(
+  variable: Variable,
+  platform: 'WEB' | 'ANDROID' | 'iOS'
+): string | null {
+  // Prefer explicit codeSyntax if set by designers
+  if (variable.codeSyntax[platform]) {
+    return variable.codeSyntax[platform];
+  }
+
+  // Fall back to auto-generated name
+  switch (platform) {
+    case 'WEB':
+      return `var(--${tokenToCSSName(variable.name)})`;
+    case 'ANDROID':
+      return `@dimen/${variable.name.replace(/\//g, '_').toLowerCase()}`;
+    case 'iOS':
+      return variable.name.replace(/\//g, '.').replace(/\s+/g, '');
+    default:
+      return null;
+  }
+}
+```
+
+---
+
+### Token Extraction Priority
+
+When extracting design tokens from a Figma file, use this priority order:
+
+1. **Variables API** (this module) — Best structured source. Includes modes, scopes, aliases, and explicit token definitions. Requires Enterprise plan.
+
+2. **Published styles** — Use `/files/:key/styles` for published library styles. Limited to published content only. See `figma-api-rest.md`.
+
+3. **File tree traversal + inference** — Walk the node tree, read fill/stroke/effect properties, and derive tokens by frequency analysis (threshold-based promotion). Works on all plans but requires heuristics.
+
+4. **Plugin API** — For local styles and variables when REST is plan-limited. Requires running a Figma plugin in-context. See `figma-api-plugin.md`.
+
+---
+
+### Error Handling
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| `400` | Invalid parameter (bad variable name, scope mismatch) | Check request body against constraints |
+| `401` | Authentication failed | Verify token and `file_variables:read/write` scope |
+| `403` | Insufficient permissions (non-Enterprise or guest) | Confirm Enterprise plan, full member status, and file access |
+| `404` | File not found | Verify file key |
+| `413` | Payload exceeds 4 MB | Split POST request into smaller batches |
+| `429` | Rate limited | Use `Retry-After` header. See `figma-api-rest.md` for backoff strategy |
+
+---
+
+## Cross-References
+
+- **`figma-api-rest.md`** — Core REST API reference (authentication, file endpoints, rate limits, node structure)
+- **`figma-api-plugin.md`** — Plugin API alternative for variables access on non-Enterprise plans
+- **`figma-api-webhooks.md`** — Webhooks v2 LIBRARY_PUBLISH event for reacting to published variable changes
+- **`design-tokens.md`** — Token extraction strategies, CSS variable naming, threshold-based promotion
+- **`design-tokens-variables.md`** — Deep dive on Figma Variables patterns (modes, fallback chains, scope usage)
+- **`css-strategy.md`** — Layered CSS approach for consuming design tokens
+- **`design-to-code-visual.md`** — Visual property extraction that consumes bound variable data