/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)

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:

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

# 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)

node ~/system/tools/figma-to-react.js <file-key> <node-id> --output ./src/app/page.tsx

Option B: Stitch HTML → React (existing)

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

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

# 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