figma-to-code

# Figma-to-Code Skill

## When to Activate

- A designer works in Figma and you need design tokens in code
- Design and code are drifting out of sync (different colors, spacing)
- Setting up an automated token sync pipeline
- Translating a Figma component into React for the first time
- Establishing handoff conventions between design and engineering

---

## The Core Problem

Without a sync pipeline:
- Designer changes `--blue-600` to `#2563eb` in Figma
- Developer doesn't know
- Production stays at `#3b82f6`
- Design and code drift apart over weeks

**Solution:** Figma Variables → export → Style Dictionary → CSS/TS tokens → commit to repo.

---

## Step 1: Figma Variables Setup (designer's job)

Figma Variables map directly to CSS Custom Properties. Establish this convention with your designer:

```
Figma Variable collection structure:

Primitives (raw values):
  colors/blue/500       = #3b82f6
  colors/blue/600       = #2563eb
  spacing/4             = 16
  radius/md             = 6

Semantic (light mode):
  color/brand           = {colors/blue/600}
  color/surface         = #ffffff
  color/text/primary    = #111827

Semantic (dark mode):     ← same names, different values via mode
  color/brand           = {colors/blue/500}
  color/surface         = #0f172a
  color/text/primary    = #f8fafc
```

This maps 1:1 to your `tokens/colors.css` from the design-system skill.

---

## Step 2: Export Tokens from Figma

### Option A: Figma Tokens Plugin (free)

1. Install "Tokens Studio for Figma" plugin
2. Connect to GitHub repository
3. Auto-syncs Figma Variables to `tokens/` JSON files on push

```json
// tokens/semantic.json (auto-generated by plugin)
{
  "color": {
    "brand": { "value": "{colors.blue.600}", "type": "color" },
    "surface": { "value": "#ffffff", "type": "color" },
    "text": {
      "primary": { "value": "#111827", "type": "color" },
      "secondary": { "value": "#6b7280", "type": "color" }
    }
  },
  "spacing": {
    "4": { "value": "16", "type": "spacing" },
    "6": { "value": "24", "type": "spacing" }
  }
}
```

### Option B: Figma Variables REST API (programmatic)

```typescript
// scripts/sync-tokens.ts
const FIGMA_FILE_ID = process.env.FIGMA_FILE_ID!;
const FIGMA_TOKEN = process.env.FIGMA_ACCESS_TOKEN!;

async function fetchFigmaVariables() {
  const response = await fetch(
    `https://api.figma.com/v1/files/${FIGMA_FILE_ID}/variables/local`,
    { headers: { 'X-Figma-Token': FIGMA_TOKEN } }
  );
  return response.json();
}

// Run: npx ts-node scripts/sync-tokens.ts
// Commit the output to version control
```

---

## Step 3: Style Dictionary (tokens → platform outputs)

Style Dictionary transforms raw JSON tokens into CSS, TypeScript, iOS, Android — one source, many targets.

```bash
npm install --save-dev style-dictionary
```

```javascript
// style-dictionary.config.js
import StyleDictionary from 'style-dictionary';

const sd = new StyleDictionary({
  source: ['tokens/**/*.json'],

  platforms: {
    css: {
      transformGroup: 'css',
      prefix: 'ds',
      buildPath: 'src/styles/generated/',
      files: [
        {
          destination: 'tokens.css',
          format: 'css/variables',
          options: { outputReferences: true },
        },
      ],
    },
    typescript: {
      transformGroup: 'js',
      buildPath: 'src/styles/generated/',
      files: [
        {
          destination: 'tokens.ts',
          format: 'javascript/es6',
        },
      ],
    },
  },
});

sd.buildAllPlatforms();
```

```bash
# Package.json script
"tokens:build": "node style-dictionary.config.js",
"tokens:sync": "npx ts-node scripts/sync-tokens.ts && npm run tokens:build"
```

**Output** (`src/styles/generated/tokens.css`):
```css
:root {
  --ds-color-brand: #2563eb;
  --ds-color-surface: #ffffff;
  --ds-color-text-primary: #111827;
  --ds-spacing-4: 16px;
}
```

---

## Step 4: Reading a Figma Component for Implementation

When implementing a component from Figma, extract in this order:

### 1. Structure first (HTML semantics)
```
Figma layer: "Card / Product"
  ├─ Image (rectangle with image fill)
  ├─ Content
  │   ├─ Title (text)
  │   ├─ Description (text)
  │   └─ Price (text)
  └─ Actions
      └─ Button / Add to cart

→ Semantic HTML:
<article>
  <img />
  <div> (content)
    <h3>
    <p>
    <p> (price)
  </div>
  <footer>
    <button>
  </footer>
</article>
```

### 2. Spacing (always check all 4 sides)
```
Figma: inspect → spacing
Padding: 16px all sides = p-4
Gap between elements: 12px = gap-3
```

### 3. Typography (always check weight + size + line-height)
```
Title:  Inter 16px / SemiBold / line-height 24px
= text-base font-semibold leading-normal

Price:  Inter 14px / Bold / line-height 20px
= text-sm font-bold
```

### 4. Colors → token names (never use hex directly)
```
Background: #ffffff → bg-surface
Border: #e5e7eb → border-border
Title: #111827 → text-text-primary
Price: #2563eb → text-text-brand
```

### 5. Interactive states (hover, focus, disabled)
```
Always ask: "What does this look like on hover / focus / disabled?"
If not in Figma, establish the convention yourself using the design system.
```

---

## Handoff Conventions

Establish these with your designer once, document in your team wiki:

| Convention | Agreement |
|---|---|
| Spacing | Designer uses 8px grid; developer uses `--space-*` tokens |
| Colors | Designer uses Variables; developer uses `--color-*` semantic tokens |
| Typography | Designer uses text styles; developer uses `--text-*` tokens |
| Breakpoints | Agreed breakpoint names: `sm/md/lg/xl` |
| States | Designer provides: default, hover, focus, disabled, error |
| Icons | Agreed icon library (Lucide, Heroicons, Phosphor) |
| Images | Designer specifies: aspect ratio, min/max size, object-fit |
| Redline units | Always px in Figma; developer converts to rem |

---

## CI Token Sync Pipeline

```yaml
# .github/workflows/sync-tokens.yml
name: Sync Design Tokens

on:
  schedule:
    - cron: '0 9 * * 1'   # Every Monday morning
  workflow_dispatch:         # Also runnable manually

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 24 }
      - run: npm ci
      - name: Fetch tokens from Figma
        env:
          FIGMA_ACCESS_TOKEN: ${{ secrets.FIGMA_ACCESS_TOKEN }}
          FIGMA_FILE_ID: ${{ secrets.FIGMA_FILE_ID }}
        run: npm run tokens:sync
      - name: Create PR if tokens changed
        uses: peter-evans/create-pull-request@v6
        with:
          title: 'chore: sync design tokens from Figma'
          body: 'Auto-generated: design tokens updated from Figma Variables.'
          branch: chore/sync-tokens
          commit-message: 'chore: sync design tokens from Figma'
```

---

## Red Flags (Design-Code Drift)

- Hardcoded hex values in components (`text-[#2563eb]`) — use tokens
- "Just eyeball it" spacing — use the scale
- Components in code that don't exist in Figma — add them to Figma
- Figma components that aren't implemented — note as tech debt
- Token names in code that differ from Figma variable names — unify them

---

## Checklist

- [ ] Figma Variables organized: Primitives + Semantic (light + dark modes)
- [ ] Token export automated (plugin or API + script)
- [ ] Style Dictionary converts tokens to CSS Custom Properties
- [ ] Generated token files committed to repo (not gitignored)
- [ ] CI workflow syncs tokens weekly or on designer push
- [ ] Handoff conventions documented and agreed with designer
- [ ] Component implementation checks all 5 layers: structure, spacing, typography, color, states
- [ ] No hardcoded hex/px values — always token references in components