Stitch React

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: "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 archives existing page implementations before replacing them, ensuring no work is lost.

Critical Rules

1. NEVER overwrite existing components or pages. Always archive first (see Archive Protocol).
2. NEVER hand-edit generated Layer 1-5 files. Use hooks from src/hooks/simplified/ and src/hooks/custom/ as-is.
3. Components consume hooks (Layer 5), never call APIs or services directly.
4. Use semantic CSS classes only — bg-primary, text-muted-foreground, etc. Never hardcode hex/rgb.
5. Use shadcn/ui components — Card, Button, Input, Badge, Tabs, etc. Never raw HTML with inline styles.
6. Use tenantConfig for any text that could vary per tenant. Never hardcode tenant strings.
7. Push "use client" to leaf components only. Keep page.tsx as a Server Component.
8. Follow the design chain: Tokens → Tailwind → Radix/shadcn → Domain components → Patterns → Pages.

Phase 0 — Pre-Flight Checks

Before any conversion work:

1. Read the target page's current implementation (if it exists) to understand what hooks, data sources, and patterns are already in use.
2. Read src/app/globals.css to understand current design tokens.
3. Read src/lib/config/tenant.config.ts to understand tenant theming and feature flags.
4. Read the Stitch screen via mcp__stitch__get_screen to get the full HTML/CSS.
5. 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 1 — 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 2 — Token Extraction

Extract design tokens from the Stitch HTML/CSS and map them to the project's existing token system.

What to extract:

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 3 — 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:

Step 3 — Identify data requirements

For each component that needs data:

1. Check if a Layer 5 hook exists in src/hooks/simplified/ or src/hooks/custom/
2. If the hook exists, note the import path and the data shape it returns
3. 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 4 — 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
  └── ...

For each component:

1. Start from the Stitch HTML structure — preserve the semantic hierarchy (headings, sections, lists)
2. Replace HTML elements with shadcn/ui equivalents:
   • <div class="card"> → <Card>, <CardHeader>, <CardContent>
   • <button> → <Button variant="...">
   • <input> → <Input>
   • Tabs → <Tabs>, <TabsList>, <TabsTrigger>, <TabsContent>
3. 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
4. Replace hardcoded text with tenantConfig where appropriate
5. 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
   }
   

6. Handle all states — loading (skeleton/spinner), error (message + retry), empty (message + action)
7. Preserve GSAP animations from the old components if they existed, or add subtle scroll reveals following the project's animation pattern

TypeScript requirements:

• Type all props explicitly
• 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 5 — 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 6 — Verification Checklist

After building, verify:

• Old page archived as page-old.tsx with archive comment
• No old component files were overwritten or modified
• New page.tsx is a Server Component (no "use client")
• All data comes from Layer 5 hooks, never direct API calls
• No hardcoded colors — only semantic Tailwind classes
• No hardcoded tenant strings — uses tenantConfig
• All components use shadcn/ui primitives
• Loading, error, and empty states handled in every data-consuming component
• TypeScript types imported from Layer 2 schemas where needed
• Heading hierarchy is correct (one h1 per page, proper nesting)
• No new hooks, services, or API routes were created

Report the checklist results to the user.

Phase 7 — Conversion Report

## Stitch → React Conversion Complete

### Screen
- **Stitch Project:** [project ID]
- **Stitch Screen:** [screen ID / name]
- **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 screen
- 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"):

1. Start with Homepage — establishes tokens and shared patterns
2. Convert in the build order from the screen prompts doc (Homepage → Pathways Hub → Pathway Detail → Content Library → ...)
3. Reuse shared components — if the homepage conversion created a PathwaysGrid component, the Pathways Hub page should import and extend it, not duplicate it
4. After each screen, verify before proceeding to the next
5. Token extraction only happens once (first screen). Subsequent screens use the established tokens.

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.