Flowstitch

---
name: flowstitch
version: 2.0.0
description: >
  Turn one sentence into a deployed website. FlowStitch is your AI design team:
  prompt engineering, design system generation, multi-page creation, quality evaluation,
  React/TypeScript export, and one-command deploy. Scrape any competitor's site and
  build something better. Import a logo and get a full brand system. Build websites,
  admin dashboards, or mobile apps. Powered by Google Stitch MCP tools.
  Free from the Flow team.
tags: [design, ui, website, stitch, react, typescript, deploy, brand, competitive-analysis, admin-dashboard, mobile-app, tailwind, shadcn, vercel]
author: Flow team
---

# FlowStitch

## Your AI design team. Idea to deployed website — in one session.

Most tools give you a component. FlowStitch gives you a **shipped product**. Say "build me a SaaS dashboard" and it handles everything — prompt engineering, design system generation, multi-page creation, quality evaluation, React export, and Vercel deploy — without you touching a single file.

**What FlowStitch does:**
- 🚀 **Zero to Shipped** — Full pipeline: one sentence → live URL
- 🔄 **Quality Loop** — Generates, evaluates, self-corrects (up to 3 passes)
- 🕵️ **Competitive Intel** — Scrapes any competitor's site and builds something better
- 🎨 **Brand Kit Import** — Logo + colors + fonts → complete design system
- 📊 **Admin Dashboards** — KPI cards, data tables, sidebars, charts
- 📱 **Mobile Apps** — Safe areas, 44px tap targets, bottom nav, native feel
- ⚛️ **React Export** — Clean, typed, Tailwind + shadcn components
- 🌐 **One-Command Deploy** — Vercel, Netlify, or GitHub Pages

---

## Prerequisites

**Stitch MCP server must be configured** before using any generation workflows:

```bash
# Verify Stitch MCP is available
list_tools | grep -i stitch

# Add via mcporter if missing:
mcporter add stitch
```

Stitch docs + prompting guide: https://stitch.withgoogle.com/docs/learn/prompting/

---

## Workflow Routing Table

| User intent | Section |
|:---|:---|
| "build me a [X]" / "zero to shipped" / "full pipeline" | [§0 Zero to Shipped ⚡](#0-zero-to-shipped-) |
| "analyze competitor" / "reverse-engineer this site" | [§A Competitive Design Analysis 🕵️](#a-competitive-design-analysis-️) |
| "import my brand" / "brand kit" / "use my logo" | [§B Brand Kit Import 🎨](#b-brand-kit-import-) |
| "enhance my prompt" / "polish this idea" | [§1 Prompt Enhancement](#1-prompt-enhancement) |
| "create/update DESIGN.md" / "analyze my Stitch project" | [§2 Design System Synthesis](#2-design-system-synthesis) |
| "design a page" / "generate a screen" / "edit this screen" | [§3 Screen Generation & Editing](#3-screen-generation--editing) |
| "build the site" / "run the loop" / "next page" | [§4 Build Loop](#4-build-loop) |
| "quality check" / "refine" / "iterate on design" | [§5 Quality Loop](#5-quality-loop) |
| "export to React" / "convert to components" | [§6 React Component Export](#6-react-component-export) |
| "deploy" / "go live" / "push to Vercel" | [§7 Deploy](#7-deploy) |
| "make a video" / "walkthrough video" | [§8 Video Walkthrough](#8-video-walkthrough-remotion) |
| "add shadcn" / "use shadcn components" | [§9 shadcn/ui Integration](#9-shadcnui-integration) |

When intent is ambiguous: *"Are you starting from scratch, analyzing a competitor, or continuing an existing project?"*

---

## §0 Zero to Shipped ⚡

**Goal:** Take one sentence from the user and produce a fully deployed, multi-page website or app with zero manual steps.

You handle everything. No hand-holding. No manual steps.

### The Pipeline

```
User prompt
    ↓
[1] Extract intent (product, audience, vibe)
    ↓
[2] Enhance prompt (§1)
    ↓
[3] Generate DESIGN.md from first screen (§2)
    ↓
[4] Build all pages via loop (§4) — typically 4–6 pages
    ↓
[5] Quality loop on each page (§5) — up to 3 refinement passes
    ↓
[6] Export to React (§6)
    ↓
[7] Live preview → Deploy (§7)
```

### Step 1 — Extract Intent

From the user's description, identify:
- **Product name** and **one-line value prop**
- **Target audience** (developers, designers, enterprise, consumers...)
- **Vibe signals** (any adjectives: "clean", "bold", "minimal", "playful")
- **Page requirements** (infer standard set if not specified)

**Standard page set by type:**

| Site type | Pages |
|:---|:---|
| SaaS landing | index, features, pricing, about, contact |
| Portfolio | index, work, about, contact |
| Startup / marketing | index, product, about, blog-index, contact |
| E-commerce | index, catalog, product-detail, about, contact |
| App / tool | index, features, docs-index, pricing |

### Step 2 — Initialize Project

```bash
mkdir -p .stitch/designs site/public
```

Create `.stitch/SITE.md` using the template from [resources/site-template.md](resources/site-template.md). Populate:
- Product name, mission, target audience, voice
- Visual language (inferred from vibe signals)
- Initial sitemap with all planned pages as unchecked `[ ]`

### Step 3 — Generate First Screen & DESIGN.md

1. Run prompt enhancement on the landing page (§1)
2. Create Stitch project: `[prefix]:create_project`
3. Generate `index` screen: `[prefix]:generate_screen_from_text`
4. Save to `.stitch/metadata.json`
5. Download screenshot + HTML
6. **Run §2 (Design System Synthesis)** on the generated screen → write `.stitch/DESIGN.md`

This DESIGN.md becomes the visual DNA for every subsequent page.

### Step 4 — Build Remaining Pages

For each remaining page in the sitemap:
1. Write baton to `.stitch/next-prompt.md` (include DESIGN.md Section 6 block)
2. Generate screen via Stitch
3. Download assets
4. Run **§5 Quality Loop** — evaluate and refine until score ≥ 8/10 or 3 passes complete
5. Integrate into `site/public/`, wire navigation
6. Update SITE.md sitemap

### Step 5 — React Export

Run §6 on all pages. Output: `src/components/` with typed, modular components.

### Step 6 — Preview & Deploy

```bash
npm run dev   # Local preview

# When ready:
npx vercel --prod   # or: npx netlify deploy --prod --dir=site/public
```

Surface the live URL to the user.

### Progress Reporting

After each page completes, report:
```
✅ index.html — generated + quality passed (score: 9/10, 1 refinement)
✅ features.html — generated + quality passed (score: 8/10, 2 refinements)
🔄 pricing.html — generating...
```

At the end:
```
🚀 FlowStitch complete!
   5 pages generated | 3 refined | React exported | Deployed
   Live URL: https://your-project.vercel.app
   Build time: ~8 minutes
```

**HARD LIMIT:** Max 5 pages × 3 quality passes = 15 Stitch calls. If budget exceeded, skip quality loop on remaining pages and deploy what's clean.

---

## §0 Error Handling

**Goal:** Recover from Stitch tool failures and download errors without aborting a multi-page build.

| Failure | Action |
|:---|:---|
| Tool call error | Check JSON structure vs tool-schemas.md; verify projectId format |
| Project not found | Run `list_projects` to confirm ID; create new project if needed |
| Download fails | Re-run `fetch-stitch.sh` with quoted URL (GCS URLs expire ~1h) |
| Generation fails mid-loop | Mark page ⚠️ in progress report, write baton to NEXT page, continue |
| Quality loop fails 3x | Accept best result, note score, continue to next page |

**Always download assets before running quality loop** — download first, then evaluate.

---

## §A Competitive Design Analysis 🕵️

**Goal:** Reverse-engineer a competitor's design language and build something better-informed and visually differentiated.

**Give it a competitor URL. Get a battle-ready design system back.**

This is how you build something that looks better than what's already out there, informed by what already works.

### Step 1 — Scrape the Competitor

```python
# Use web_fetch for clean extraction
url = "[competitor URL]"
html = web_fetch(url)
```

If the site is JS-heavy or blocks scrapers, use the browser tool:
```
browser: navigate to [url], snapshot, screenshot
```

Also fetch their CSS if accessible (look for `<link rel="stylesheet">` in HTML head).

### Step 2 — Extract Design Language

Analyze the scraped HTML/CSS for:

**Colors:**
- CSS custom properties (`--primary`, `--background`, `--foreground`, etc.)
- Most-used hex/rgb values in inline styles or Tailwind classes
- Button colors, link colors, background colors, text colors

**Typography:**
- `font-family` declarations (Google Fonts links in `<head>` are a goldmine)
- Font size patterns (`text-4xl`, `text-lg`, etc.)
- Font weights used for headings vs. body

**Layout patterns:**
- Max-width containers (e.g., `max-w-7xl`, `max-w-screen-xl`)
- Grid and flex patterns
- Section padding/margin scale

**Components:**
- Navigation style (minimal? mega-menu? centered logo?)
- CTA button shape (rounded? pill? square?)
- Card patterns (shadow? border? glassmorphism?)
- Hero layout (full-width image? split? gradient?)

**Overall vibe:**
- Describe it in 3 adjectives
- Identify what works well and what you'd improve

### Step 3 — Generate Competitor DESIGN.md

Write to `.stitch/competitor-DESIGN.md`:

```markdown
# Competitor Design Analysis: [Brand Name]
**Source URL:** [URL]
**Analyzed:** [date]

## What They Did Well
[3–5 specific observations]

## What's Missing / Weak
[3–5 specific gaps or dated choices]

## 1. Visual Theme & Atmosphere
[Analysis]

## 2. Color Palette (Extracted)
- **[Name]** (#hex) — [role observed]

## 3. Typography
[Font stack, weight patterns]

## 4. Layout Patterns
[Max-width, grid, spacing]

## 5. Component Patterns
[Buttons, cards, nav style]
```

### Step 4 — Generate Your Improved DESIGN.md

Now synthesize a `.stitch/DESIGN.md` that:
- **Keeps** what works (proven color contrast, clean grid)
- **Improves** what's weak (modernize dated typography, add personality to generic layouts)
- **Differentiates** intentionally (if they're dark, go light; if they're cold, go warm)

Tell the user: *"Here's what [Competitor] is doing and here's how we're going to beat them at their own game."*

Then run §0 Zero to Shipped (starting at Step 3) using this new DESIGN.md.

---

## §B Brand Kit Import 🎨

**Goal:** Transform raw brand assets (logo, colors, fonts) into a complete, production-ready design system.

**Drop in a logo, colors, and fonts. Get a complete design system back.**

Eliminates the #1 reason designs look generic: they don't reflect the actual brand.

### What You Need (Any Combination)

- **Logo file** — PNG, SVG, or URL (image analysis will extract dominant colors)
- **Brand colors** — Hex codes, even if just one primary color
- **Fonts** — Google Font names, or just "use something like [brand adjective]"
- **Vibe words** — How the brand should feel
- **Inspiration** — "Like Linear but warmer" / "Like Stripe but for small business"

You can work with as little as a logo alone.

### Step 1 — Analyze Logo (if provided)

Use the `image` tool to analyze the logo:

```
Analyze this logo image. Extract:
1. Primary color (most prominent, usually the brand color)
2. Secondary color (accent or complement)
3. Background/neutral color
4. Overall style (geometric? organic? minimal? bold?)
5. Adjectives that describe the brand personality
```

Map extracted colors to roles:
- Primary brand color → Primary Accent
- Dark version or complementary → Text Primary / CTA
- Light version → Surface / Background

### Step 2 — Build the Color System

From the provided/extracted colors, derive a full palette:

| Role | Source |
|:---|:---|
| **Primary Accent** | Main brand color from logo/brief |
| **Background** | If dark brand → near-black canvas; if light brand → warm white or cream |
| **Surface** | 4–8% lighter or darker than background |
| **Text Primary** | High-contrast against background (≥4.5:1 ratio) |
| **Text Secondary** | 60–70% opacity of text primary |
| **Border/Divider** | Subtle version of surface, barely visible |
| **Success/Error** | Industry-standard green/red unless brand specifically defines |

**Color naming rule:** Every color must have a descriptive name, not a technical one.
- ✅ "Electric Indigo (#6366f1) for primary actions"
- ❌ "Purple (#6366f1) for buttons"

### Step 3 — Select Typography

If fonts are provided: validate they're available on Google Fonts, confirm loading.

If not provided, select based on brand personality:

| Brand feel | Font recommendation |
|:---|:---|
| Technical / SaaS | Inter, Geist, or JetBrains Mono for code |
| Premium / luxury | Playfair Display (display) + Inter (body) |
| Friendly / consumer | Nunito, Poppins, or Outfit |
| Editorial / media | Fraunces (display) + Source Serif 4 (body) |
| Startup / modern | Cal Sans or Plus Jakarta Sans |
| Minimalist | DM Sans or Figtree |

Define the full type scale: display size, H1–H3, body, small/meta.

### Step 4 — Write DESIGN.md

Generate a complete `.stitch/DESIGN.md` with all 6 sections populated from the brand analysis.

Section 6 must be immediately usable as a Stitch prompt block — copy-paste ready.

Confirm with the user:
```
🎨 Brand kit imported. Here's what I built:

Primary: Cobalt Blue (#2563eb) — your main brand color
Accent: Electric Sky (#7dd3fc) — highlights and links  
Background: Deep Navy (#0f172a) — canvas
Font: Inter (body) + Cal Sans (display)

Does this capture your brand? Say "looks good" to continue,
or describe any changes.
```

Wait for approval before proceeding to generation.

---

## §1 Prompt Enhancement

**Goal:** Transform a vague UI idea into a structured, Stitch-optimized prompt that produces high-fidelity, consistent results.

Always run this before calling any Stitch generation tool.

### Step 1 — Assess Gaps

| Missing element | Action |
|:---|:---|
| Platform | Infer from context or default to Web, Desktop-first |
| Page type | Infer (landing page, dashboard, form, etc.) |
| Visual style | Add atmosphere keywords (see [references/prompt-keywords.md](references/prompt-keywords.md)) |
| Color palette | Apply DESIGN.md Section 6 if available; otherwise suggest |
| Component names | Translate vague → specific (see [references/design-mappings.md](references/design-mappings.md)) |

### Step 2 — Check for DESIGN.md

- **If `.stitch/DESIGN.md` exists:** Extract Section 6 verbatim as the `DESIGN SYSTEM (REQUIRED)` block.
- **If missing:** Suggest creating one via §2 or §B. Add tip at prompt end.

### Step 3 — Format Output

```markdown
[One-line vibe + purpose description]

**DESIGN SYSTEM (REQUIRED):**
- Platform: [Web/Mobile], [Desktop/Mobile]-first
- Theme: [Light/Dark], [2–3 style descriptors]
- Background: [Descriptive Name] (#hex)
- Primary Accent: [Descriptive Name] (#hex) for [role]
- Text Primary: [Descriptive Name] (#hex)
- Font: [Description]
- Buttons: [Shape and padding description]
- Cards: [Corner radius and shadow description]
- Layout: [Container width, spacing philosophy]

**Page Structure:**
1. **[Section]:** [Specific description]
2. **[Section]:** [Specific description]
...
```

### Step 4 — Accessibility

Always add to Page Structure: "All interactive elements have visible focus rings. Minimum 44px tap targets. Color contrast ≥4.5:1 (WCAG AA)."

See [examples/enhanced-prompt.md](examples/enhanced-prompt.md) for before/after reference.

---

## §2 Design System Synthesis

**Goal:** Analyze a Stitch project's screens and generate `.stitch/DESIGN.md`.

### Step 1 — Retrieve Assets

1. `list_tools` → find Stitch MCP prefix
2. `[prefix]:list_projects` (filter: "view=owned") if no project ID
3. `[prefix]:list_screens` if no screen ID
4. `[prefix]:get_screen` with both IDs (numeric only)
5. `web_fetch` the `htmlCode.downloadUrl` → parse Tailwind config from `<head>`
6. `[prefix]:get_project` (full `projects/{id}` path) → get `designTheme`

### Step 2 — Analyze

Extract and translate:
- **Atmosphere:** 2–3 evocative adjectives describing mood and density
- **Colors:** Name + hex + role for every distinct color used
- **Typography:** Font family character, weight hierarchy, spacing style
- **Geometry:** CSS border-radius → natural language (see [references/prompt-keywords.md](references/prompt-keywords.md))
- **Depth:** Shadow philosophy (flat / whisper-soft / floating / dramatic)
- **Layout:** Grid, max-width, spacing scale, section margins

### Step 3 — Write `.stitch/DESIGN.md`

Follow the 6-section structure. Section 6 is the most critical — it must be verbatim-copyable into any Stitch prompt and produce consistent results.

See [examples/DESIGN.md](examples/DESIGN.md) for gold-standard reference.

---

## §2A Admin Dashboard Design Patterns

**Goal:** Generate data-dense, functional admin dashboards that look premium, not bloated.

Admin dashboards are a distinct design context: information-dense, utility-first, with clear visual hierarchy for data scanning. Always add `data-dense, utilitarian` to Platform in the DESIGN SYSTEM block.

**Key dashboard DESIGN SYSTEM additions:**
```
- Platform: Web, Desktop-first, data-dense, admin panel
- Sidebar: 240px expanded (icon+label) / 60px collapsed (icon-only)
- Tables: Striped rows, hover highlight, fixed header, 40px row height
- Charts: [accent] primary line, barely-visible grid lines
```

**Component patterns** (detailed examples in [examples/admin-dashboard.md](examples/admin-dashboard.md)):

| Component | Pattern |
|:---|:---|
| KPI Card | Bold 2.5rem value, label, trend arrow + %, semantic color |
| Data Table | Fixed header, alternating rows, sortable columns, pagination |
| Sidebar | Collapsed/expanded toggle, accent strip on active item |
| Filter Bar | Search + dropdowns + active chips + clear |
| Chart Wrapper | Title + time range selector + legend |

---

## §2B Mobile App Design Patterns

**Goal:** Generate native-feeling mobile screens with proper touch ergonomics.

Mobile apps require: bottom tab navigation, 44px minimum tap targets, status bar + home indicator safe areas.

**Key mobile DESIGN SYSTEM additions:**
```
- Platform: Mobile, iOS-first
- Navigation: Bottom tab bar (49px height, 5 tabs max)
- Buttons: Full-width, minimum 52px height
- Safe Areas: 47px status bar (top), 34px home indicator (bottom) — no interactive elements
- Minimum tap target: 44×44px for ALL interactive elements
```

**Mobile specs** (full examples in [examples/mobile-app.md](examples/mobile-app.md)):

| Element | Specification |
|:---|:---|
| Bottom nav | 49px height (iOS), 56px (Android MD3) |
| Status bar safe area | 44–47px at top |
| Home indicator safe area | 34px at bottom |
| Min tap target | 44×44px |
| Min font size | 16px body (never smaller) |

---

## §3 Screen Generation & Editing

**Goal:** Create and refine Stitch screens with correct tool calls and reliable asset downloads.

**Namespace first:** Always `list_tools` to find active Stitch MCP prefix.

### Generate

```json
{
  "projectId": "4044680601076201931",
  "prompt": "[Enhanced prompt from §1 — must include DESIGN SYSTEM block]",
  "deviceType": "DESKTOP"
}
```

After generation:
1. Update `.stitch/metadata.json` via `[prefix]:get_project`
2. Download HTML → `.stitch/designs/{page}.html`
3. Download screenshot (append `=w{width}`) → `.stitch/designs/{page}.png`
4. Surface `outputComponents` AI suggestions to user

### Edit (prefer over regenerating)

```json
{
  "projectId": "4044680601076201931",
  "selectedScreenIds": ["screenId"],
  "prompt": "One specific, targeted change. Preserve everything else."
}
```

Full tool schemas: [references/tool-schemas.md](references/tool-schemas.md)

---

## §4 Build Loop

**Goal:** Autonomously generate all pages of a site using the baton-passing pattern.

### Prerequisites

- `.stitch/DESIGN.md` — the visual DNA (run §2 first)
- `.stitch/SITE.md` — sitemap, roadmap, visual language
- `.stitch/next-prompt.md` — the baton (current task)

### Each Iteration

1. **Read baton** — parse `page` from YAML frontmatter, prompt from body
2. **Check sitemap** — skip pages already marked `[x]` in SITE.md Section 4
3. **Generate** — call `[prefix]:generate_screen_from_text` with full DESIGN.md Section 6 block
4. **Quality loop** — run §5 on the generated screen (up to 3 passes)
5. **Integrate** — move to `site/public/`, fix paths, wire navigation
6. **Update SITE.md** — mark page `[x]` in sitemap
7. **Write next baton** ⚠️ — MUST happen before completing iteration

### Baton Format

```markdown
---
page: pricing
---
[One-line description + full DESIGN SYSTEM block + Page Structure]
```

Schema: [resources/baton-schema.md](resources/baton-schema.md)

### metadata.json Schema

```json
{
  "projectId": "6139132077804554844",
  "title": "My App",
  "deviceType": "DESKTOP",
  "screens": {
    "index": {
      "id": "abc123",
      "sourceScreen": "projects/6139132077804554844/screens/abc123",
      "width": 1440, "height": 900
    }
  }
}
```

### Pitfalls
- ❌ Forgetting to update `next-prompt.md` — breaks the loop
- ❌ Rebuilding existing pages — check sitemap first
- ❌ Dropping the DESIGN.md Section 6 block from prompts — causes visual drift

---

## §5 Quality Loop

**Goal:** Evaluate every generated screen against DESIGN.md criteria, score it out of 10, and refine until it passes (≥8/10) or 3 passes are exhausted.

Most AI design tools generate and move on. FlowStitch checks its own work.

### How It Works

After any screen generation, run this loop:

```
Generate screen
    ↓
Download screenshot
    ↓
Evaluate against DESIGN.md criteria → score /10
    ↓
Score ≥ 8? → PASS → continue
Score < 8? → Generate targeted edit prompt → edit_screens → re-evaluate
    ↓
Maximum 3 passes total. After 3, accept best result and note gaps.
```

### Evaluation Criteria

Score each screen on these dimensions (2 points each, total 10):

**1. Color Fidelity (0–2)**
- All colors match DESIGN.md palette within 10% perceptual distance
- No rogue colors introduced; no gradient where solid was specified
- Deduct 1 if any major element uses wrong color family

**2. Typography Adherence (0–2)**
- Font family matches specification
- Weight hierarchy correct (bold headlines, regular body)
- No inconsistent sizes or mixed font families
- Deduct 1 if font family visually differs from spec

**3. Layout & Spacing (0–2)**
- Component structure matches Page Structure spec (sections present and ordered)
- Spacing feels consistent with DESIGN.md principles
- Max-width container applied; grid alignment clean
- Deduct 1 if major sections missing or order wrong

**4. Component Quality (0–2)**
- Buttons, cards, inputs match DESIGN.md component stylings
- Corner radii, shadows, borders match descriptions
- Navigation style matches spec
- Deduct 1 if components clearly deviate (pill buttons when square specified, etc.)

**5. Atmosphere Match (0–2)**
- Overall visual impression matches DESIGN.md atmosphere description
- Density, whitespace, mood are aligned
- Screenshot could plausibly appear on the target brand's website
- Deduct 1–2 if vibe feels completely off

### Scoring Action

| Score | Action |
|:---|:---|
| 8–10 | ✅ PASS — proceed |
| 6–7 | 🔄 Refine — generate targeted edit, re-evaluate |
| 4–5 | 🔄 Refine — significant edit prompt, may need regeneration |
| 0–3 | 🔄 Regenerate from scratch with stronger prompt |

### Targeted Edit Prompt Formula

When score < 8, generate an edit prompt targeting only the failing dimensions:

```
Fix the following issues while preserving all correct elements:

[List specific issues with precise descriptions]

Example issues:
- "The CTA button is using orange (#f97316) but should be Deep Blue (#2563eb)"
- "The hero section font appears to be serif — change to Inter or system sans-serif"
- "The card corners are too sharp — apply gently rounded 12px corners"
- "Section spacing is too tight — add 80px between major sections"

Make ONLY these changes. Preserve all other visual elements exactly.
```

### Pass Log

After completing the quality loop, write to `.stitch/quality-log.json`:

```json
{
  "index": {
    "passes": 2,
    "finalScore": 9,
    "issues": ["Typography needed correction on pass 1"]
  },
  "pricing": {
    "passes": 1,
    "finalScore": 8,
    "issues": []
  }
}
```

---

## §6 React Component Export

**Goal:** Convert Stitch HTML into modular, typed Vite + React/TypeScript components.

### Step 1 — Get Assets

Check if `.stitch/designs/{page}.html` exists. If not, download:

```bash
bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" ".stitch/designs/{page}.html"
bash scripts/fetch-stitch.sh "[screenshot.downloadUrl]=w{width}" ".stitch/designs/{page}.png"
```

The `fetch-stitch.sh` script handles GCS redirects and TLS handshakes that raw fetch tools fail on.

### Step 2 — Extract Style Tokens

Parse `tailwind.config` from the HTML `<head>`. Sync to your project's Tailwind theme. Use only theme-mapped classes — no raw hex values in component code.

### Step 3 — Build Components

**Architecture rules** (non-negotiable):
- One component per file
- Business logic → `src/hooks/`
- Static data → `src/data/mockData.ts`
- Every component has a `Readonly<T>` props interface named `[Name]Props`
- No `any` types

Start from [resources/component-template.tsx](resources/component-template.tsx). Reference [examples/gold-standard-card.tsx](examples/gold-standard-card.tsx) for the pattern.

### Step 3a — Class Composition with cn()

Use `cn()` (from `@/lib/utils`) for any conditional or composed class strings:

```typescript
import { cn } from "@/lib/utils"
// ✅ Correct: theme classes + conditional + override
className={cn("rounded-lg bg-surface p-4", isActive && "ring-2 ring-primary", className)}
// ❌ Wrong: hardcoded hex in className
className="bg-[#2563eb]"
```

### Step 3b — Wire Entry Point

Wire components into `App.tsx` or `src/pages/` after building:

```typescript
// src/App.tsx — import and render each page component
export default function App() {
  return <main><HeroSection /><FeaturesGrid /></main>
}
```

### Step 3c — Admin Dashboard Components

For admin dashboards, create: `DataTable.tsx`, `KPICard.tsx`, `ChartWrapper.tsx`, `FilterBar.tsx`, `Sidebar.tsx` in `src/components/dashboard/` and `src/components/layout/`.

### Step 3d — Performance Patterns

```typescript
// Code splitting: lazy-load route-level components for faster initial load
const DashboardPage = lazy(() => import('./pages/DashboardPage'))
// Images: loading="lazy" decoding="async" on all non-hero images
// Lists >100 items: comment suggesting react-window virtualization
```

### Step 4 — Quality Gate

```bash
npm run validate <file>   # TypeScript + architecture check
npm run dev               # Visual verification in browser
```

Full checklist: [resources/architecture-checklist.md](resources/architecture-checklist.md)

Sync Tailwind config to `resources/style-guide.json` (extract from Stitch HTML `<head>` `tailwind.config` block).

---

## §7 Deploy

**Goal:** Get the site live with one command after React export.

### Option A — Vercel (Recommended)

```bash
# First time
npm install -g vercel
vercel login

# Deploy
vercel --prod

# Output: https://your-project.vercel.app
```

For React/Vite projects, Vercel auto-detects the framework. No config needed.

If deploying raw HTML from `site/public/`:
```bash
vercel --prod site/public/
```

### Option B — Netlify

```bash
# First time
npm install -g netlify-cli
netlify login

# Deploy raw HTML
netlify deploy --prod --dir=site/public

# Deploy React build
npm run build
netlify deploy --prod --dir=dist
```

### Option C — GitHub Pages (Static HTML only)

```bash
# From site/public/
git init && git add . && git commit -m "initial"
git remote add origin https://github.com/[user]/[repo].git
git push -u origin main

# Enable Pages in repo Settings → Pages → Deploy from branch: main
```

### Pre-Deploy: SEO & Metadata

Add to each page's `<head>` before deploying:

```html
<!-- Core SEO -->
<title>[Page Title] | [Brand Name]</title>
<meta name="description" content="[Page description, 150-160 chars]">
<link rel="canonical" href="https://[your-domain]/[page]">

<!-- Open Graph (social sharing) -->
<meta property="og:title" content="[Page Title]">
<meta property="og:description" content="[Description]">
<meta property="og:image" content="https://[your-domain]/og-image.png">
<meta property="og:url" content="https://[your-domain]">
<meta property="og:type" content="website">

<!-- Favicon -->
<link rel="icon" href="/favicon.ico">
<link rel="apple-touch-icon" href="/apple-touch-icon.png">

<!-- Font performance: preload + display=swap -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preload" as="style" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap">
<link rel="stylesheet" href="...&display=swap">
```

**Image optimization before deploy:**
```bash
# Compress images (install: npm install -g sharp-cli)
sharp -i public/hero.jpg -o public/hero.jpg --quality 85
# Or use Squoosh (squoosh.app) for manual optimization
```

### Post-Deploy Checklist

- [ ] All pages load (spot-check 3+ pages)
- [ ] Navigation links work across all pages
- [ ] Images load (check browser network tab)
- [ ] Mobile responsive (resize or use DevTools)
- [ ] No console errors
- [ ] OG tags render correctly (test: https://opengraph.xyz)
- [ ] Page titles and meta descriptions are set per page
- [ ] Favicon appears in browser tab
- [ ] Share the live URL with the user 🎉

---

## §8 Video Walkthrough (Remotion)

**Goal:** Generate a professional walkthrough video from Stitch screens.

### Setup

```bash
npm create video@latest -- --blank
cd video
npm install @remotion/transitions @remotion/animated-emoji
```

### Workflow

1. `[prefix]:list_screens` → gather all screen IDs
2. `[prefix]:get_screen` for each → get dimensions + download URLs
3. Download screenshots at full res (append `=w{width}`) → `public/assets/screens/`
4. Create `screens.json` manifest (see [resources/composition-checklist.md](resources/composition-checklist.md))
5. Build `ScreenSlide.tsx` + `WalkthroughComposition.tsx` components
6. Preview: `npm run dev` → Remotion Studio
7. Render: `npx remotion render WalkthroughComposition output.mp4 --codec h264`

Transitions: Fade (`@remotion/transitions/fade`) for general use, Slide for sequential flows, Zoom via `spring()` for feature highlights.

Full quality gate: [resources/composition-checklist.md](resources/composition-checklist.md)

---

## §9 shadcn/ui Integration

**Goal:** Layer production-grade accessible components on top of Stitch designs.

### Setup

```bash
npx shadcn@latest init   # existing project
# or
npx shadcn@latest create # new project with full config
```

### MCP Discovery

```
list_tools | grep shadcn  # find prefix
[prefix]:list_components  # browse catalog
[prefix]:get_component_demo  # see usage
[prefix]:get_block           # full UI blocks
```

### Install

```bash
npx shadcn@latest add button card dialog form table
```

### Key Patterns

**Always use `cn()` for class composition:**
```typescript
import { cn } from "@/lib/utils"
className={cn("base", conditional && "extra", className)}
```

**Extend, never modify `components/ui/`:**
```typescript
// components/brand-button.tsx
import { Button } from "@/components/ui/button"
export function BrandButton({ ...props }) {
  return <Button className="bg-primary rounded-full px-8" {...props} />
}
```

**Theme via CSS variables in `globals.css`:**
```css
:root { --primary: 221.2 83.2% 53.3%; }
.dark { --primary: 213.1 93.9% 67.8%; }
```

---

## File Reference

| Path | Purpose |
|:---|:---|
| `references/prompt-keywords.md` | UI/UX keywords, adjective palettes, shape translations, admin + mobile patterns |
| `references/design-mappings.md` | Vague → professional term mappings, vibe descriptors, anti-patterns, gradient rules |
| `references/tool-schemas.md` | Stitch MCP tool call formats with examples |
| `resources/baton-schema.md` | Build loop baton format + validation checklist |
| `resources/site-template.md` | SITE.md + DESIGN.md starter templates |
| `resources/style-guide.json` | Tailwind config sync reference + CSS custom property template |
| `resources/component-template.tsx` | React component starter (Readonly<T>, cn(), dark mode — replace StitchComponent) |
| `resources/architecture-checklist.md` | React export quality gate (includes admin dashboard + mobile checklists) |
| `resources/composition-checklist.md` | Remotion video quality gate |
| `resources/quality-rubric.md` | Design quality evaluation scoring guide |
| `examples/enhanced-prompt.md` | Before/after prompt enhancement examples (landing page + login + edit) |
| `examples/DESIGN.md` | Gold-standard DESIGN.md (furniture/e-commerce example) |
| `examples/brand-kit-import.md` | Full §B Brand Kit Import walkthrough (Driftwood startup) |
| `examples/competitive-analysis.md` | Full §A Competitive Analysis walkthrough (Linear vs Loopback) |
| `examples/admin-dashboard.md` | Admin dashboard DESIGN.md + prompt template + component structure |
| `examples/mobile-app.md` | Mobile app DESIGN.md + screen prompt + safe area implementation |
| `examples/gold-standard-card.tsx` | Reference React component (ActivityCard — Readonly<T>, dark mode, a11y) |
| `scripts/fetch-stitch.sh` | Reliable Stitch asset downloader (handles GCS redirects/TLS) |