how-to-guide

How to Navigate the 4-Phase Conversion Process in stitch::react-components

July 12, 2026 google-labs-code/stitch-skills ↗

The stitch::react-components workflow converts Stitch designs into production-ready React code through four mandatory phases—Retrieval & Networking, Style Extraction, Architectural Rules, and Execution & Validation—each guarded by specific gates that must be satisfied before proceeding.

The google-labs-code/stitch-skills repository provides a structured skill for transforming Stitch design files into a type-safe Vite/React codebase. Understanding how to navigate the 4-phase conversion process ensures you produce modular, validated components that strictly adhere to the architectural rules defined in SKILL.md.

Phase 1: Retrieval & Networking

The first phase focuses on pulling every screen’s design assets from the Stitch MCP and auditing them visually. You must treat this as a mandatory prerequisite; the subsequent phases depend on these local assets.

Gate: Asset Download and Visual Audit

You cannot proceed until all screens have been downloaded via scripts/fetch-stitch.sh and each screenshot has been inspected.

Begin by discovering the MCP prefix using list_tools. Then call [prefix]:get_screen for every screen in the design. Check if .stitch/designs/{page}.html and .stitch/designs/{page}.png already exist; if they do, ask whether to reuse or refresh them.

Execute the download commands for both HTML and screenshot assets:


# Download HTML and screenshot (append =w{width} for images)

bash scripts/fetch-stitch.sh "https://storage.googleapis.com/.../screen.html" ".stitch/designs/home.html"
bash scripts/fetch-stitch.sh "https://storage.googleapis.com/.../screen.png=w360" ".stitch/designs/home.png"

Visually audit each .png to verify the download succeeded, then save project metadata to .stitch/metadata.json.

Phase 2: Style Extraction

Once assets are local, extract the design tokens to build a project-specific Tailwind configuration. This phase ensures your React components use consistent colors, typography, and spacing derived directly from the Stitch design.

Gate: Tailwind Token Verification

You must confirm that resources/style-guide.json contains tokens freshly extracted from the current project’s HTML <head>.

Open each downloaded HTML file and locate the <script> block that declares tailwind.config. Extract the color, font, spacing, border-radius, and typography tokens. Overwrite resources/style-guide.json with these values and verify that the primary color, fonts, and spacing match the design screenshots.

// Example structure for resources/style-guide.json
{
  "colors": {
    "primary": "#3b82f6",
    "secondary": "#64748b"
  },
  "fontFamily": {
    "sans": ["Inter", "sans-serif"]
  }
}

Phase 3: Architectural Rules

This phase restructures the design into a clean, modular React codebase. The goal is strict separation of concerns: UI components remain presentational, logic lives in hooks, and data is decoupled into mock files.

Gate: Validation Compliance

Every component must satisfy all architectural rules; otherwise npm run validate will fail.

Modular components – Create a separate file under src/components/ for each reusable UI pattern (cards, badges, navigation bars).

Logic isolation – Move event handlers and business logic into custom hooks under src/hooks/.

Data decoupling – Place all static text, image URLs, and lists in src/data/mockData.ts.

Type safety – Each component file must export a Readonly props interface named <ComponentName>Props.

Navigation wiring – Replace every href="#" with a React-Router <Link>; ensure the top-app-bar logo links to /.

Style mapping – Use Tailwind classes derived from style-guide.json; avoid hard-coded hex values.

Dark mode – Apply dark: variants to all color classes.

// Example component scaffold from resources/component-template.tsx
import React from "react";

interface HeaderProps {
  readonly title: string;
}

export const Header: React.FC<HeaderProps> = ({ title }) => (
  <header className="bg-primary text-white dark:bg-primary-dark p-4">
    <h1>{title}</h1>
  </header>
);

export default Header;

Phase 4: Execution & Validation

The final phase assembles the codebase, runs validation scripts, and optionally starts the development server. This is where you verify that the conversion meets the architectural standards.

You must obtain explicit user consent before running any validation scripts, starting the dev server, or performing automated browser testing.

First, run npm install if node_modules is missing. Populate src/data/mockData.ts with the extracted design content. Scaffold components from resources/component-template.tsx, replacing the placeholder StitchComponent with your real component name. Wire the new components into App.tsx (or the appropriate route entry).

After receiving permission, execute the validation pipeline:


# Validate individual components

npm run validate src/components/Header.tsx

# Ensure TypeScript compiles

tsc --noEmit

# Compare against the architecture checklist

If validation passes, start the dev server with npm run dev and perform a final visual audit.

Key Files and Resources

The conversion process relies on specific files within the google-labs-code/stitch-skills repository:

Summary

  • Respect the gates – Each phase has a mandatory gate that blocks progression until satisfied; skipping steps causes validation failures.
  • Automate asset retrieval – Use scripts/fetch-stitch.sh to download screens and always visually audit the resulting PNG files.
  • Extract tokens early – Generate resources/style-guide.json from the HTML <head> before writing components to ensure design consistency.
  • Enforce architecture – Isolate logic in src/hooks/, data in src/data/mockData.ts, and UI in src/components/ with Readonly TypeScript interfaces.
  • Validate before serving – Run npm run validate and tsc --noEmit after user consent, comparing results against resources/architecture-checklist.md.

Frequently Asked Questions

What happens if I skip a gate in the stitch::react-components process?

Skipping any mandatory gate will cause validation failures in subsequent phases. For example, proceeding to Phase 3 without extracted style tokens in resources/style-guide.json will result in hard-coded values that fail the architectural validation rules. The npm run validate command specifically checks for compliance with the previous phases' outputs.

Can I reuse existing design files from a previous conversion?

Yes, but you must explicitly verify their currency. If .stitch/designs/{page}.html and .png files exist, the workflow requires you to ask the user whether to reuse or refresh them. Even when reusing, you must still satisfy the Phase 1 gate by visually auditing the existing screenshots to confirm they match the current design requirements.

Where should I place business logic in the converted React codebase?

Business logic and event handlers must be isolated in custom hooks under src/hooks/. The architectural rules in Phase 3 strictly forbid placing logic directly inside component files in src/components/. This separation ensures that components remain presentational and easily testable, while complex interactions are centralized in reusable hook functions.

How do I ensure dark mode support in the converted components?

During Phase 3, you must apply dark: Tailwind variants to all color classes derived from resources/style-guide.json. The validation step in Phase 4 checks that color values use these variants rather than static hex codes. This ensures the application responds correctly to system dark mode preferences while maintaining the design token consistency established in Phase 2.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →