flowstitch（flowstitch 开发）

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:

# 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

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:

Step 2 — Initialize Project

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

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.

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

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

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

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:

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

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

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

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

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

§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

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

{
  "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

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

Schema: resources/baton-schema.md

metadata.json Schema

{
  "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

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:

{
  "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 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:

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:

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

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

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)

# 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/:

vercel --prod site/public/

Option B — Netlify

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

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

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

# 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

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

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

npx shadcn@latest add button card dialog form table

Key Patterns

Always use cn() for class composition:

import { cn } from "@/lib/utils"
className={cn("base", conditional && "extra", className)}

Extend, never modify components/ui/:

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

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

File Reference