/stitch-design-md

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

# 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:

# Design System: [Project Title]
**Project ID:** [numeric ID]
**Devic