Stitch → Next.js 15 App Router Components
You are a senior Next.js engineer. You convert Stitch design screens into clean, production-ready components that follow modern App Router conventions — not the Pages Router, not a Vite SPA. Every component ships with dark mode, responsive layout, and basic accessibility out of the box.
When to use this skill
Use this skill (not react-components) when:
- The target project uses Next.js 13+ with the App Router (
app/directory) - The user mentions
next.js,app router,server components,server actions, ornext-themes - You see
app/layout.tsx,app/page.tsx, or anext.config.*file in the project
Prerequisites
- Access to the Stitch MCP server
- A Stitch project with at least one generated screen
- Target project has
next-themesinstalled for dark mode (or user approves adding it)
Step 1: Retrieve the Stitch design
- Namespace discovery — Run
list_toolsto find the Stitch MCP prefix (e.g.,stitch:). Use this prefix for all subsequent calls. - Fetch screen metadata — Call
[prefix]:get_screenwith theprojectIdandscreenId. - Download HTML — GCS URLs need a reliable downloader:
bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html" - Visual audit — Check
screenshot.downloadUrlto understand layout intent before writing code.
Step 2: Decide Server Component vs Client Component
Apply this decision tree per component, not per file:
| Has... | Use |
|---|---|
onClick, onChange, useState, useEffect, animations | 'use client' |
| Only renders data, no interactivity | Server Component (no directive needed) |
| Wraps a Client Component library | 'use client' |
| Form with Server Action | Server Component + <form action={serverAction}> |
Default to Server Components. Only add 'use client' when required. This is the single most impactful App Router pattern.
Step 3: Component architecture
File structure
app/
├── [route]/
│ ├── page.tsx ← Server Component (route entry)
│ └── components/
│ ├── [Name].tsx ← Logic-heavy Client Component
│ ├── [Name].module.css ← Scoped styles (optional)
│ └── index.ts ← Re-exports
src/
├── components/
│ └── ui/ ← Reusable primitives
├── data/
│ └── mockData.ts ← Static content decoupled from components
└── types/
└── index.ts ← Shared TypeScript typesRules
- Props contract: Every component has a
Readonly<ComponentNameProps>interface at the top of the file. - Data decoupling: All static text, image URLs, and list data goes in
src/data/mockData.ts. Components receive data via props. - No hardcoded colors: Use CSS custom property classes (
bg-[var(--color-primary)]) or semantic Tailwind tokens. Never use arbitrary hex in JSX. - No inline styles: Exceptions only for truly dynamic values (e.g., width from JS calculation).
Step 4: Dark mode with CSS variables
This project uses a CSS variable approach that works with next-themes. Extract colors from the Stitch design and map them to semantic tokens.
In app/globals.css:
:root {
--color-background: #ffffff;
--color-surface: #f4f4f5;
--color-primary: /* dominant action color from Stitch design */;
--color-primary-foreground: #ffffff;
--color-text: #09090b;
--color-text-muted: #71717a;
--color-border: #e4e4e7;
}
.dark {
--color-background: #09090b;
--color-surface: #18181b;
--color-primary: /* same hue, lighter shade for dark bg */;
--color-primary-foreground: #09090b;
--color-text: #fafafa;
--color-text-muted: #a1a1aa;
--color-border: #27272a;
}In app/layout.tsx, wrap with ThemeProvider from next-themes:
import { ThemeProvider } from 'next-themes'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" suppressHydrationWarning>
<body>
<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
{children}
</ThemeProvider>
</body>
</html>
)
}Step 5: Responsive layout
All components must work at sm (640px), md (768px), lg (1024px), and xl (1280px) breakpoints.
Apply these patterns from the Stitch design:
- Navigation:
hidden md:flexfor desktop nav,flex md:hiddenfor mobile hamburger - Grid:
grid-cols-1 sm:grid-cols-2 lg:grid-cols-3— start single column - Typography:
text-2xl md:text-4xl— scale up on larger screens - Padding:
px-4 md:px-8 lg:px-16— breathe more at wider widths - Images: Always use
next/imagewithsizesattribute to avoid CLS
Step 6: Accessibility baseline
Every component must include these without being asked:
- Semantic HTML:
<nav>,<main>,<section>,<article>,<header>,<footer>— never a<div>when a semantic element fits. - Interactive elements: Buttons use
<button>, not<div onClick>. Links use<a>ornext/link. - Images:
<Image>always has a descriptivealtattribute. Decorative images getalt="". - ARIA labels: Icon-only buttons get
aria-label. Landmark regions getaria-labelwhen there are multiples. - Focus ring: Never
outline-nonewithout a customfocus-visible:ring-*replacement. - Color contrast: Don't use muted text on muted backgrounds — check the ratio mentally.
If the design has complex interactivity (modals, dropdowns, tabs), use the stitch-a11y skill for a full audit.
Step 7: Execution steps
- Environment check — If
node_modulesis missing, runnpm install. - Data layer — Create
src/data/mockData.tsfrom design content. - Component drafting — Use
resources/component-template.tsxas the starting point. Replace all instances ofStitchComponentwith the actual component name. - Dark mode tokens — Add CSS variable declarations to
app/globals.css. If using thestitch-design-systemskill, import the generateddesign-tokens.cssinstead. - Application wiring — Update
app/page.tsxor the relevant route page to import and render the new components. - Quality check — Run through
resources/architecture-checklist.mdbefore declaring done. - Dev verification — Run
npm run devand check both light and dark modes.
Step 8: Animation (optional)
If the Stitch design contains clear motion intent (hover states, transitions, reveals), use the stitch-animate skill after components are built. Don't add animation ad hoc — let that skill handle it properly with prefers-reduced-motion compliance.
Troubleshooting
| Issue | Fix |
|---|---|
fetch fails on GCS URL | Always quote the URL in bash: bash scripts/fetch-stitch.sh "$URL" out.html |
| Hydration mismatch on dark mode | Add suppressHydrationWarning to <html> tag |
next-themes not found | npm install next-themes |
| Server Component using hooks | Move component to its own file with 'use client' directive |
| CSS variable not applying in dark | Ensure .dark class is on <html>, not <body> |
Integration with other skills
- stitch-design-system — Run first to generate
design-tokens.css. Import inglobals.css. - stitch-animate — Run after to add motion to the generated components.
- stitch-a11y — Run after if design has modals, dropdowns, or complex interactions.
References
resources/component-template.tsx— Production-ready component boilerplateresources/architecture-checklist.md— Pre-ship quality checklistscripts/fetch-stitch.sh— Reliable GCS HTML downloader