# Design-to-Code Pipeline Patterns

Orchestration workflows chaining Stitch design generation with ClaudeKit implementation skills.

## Basic Pipeline

```
Prompt -> Stitch Generate -> Export HTML -> Claude Implements Components
```

### Steps

1. User describes desired UI in natural language
2. Run `stitch-generate.ts` with the prompt
3. Show preview image to user for approval
4. Run `stitch-export.ts --format all` to get HTML + DESIGN.md
5. Hand DESIGN.md to implementation skill
6. Implementation skill reads DESIGN.md and codes components

### Example

```bash
# 1. Generate
npx tsx stitch-generate.ts "E-commerce product page with image gallery, price, reviews, add-to-cart button"

# 2. Export
npx tsx stitch-export.ts <screen-id> --format all --output ./stitch-exports/

# 3. Implementation skill reads ./stitch-exports/DESIGN.md
# 4. Activate ck:frontend-design to implement React components from the spec
```

## Advanced Pipeline (with Variants)

```
Prompt -> Generate -> Variants -> User Picks -> Export -> Implement
```

### Steps

1. Generate base design
2. Generate 2-3 variants with different aspects (color, layout)
3. Show all variants to user
4. User selects preferred variant
5. Export selected variant
6. Hand off to implementation

### Example

```bash
# Generate with variants
npx tsx stitch-generate.ts "SaaS pricing page" --variants 3

# User reviews images, picks variant 2
npx tsx stitch-export.ts <variant-2-screen-id> --format all
```

## DESIGN.md Specification

DESIGN.md is an agent-readable markdown file containing extracted design tokens.

### Structure

```markdown
# Design System

## Colors
- `bg-blue-600` (primary background)
- `text-gray-900` (body text)
- `border-gray-200` (dividers)

## Typography
- `text-2xl font-bold` (headings)
- `text-base font-normal` (body)

## Spacing
- `p-4` (card padding)
- `gap-6` (grid gaps)

## Components
- `<nav>` (top navigation)
- `<section>` (content sections)
- `<form>` (user inputs)
- `<button>` (actions)

## Notes
- Generated by Google Stitch AI
- Tailwind CSS utility classes
```

### How Implementation Skills Consume It

1. Skill checks for `DESIGN.md` in project root or plan directory
2. If found: reads tokens and uses them as constraints for implementation
3. If not found: falls back to text-based design (existing behavior)
4. DESIGN.md takes precedence over verbal design descriptions

## Skill Routing

| Design Need | Skill | What It Does |
|-------------|-------|-------------|
| React/Vue/Svelte components | `ck:frontend-design` | Converts Tailwind HTML to framework components |
| Full page with style guide | `ck:ui-ux-pro-max` | Builds complete layouts with design system |
| Design token extraction | `ck:ui-styling` | Extracts shadcn/Tailwind tokens from DESIGN.md |

## Handoff Protocol

1. `ck:stitch` exports artifacts to `./stitch-exports/` (or plan directory)
2. Copy `DESIGN.md` to project root if implementation skill expects it there
3. Activate target skill with instruction: "Implement from DESIGN.md in project root"
4. Target skill reads DESIGN.md, applies tokens, generates code
5. No modifications needed to existing skills — they read DESIGN.md opportunistically

## Quota-Aware Pipeline

Always check quota before generating:

```bash
# Pre-check
npx tsx stitch-quota.ts check

# If exhausted (exit code 2):
# -> Skip Stitch, use ck:ui-ux-pro-max for text-based design instead

# If available:
npx tsx stitch-generate.ts "<prompt>"
npx tsx stitch-quota.ts increment
```