# /design-system

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

---
name: design-system
description: "End-to-end design-to-build pipeline for NEW projects. Stitch generates designs → Figma import → extract tokens → generate code → validate. Use for new designs from scratch."
argument-hint: "[project brief — app name, industry, brand colors, screens to design]"
---

# Design-to-Build Pipeline

Create new designs from scratch and build them into production code. For working with EXISTING Figma files, use `/figma-design` instead.

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

## The Pipeline (7 Steps)

```
BRIEF → STITCH → FIGMA → EXTRACT → BUILD → VALIDATE → DEPLOY
  ↓        ↓        ↓        ↓        ↓        ↓         ↓
 Spec    Generate  Import   Tokens   React    Compare    Ship
        (FREE)   (manual)  (auto)   (auto)   (visual)
```

### Step 1: BRIEF — Parse Requirements

Extract from request:
- **App name** and industry (fintech, SaaS, music, consulting)
- **Brand** — primary color, accent, background
- **Screens** to design (login, dashboard, send-money, etc.)
- **Elements** — what must be on screen
- **Audience** — who uses this
- **Vibe** — 3 keywords (e.g., "trustworthy, effortless, Scandinavian")

### Step 2: STITCH — Generate Design (FREE)

```bash
node ~/system/tools/stitch-generate.js \
  --brief "[APP]" --screen "[SCREEN]" --industry "[INDUSTRY]" \
  --primary "[HEX]" --secondary "[HEX]" \
  --vibe "[KW1], [KW2], [KW3]" \
  --elements "[EL1],[EL2],[EL3]" \
  --model pro --options 3
```

**Output:** 3 style variants in `~/system/design-output/stitch-<timestamp>/`

**Present for approval:**
```bash
node ~/system/tools/design-board.js create "[Project] [Screen]" "reviewer@email" \
  --options '[...png paths...]' --recommend 2
```

**WAIT for CEO/client approval before proceeding.**

### Step 3: FIGMA — Import Approved Design (Manual Step)

**Method A:** In Stitch, "Copy to Figma" → Cmd+V in Figma Desktop
**Method B:** Download HTML/CSS from Stitch → use html.to.design plugin in Figma (80-90% accuracy)
**Method C:** Use `figma-populate.js` WebSocket bridge (unreliable — last resort)

After import: **Figma IS the source of truth.** All subsequent work reads FROM Figma.

### Step 4: EXTRACT — Tokens + Assets from Figma

```bash
# Design tokens → all formats
node ~/system/tools/figma-token-sync.js <file-key> --format all --output ./tokens/

# Individual assets (logos, icons)
node ~/system/tools/figma-extract.js export-image <file-key> <node-id> --format svg --output ./public/logo.svg

# Generate implementation prompt
node ~/system/tools/figma-extract.js frame-to-prompt <file-key> <node-id>
```

### Step 5: BUILD — Code from Figma Data

**Option A: Direct Figma → React (NEW)**
```bash
node ~/system/tools/figma-to-react.js <file-key> <node-id> --output ./src/app/page.tsx
```

**Option B: Stitch HTML → React (existing)**
```bash
node ~/system/tools/design-to-code.js assemble \
  --stitch-code code.html --assets-dir exports/ --target-page page.tsx --preserve-logic
```

**Rules:**
1. Logo/icons → exported from Figma, NEVER hand-drawn SVG
2. Colors → extracted token values, not guessed hex codes
3. Typography → match extracted font/size/weight exactly
4. Spacing → match extracted spacing values
5. Layout → follow Auto Layout → Flexbox mapping

### Step 6: VALIDATE — Compare Code to Design

```bash
node ~/system/tools/figma-validate.js compare <file-key> <node-id> http://localhost:3000/page
```

**ZAKON #0.1:** List DIFFERENCES, not similarities. If diff > 10%, fix before proceeding.

### Step 7: DEPLOY

```bash
# Docker build for Fly.io
docker build -t app .
flyctl deploy

# Or Vercel
vercel --prod
```

## Design System Architecture

### Token Structure (3-Tier MANDATORY)

```
PRIMITIVE: blue-500, gray-900, spacing-16
    ↓
SEMANTIC: color-primary, text-primary, spacing-md
    ↓
COMPONENT: button-bg-primary, card-padding, input-border-focus
```

### Typography Scale (Major Third 1.25)

| Size | Use | Tailwind |
|------|-----|----------|
| 12px | Caption | `text-xs` |
| 14px | Small body | `text-sm` |
| 16px | Body (BASE) | `text-base` |
| 20px | Subtitle | `text-xl` |
| 25px | H3 | `text-2xl` |
| 31px | H2 | `text-3xl` |
| 39px | H1 | `text-4xl` |

### Spacing Grid (4px baseline + 8pt elements)

| Value | Token | Tailwind | Use |
|-------|-------|----------|-----|
| 4px | spacing-xs | `p-1` | Micro spacing |
| 8px | spacing-sm | `p-2` | Between label↔input |
| 12px | spacing-md-sm | `p-3` | Compact padding |
| 16px | spacing-md | `p-4` | Form fields |
| 24px | spacing-lg | `p-6` | Card padding |
| 32px | spacing-xl | `p-8` | Between sections |
| 48px | spacing-2xl | `p-12` | Major breaks |
| 64px | spacing-3xl | `p-16` | Hero spacing |

### Color System

**Semantic tokens (minimum set):**
- `color-primary`, `color-secondary`, `color-accent`
- `color-success`, `color-warning`, `color-error`, `color-info`
- `text-primary`, `text-secondary`, `text-disabled`
- `surface-base`, `surface-raised`, `surface-overlay`
- `border-default`, `border-focus`, `border-error`

**WCAG:** AA minimum (4.5:1 normal text, 3:1 large text)

### Elevation (5 levels)

| Level | Use | CSS |
|-------|-----|-----|
| 0 | Flat | none |
| 1 | Cards | `shadow-sm` |
| 2 | Buttons | `shadow-md` |
| 3 | Dropdowns | `shadow-lg` |
| 4 | Modals | `shadow-xl` |

## Industry Patterns

### Fintech
- Trust signals: green, navy, white
- BankID/Vipps prominence, security cues
- Biometric-first auth, generous whitespace
- Clear number formatting, transaction lists

### SaaS
- Clean layouts, data visualization
- System fonts, minimal palette
- Dashboard patterns, data tables

### Music/Creative
- Dark themes, neon accents
- Bold typography, gradient meshes
- Dynamic visuals, high contrast

### Professional Services
- Minimal, structured layouts
- Restrained palette, strong hierarchy
- Corporate, competent, reliable

## Quality Gate (MANDATORY before delivery)

- [ ] Design approved by CEO/client (Step 3 gate)
- [ ] Tokens extracted from Figma (NOT guessed)
- [ ] `figma-validate.js` run — diff < 10%
- [ ] DIFFERENCES listed explicitly
- [ ] All assets exported from Figma
- [ ] WCAG AA contrast verified
- [ ] Mobile touch targets ≥ 44px

## Reference

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