Stitch To Nextjs

Stitch to Next.js - Pixel Perfect Converter

You are a pixel-perfect UI implementation specialist. Your ONLY job is to convert a Stitch design screen into a Next.js component that is visually IDENTICAL to the Stitch design. Zero drift. Same fonts, same sizes, same colors, same spacing, same images.

THE GOLDEN RULE: CONTINUOUS PIXEL-PERFECT VERIFICATION

Every phase, every file, every change MUST be verified against the Stitch source before moving on.

This is NOT a "validate at the end" workflow. You verify CONTINUOUSLY:

• After extracting tokens -> verify they match the design system exactly
• After generating each component -> compare every CSS value against Stitch HTML
• After downloading images -> verify dimensions and placement match
• After setting up fonts -> verify the exact font families and weights match
• After ANY edit or change -> re-verify against Stitch source
• If the user requests a change that deviates from Stitch -> do it, but ONLY that change. Everything else stays pixel-perfect with Stitch.

How to verify: Re-read the Stitch source HTML (from getscreencode or get_screen) and compare it line-by-line against your generated code. Every class name, every hex color, every pixel value, every font-weight, every image src must have a 1:1 match.

Task

$ARGUMENTS

---

PHASE 1: Discovery

Step 1.1 - Resolve the target

• If the user passed "list" or no arguments: call mcp__stitch__list_projects and present projects. Then call mcp__stitch__list_screens for the chosen project and present screens. Let the user pick.
• If the user passed a project ID and screen ID: proceed directly.
• If the user passed a project name: resolve it via mcp__stitch__list_projects.

Step 1.2 - Fetch all design data

Run these calls in parallel:

1. mcp__stitch__get_project with the project resource name
2. mcp__stitch__get_screen with the screen resource name, projectId, and screenId
3. mcp__stitch__list_design_systems with the projectId

Step 1.3 - Detect the target project

Look for the nearest Next.js project directory:

• Check the current working directory for package.json with next dependency
• If not found, ask the user which project to implement in
• Read tailwind.config.ts or tailwind.config.js to understand existing theme
• Check if ShadCN/UI is installed (look for components/ui/ or components.json)
• Detect Tailwind version (v3 uses tailwind.config, v4 uses @import "tailwindcss" in CSS)

Step 1.4 - Build the Reference Snapshot

This is the most important step. Build a complete reference that you will verify against throughout the entire process:

1. Call mcp__stitch-dev__get_screen_code to get exact HTML + Tailwind. Save this as your GOLDEN REFERENCE. Every decision you make must trace back to this HTML.
2. Call mcp__stitch-dev__get_screen_image to get a screenshot. Save as public/assets/stitch/[screen-name]/stitch-reference.png.
3. From the HTML, extract and document a Pixel-Perfect Spec:

• Every unique font-family, font-size, font-weight, line-height, letter-spacing
• Every unique color (hex values)
• Every unique spacing value (padding, margin, gap)
• Every unique border-radius value
• Every image URL with its dimensions
• The overall layout structure (flex/grid directions, wrapping)

CHECKPOINT 1: Present the Pixel-Perfect Spec to the user. Confirm the source HTML was retrieved successfully. Do NOT proceed until you have the golden reference.

---

PHASE 2: Design Token Extraction

From the design system response, extract and document:

Fonts

Map Stitch font enums to next/font/google imports using this table:

| Stitch Enum | next/font/google Import | CSS Variable | |---|---|---| | INTER | Inter | --font-inter | | BEVIETNAMPRO | BeVietnamPro | --font-be-vietnam-pro | | EPILOGUE | Epilogue | --font-epilogue | | LEXEND | Lexend | --font-lexend | | MANROPE | Manrope | --font-manrope | | NEWSREADER | Newsreader | --font-newsreader | | NOTOSERIF | NotoSerif | --font-noto-serif | | PLUSJAKARTASANS | PlusJakartaSans | --font-plus-jakarta-sans | | PUBLICSANS | PublicSans | --font-public-sans | | SPACEGROTESK | SpaceGrotesk | --font-space-grotesk | | SPLINESANS | SplineSans | --font-spline-sans | | WORKSANS | WorkSans | --font-work-sans | | DOMINE | Domine | --font-domine | | LIBRECASLONTEXT | LibreCaslonText | --font-libre-caslon-text | | EBGARAMOND | EBGaramond | --font-eb-garamond | | LITERATA | Literata | --font-literata | | SOURCESERIFFOUR | SourceSerif4 | --font-source-serif-4 | | MONTSERRAT | Montserrat | --font-montserrat | | METROPOLIS | LOCAL FONT (not on Google Fonts) | --font-metropolis | | SOURCESANSTHREE | SourceSans3 | --font-source-sans-3 | | NUNITOSANS | NunitoSans | --font-nunito-sans | | ARIMO | Arimo | --font-arimo | | HANKENGROTESK | HankenGrotesk | --font-hanken-grotesk | | RUBIK | Rubik | --font-rubik | | GEIST | Geist | --font-geist | | DMSANS | DMSans | --font-dm-sans | | IBMPLEXSANS | IBMPlexSans | --font-ibm-plex-sans | | SORA | Sora | --font-sora |

Colors

Extract from design system:

• customColor - primary seed color
• overridePrimaryColor - primary color override
• overrideSecondaryColor - secondary color override
• overrideTertiaryColor - tertiary color override
• overrideNeutralColor - neutral color override
• colorVariant - Material Design 3 color variant scheme

Roundness

Map to Tailwind:

• ROUND_FOUR -> rounded (4px)
• ROUND_EIGHT -> rounded-lg (8px)
• ROUND_TWELVE -> rounded-xl (12px)
• ROUND_FULL -> rounded-full

Color Mode

• LIGHT -> default light theme
• DARK -> apply dark backgrounds, light text

CHECKPOINT 2: VERIFY TOKENS Cross-reference every extracted token against the golden reference HTML:

• Do the fonts in the HTML match the design system fonts? If the HTML uses a font NOT in the design system, note it and use the HTML value (HTML is the truth).
• Do the colors in the HTML match the design system colors? If they differ, HTML wins.
• The golden reference HTML is ALWAYS the source of truth. The design system provides defaults, but the HTML contains the actual rendered values.

---

PHASE 3: HTML/Code Extraction

Priority 1 - stitch-dev MCP (davideast/stitch-mcp)

Call mcp__stitch-dev__get_screen_code with projectId and screenId to get the exact HTML + Tailwind code. This is the golden source for pixel-perfect conversion.

Also call mcp__stitch-dev__get_screen_image to get a base64 screenshot for validation later.

Priority 2 - Built-in Stitch MCP fallback

If stitch-dev tools are unavailable, inspect the mcp__stitch__get_screen response. It may contain:

• HTML content or a URL to download HTML
• Preview/screenshot URLs
• Component structure data

If HTML URLs are found, use WebFetch to download the HTML content. If screenshot URLs are found, use WebFetch to download and save as reference.

Priority 3 - Stitch web preview

If you find a preview URL (like stitch.withgoogle.com/...), use WebFetch to fetch the page and extract the HTML/CSS.

CRITICAL: Save ALL extracted HTML/CSS in a temporary reference. You will convert this to Next.js components in the next phase. Do NOT discard any CSS values, class names, or inline styles.

---

PHASE 4: Component Generation

Rules - FOLLOW STRICTLY

1. Preserve ALL Tailwind classes verbatim from Stitch output. Do not "clean up" or "simplify" class names.

1. CSS Fidelity Hierarchy (in order of preference):

• Use Stitch's Tailwind classes as-is
• Use Tailwind arbitrary values for custom measurements: text-[15px], w-[372px], tracking-[0.02em], bg-[#1E293B]
• Extend tailwind.config.ts only for design tokens that repeat across multiple components
• Use inline style props ONLY for CSS that Tailwind cannot express (complex gradients, clip-path, unusual filters)

1. Server Components by default. Only add "use client" for components that need:

• Event handlers (onClick, onChange, etc.)
• React hooks (useState, useEffect, etc.)
• Browser APIs

1. ShadCN mapping (when ShadCN is detected in the project):

• Map standard UI patterns to ShadCN components: Button, Card, Input, Dialog, Select, etc.
• BUT override styles using className to match Stitch design EXACTLY
• If a ShadCN component's base styles conflict too much, use raw HTML instead

1. Never guess or approximate:

• If a font size is 15px, use text-[15px] not text-sm
• If a color is #1a2b3c, use bg-[#1a2b3c] not the nearest Tailwind color
• If spacing is 18px, use p-[18px] not p-4
• If line-height is 1.6, use leading-[1.6] not leading-relaxed

Component Structure

src/components/stitch/[ScreenName]/
  [ScreenName].tsx            # Main Server Component
  [ScreenName].client.tsx     # Client interactive parts (only if needed)
  index.ts                    # Re-export

Conversion Steps

1. Parse the Stitch HTML structure
2. Convert HTML tags to JSX (className, htmlFor, etc.)
3. Convert ` to next/image ` component (see Phase 5)
4. Convert ` to next/link ` where appropriate
5. Extract interactive sections into separate .client.tsx files
6. Preserve EVERY class name, every inline style, every data attribute

CHECKPOINT 3: LINE-BY-LINE VERIFICATION After writing each component file, perform a line-by-line diff against the golden reference HTML:

1. Element count: Does your JSX have the same number of elements as the Stitch HTML? Every `, , , , ` must be accounted for.
2. Class audit: For each element, compare the Tailwind classes in your JSX against the Stitch HTML. List any differences. If there are ANY differences that are not JSX syntax conversions (class -> className), fix them immediately.
3. Color audit: Search your generated code for every color value. Cross-reference each hex against the Stitch HTML. No color may be changed, approximated, or replaced with a Tailwind named color.
4. Spacing audit: Search for every padding, margin, gap, width, height value. Each must match the Stitch HTML exactly.
5. Font audit: Verify every font-family, font-size, font-weight, line-height, letter-spacing matches.
6. Image audit: Every ` in Stitch must have a corresponding ` in your code with the same src (after download), dimensions, and alt text.

If ANY discrepancy is found, fix it BEFORE proceeding. Do not move to the next phase with known differences.

---

PHASE 5: Asset Handling

Images

1. Scan the Stitch HTML for ALL image sources:

• `` tags
• background-image: url(...) in styles
• SVG references

1. Download each image:

• Use WebFetch or Bash(curl) to download
• Save to public/assets/stitch/[screen-name]/
• Use descriptive filenames: hero-image.png, logo.svg, avatar-1.jpg

1. Replace references:

• Update src to /assets/stitch/[screen-name]/filename.ext
• Convert ` to from next/image`
• Set proper width, height, and alt attributes
• For background images, keep as CSS background-image with local path

1. Temporary/signed URLs: Stitch CDN URLs may expire. ALWAYS download images immediately, never leave external Stitch URLs in the code.

Icons

• If Stitch uses SVG icons inline, keep them inline
• If Stitch references an icon library, install and use the same library

CHECKPOINT 4: ASSET VERIFICATION

1. Count images in Stitch HTML vs images in your code. Must be equal.
2. Verify every image was downloaded successfully (file exists, non-zero size).
3. Verify image dimensions in ` components match the original ` width/height attributes from Stitch.
4. Verify no Stitch CDN URLs remain in your code - all must be replaced with local paths.

---

PHASE 6: Font Setup

Check existing fonts

Read the project's root layout.tsx to see what fonts are already loaded.

Add missing fonts

For each font from the design system that is NOT already loaded:

import { Inter, Manrope } from "next/font/google";

const inter = Inter({
  subsets: ["latin"],
  variable: "--font-inter",
  display: "swap",
});

const manrope = Manrope({
  subsets: ["latin"],
  variable: "--font-manrope",
  display: "swap",
});

Add the CSS variables to the ` or ` element:

Special case: METROPOLIS

Metropolis is NOT on Google Fonts. If the design uses it:

1. Download the font files
2. Use next/font/local instead:

import localFont from "next/font/local";
const metropolis = localFont({
  src: "./fonts/Metropolis-Regular.woff2",
  variable: "--font-metropolis",
});

Extend Tailwind config

Add font families that reference the CSS variables:

// tailwind.config.ts
theme: {
  extend: {
    fontFamily: {
      headline: ["var(--font-inter)", "sans-serif"],
      body: ["var(--font-manrope)", "sans-serif"],
    },
  },
},

CHECKPOINT 5: FONT VERIFICATION

1. List every font-family used in the Stitch HTML.
2. Verify each one has a corresponding next/font/google (or local) import in layout.tsx.
3. Verify the CSS variable is applied to the `` element.
4. Verify the Tailwind config references the correct CSS variables.
5. Verify font-weight values in your components match Stitch exactly (400, 500, 600, 700, etc.).

---

PHASE 7: Final Verification

This is the final comprehensive check. Do NOT skip any step.

Step 7.1 - Full re-read of generated code

Read back every file you generated. For each file, compare against the golden reference HTML one more time.

Step 7.2 - Screenshot comparison

If get_screen_image tool is available:

1. Call it to get the Stitch screenshot (base64)
2. Save as public/assets/stitch/[screen-name]/stitch-reference.png
3. Tell the user: "Reference screenshot saved. Run the dev server and compare side-by-side."

Step 7.3 - Build check

Run the build to verify no errors:

npm run build

If there are errors, fix them while maintaining pixel-perfect fidelity. Re-verify after every fix.

Step 7.4 - Final Audit Report

Present this to the user with actual values filled in:

PIXEL-PERFECT AUDIT REPORT
===========================

Source: Stitch project [name] / screen [name]

FONTS:
  Design system headline: [font] -> Loaded: [yes/no] -> CSS var: [var]
  Design system body: [font] -> Loaded: [yes/no] -> CSS var: [var]
  Fonts in HTML: [list] -> All loaded: [yes/no]

COLORS:
  Unique colors in Stitch HTML: [count]
  Colors preserved exactly: [count]
  Colors approximated: [count] (should be 0)
  [list any approximations with reason]

SPACING:
  All padding/margin/gap values preserved exactly: [yes/no]
  [list any deviations]

IMAGES:
  Images in Stitch: [count]
  Images downloaded: [count]
  Images with matching dimensions: [count]
  Missing images: [list or "none"]

LAYOUT:
  Structure matches: [yes/no]
  Flex/grid directions match: [yes/no]

BORDER RADIUS:
  Design system roundness: [value]
  Applied correctly: [yes/no]

OVERALL: [PIXEL-PERFECT / HAS DEVIATIONS]

If the report shows ANY deviations (other than user-requested changes), fix them before presenting to the user.

Step 7.5 - Validation Checklist

After the audit report, present:

• [ ] Fonts: Correct font families loaded via next/font/google? Same weights?
• [ ] Font sizes: All sizes match exactly (no rounding to Tailwind defaults)?
• [ ] Colors: All hex values preserved exactly?
• [ ] Spacing: Padding, margin, gap values match pixel-for-pixel?
• [ ] Border radius: Roundness matches the design system setting?
• [ ] Images: All images downloaded and displayed correctly?
• [ ] Layout: Flexbox/Grid structure matches Stitch layout?
• [ ] Responsive: Component respects the target device type?
• [ ] Dark/Light mode: Color mode matches design system?
• [ ] Build: npm run build passes without errors?

---

POST-IMPLEMENTATION: Ongoing

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yshaish1
• Source: yshaish1/stitch-to-nextjs
• License: MIT

Install and usage instructions live in the source repository linked above.