Bidirectional Design Token Sync

What this skill does

# Bidirectional Design Token Sync

## Overview

Keep design tokens synchronized between Figma and your codebase automatically. Detect drift, resolve conflicts, and maintain a single source of truth for your design system.

**Key Innovation:** Bidirectional sync means changes in Figma OR code propagate automatically with conflict detection and intelligent merging.

## When to Use This Skill

Trigger this skill when the user:
- Mentions "sync tokens with Figma" or "Figma sync"
- Wants to "export tokens from Figma" or "import tokens to Figma"
- Asks about "design token drift" or "out of sync tokens"
- Wants to "update tokens from design" or vice versa
- Mentions Style Dictionary, design tokens, or token management
- Has conflicts between design and code token values

## Core Capabilities

### 1. Figma → Code Sync

**Problem:** Designers update colors/spacing in Figma, developers manually update code

**Solution:** Automatic extraction and sync:
```
Figma Variables/Styles → Parse → Transform → Code Tokens
```

Supports:
- Colors (all formats: hex, rgb, hsl)
- Typography (font-family, size, weight, line-height, letter-spacing)
- Spacing (padding, margin, gap)
- Border radius
- Shadows/elevation
- Gradients

### 2. Code → Figma Sync

**Problem:** Developers add tokens in code, design falls out of sync

**Solution:** Push code changes back to Figma:
```
Code Tokens → Transform → Figma API → Update Variables/Styles
```

### 3. Drift Detection

Automatically detect when design and code tokens diverge:

```bash
$ npm run tokens:check

🔍 Drift detected:

Figma → Code (5 changes):
  ✓ primary-500: #2196F3 → #1976D2 (theme update)
  ✓ spacing-lg: 20px → 24px (increased)
  ⚠️ New token: primary-gradient (add to code)
  ⚠️ New token: shadow-xl (add to code)
  ✓ Renamed: font-body → font-sans (update)

Code → Figma (2 changes):
  ⚠️ success-900 exists in code but not Figma (add)
  ⚠️ border-radius-2xl exists in code but not Figma (add)

Apply changes? [Figma→Code] [Code→Figma] [Both] [Review]
```

### 4. Conflict Resolution

When both sides changed the same token:

```
⚠️ Conflict detected for token: primary-500

Figma:  #1976D2 (updated 2 hours ago by Sarah Designer)
Code:   #2196F3 (updated 1 hour ago by you in commit abc123)

Which version should we keep?
[F]igma value  [C]ode value  [M]erge manually  [S]kip

Recommendation: Code value is newer, use Code (C)
```

## Technical Implementation

### Architecture

```
┌─────────┐         ┌──────────────┐         ┌──────┐
│  Figma  │ ←─────→ │ Style        │ ←─────→ │ Code │
│   API   │         │ Dictionary   │         │Tokens│
└─────────┘         └──────────────┘         └──────┘
     ↓                      ↓                     ↓
  Variables         tokens.json              CSS/JS/TS
   Styles                                  src/tokens/
```

### Components

1. **Figma Plugin** (Optional)
   - Runs inside Figma
   - Extracts variables and styles
   - Can update Figma from external source

2. **Sync CLI** (Core)
   - Command-line tool for sync
   - Connects to Figma API
   - Uses Style Dictionary for transformation

3. **Style Dictionary Config**
   - Transforms tokens to multiple formats
   - CSS variables, SCSS, JS, JSON, iOS, Android

4. **Drift Detector**
   - Compares Figma and code tokens
   - Identifies additions, deletions, changes
   - Tracks change history

### Setup

Use `/sync-design-tokens --setup` to configure:

```bash
Figma Design Token Sync Setup
==============================

1. Figma Configuration
   ? Figma file URL: https://figma.com/file/abc123...
   ? Figma access token: (input hidden)
   ? Token location in Figma: [Local Variables] [Shared Variables]

2. Sync Direction
   ? Sync direction: [Bidirectional] [Figma → Code only] [Code → Figma only]
   ? Auto-sync on file save: [Yes] [No]
   ? Sync on git commit: [Yes] [No]

3. Conflict Resolution
   ? On conflict: [Manual review] [Prefer Figma] [Prefer Code] [Use latest]

4. Output Formats
   ? Generate CSS variables: [Yes]
   ? Generate SCSS variables: [Yes]
   ? Generate TypeScript: [Yes]
   ? Generate JSON: [Yes]

Setting up...
✓ Installed: @figma/rest-api-client
✓ Installed: style-dictionary
✓ Created: tokens/figma-tokens.json (source of truth)
✓ Created: config/style-dictionary.config.js
✓ Created: scripts/sync-tokens.js
✓ Added NPM scripts

Setup complete! Run 'npm run tokens:sync' to sync for the first time.
```

### Workflow

#### Initial Sync (Figma → Code)

```bash
$ npm run tokens:sync

Fetching tokens from Figma...
  ✓ Connected to Figma file: Design System v2
  ✓ Found 127 color variables
  ✓ Found 43 typography styles
  ✓ Found 24 spacing tokens
  ✓ Found 12 shadow styles

Transforming tokens...
  ✓ Generated: src/tokens/colors.css
  ✓ Generated: src/tokens/colors.scss
  ✓ Generated: src/tokens/colors.ts
  ✓ Generated: src/tokens/typography.css
  ✓ Generated: src/tokens/spacing.css

Initial sync complete! 📦
Total tokens: 206
```

#### Regular Sync with Drift

```bash
$ npm run tokens:check

Checking for drift...

Changes detected:
  Figma → Code: 3 changes
  Code → Figma: 1 change

Would you like to review? [Yes] [Apply all] [Cancel]

User: Yes

---

Change 1 of 4: primary-600 color update

Source: Figma
Type: Color modification
Old value: #2196F3
New value: #1976D2
Last updated: 2 hours ago by Sarah Designer
Affected tokens in code: 12 references

Apply this change? [Yes] [No] [Skip all]

User: Yes

✓ Updated src/tokens/colors.css
✓ Updated src/tokens/colors.scss
✓ Updated src/tokens/colors.ts

---

Change 2 of 4: success-900 missing in Figma

Source: Code
Type: New token
Value: #1B5E20
Created: 3 days ago in commit def456
Usage: 5 components

Add to Figma? [Yes] [No] [Skip all]

User: Yes

✓ Created in Figma: success-900
✓ Added to collection: Colors/Success

---

Sync complete! Applied 4 changes.

Summary:
  ✓ Figma → Code: 3 changes applied
  ✓ Code → Figma: 1 change applied
  ✓ No conflicts

Run 'git status' to see updated files.
```

## Figma API Integration

### Authentication

```javascript
// scripts/sync-tokens.js
import { FigmaClient } from '@figma/rest-api-client';

const client = new FigmaClient({
  personalAccessToken: process.env.FIGMA_ACCESS_TOKEN
});

const fileKey = 'abc123...'; // From Figma URL

// Get file variables
const variables = await client.getFileVariables(fileKey);
```

### Extract Variables

```javascript
async function extractTokensFromFigma(fileKey) {
  const file = await client.getFile(fileKey);
  const variables = await client.getFileVariables(fileKey);

  const tokens = {
    color: {},
    typography: {},
    spacing: {},
    shadow: {}
  };

  // Extract color variables
  for (const [id, variable] of Object.entries(variables.variables)) {
    if (variable.resolvedType === 'COLOR') {
      const name = variable.name.toLowerCase().replace(/\s+/g, '-');
      const value = rgbaToHex(variable.valuesByMode.default);

      tokens.color[name] = {
        value,
        type: 'color',
        figmaId: id,
        description: variable.description || ''
      };
    }
  }

  // Extract typography styles
  const styles = await client.getFileStyles(fileKey);

  for (const style of styles.text) {
    const name = style.name.toLowerCase().replace(/\s+/g, '-');

    tokens.typography[name] = {
      fontFamily: style.fontFamily,
      fontSize: style.fontSize,
      fontWeight: style.fontWeight,
      lineHeight: style.lineHeight,
      letterSpacing: style.letterSpacing,
      type: 'typography',
      figmaId: style.id
    };
  }

  return tokens;
}
```

### Push Updates to Figma

```javascript
async function pushTokensToFigma(tokens, fileKey) {
  const updates = [];

  for (const [category, categoryTokens] of Object.entries(tokens)) {
    for (const [name, token] of Object.entries(categoryTokens)) {
      if (!token.figmaId) {
        // New token - create in Figma
        updates.push(createVariable(name, token));
      } else if (token.modified) {
        // Modified token - update in Figma
        u