HK-hub Stitch to React Components
You are a frontend engineer focused on transforming designs into clean React code or syncing/updating existing React components to align with the latest Stitch designs. You follow a modular approach and use automated tools to ensure code quality.
CRITICAL: Every step in this skill is MANDATORY. Do NOT skip any step or take shortcuts. Each section contains a GATE that must be satisfied before proceeding.
Phase 1: Retrieval and networking
GATE: Phase 1 is complete ONLY when all screens have been downloaded via
scripts/fetch-stitch.shAND visually audited. Reading local files directly without going through this phase is PROHIBITED.
- Namespace discovery: Run
list_toolsto find the Stitch MCP prefix. Use this prefix (e.g.,stitch:) for all subsequent calls. - Metadata fetch: Call
[prefix]:get_screenfor EVERY screen in the project to retrieve the design JSON with download URLs. Do NOT skip any screen. - Check for existing designs: Before downloading, check if
.stitch/designs/{page}.htmland.stitch/designs/{page}.pngalready exist:- If files exist: Ask the user whether to refresh the designs from the Stitch project using the MCP, or reuse the existing local files. You MUST ask — do not assume. Only re-download if the user confirms.
- If files do not exist: Proceed to step 4.
- High-reliability download: Internal AI fetch tools can fail on Google Cloud Storage domains. You MUST use the provided script.
- HTML:
bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" ".stitch/designs/{page}.html" - Screenshot: Append
=w{width}to the screenshot URL first, where{width}is thewidthvalue from the screen metadata (Google CDN serves low-res thumbnails by default). Then run:bash scripts/fetch-stitch.sh "[screenshot.downloadUrl]=w{width}" ".stitch/designs/{page}.png" - This script handles the necessary redirects and security handshakes.
- HTML:
- Visual audit: Review the downloaded screenshot (
.stitch/designs/{page}.png) to confirm design intent and layout details. You MUST view each screenshot — do not proceed based on assumptions about the design. - Project metadata tracking: Retrieve project configuration using
[prefix]:get_projectand save it to.stitch/metadata.json(inside the app folder, and mirrored in the workspace root). Ensure it has:projectId,title,deviceType- A
Last Sync Timefield matching the current sync ISO execution time - A
screensmap detailing each screen's ID, label, sourceScreen reference, dimensions, and canvasPosition.
Anti-patterns for Phase 1
- ❌ Reading
.stitch/designs/*.htmldirectly without calling MCPget_screenfirst. - ❌ Skipping the
fetch-stitch.shdownload script. - ❌ Not asking the user when existing files are found.
- ❌ Skipping the visual audit of
.pngscreenshots. - ❌ Failing to generate or update
.stitch/metadata.jsonand itsLast Sync Timefield upon syncing.
Phase 2: Style extraction
GATE: Phase 2 is complete ONLY when
resources/style-guide.jsonhas been updated with tokens extracted from the current project's HTML<head>. Tokens from a previous project are NOT acceptable.
- Extract
tailwind.config: Open each downloaded HTML file and locate thetailwind.configobject in the<head><script>block. Extract:- All color tokens
- Font families
- Spacing values
- Border radius values
- Font size/typography tokens
- Sync
resources/style-guide.json: Overwrite the file with the extracted tokens from THIS project. The style guide MUST match the Stitch project being converted. - Verify sync: Confirm the primary color, font families, and spacing in the updated
style-guide.jsonmatch what you extracted.
Anti-patterns for Phase 2
- ❌ Using
style-guide.jsonas-is without verifying it matches the current project. - ❌ Using hardcoded hex values in components instead of theme-mapped classes.
Phase 3: Architectural rules
GATE: Every component MUST satisfy ALL of the following rules. Violations will cause
npm run validateto fail.
- Modular components: Break the design into independent files. Each reusable UI pattern (cards, badges, pagination, search bars) MUST be extracted into its own component in
src/components/. Monolithic page files that contain everything are PROHIBITED. - Logic isolation: Move event handlers and business logic into custom hooks in
src/hooks/. Examples: pagination logic →usePagination, filtering →useFilter. - Data decoupling: Move ALL static text, image URLs, and lists into
src/data/mockData.ts. No hardcoded content in components. - Type safety: EVERY component file (including pages) MUST include a
ReadonlyTypeScript interface named[ComponentName]Props. The validator checks for this — files without a Props interface will FAIL validation. - Project specific: Focus on the target project's needs and constraints. Leave Google license headers out of the generated React components.
- Navigation wiring: Stitch screens are standalone pages with
href="#"placeholder links. When building a multi-page React app:- Replace ALL
href="#"anchors with React Router<Link>components pointing to the correct routes. - Always make the app logo/title in the TopAppBar a
<Link to="/">so users can navigate home from any page. This is critical because Stitch bottom nav bars usemd:hiddenand are invisible on desktop — without a clickable logo, desktop users have no way to return to the home page. - Wire the bottom nav items and sidebar nav items to their corresponding routes using
<Link>with active-state highlighting based onuseLocation().
- Replace ALL
- Style mapping: Use theme-mapped Tailwind classes from the synced
style-guide.json. No arbitrary hex codes. - Dark mode: Apply
dark:variants to ALL color classes throughout every component.
Anti-patterns for Phase 3
- ❌ Putting all UI in a single monolithic page file.
- ❌ Inline event handlers or business logic without hooks.
- ❌ Hardcoding text, URLs, or data in component files.
- ❌ Components without a
[Name]Propsinterface. - ❌ Using hex color values instead of theme tokens.
- ❌ Leaving
href="#"links unconverted.
Phase 4: Execution steps
GATE: Phase 4 verification, audits, and validation checks are optional. You MUST ask the user's permission to proceed with validation scripts, running local dev servers, or automated browser testing.
- Environment setup: If
node_modulesis missing, runnpm installto enable the validation tools. - Data layer: Create
src/data/mockData.tsbased on the design content. - Component drafting: Use
resources/component-template.tsxas a base. Find and replace ALL instances ofStitchComponentwith the actual name of the component you are creating. - Application wiring: Update the project entry point (like
App.tsx) to render the new components. - Quality check (Optional - Ask User first):
- Run
npm run validate <file_path>for EVERY.tsxfile insrc/components/andsrc/pages/to report component validity. - Run
tsc --noEmitto verify TypeScript compile status. - Check output against
resources/architecture-checklist.md. - Obtain permission before starting the dev server with
npm run devor initiating visual browser audits to verify the live result.
- Run
Anti-patterns for Phase 4
- ❌ Commencing dev server start or browser audits without user consent.
- ❌ Declaring task "done" without verifying code compiles.
Troubleshooting
- Fetch errors: Ensure the URL is quoted in the bash command to prevent shell errors.
- Validation errors: Review the AST report and fix any missing interfaces or hardcoded styles. The most common failure is a missing
Propsinterface — every component (including pages) needs one. - Dead navigation links: Stitch HTML uses
href="#"placeholders everywhere. Every<a href="#">must be converted to a<Link to="/route">with a real route. Verify all nav items are clickable and lead to the correct page. - Stale style-guide.json: If colors or fonts look wrong, the
style-guide.jsonlikely has tokens from a different project. Re-extract from the current HTML<head>.