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:

CODEBLOCK0

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

CODEBLOCK1

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

CODEBLOCK2

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 INLINECODE1

Step 3 — Generate First Screen & DESIGN.md

1. 1. Run prompt enhancement on the landing page (§1)
2. Create Stitch project: INLINECODE2
3. Generate index screen: INLINECODE4
4. Save to INLINECODE5
5. Download screenshot + HTML
6. Run §2 (Design System Synthesis) on the generated screen → write INLINECODE6

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

Step 4 — Build Remaining Pages

For each remaining page in the sitemap:

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

CODEBLOCK3

Surface the live URL to the user.

Progress Reporting

After each page completes, report:
CODEBLOCK4

At the end:
CODEBLOCK5

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

CODEBLOCK6

If the site is JS-heavy or blocks scrapers, use the browser tool:
CODEBLOCK7

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:

CODEBLOCK8

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:

CODEBLOCK9

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

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

CODEBLOCK11

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. 1. list_tools → find Stitch MCP prefix
2. INLINECODE30 (filter: "view=owned") if no project ID
3. INLINECODE31 if no screen ID
4. INLINECODE32 with both IDs (numeric only)
5. INLINECODE33 the htmlCode.downloadUrl → parse Tailwind config from INLINECODE35
6. INLINECODE36 (full projects/{id} path) → get INLINECODE38

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

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

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

CODEBLOCK14

After generation:

1. 1. Update .stitch/metadata.json via INLINECODE43
2. Download HTML → INLINECODE44
3. Download screenshot (append =w{width}) → INLINECODE46
4. Surface outputComponents AI suggestions to user

Edit (prefer over regenerating)

CODEBLOCK15

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)
• INLINECODE49 — sitemap, roadmap, visual language
• INLINECODE50 — the baton (current task)

Each Iteration

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

CODEBLOCK16

Schema: resources/baton-schema.md

metadata.json Schema

CODEBLOCK17

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:

CODEBLOCK18

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:

CODEBLOCK19

Pass Log

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

CODEBLOCK20

---

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

CODEBLOCK21

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 → INLINECODE62
• Static data → INLINECODE63
• Every component has a Readonly<T> props interface named INLINECODE65
• 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:

CODEBLOCK22

Step 3b — Wire Entry Point

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

CODEBLOCK23

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

CODEBLOCK24

Step 4 — Quality Gate

CODEBLOCK25

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)

CODEBLOCK26

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

If deploying raw HTML from site/public/:
CODEBLOCK27

Option B — Netlify

CODEBLOCK28

Option C — GitHub Pages (Static HTML only)

CODEBLOCK29

Pre-Deploy: SEO & Metadata

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

CODEBLOCK30

Image optimization before deploy:
CODEBLOCK31

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

CODEBLOCK32

Workflow

1. 1. [prefix]:list_screens → gather all screen IDs
2. INLINECODE84 for each → get dimensions + download URLs
3. Download screenshots at full res (append =w{width}) → INLINECODE86
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: INLINECODE91

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

CODEBLOCK33

MCP Discovery

CODEBLOCK34

Install

CODEBLOCK35

Key Patterns

Always use cn() for class composition:
CODEBLOCK36

Extend, never modify components/ui/:
CODEBLOCK37

Theme via CSS variables in globals.css:

:root { --primary: 221.2 83.2% 53.3%; }
.dark { --primary: 213.1 93.9% 67.8%; }

---

File Reference

Path	Purpose
INLINECODE97	UI/UX keywords, adjective palettes, shape translations, admin + mobile patterns
INLINECODE98

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