FlowStitch

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.

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 ⚡
"analyze competitor" / "reverse-engineer this site"	§A Competitive Design Analysis 🕵️
"import my brand" / "brand kit" / "use my logo"	§B Brand Kit Import 🎨
"enhance my prompt" / "polish this idea"	§1 Prompt Enhancement
"create/update DESIGN.md" / "analyze my Stitch project"	§2 Design System Synthesis
"design a page" / "generate a screen" / "edit this screen"	§3 Screen Generation & Editing
"build the site" / "run the loop" / "next page"	§4 Build Loop
"quality check" / "refine" / "iterate on design"	§5 Quality Loop
"export to React" / "convert to components"	§6 React Component Export
"deploy" / "go live" / "push to Vercel"	§7 Deploy
"make a video" / "walkthrough video"	§8 Video Walkthrough
"add shadcn" / "use shadcn components"	§9 shadcn/ui 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

text

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. 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:

text

✅ 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:

text

🚀 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:

text

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:

text

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:

text

🎨 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)
Color palette	Apply DESIGN.md Section 6 if available; otherwise suggest
Component names	Translate vague → specific (see 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 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)
• 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 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:

text

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

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:

text

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

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

---

§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

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:

text

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:

text

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. Reference 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

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

---

§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

text

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, 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, dark mode, a11y)
scripts/fetch-stitch.sh	Reliable Stitch asset downloader (handles GCS redirects/TLS)