State Management, Pitfalls & Templates
metadata.json Schema
{
"projectId": "",
"projectTitle": "",
"designSystemId": "",
"screens": {
"desktop": {
"current": "",
"history": []
},
"mobile": {
"current": "",
"history": []
}
},
"interview": {
"projectName": "",
"description": "",
"targetUsers": "",
"cta": "",
"brandFeel": [],
"colorMode": "",
"primaryColor": "",
"colorVariant": "",
"headlineFont": "",
"bodyFont": "",
"roundness": ""
},
"iterationCount": 0,
"status": "interview"
}State Management Rules
- Create
.stitch/directory at project start. - Write
metadata.jsonafter every state-changing operation (project creation, design system creation, screen generation, edit, variant selection, approval). - Status flow:
interview-->designing-->approved-->delivered - If
metadata.jsonexists when the skill starts:interview: resume the interview from where it left off (check which fields are populated).designing: open the last saved HTML in the browser and resume the review loop.approved: proceed to Phase 4 delivery.delivered: inform the user the bundle has already been created and ask if they want to revise.
Common Pitfalls
| Pitfall | Wrong | Right |
|---|---|---|
| Letting user skip brand interview | "Sure, I'll just generate something" | "5 minutes of brand questions saves you 5 rounds of 'this doesn't feel right'" |
| Asking for image uploads | "Can you share your logo?" | Never ask. If user sends one, extract style and save original. |
| Translating CSS feedback literally | Passing "add padding-top: 40px" to Stitch | Translate to design intent: "Add more breathing room above the headline" |
| Overloading prompts | 500-word generation prompt | 6-8 sentences. One sentence per section. |
| Skipping browser preview | Describing the result in text | Always download the HTML and open it in the browser. |
| Retrying slow generation | Calling generate again after 30 seconds | Wait. Use get_screen to check if it completed. |
| Skipping update_design_system | Only calling create_design_system | Must call update immediately after create. |
| Hardcoding tool names | create_project(...) |
Discover namespace via list_tools first. |
| Ignoring output_components | Skipping Stitch suggestions | Present any generation suggestions to the user. |
| Too many interview questions | 20-question survey | 10 questions max across 3 phases. |
DEPLOY.md Template
Use this template when generating the deployment checklist for the bundle:
# {Project Name} -- Landing Page Deployment
## What's In This Bundle
- `index.html` -- Landing page (desktop layout), generated by Stitch
- `mobile.html` -- Mobile-optimized version (if applicable)
- `design/DESIGN.md` -- Brand design system and rationale
- `design/color-tokens.json` -- Design tokens for use in your app's theme
- `assets/` -- Source images for integration (logos, screenshots you provided)
## Design Tokens
- Primary Color: {color name} ({hex})
- Headline Font: {font name} (Google Fonts: {family name})
- Body Font: {font name} (Google Fonts: {family name})
- Border Radius: {roundness description} ({px value})
- Color Mode: {Light/Dark}
## Deployment Checklist
1. Replace placeholder images with real product screenshots or photos
2. Update the CTA link to point to: {CTA destination}
3. If you provided images in `assets/`, swap them into the HTML where placeholders appear
4. Add your analytics snippet (Plausible, PostHog, Google Analytics, etc.)
5. Verify Google Fonts load correctly for: {headline font}, {body font}
6. Test on mobile before going live
## Deployment Options
- **Static host:** Drop `index.html` into Vercel (`vercel deploy`), Netlify (`netlify deploy`), or GitHub Pages
- **Integrate with existing site:** Copy the HTML into your framework's landing route and adjust paths
- **Custom domain:** Point your domain's DNS to your hosting provider per their docs
## Design Decisions
{2-3 sentences explaining key choices made during the session}