# /figma-design

**Source:** `~/.claude/skills/figma-design/SKILL.md`
---

---
name: figma-design
description: "Figma specialist for EXISTING Figma files. Extracts tokens, generates React code, validates builds, exports assets. Use when working WITH a Figma file. For NEW designs from scratch, use /design-system."
argument-hint: "[Figma file key or 'drop' shortcut] [what to do — extract, generate, validate, export]"
---

# Figma Design Specialist

You work with EXISTING Figma files — extracting tokens, generating code, validating builds, and exporting assets.

**Knowledge Base:** `~/system/context/figma-knowledge-base.md` — READ THIS FIRST for all Figma operations.

## When This Skill Triggers

- "extract from Figma", "Figma tokens", "export from Figma"
- "generate code from Figma", "Figma to React"
- "compare with Figma", "validate against Figma"
- Working with an existing Figma file
- Design token extraction or sync

## Tools Available

| Tool | Command | What It Does |
|------|---------|-------------|
| `figma-extract.js` | `extract-tokens`, `extract-components`, `frame-to-prompt`, `export-image`, `list-nodes` | Read Figma REST API |
| `figma-to-react.js` | `<file-key> <node-id>` | Generate React + Tailwind from Figma frame |
| `figma-token-sync.js` | `<file-key> --format all` | Variables → W3C tokens + Tailwind + CSS vars |
| `figma-validate.js` | `compare <file-key> <node-id> <url>` | Visual diff: Figma vs built page |
| `design-to-code.js` | `assemble --stitch-code X --assets-dir Y` | Stitch HTML → React TSX |

## Common Workflows

### Extract Design Tokens
```bash
# Get all tokens (colors, typography, spacing)
node ~/system/tools/figma-extract.js extract-tokens <file-key>

# Sync variables to code-ready formats
node ~/system/tools/figma-token-sync.js <file-key> --format all --output ./tokens/
```

### Generate React from Figma Frame
```bash
# List nodes to find the right frame
node ~/system/tools/figma-extract.js list-nodes <file-key>

# Generate React + Tailwind component
node ~/system/tools/figma-to-react.js <file-key> <node-id> --output ./src/components/Screen.tsx
```

### Export Assets
```bash
# Export frame as PNG (2x retina)
node ~/system/tools/figma-extract.js export-image <file-key> <node-id> --format png --scale 2 --output ./public/frame.png

# Export as SVG (icons, logos)
node ~/system/tools/figma-extract.js export-image <file-key> <node-id> --format svg --output ./public/icon.svg
```

### Validate Build Against Design
```bash
# Compare Figma design vs built page — outputs diff report
node ~/system/tools/figma-validate.js compare <file-key> <node-id> http://localhost:3000/login
```

## Drop App Shortcuts

**File key:** `P535qC6nAREfoTsMWfOqqi`

| Page | Node ID | Description |
|------|---------|-------------|
| Page 1 | `0:1` | Main page |
| Design System | `6:2` | Colors, typography, components |
| Screen Test | `6:140` | Component testing |
| Screens | `6:142` | Full app screens |
| Login v2 UX | `6:175` | Login flow variations |

## Figma REST API Quick Reference

| Endpoint | What |
|----------|------|
| `GET /v1/files/{key}` | Full file data |
| `GET /v1/files/{key}/nodes?ids=X` | Specific nodes |
| `GET /v1/images/{key}?ids=X&format=png&scale=2` | Export as image |
| `GET /v1/files/{key}/variables/local` | Design variables |
| `GET /v1/files/{key}/components` | Components |

**Auth:** `X-Figma-Token` header from `~/system/config/figma.json`
**Rate limits:** 6-20 req/min (Tier 1), use 200ms delay between requests
**Export:** PNG/JPG up to 4x scale (max 32MP), SVG/PDF at 1x only, URLs expire in 30 days

## Figma Live Bridge (WebSocket — PROTOTYPE)

For direct manipulation of Figma Desktop. **Reliability: ~40%** — use REST API tools above instead when possible.

**Setup:** Figma Desktop → Plugins → Development → Claude MCP Plugin → get channel ID
**Connection:** WebSocket on port 3055 via `bun socket`
**Commands:** `create_frame`, `create_text`, `create_rectangle`, `create_ellipse`, `set_fill_color`, `get_document_info`, `get_node_info`
**Timeouts:** `set_corner_radius`, `set_effects`, `set_auto_layout` — use workarounds

## Design Token Architecture (3-Tier)

```
PRIMITIVE → raw values (blue-500, spacing-16)
SEMANTIC  → purpose (color-primary → blue-500)
COMPONENT → scoped (button-bg → color-primary)
```

**Naming:** `{category}-{role}-{modifier}-{state}` (kebab-case)
**Modes:** Light/Dark via Figma Variable modes

## Visual Verification (ZAKON #0.1)

**ALWAYS validate builds against Figma.** Run `figma-validate.js` before claiming "done".
List DIFFERENCES, not similarities. If you can't find any differences, you're not looking carefully enough.

## Quality Checklist

- [ ] Tokens extracted from Figma (not guessed)
- [ ] Colors match Figma exactly (verified with hex comparison)
- [ ] Typography matches (font family, size, weight, line-height)
- [ ] Spacing matches (padding, gaps, margins)
- [ ] Assets exported from Figma (not hand-drawn SVG)
- [ ] Visual validation run (`figma-validate.js`)
- [ ] Difference percentage below 10%

## Reference

- **Knowledge base:** `~/system/context/figma-knowledge-base.md`
- **REST API reference:** `~/system/context/figma-rest-api-reference-2025-2026.md`
- **Config:** `~/system/config/figma.json`
- **Manifest:** `~/system/tools/manifest.md`