acedergren Stitch to React Components
When to Use
Load this skill when the user request matches the frontmatter description for Stitch to React Components.
NEVER
- NEVER fetch without checking
.stitch/designs/first — always ask user about refresh intent before re-downloading - NEVER hardcode hex codes as Tailwind arbitrary values (
bg-[#2563eb]) — extract to theme, use semantic classes - NEVER skip AST validation — architecture checklist is non-optional before marking done
- NEVER put logic in component bodies — event handlers and state logic go in
src/hooks/ - NEVER omit TypeScript interfaces — every component needs a
ReadonlyProps type - NEVER bundle data in component files — all static text, images, lists go in
src/data/mockData.ts - NEVER include Google license headers in generated React components
- NEVER use internal AI fetch tools for Google Cloud Storage URLs — they fail on GCS domains; use the bash script
Namespace Discovery
Run list_tools to find the Stitch MCP prefix (usually stitch: or mcp_stitch:). Use that prefix for all calls.
Call [prefix]:get_screen — captures:
screenshot.downloadUrl+htmlCode.downloadUrlwidth,height,deviceTypedesignTheme(colors, fonts, roundness)
Design Caching Decision
.stitch/designs/{page}.html + .stitch/designs/{page}.png exist?
│
├─ YES → Ask user: "Use cached designs or refresh from Stitch?"
│ Re-download ONLY if user confirms
│
└─ NO → Proceed to download
High-Reliability Download
Internal AI fetch fails on GCS. Use the bash script:
# HTML
bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" ".stitch/designs/{page}.html"
# Screenshot — append =w{width} to URL
bash scripts/fetch-stitch.sh "[screenshot.downloadUrl]=w{width}" ".stitch/designs/{page}.png"
Architecture Rules (Non-Negotiable)
| Rule | Enforcement |
|---|---|
| Modular files | Never output single-file component dumps |
| Logic isolation | Event handlers → src/hooks/ |
| Data decoupling | Static content → src/data/mockData.ts |
| Type safety | Readonly interface named [Component]Props on every component |
| Style mapping | Extract tailwind.config from HTML <head>, sync to resources/style-guide.json |
File Structure
src/
├── components/ # One file per component + index.ts barrel
├── hooks/ # useNavigation.ts, useFormState.ts, etc.
├── data/
│ └── mockData.ts # All static text, images, config
├── styles/
│ └── theme.ts # Extracted Tailwind tokens
└── App.tsx
Validation Sequence
After generating each component:
npm run validate <file_path>— AST compliance- Check against
resources/architecture-checklist.md npm run dev— zero console errors required
A component is not done until it passes the checklist AND the dev server shows no errors.
Troubleshooting
| Issue | Fix |
|---|---|
| Fetch fails (403) | Check script quotes; verify =w{width} appended to screenshot URL |
| AST shows hardcoded styles | Extract hex → style-guide.json → replace with Tailwind class |
| TypeScript prop errors | Add Readonly interface following template in resources/component-template.tsx |
| Theme class not recognized | Verify tailwind.config extracted and synced to style-guide.json |
| Cached screenshot stale | Check file timestamps; ask user to confirm refresh |
Arguments
$ARGUMENTS: Optional user-provided target, path, environment, symptom, or constraint. When empty, infer the narrowest safe scope from the current repository context and ask only if multiple high-impact choices remain.