You are an expert in exporting design tokens from Figma for developer-designer collaboration using Figma.

## Key Points

- Multi-file token structures
- Git push/pull to GitHub, GitLab, or Azure DevOps
- Theme and set management
- Automatic Style Dictionary integration
- **Establish a naming convention** — Use a consistent hierarchy like `category/property/variant` (e.g., `color/primary/500`, `spacing/md`). This directly maps to nested JSON and CSS variable names.
- **Use aliases for semantic tokens** — Define primitive tokens (`blue-600`) and alias them to semantic tokens (`color-primary`). This allows theme switching without changing component code.
- **Version your tokens** — Treat the token JSON files as versioned artifacts. Use semver or timestamps so consumers can pin to stable releases.
- **Automate the pipeline** — Manual copy-paste of token values introduces drift. Automate extraction and transformation in CI.
- **Validate tokens** — Add schema validation to catch malformed tokens before they reach production.
- **Manually transcribing values** — Copying hex codes or spacing values by hand guarantees drift between design and code.
- **Flat token structures** — Dumping all tokens into a single flat list makes them hard to maintain. Use nested groupings.
- **Ignoring multi-mode support** — Tokens must account for light/dark themes, density scales, and brand variants. A single-mode export is insufficient for most products.

## Quick Example

```bash
curl -H "X-Figma-Token: YOUR_TOKEN" \
  "https://api.figma.com/v1/files/FILE_KEY/variables/local"
```

Design Tokens Export — Figma for Developers

You are an expert in exporting design tokens from Figma for developer-designer collaboration using Figma.

Core Philosophy

Overview

Design tokens are the atomic values of a design system — colors, typography scales, spacing units, border radii, shadows, and more. Figma stores these as styles and variables. Exporting them into code-consumable formats (CSS custom properties, JSON, SCSS variables, Tailwind config) ensures that design decisions propagate consistently into production without manual transcription.

Core Concepts

Figma Variables

Figma Variables (introduced as a successor to styles for primitive values) support multiple modes (e.g., light/dark themes) and scoping. Variables can represent colors, numbers, strings, and booleans. They are organized into collections and can alias one another.

Figma Styles

Styles define reusable color fills, text properties, effects (shadows, blurs), and grids. Each style has a name and a set of values. Styles predate variables and remain widely used for typography and effects.

Token Formats

The W3C Design Tokens Community Group defines a standard JSON format (DTCG) for interoperability:

{
  "color": {
    "primary": {
      "$value": "#6C5CE7",
      "$type": "color"
    },
    "surface": {
      "$value": "#FFFFFF",
      "$type": "color"
    }
  },
  "spacing": {
    "sm": {
      "$value": "8px",
      "$type": "dimension"
    },
    "md": {
      "$value": "16px",
      "$type": "dimension"
    }
  }
}

Token Transformation

Raw tokens from Figma need transformation into platform-specific outputs. Style Dictionary (by Amazon) is the most established tool for this:

// style-dictionary.config.js
module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'dist/css/',
      files: [{
        destination: 'variables.css',
        format: 'css/variables',
      }],
    },
    scss: {
      transformGroup: 'scss',
      buildPath: 'dist/scss/',
      files: [{
        destination: '_variables.scss',
        format: 'scss/variables',
      }],
    },
    js: {
      transformGroup: 'js',
      buildPath: 'dist/js/',
      files: [{
        destination: 'tokens.js',
        format: 'javascript/es6',
      }],
    },
  },
};

Implementation Patterns

Using the Figma Variables REST API

Figma exposes variables through the REST API, enabling automated extraction:

curl -H "X-Figma-Token: YOUR_TOKEN" \
  "https://api.figma.com/v1/files/FILE_KEY/variables/local"

The response includes variable collections, modes, and resolved values. A script can parse this into DTCG format:

interface FigmaVariable {
  id: string;
  name: string;
  resolvedType: 'COLOR' | 'FLOAT' | 'STRING' | 'BOOLEAN';
  valuesByMode: Record<string, any>;
}

function toDesignToken(variable: FigmaVariable, modeId: string) {
  const value = variable.valuesByMode[modeId];
  if (variable.resolvedType === 'COLOR') {
    const { r, g, b, a } = value;
    return {
      $value: `rgba(${Math.round(r * 255)}, ${Math.round(g * 255)}, ${Math.round(b * 255)}, ${a})`,
      $type: 'color',
    };
  }
  if (variable.resolvedType === 'FLOAT') {
    return { $value: `${value}px`, $type: 'dimension' };
  }
  return { $value: String(value), $type: 'string' };
}

Tokens Studio Plugin

Tokens Studio (formerly Figma Tokens) is a popular plugin that manages tokens inside Figma and syncs them to Git repositories. It supports:

• Multi-file token structures
• Git push/pull to GitHub, GitLab, or Azure DevOps
• Theme and set management
• Automatic Style Dictionary integration

Generating a Tailwind Config

After extracting tokens to JSON, they can feed a Tailwind CSS configuration:

const tokens = require('./dist/js/tokens.js');

module.exports = {
  theme: {
    colors: {
      primary: tokens.colorPrimary,
      secondary: tokens.colorSecondary,
      surface: tokens.colorSurface,
    },
    spacing: {
      sm: tokens.spacingSm,
      md: tokens.spacingMd,
      lg: tokens.spacingLg,
    },
    borderRadius: {
      sm: tokens.radiusSm,
      md: tokens.radiusMd,
      lg: tokens.radiusLg,
    },
  },
};

CI Pipeline Integration

Automate token export in CI so that design changes flow into code via pull requests:

# .github/workflows/sync-tokens.yml
name: Sync Design Tokens
on:
  workflow_dispatch:
  schedule:
    - cron: '0 9 * * 1' # Weekly on Monday

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: node scripts/fetch-figma-tokens.js
        env:
          FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}
          FIGMA_FILE_KEY: ${{ secrets.FIGMA_FILE_KEY }}
      - run: npx style-dictionary build
      - uses: peter-evans/create-pull-request@v6
        with:
          title: 'chore: update design tokens'
          branch: design-tokens-update

Best Practices

• Establish a naming convention — Use a consistent hierarchy like category/property/variant (e.g., color/primary/500, spacing/md). This directly maps to nested JSON and CSS variable names.
• Use aliases for semantic tokens — Define primitive tokens (blue-600) and alias them to semantic tokens (color-primary). This allows theme switching without changing component code.
• Version your tokens — Treat the token JSON files as versioned artifacts. Use semver or timestamps so consumers can pin to stable releases.
• Automate the pipeline — Manual copy-paste of token values introduces drift. Automate extraction and transformation in CI.
• Validate tokens — Add schema validation to catch malformed tokens before they reach production.

Common Pitfalls

• Manually transcribing values — Copying hex codes or spacing values by hand guarantees drift between design and code.
• Flat token structures — Dumping all tokens into a single flat list makes them hard to maintain. Use nested groupings.
• Ignoring multi-mode support — Tokens must account for light/dark themes, density scales, and brand variants. A single-mode export is insufficient for most products.
• Not handling aliases — If a token references another token, the export must resolve or preserve that alias. Dropping aliases breaks the semantic layer.
• Skipping typography tokens — Teams often export colors but forget font families, weights, sizes, and line heights, leading to inconsistent text rendering.

Anti-Patterns

Over-engineering for hypothetical scale. Building for millions of users when you have hundreds adds complexity without value. Solve today's problems first.

Ignoring the existing ecosystem. Reinventing functionality that mature libraries already provide well wastes time and introduces unnecessary risk.

Premature abstraction. Creating elaborate frameworks and utilities before you have enough concrete cases to know what the abstraction should look like produces the wrong abstraction.

Neglecting error handling at boundaries. Internal code can trust its inputs, but system boundaries (user input, APIs, file I/O) require defensive validation.

Skipping documentation for obvious code. What is obvious to you today will not be obvious to your colleague next month or to you next year.