---
name: stitch-design-md
description: Analyzes a Stitch project's screens and synthesizes a natural-language DESIGN.md — visual atmosphere, color palette with hex values, typography rules, and Stitch-ready prompt snippets. Use this before stitch-loop or any multi-page build to establish design consistency.
allowed-tools:
  - "stitch*:*"
  - "Read"
  - "Write"
---

# Stitch → DESIGN.md

**Constraint:** Only use this skill when the user explicitly mentions "Stitch" or when preparing design system documentation for Stitch generation.

You are an expert **Design Systems Lead**. Your job is to analyze Stitch project assets and synthesize a **Semantic Design System** into a file named `DESIGN.md` — written in natural language, not CSS.

## When to use this vs. stitch-design-system

| Skill | What it produces | Use it for |
|-------|-----------------|-----------|
| `stitch-design-md` | Natural-language `DESIGN.md` | Feeding back into Stitch prompts; multi-page visual consistency; design docs |
| `stitch-design-system` | `design-tokens.css`, `tailwind-theme.css`, `DESIGN.md` | Code-level theming for Next.js, Svelte, React, HTML output |

Use `stitch-design-md` first if you're building more Stitch screens. Use `stitch-design-system` when you're converting to code.

## Prerequisites

- Stitch MCP Server configured
- A Stitch project with at least one designed screen

---

## Step 1: Retrieve the design

### If the user provides a Stitch URL

If the user pastes a Stitch design URL like `https://stitch.withgoogle.com/projects/3492931393329678076?node-id=375b1aadc9cb45209bee8ad4f69af450`:

1. Parse the URL:
   - `projectId` = segment after `/projects/` and before `?` (e.g. `3492931393329678076`)
   - `screenId` = query param `node-id` (e.g. `375b1aadc9cb45209bee8ad4f69af450`)
2. Call `[prefix]:get_screen` with those IDs
3. Skip ahead to Step 2

### If project/screen IDs are unknown

1. Run `list_tools` → find the Stitch MCP prefix
2. Call `[prefix]:list_projects` with `filter: "view=owned"` → select project by title → extract numeric ID
3. Call `[prefix]:list_screens` with `projects/[projectId]` → pick the representative screen
4. Call `[prefix]:get_screen` with numeric `projectId` and `screenId`
5. Call `[prefix]:get_project` with `projects/[projectId]` → get full `designTheme` including:
   - Core: `colorMode`, `customColor`, `colorVariant`, `roundness`, `spacingScale`
   - Fonts: `headlineFont`, `bodyFont`, `labelFont`
   - Colors: `namedColors` (40+ semantic tokens), override colors
   - Documentation: `designMd` (auto-generated design system — if present, use as foundation for DESIGN.md)
   - Backgrounds: `backgroundLight`, `backgroundDark`

### Download the assets

```bash
# Download the HTML for color and Tailwind class analysis
bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"
```

Parse the HTML for:
- Tailwind utility classes (colors, typography, spacing, shadows)
- Inline `tailwind.config` block (custom tokens)
- CSS variables

---

## Step 2: Analyze the design

Work through these layers systematically:

### 2.1 Project identity
- Project title and numeric ID (from `name` field)
- `deviceType` (MOBILE / DESKTOP / TABLET / AGNOSTIC)
- `designTheme.headlineFont`, `designTheme.bodyFont`, `designTheme.labelFont` (font roles)
- `designTheme.roundness`, `designTheme.colorMode`, `designTheme.colorVariant`
- `designTheme.spacingScale` (0=minimal, 1=compact, 2=normal, 3=spacious)

### 2.2 Visual atmosphere
If `designTheme.description` exists, use it as the starting point. If `designTheme.designMd` exists, it contains a full design system document — extract the creative direction, do's/don'ts, and component philosophy from it.

Then describe the aesthetic in 2–3 sentences. Go beyond generic adjectives — what does it feel like? What editorial or product category does it evoke?

Examples:
- "Sophisticated minimalist sanctuary — gallery-like spaciousness, photography-first, Scandinavian calm"
- "High-density productivity tool — information-first, sharp edges, focused contrast"
- "Warm artisanal brand — handcrafted feel, organic textures, generous breathing room"

### 2.3 Color palette

**If `namedColors` is available from `get_project`:** Use it as the authoritative color source. It provides 40+ semantic tokens (primary, secondary, tertiary, surface hierarchy, error states, inverse variants). Map these directly to palette documentation instead of guessing from HTML.

**If `backgroundLight`/`backgroundDark` are available:** Use them as the canonical background colors for light/dark modes.

For each key color, write:
```
[Descriptive name] ([hex]) — [functional role]
```

Example:
```
Deep Muted Teal-Navy (#294056) — Primary actions, links, active states
Warm Barely-There Cream (#FCFAFA) — Page background
Charcoal Near-Black (#2C2C2C) — Headlines and product names
Soft Warm Gray (#6B6B6B) — Body copy and metadata
```

Aim for 4–6 colors. Include light AND dark mode backgrounds if both present.

### 2.4 Typography
- Font family name (from `designTheme.font` or Tailwind class)
- Weight scale (what's used for display, section headers, body, labels)
- Any notable letter-spacing, line-height, or size conventions

### 2.5 Shape and geometry
Translate Tailwind classes to descriptive language:
- `rounded-full` → "Pill-shaped"
- `rounded-lg` (12px) → "Gently rounded corners"
- `rounded-md` (8px) → "Subtly rounded corners"
- `rounded-none` → "Sharp, squared-off edges"

### 2.6 Depth and elevation
Describe shadow presence and style:
- `shadow-none` → "Flat, no shadow"
- `shadow-sm` → "Whisper-soft diffused shadow"
- `shadow-lg` → "Prominent floating elevation"

### 2.7 Layout principles
- Max content width, grid columns, breakpoint behavior
- Base spacing unit (4px / 8px system)
- Section margins and padding patterns
- Touch target sizes (if mobile)

---

## Step 3: Write DESIGN.md

Use this exact structure:

```markdown
# Design System: [Project Title]
**Project ID:** [numeric ID]
**Device:** [MOBILE / DESKTOP / TABLET / AGNOSTIC]

## 1. Visual Theme & Atmosphere
[2–3 sentences describing the overall aesthetic and mood]

## 2. Color Palette & Roles
- **[Descriptive Name]** ([#hex]) — [Functional role]
- **[Descriptive Name]** ([#hex]) — [Functional role]
[...4–6 colors total]

## 3. Typography Rules
**Primary Font:** [Name] — [One-line character description]

- **Display (H1):** [weight], [size range]
- **Section (H2):** [weight], [size range]
- **Body:** [weight], line-height [value], [size]
- **Labels/Captions:** [weight], [size]

## 4. Component Stylings
- **Buttons:** [shape (Xpx radius)], [color], [padding]; hover [behavior]
- **Cards/Containers:** [roundness (Xpx)], [background], [shadow]; hover [behavior]
- **Inputs/Forms:** [border style], [background], [roundness], [focus behavior]

## 5. Layout Principles
- Max content width: [value]; [grid description]; [column behavior at breakpoints]
- Base spacing unit: [4px/8px]; section margins [range]; touch targets [size]

## 6. Design System Notes for Stitch Generation
[This section is copy-paste ready for new Stitch prompts]

When creating new screens:
- **Atmosphere:** "[Quote the atmosphere description from Section 1]"
- **Colors:** Always use descriptive name + hex (e.g. "[Name] ([#hex])")
- **Shape:** "[Describe buttons and cards using the language from Section 4]"
- **Spacing:** "[Describe the whitespace/density philosophy]"
- **Font:** [Font name] — [one-line descriptor]
```

---

## Step 4: Integration

Tell the user what to do with it:

```
## DESIGN.md created

Saved to: ./DESIGN.md

**How to use it:**

1. **More Stitch screens:** Copy Section 6 into the DESIGN SYSTEM block of your next Stitch prompt.
   This keeps every new screen visually consistent with your existing design.

2. **Multi-page build with stitch-loop:** Include Section 6 in every `next-prompt.md` baton file.

3. **Code conversion:** Hand off to `stitch-design-system` when you're ready to generate
   `design-tokens.css` and `tailwind-theme.css` for your framework.
```

---

## Best practices

- **Descriptive over technical:** "Ocean-deep Cerulean (#0077B6)" not just "blue"
- **Functional roles matter:** Don't just name the color — say what it does
- **Section 6 is the payoff:** This is the copy-paste block that makes every future screen consistent
- **Be precise:** Exact hex codes always. Vague approximations ("kind of warm beige") are useless

## Common pitfalls

- Leaving `rounded-xl` in the doc instead of translating to "generously rounded corners (12px)"
- Listing colors without functional roles
- Skipping the font weight scale (just saying "Manrope" doesn't tell you when to use 400 vs 600)
- Writing Section 6 without the actual hex codes — useless for Stitch

---

## References

- `examples/usage.md` — Worked examples
- `examples/DESIGN.md` — Complete sample output for a furniture e-commerce site
- `docs/color-prompt-guide.md` — 8 ready-to-use color palettes for inspiration
- `scripts/fetch-stitch.sh` — Reliable HTML downloader for GCS URLs