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