# State Management, Pitfalls & Templates

## metadata.json Schema

```json
{
  "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:

```markdown
# {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}
```
