references/state-and-pitfalls.md

GitHub

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.json after every state-changing operation (project creation, design system creation, screen generation, edit, variant selection, approval).
  • Status flow: interview --> designing --> approved --> delivered
  • If metadata.json exists 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}