Sync Design Tokens

Sync Design Tokens

Overview

This skill extracts design tokens (variables and styles) from Figma and transforms them into production-ready code formats. It bridges the gap between Figma's variable system and your codebase's token architecture.

Related documentation:

• ../../agents/design-token-sync.AGENT.md - Technical reference for token synchronization
• ../../agents/AGENTS.md - Full MCP tool reference
• ../create-design-system-rules/SKILL.md - Design system rules workflow

Prerequisites

• Figma MCP server must be connected and accessible
• User must provide a Figma URL: https://figma.com/design/:fileKey/:fileName?node-id=1-2
• OR when using figma-desktop MCP: User can select a node directly in the Figma desktop app
• Target output format should be specified (CSS, JSON, TypeScript, Tailwind, etc.)

Required Workflow

Follow these steps in order. Do not skip steps.

Step 1: Determine Extraction Scope

Ask the user or infer from context:

Step 2: Parse Figma URL

Extract from the Figma URL:

• File key: Segment after /design/
• Node ID: Value of node-id parameter (convert 1-2 to 1:2)

Example:

URL: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15
File key: kL9xQn2VwM8pYrTb4ZcHjF
Node ID: 42:15

Step 3: Fetch Variable Definitions

Run get_variable_defs to extract tokens:

get_variable_defs(fileKey=":fileKey", nodeId=":nodeId")

Extracts:

• Color variables and styles
• Spacing/dimension variables
• Typography styles (font family, size, weight, line-height)
• Radius variables
• Shadow/effect styles
• Variable modes (Light/Dark, Brand variants)

Step 4: Analyze Existing Token Structure

Before generating output, check the codebase for existing token files:

Common locations:

• src/styles/tokens.css
• src/theme/variables.css
• tokens/ directory
• tailwind.config.js or tailwind.config.ts
• src/styles/theme.ts

Determine:

• What format is currently used?
• What naming conventions exist?
• Are there modes/themes already defined?
• What's the token hierarchy (primitive → semantic)?

Step 5: Transform Tokens

Transform extracted tokens to match the project's format and conventions.

Output Format: CSS Custom Properties

:root {
  /* Colors - Primitives */
  --color-blue-500: #3b82f6;
  --color-gray-900: #111827;

  /* Colors - Semantic */
  --color-background: var(--color-white);
  --color-text-primary: var(--color-gray-900);

  /* Spacing */
  --space-1: 4px;
  --space-2: 8px;

  /* Typography */
  --font-size-base: 16px;
  --line-height-normal: 1.5;

  /* Radius */
  --radius-md: 8px;
}

/* Dark mode */
[data-theme="dark"] {
  --color-background: var(--color-gray-900);
  --color-text-primary: var(--color-white);
}

Output Format: JSON (W3C Design Tokens)

{
  "color": {
    "background": {
      "$value": "#ffffff",
      "$type": "color"
    },
    "text": {
      "primary": {
        "$value": "#111827",
        "$type": "color"
      }
    }
  },
  "spacing": {
    "1": { "$value": "4px", "$type": "dimension" },
    "2": { "$value": "8px", "$type": "dimension" }
  }
}

Output Format: TypeScript

export const tokens = {
  colors: {
    background: 'var(--color-background)',
    text: {
      primary: 'var(--color-text-primary)',
    },
  },
  spacing: {
    1: 'var(--space-1)',
    2: 'var(--space-2)',
  },
} as const;

export type ColorToken = keyof typeof tokens.colors;
export type SpacingToken = keyof typeof tokens.spacing;

Output Format: Tailwind Extension

// tailwind.tokens.js
module.exports = {
  colors: {
    background: 'var(--color-background)',
    foreground: 'var(--color-text-primary)',
    primary: {
      DEFAULT: 'var(--color-primary)',
      hover: 'var(--color-primary-hover)',
    },
  },
  spacing: {
    1: 'var(--space-1)',
    2: 'var(--space-2)',
  },
};

Step 6: Generate Output Files

Based on project structure, generate or update token files:

New project:

tokens/
├── colors.css
├── spacing.css
├── typography.css
└── index.css (imports all)

Existing project:

• Update existing token files
• Preserve tokens not in Figma
• Add new tokens from Figma
• Flag removed/changed tokens

Step 7: Report Changes

Provide a summary of extracted tokens:

Token Extraction Summary
========================
Source: https://figma.com/design/.../DesignSystem?node-id=42-15

Extracted:
  Colors:      24 tokens (12 primitives, 12 semantic)
  Spacing:      8 tokens
  Typography:  10 tokens
  Radius:       4 tokens
  Shadows:      3 tokens

Modes detected: Light, Dark

Files generated/updated:
  ✓ src/styles/tokens.css
  ✓ tailwind.tokens.js

New tokens added: 8
Updated tokens: 3
Unchanged: 38

Handling Modes

When Figma has multiple modes (Light/Dark, Brand variants):

Option 1: CSS Data Attributes

:root { --color-bg: #ffffff; }
[data-theme="dark"] { --color-bg: #0a0a0a; }

Option 2: CSS Media Query

:root { --color-bg: #ffffff; }
@media (prefers-color-scheme: dark) {
  :root { --color-bg: #0a0a0a; }
}

Option 3: Separate Files

tokens/
├── themes/
│   ├── light.css
│   └── dark.css

Ask the user which approach matches their project or which they prefer.

Examples

Example 1: Extract All Tokens to CSS

User says: "Sync tokens from this Figma file to CSS: https://figma.com/design/abc123/Tokens?node-id=1-5"

Actions:

1. Parse URL: fileKey=abc123, nodeId=1:5
2. Run get_variable_defs(fileKey="abc123", nodeId="1:5")
3. Check for existing tokens.css or similar
4. Transform to CSS custom properties
5. Generate src/styles/tokens.css with all tokens
6. Report: "Extracted 45 tokens across 5 categories"

Example 2: Update Existing Tokens

User says: "Update our design tokens from Figma"

Actions:

1. Ask for Figma URL (or use selection if figma-desktop)
2. Fetch variables with get_variable_defs
3. Read existing token files in project
4. Compare Figma tokens vs existing tokens
5. Generate diff report:
   • New tokens to add
   • Changed token values
   • Tokens in code but not in Figma
6. Update token files with changes
7. Report changes made

Example 3: Tailwind Integration

User says: "Export Figma tokens for Tailwind"

Actions:

1. Get Figma URL and extract tokens
2. Find tailwind.config.js in project
3. Generate tailwind.tokens.js with theme extension format
4. Show how to import in Tailwind config:

   const tokens = require('./tailwind.tokens');
   module.exports = {
     theme: { extend: tokens },
   };
   

Best Practices

Preserve Token Hierarchy

Maintain the primitive → semantic relationship:

• Primitives: Raw values (blue-500: #3b82f6)
• Semantic: References (primary: var(--color-blue-500))

Match Project Conventions

Always analyze existing tokens first. Match:

• Naming patterns (color-* vs --*-color)
• File organization
• Format (CSS vs JSON vs TypeScript)

Document Mode Handling

When modes exist, document how to switch:

// Set theme mode
document.documentElement.dataset.theme = 'dark';

Validate Before Committing

Check that:

• All aliases resolve
• No duplicate names
• Values are valid CSS
• Modes have complete coverage

Common Issues and Solutions

Issue: Missing variables in extraction

Cause: The selected node doesn't use all variables in the system. Solution: Select a higher-level frame or page that references all variables.

Issue: Alias chains don't resolve

Cause: Variables reference other variables outside the extraction scope. Solution: Extract from a scope that includes all referenced variables, or resolve to primitive values.

Issue: Naming conflicts with existing tokens

Cause: Figma names don't match codebase conventions. Solution: Create a mapping and transform names during extraction.

Additional Resources

• design-token-sync.AGENT.md - Technical reference for token synchronization
• Figma Variables Guide
• W3C Design Tokens Format
• Style Dictionary