Convert Stitch screen(s) to React components for: $ARGUMENTS
$ARGUMENTS should include:
- A Stitch project ID or screen ID, OR "list" to browse available projects
- The target page route (e.g., "homepage", "pathways", "content/books")
- Optionally: "tokens-only" to extract design tokens without building components
- Optionally: "fetch-only" to download designs without converting
- Optionally: "all" to convert all screens in a project sequentially
- Empty — list projects and ask the user what to convert
Purpose
This skill takes a generated Stitch screen (HTML/CSS) and converts it into production React components that integrate with the project's six-layer type safety chain. It fetches and caches design assets locally for reliable access, archives existing page implementations before replacing them, and ensures no work is lost.
Critical Rules
- NEVER overwrite existing components or pages. Always archive first (see Archive Protocol).
- NEVER hand-edit generated Layer 1-5 files. Use hooks from
src/hooks/simplified/ and src/hooks/custom/ as-is.
- Components consume hooks (Layer 5), never call APIs or services directly.
- Use semantic CSS classes only —
bg-primary, text-muted-foreground, etc. Never hardcode hex/rgb.
- Use shadcn/ui components —
Card, Button, Input, Badge, Tabs, etc. Never raw HTML with inline styles.
- Use
tenantConfig for any text that could vary per tenant. Never hardcode tenant strings.
- Push "use client" to leaf components only. Keep page.tsx as a Server Component.
- Follow the design chain: Tokens → Tailwind → Radix/shadcn → Domain components → Patterns → Pages.
Phase 0 — Fetch & Cache Designs
Stitch assets live behind Google Cloud Storage signed URLs that expire and often fail with AI tool built-in fetch. Always download to local cache first.
Cache structure
.stitch/designs/
├── {page-slug}.html # Full HTML from Stitch
├── {page-slug}.png # Screenshot at full width
└── {page-slug}.meta.json # Screen metadata (id, title, dimensions, deviceType)
The {page-slug} is derived from the screen title: lowercase, spaces→hyphens, strip parenthetical suffixes. Example: "Homepage: The Modern Archivist (Full)" → homepage-the-modern-archivist.
Fetch workflow
Get screen metadata via mcp__stitch__get_screen to retrieve htmlCode.downloadUrl, screenshot.downloadUrl, width, height, title, and deviceType.
Check local cache — if .stitch/designs/{page-slug}.html and .stitch/designs/{page-slug}.png already exist:
- Ask the user whether to refresh from Stitch or reuse existing files.
- Only re-download if the user confirms.
Download HTML:
bash scripts/fetch-stitch.sh "{htmlCode.downloadUrl}" ".stitch/designs/{page-slug}.html"
Download screenshot — append =w{width} to the screenshot URL first (Google CDN serves low-res thumbnails by default):
bash scripts/fetch-stitch.sh "{screenshot.downloadUrl}=w{width}" ".stitch/designs/{page-slug}.png"
Save metadata:
{
"screenId": "projects/{project}/screens/{screen}",
"title": "Homepage: The Modern Archivist (Full)",
"width": 2560,
"height": 15320,
"deviceType": "DESKTOP",
"fetchedAt": "2026-03-21T14:00:00Z"
}
Visual audit — read the downloaded .png to confirm design intent and layout details before proceeding with conversion.
Fetch-only mode
If the user specified "fetch-only", stop after this phase. This is useful for bulk-downloading a project's screens for browsing/selection before deciding what to convert.
Stitch API reference
- htmlCode.downloadUrl: Signed URL requiring
curl -L (redirects + TLS/SNI). AI fetch tools often fail on these.
- screenshot.downloadUrl: Serves low-res thumbnail by default. Append
=w{width} for full resolution.
- deviceType: Usually
DESKTOP with 2560px base width. Components should be responsive from this base.
- Element tracking: Preserve
data-stitch-id attributes as comments in TSX for future design sync.
Phase 1 — Pre-Flight Checks
Before any conversion work:
- Read the cached HTML from
.stitch/designs/{page-slug}.html.
- Read the target page's current implementation (if it exists) to understand what hooks, data sources, and patterns are already in use.
- Read
src/app/globals.css to understand current design tokens.
- Read
src/lib/config/tenant.config.ts to understand tenant theming and feature flags.
- Extract the Tailwind config from the Stitch HTML
<head> — this contains the design's color/font/spacing definitions. Compare with project's tailwind.config.ts to identify token gaps.
- Identify which database entities the page needs (e.g., homepage needs pathways, content items, courses). Map each to its Layer 5 hook file in
src/hooks/simplified/ or src/hooks/custom/.
Phase 2 — Archive Existing Page (Archive Protocol)
This phase is MANDATORY when a page already exists at the target route.
For a page file (page.tsx):
src/app/(public)/page.tsx → src/app/(public)/page-old.tsx (rename, remove default export)
The archived file should be renamed by appending -old before the extension. Remove or comment out the export default so Next.js doesn't conflict with the new page. Add a comment at the top:
// ARCHIVED: [date] — replaced by stitch-react conversion from Stitch screen [screen-id]
// This file is preserved for reference. Delete when the new implementation is verified.
For section components referenced by the page:
Do NOT archive individual section components (e.g., src/components/hero.tsx). The new page will import NEW components from a screen-specific directory. Old components remain untouched and available — they just won't be imported by the new page.
For pages with -old suffix already existing:
If page-old.tsx already exists, use page-old-2.tsx, page-old-3.tsx, etc. Never overwrite an archive.
What to record:
After archiving, note in your conversion report:
- What was archived and where
- Which hooks/data sources the old page used (carry forward to new implementation)
- Which section components the old page imported (for reference during conversion)
Phase 3 — Token Extraction
Extract design tokens from the Stitch HTML/CSS and map them to the project's existing token system.
Token source
The Stitch HTML <head> contains a localized tailwind.config with the screen's color/font/spacing definitions. Extract this first, then map to project tokens.
What to extract:
| Stitch artifact |
Maps to |
Location |
| Color palette (backgrounds, text, accents) |
CSS custom properties |
src/app/globals.css (:root and .dark) |
| Font families |
Tailwind font config |
tailwind.config.ts |
| Font sizes / weights / line heights |
Tailwind type scale |
tailwind.config.ts or globals.css |
| Spacing rhythm (padding, gap, margin patterns) |
Tailwind spacing scale |
Note patterns, don't add custom tokens unless necessary |
| Border radius values |
--radius variable |
globals.css |
| Shadow patterns |
Tailwind shadow utilities |
Note patterns |
Rules for token updates:
- Only update tokens if the Stitch design meaningfully differs from current tokens. If the existing tokens are close enough, use them.
- Prefer mapping Stitch values to existing semantic tokens over adding new ones.
- If adding new CSS variables, follow the existing naming convention in globals.css (e.g.,
--card, --popover, --accent).
- Support both light and dark mode. If Stitch generated a dark-mode design, ensure light mode values also exist.
- Ask the user before changing existing token values — these affect the entire site.
Token-only mode:
If the user specified "tokens-only", stop after this phase and report the token mapping. This is useful for the first screen conversion to establish the design foundation before converting components.
Phase 4 — Component Decomposition Plan
Analyze the Stitch HTML and create a conversion plan BEFORE writing any code.
Step 1 — Identify sections
Break the Stitch screen into logical sections. For a homepage this might be:
- Hero
- Social proof / logos
- Pathways grid
- Content sampler
- AI Lab teaser
- Course CTA
- Newsletter signup
Step 2 — Map sections to components
For each section, determine:
| Section |
New component path |
shadcn/ui primitives used |
Data source (hook) |
Client or Server? |
| Hero |
src/components/home/hero.tsx |
Button |
tenantConfig (static) |
Server |
| Pathways |
src/components/home/pathways.tsx |
Card, Badge |
usePathwaysList |
Client |
| ... |
... |
... |
... |
... |
Step 3 — Identify data requirements
For each component that needs data:
- Check if a Layer 5 hook exists in
src/hooks/simplified/ or src/hooks/custom/
- If the hook exists, note the import path and the data shape it returns
- If NO hook exists, note what custom hook or data fetch is needed and flag it for the user
NEVER create new hooks, services, or API routes. If a hook doesn't exist, flag it and ask the user whether to:
- Use an existing hook with filtering
- Skip that section for now
- Run
/generate to create the missing layers first
Step 4 — Present the plan
Show the full conversion plan to the user and wait for approval before proceeding. The plan should include:
- Archive targets (what gets renamed)
- New component tree (file paths and hierarchy)
- Token changes (if any)
- Data source mapping (which hooks wire to which components)
- Anything that can't be converted (missing hooks, unsupported patterns)
Phase 5 — Build Components
After the user approves the plan, build components bottom-up (leaf components first, page composition last).
Component file structure:
src/components/[page-name]/
├── hero.tsx # Section component
├── pathways-grid.tsx # Section component
├── content-sampler.tsx # Section component
└── ...
JSX syntax rules (when converting from raw Stitch HTML)
State discipline
Only add useState/useEffect where behavior is actually needed. Static sections (hero, social proof, navigation) should be Server Components with no state. Never wire fake interactivity or invent business logic not present in the design.
For each component:
- Start from the Stitch HTML structure — preserve the semantic hierarchy (headings, sections, lists)
- Replace HTML elements with shadcn/ui equivalents:
<div class="card"> → <Card>, <CardHeader>, <CardContent>
<button> → <Button variant="...">
<input> → <Input>
- Tabs →
<Tabs>, <TabsList>, <TabsTrigger>, <TabsContent>
- Replace all colors with semantic tokens:
- Any background color →
bg-background, bg-card, bg-primary, bg-muted
- Any text color →
text-foreground, text-muted-foreground, text-primary
- Any border →
border-border, border-primary
- Replace hardcoded text with
tenantConfig where appropriate
- Wire data from hooks:
"use client";
import { useContentItemsList } from "@/hooks/simplified/content-items.hooks";
export function ContentSampler() {
const { data, isLoading, error } = useContentItemsList({
status: "published",
limit: 6
});
// Handle loading, error, and data states
}
- Handle all states — loading (skeleton/spinner), error (message + retry), empty (message + action)
- Preserve GSAP animations from the old components if they existed, or add subtle scroll reveals following the project's animation pattern
- Treat background images as dynamic data — extract image URLs from Stitch HTML into tenant config or content hooks rather than hardcoding into styles
TypeScript requirements:
- Type all props with
Readonly interfaces: interface HeroProps { readonly title: string; ... }
- Use types from Layer 2 schemas when referencing entity shapes:
import type { ContentItems } from "@/lib/schemas"
- Never use
any
Accessibility:
- Preserve heading hierarchy (h1 → h2 → h3, no skipping)
- All images need
alt text
- Interactive elements need visible focus states (shadcn handles this)
- Tap targets minimum 44x44px
Phase 6 — Compose the Page
Create the new page.tsx that imports and arranges all section components.
// src/app/(public)/page.tsx
import { Hero } from "@/components/home/hero";
import { PathwaysGrid } from "@/components/home/pathways-grid";
import { ContentSampler } from "@/components/home/content-sampler";
// ... etc
export default function HomePage() {
return (
<>
<Hero />
<PathwaysGrid />
<ContentSampler />
{/* ... */}
</>
);
}
Rules:
- Page file is a Server Component (no "use client")
- Section components that need data are Client Components (they have "use client")
- Static sections (hero with tenant config only) can be Server Components
- Check feature flags:
{tenantConfig.features.chat && <AILabTeaser />}
Phase 7 — Verification Checklist
After building, verify:
Report the checklist results to the user.
Phase 8 — Conversion Report
## Stitch → React Conversion Complete
### Screen
- **Stitch Project:** [project ID]
- **Stitch Screen:** [screen ID / title]
- **Local Cache:** `.stitch/designs/{page-slug}.html`
- **Target Route:** [e.g., / (homepage)]
### Archived
- `src/app/(public)/page.tsx` → `src/app/(public)/page-old.tsx`
### New Files Created
1. `src/app/(public)/page.tsx` — Page composition (Server Component)
2. `src/components/home/hero.tsx` — Hero section
3. `src/components/home/pathways-grid.tsx` — Pathways grid (Client)
4. ...
### Token Changes
- [List any globals.css or tailwind.config.ts changes, or "None"]
### Data Sources Wired
| Component | Hook | Entity |
|-----------|------|--------|
| PathwaysGrid | `usePathwaysList` | pathways |
| ContentSampler | `useContentItemsList` | content_items |
### Flagged Issues
- [Any missing hooks, unsupported patterns, or items needing manual attention]
### Next Steps
- Run `pnpm dev` and verify the page renders
- Compare visually with the Stitch screenshot at `.stitch/designs/{page-slug}.png`
- Run `/design-audit` to check visual quality
- Run `/responsive-audit` to check breakpoints
- Delete `page-old.tsx` once verified
Multi-Screen Workflow
When converting multiple screens (e.g., "all"):
- Start with Homepage — establishes tokens and shared patterns
- Convert in the build order from the screen prompts doc (Homepage → Pathways Hub → Pathway Detail → Content Library → ...)
- Reuse shared components — if the homepage conversion created a
PathwaysGrid component, the Pathways Hub page should import and extend it, not duplicate it
- After each screen, verify before proceeding to the next
- Token extraction only happens once (first screen). Subsequent screens use the established tokens.
Bulk fetch workflow
To download all screens for browsing before converting:
- Call
mcp__stitch__list_screens to get all screen metadata
- For each screen, run the fetch workflow (Phase 0) to cache HTML + screenshot
- Present a summary table of cached designs with titles and file paths
- User selects which screens to convert
Anti-Patterns
- Never modify generated Layer 1-5 files (schema, Zod, services, routes, hooks). If something is missing, use
/generate or /validate first.
- Never create a new API route or service as part of a conversion. Flag the gap and let the user decide.
- Never copy Stitch CSS verbatim. Extract the design intent and express it through the project's token system.
- Never put all sections in one giant component. Decompose into focused section components.
- Never skip the archive step. Even if the current page "looks bad," it contains valuable context about data wiring and hooks.
- Never use arbitrary Tailwind values (
text-[#ff6b35], p-[37px]). Map to the token system.
- Never create component files in
src/components/ui/. That's reserved for shadcn primitives. Use src/components/[page-name]/ for page sections.
- Never use AI built-in fetch for Stitch URLs. Always use
scripts/fetch-stitch.sh — Google Cloud Storage URLs require curl with redirect handling.
- Never leave document-level HTML in component output. Strip
<!DOCTYPE>, <html>, <head>, <body>, and CDN <script> tags — these don't belong inside React components.
- Never use icon font text nodes. Replace
<span class="material-symbols-outlined">icon_name</span> with the equivalent lucide-react import. Lucide is already in the project — use it.
1---2name: stitch-react3description: "Convert Stitch screens to React components — fetches and caches designs locally, extracts design tokens, decomposes HTML into shadcn/ui components, generates TypeScript types, wires Layer 5 hooks, and archives existing pages. Triggers on: Stitch React, component conversion, React conversion, HTML to React. NOT for: new React apps, API routes, services, or schema changes."4user-invocable: true5allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent, mcp__stitch__list_projects, mcp__stitch__list_screens, mcp__stitch__get_screen, mcp__stitch__get_project6metadata:7 source: https://skillmd.com/skills/joshuashepherd/stitch-react8---910Convert Stitch screen(s) to React components for: $ARGUMENTS1112$ARGUMENTS should include:13- A Stitch project ID or screen ID, OR "list" to browse available projects14- The target page route (e.g., "homepage", "pathways", "content/books")15- Optionally: "tokens-only" to extract design tokens without building components16- Optionally: "fetch-only" to download designs without converting17- Optionally: "all" to convert all screens in a project sequentially18- Empty — list projects and ask the user what to convert1920---2122## Purpose2324This skill takes a generated Stitch screen (HTML/CSS) and converts it into production React components that integrate with the project's six-layer type safety chain. It fetches and caches design assets locally for reliable access, archives existing page implementations before replacing them, and ensures no work is lost.2526## Critical Rules27281. **NEVER overwrite existing components or pages.** Always archive first (see Archive Protocol).292. **NEVER hand-edit generated Layer 1-5 files.** Use hooks from `src/hooks/simplified/` and `src/hooks/custom/` as-is.303. **Components consume hooks (Layer 5), never call APIs or services directly.**314. **Use semantic CSS classes only** — `bg-primary`, `text-muted-foreground`, etc. Never hardcode hex/rgb.325. **Use shadcn/ui components** — `Card`, `Button`, `Input`, `Badge`, `Tabs`, etc. Never raw HTML with inline styles.336. **Use `tenantConfig`** for any text that could vary per tenant. Never hardcode tenant strings.347. **Push "use client" to leaf components only.** Keep page.tsx as a Server Component.358. **Follow the design chain:** Tokens → Tailwind → Radix/shadcn → Domain components → Patterns → Pages.3637---3839## Phase 0 — Fetch & Cache Designs4041Stitch assets live behind Google Cloud Storage signed URLs that expire and often fail with AI tool built-in fetch. **Always download to local cache first.**4243### Cache structure44```45.stitch/designs/46 ├── {page-slug}.html # Full HTML from Stitch47 ├── {page-slug}.png # Screenshot at full width48 └── {page-slug}.meta.json # Screen metadata (id, title, dimensions, deviceType)49```5051The `{page-slug}` is derived from the screen title: lowercase, spaces→hyphens, strip parenthetical suffixes. Example: "Homepage: The Modern Archivist (Full)" → `homepage-the-modern-archivist`.5253### Fetch workflow54551. **Get screen metadata** via `mcp__stitch__get_screen` to retrieve `htmlCode.downloadUrl`, `screenshot.downloadUrl`, `width`, `height`, `title`, and `deviceType`.56572. **Check local cache** — if `.stitch/designs/{page-slug}.html` and `.stitch/designs/{page-slug}.png` already exist:58 - Ask the user whether to **refresh** from Stitch or **reuse** existing files.59 - Only re-download if the user confirms.60613. **Download HTML:**62 ```bash63 bash scripts/fetch-stitch.sh "{htmlCode.downloadUrl}" ".stitch/designs/{page-slug}.html"64 ```65664. **Download screenshot** — append `=w{width}` to the screenshot URL first (Google CDN serves low-res thumbnails by default):67 ```bash68 bash scripts/fetch-stitch.sh "{screenshot.downloadUrl}=w{width}" ".stitch/designs/{page-slug}.png"69 ```70715. **Save metadata:**72 ```json73 {74 "screenId": "projects/{project}/screens/{screen}",75 "title": "Homepage: The Modern Archivist (Full)",76 "width": 2560,77 "height": 15320,78 "deviceType": "DESKTOP",79 "fetchedAt": "2026-03-21T14:00:00Z"80 }81 ```82836. **Visual audit** — read the downloaded `.png` to confirm design intent and layout details before proceeding with conversion.8485### Fetch-only mode86If the user specified "fetch-only", stop after this phase. This is useful for bulk-downloading a project's screens for browsing/selection before deciding what to convert.8788### Stitch API reference89- **htmlCode.downloadUrl**: Signed URL requiring `curl -L` (redirects + TLS/SNI). AI fetch tools often fail on these.90- **screenshot.downloadUrl**: Serves low-res thumbnail by default. Append `=w{width}` for full resolution.91- **deviceType**: Usually `DESKTOP` with 2560px base width. Components should be responsive from this base.92- **Element tracking**: Preserve `data-stitch-id` attributes as comments in TSX for future design sync.9394---9596## Phase 1 — Pre-Flight Checks9798Before any conversion work:991001. **Read the cached HTML** from `.stitch/designs/{page-slug}.html`.1012. **Read the target page's current implementation** (if it exists) to understand what hooks, data sources, and patterns are already in use.1023. **Read `src/app/globals.css`** to understand current design tokens.1034. **Read `src/lib/config/tenant.config.ts`** to understand tenant theming and feature flags.1045. **Extract the Tailwind config from the Stitch HTML `<head>`** — this contains the design's color/font/spacing definitions. Compare with project's `tailwind.config.ts` to identify token gaps.1056. **Identify which database entities the page needs** (e.g., homepage needs pathways, content items, courses). Map each to its Layer 5 hook file in `src/hooks/simplified/` or `src/hooks/custom/`.106107---108109## Phase 2 — Archive Existing Page (Archive Protocol)110111**This phase is MANDATORY when a page already exists at the target route.**112113### For a page file (`page.tsx`):114```115src/app/(public)/page.tsx → src/app/(public)/page-old.tsx (rename, remove default export)116```117118The archived file should be renamed by appending `-old` before the extension. Remove or comment out the `export default` so Next.js doesn't conflict with the new page. Add a comment at the top:119120```typescript121// ARCHIVED: [date] — replaced by stitch-react conversion from Stitch screen [screen-id]122// This file is preserved for reference. Delete when the new implementation is verified.123```124125### For section components referenced by the page:126Do NOT archive individual section components (e.g., `src/components/hero.tsx`). The new page will import NEW components from a screen-specific directory. Old components remain untouched and available — they just won't be imported by the new page.127128### For pages with `-old` suffix already existing:129If `page-old.tsx` already exists, use `page-old-2.tsx`, `page-old-3.tsx`, etc. Never overwrite an archive.130131### What to record:132After archiving, note in your conversion report:133- What was archived and where134- Which hooks/data sources the old page used (carry forward to new implementation)135- Which section components the old page imported (for reference during conversion)136137---138139## Phase 3 — Token Extraction140141Extract design tokens from the Stitch HTML/CSS and map them to the project's existing token system.142143### Token source144The Stitch HTML `<head>` contains a localized `tailwind.config` with the screen's color/font/spacing definitions. Extract this first, then map to project tokens.145146### What to extract:147| Stitch artifact | Maps to | Location |148|-----------------|---------|----------|149| Color palette (backgrounds, text, accents) | CSS custom properties | `src/app/globals.css` (`:root` and `.dark`) |150| Font families | Tailwind font config | `tailwind.config.ts` |151| Font sizes / weights / line heights | Tailwind type scale | `tailwind.config.ts` or `globals.css` |152| Spacing rhythm (padding, gap, margin patterns) | Tailwind spacing scale | Note patterns, don't add custom tokens unless necessary |153| Border radius values | `--radius` variable | `globals.css` |154| Shadow patterns | Tailwind shadow utilities | Note patterns |155156### Rules for token updates:157- **Only update tokens if the Stitch design meaningfully differs from current tokens.** If the existing tokens are close enough, use them.158- **Prefer mapping Stitch values to existing semantic tokens** over adding new ones.159- **If adding new CSS variables, follow the existing naming convention** in globals.css (e.g., `--card`, `--popover`, `--accent`).160- **Support both light and dark mode.** If Stitch generated a dark-mode design, ensure light mode values also exist.161- **Ask the user before changing existing token values** — these affect the entire site.162163### Token-only mode:164If the user specified "tokens-only", stop after this phase and report the token mapping. This is useful for the first screen conversion to establish the design foundation before converting components.165166---167168## Phase 4 — Component Decomposition Plan169170Analyze the Stitch HTML and create a conversion plan BEFORE writing any code.171172### Step 1 — Identify sections173Break the Stitch screen into logical sections. For a homepage this might be:174- Hero175- Social proof / logos176- Pathways grid177- Content sampler178- AI Lab teaser179- Course CTA180- Newsletter signup181182### Step 2 — Map sections to components183For each section, determine:184185| Section | New component path | shadcn/ui primitives used | Data source (hook) | Client or Server? |186|---------|-------------------|---------------------------|--------------------|--------------------|187| Hero | `src/components/home/hero.tsx` | Button | tenantConfig (static) | Server |188| Pathways | `src/components/home/pathways.tsx` | Card, Badge | `usePathwaysList` | Client |189| ... | ... | ... | ... | ... |190191### Step 3 — Identify data requirements192For each component that needs data:1931. Check if a Layer 5 hook exists in `src/hooks/simplified/` or `src/hooks/custom/`1942. If the hook exists, note the import path and the data shape it returns1953. If NO hook exists, note what custom hook or data fetch is needed and flag it for the user196197**NEVER create new hooks, services, or API routes.** If a hook doesn't exist, flag it and ask the user whether to:198- Use an existing hook with filtering199- Skip that section for now200- Run `/generate` to create the missing layers first201202### Step 4 — Present the plan203Show the full conversion plan to the user and wait for approval before proceeding. The plan should include:204- Archive targets (what gets renamed)205- New component tree (file paths and hierarchy)206- Token changes (if any)207- Data source mapping (which hooks wire to which components)208- Anything that can't be converted (missing hooks, unsupported patterns)209210---211212## Phase 5 — Build Components213214After the user approves the plan, build components bottom-up (leaf components first, page composition last).215216### Component file structure:217```218src/components/[page-name]/219 ├── hero.tsx # Section component220 ├── pathways-grid.tsx # Section component221 ├── content-sampler.tsx # Section component222 └── ...223```224225### JSX syntax rules (when converting from raw Stitch HTML)226- `class` → `className`227- `for` → `htmlFor`228- `style="color: red"` → `style={{ color: "red" }}`229- Self-closing tags: `<img>`, `<input>`, `<br>` → `<img />`, `<input />`, `<br />`230- Comments: `<!-- text -->` → `{/* text */}`231- Replace icon font text nodes with lucide-react imports:232 ```tsx233 // Bad: <span class="material-symbols-outlined">search</span>234 // Good:235 import { Search } from "lucide-react";236 <Search size={18} />237 ```238239### State discipline240Only add `useState`/`useEffect` where behavior is actually needed. Static sections (hero, social proof, navigation) should be Server Components with no state. Never wire fake interactivity or invent business logic not present in the design.241242### For each component:2432441. **Start from the Stitch HTML structure** — preserve the semantic hierarchy (headings, sections, lists)2452. **Replace HTML elements with shadcn/ui equivalents:**246 - `<div class="card">` → `<Card>`, `<CardHeader>`, `<CardContent>`247 - `<button>` → `<Button variant="...">`248 - `<input>` → `<Input>`249 - Tabs → `<Tabs>`, `<TabsList>`, `<TabsTrigger>`, `<TabsContent>`2503. **Replace all colors with semantic tokens:**251 - Any background color → `bg-background`, `bg-card`, `bg-primary`, `bg-muted`252 - Any text color → `text-foreground`, `text-muted-foreground`, `text-primary`253 - Any border → `border-border`, `border-primary`2544. **Replace hardcoded text with `tenantConfig`** where appropriate2555. **Wire data from hooks:**256 ```tsx257 "use client";258 import { useContentItemsList } from "@/hooks/simplified/content-items.hooks";259260 export function ContentSampler() {261 const { data, isLoading, error } = useContentItemsList({262 status: "published",263 limit: 6264 });265 // Handle loading, error, and data states266 }267 ```2686. **Handle all states** — loading (skeleton/spinner), error (message + retry), empty (message + action)2697. **Preserve GSAP animations** from the old components if they existed, or add subtle scroll reveals following the project's animation pattern2708. **Treat background images as dynamic data** — extract image URLs from Stitch HTML into tenant config or content hooks rather than hardcoding into styles271272### TypeScript requirements:273- Type all props with `Readonly` interfaces: `interface HeroProps { readonly title: string; ... }`274- Use types from Layer 2 schemas when referencing entity shapes: `import type { ContentItems } from "@/lib/schemas"`275- Never use `any`276277### Accessibility:278- Preserve heading hierarchy (h1 → h2 → h3, no skipping)279- All images need `alt` text280- Interactive elements need visible focus states (shadcn handles this)281- Tap targets minimum 44x44px282283---284285## Phase 6 — Compose the Page286287Create the new `page.tsx` that imports and arranges all section components.288289```tsx290// src/app/(public)/page.tsx291import { Hero } from "@/components/home/hero";292import { PathwaysGrid } from "@/components/home/pathways-grid";293import { ContentSampler } from "@/components/home/content-sampler";294// ... etc295296export default function HomePage() {297 return (298 <>299 <Hero />300 <PathwaysGrid />301 <ContentSampler />302 {/* ... */}303 </>304 );305}306```307308Rules:309- Page file is a **Server Component** (no "use client")310- Section components that need data are Client Components (they have "use client")311- Static sections (hero with tenant config only) can be Server Components312- Check feature flags: `{tenantConfig.features.chat && <AILabTeaser />}`313314---315316## Phase 7 — Verification Checklist317318After building, verify:319320- [ ] Designs cached in `.stitch/designs/` with HTML, PNG, and metadata321- [ ] Old page archived as `page-old.tsx` with archive comment322- [ ] No old component files were overwritten or modified323- [ ] New page.tsx is a Server Component (no "use client")324- [ ] All data comes from Layer 5 hooks, never direct API calls325- [ ] No hardcoded colors — only semantic Tailwind classes326- [ ] No hardcoded tenant strings — uses `tenantConfig`327- [ ] All components use shadcn/ui primitives328- [ ] Loading, error, and empty states handled in every data-consuming component329- [ ] TypeScript types imported from Layer 2 schemas where needed330- [ ] Heading hierarchy is correct (one h1 per page, proper nesting)331- [ ] No new hooks, services, or API routes were created332- [ ] Image URLs extracted to config/hooks, not hardcoded in styles333334Report the checklist results to the user.335336---337338## Phase 8 — Conversion Report339340```markdown341## Stitch → React Conversion Complete342343### Screen344- **Stitch Project:** [project ID]345- **Stitch Screen:** [screen ID / title]346- **Local Cache:** `.stitch/designs/{page-slug}.html`347- **Target Route:** [e.g., / (homepage)]348349### Archived350- `src/app/(public)/page.tsx` → `src/app/(public)/page-old.tsx`351352### New Files Created3531. `src/app/(public)/page.tsx` — Page composition (Server Component)3542. `src/components/home/hero.tsx` — Hero section3553. `src/components/home/pathways-grid.tsx` — Pathways grid (Client)3564. ...357358### Token Changes359- [List any globals.css or tailwind.config.ts changes, or "None"]360361### Data Sources Wired362| Component | Hook | Entity |363|-----------|------|--------|364| PathwaysGrid | `usePathwaysList` | pathways |365| ContentSampler | `useContentItemsList` | content_items |366367### Flagged Issues368- [Any missing hooks, unsupported patterns, or items needing manual attention]369370### Next Steps371- Run `pnpm dev` and verify the page renders372- Compare visually with the Stitch screenshot at `.stitch/designs/{page-slug}.png`373- Run `/design-audit` to check visual quality374- Run `/responsive-audit` to check breakpoints375- Delete `page-old.tsx` once verified376```377378---379380## Multi-Screen Workflow381382When converting multiple screens (e.g., "all"):3833841. **Start with Homepage** — establishes tokens and shared patterns3852. **Convert in the build order** from the screen prompts doc (Homepage → Pathways Hub → Pathway Detail → Content Library → ...)3863. **Reuse shared components** — if the homepage conversion created a `PathwaysGrid` component, the Pathways Hub page should import and extend it, not duplicate it3874. **After each screen**, verify before proceeding to the next3885. **Token extraction only happens once** (first screen). Subsequent screens use the established tokens.389390### Bulk fetch workflow391To download all screens for browsing before converting:3921. Call `mcp__stitch__list_screens` to get all screen metadata3932. For each screen, run the fetch workflow (Phase 0) to cache HTML + screenshot3943. Present a summary table of cached designs with titles and file paths3954. User selects which screens to convert396397---398399## Anti-Patterns400401- **Never modify generated Layer 1-5 files** (schema, Zod, services, routes, hooks). If something is missing, use `/generate` or `/validate` first.402- **Never create a new API route or service** as part of a conversion. Flag the gap and let the user decide.403- **Never copy Stitch CSS verbatim.** Extract the design intent and express it through the project's token system.404- **Never put all sections in one giant component.** Decompose into focused section components.405- **Never skip the archive step.** Even if the current page "looks bad," it contains valuable context about data wiring and hooks.406- **Never use arbitrary Tailwind values** (`text-[#ff6b35]`, `p-[37px]`). Map to the token system.407- **Never create component files in `src/components/ui/`.** That's reserved for shadcn primitives. Use `src/components/[page-name]/` for page sections.408- **Never use AI built-in fetch for Stitch URLs.** Always use `scripts/fetch-stitch.sh` — Google Cloud Storage URLs require curl with redirect handling.409- **Never leave document-level HTML in component output.** Strip `<!DOCTYPE>`, `<html>`, `<head>`, `<body>`, and CDN `<script>` tags — these don't belong inside React components.410- **Never use icon font text nodes.** Replace `<span class="material-symbols-outlined">icon_name</span>` with the equivalent lucide-react import. Lucide is already in the project — use it.