stitch-integration

What this skill does

# Stitch Integration

This skill encodes the conventions for working with Google Stitch MCP across the design pipeline. Every command that generates or evaluates visual designs references these patterns.

## Tool Discovery

### Finding Stitch MCP Tools

Use `ToolSearch` to locate Stitch tools before invoking them:

```
ToolSearch query: "+stitch"
```

Stitch tools are exposed through MCP and may carry a namespace prefix (e.g., `mcp__stitch__create_project`). The prefix depends on the user's MCP server configuration. Always discover the exact names at runtime rather than hard-coding them.

### Fallback When Stitch Is Not Available

If `ToolSearch` returns no Stitch tools:

1. **Inform the user** — explain that Stitch MCP is required for visual generation and link to setup docs.
2. **Offer text-only mode** — the design pipeline commands can still produce DESIGN.md, prompt libraries, and design specs without Stitch. Skip generation and verification steps.
3. **Never fabricate tool names** — if the tools are not discovered, do not guess at names or attempt calls that will fail.

## Prompt Construction Rules

Every prompt sent to `generate_screen_from_text` or `edit_screens` must follow the **5-element structure**:

### 1. Purpose Statement
A single sentence describing what the screen does and who it serves.

> "A restaurant menu browsing screen for hungry customers deciding what to order."

### 2. Design System Block
Inject the relevant DESIGN.md sections directly into the prompt. At minimum include:
- Color palette with hex values
- Typography scale
- Spacing and radius tokens
- Component patterns relevant to the screen

### 3. Component List
Enumerate the specific UI components that appear on the screen, with their states:
- Navigation bar (active tab: Menu)
- Category filter chips (scrollable, one selected)
- Menu item cards (image, name, price, add-to-cart button)
- Floating cart summary (item count, total, checkout CTA)

### 4. Layout Description
Describe the spatial arrangement:
- Stacking order (what is above/below what)
- Alignment (centered, left-aligned, edge-to-edge)
- Scroll behavior (fixed header, scrollable body)
- Grid or column structure if applicable

### 5. Styling and Mood
Descriptive language about the visual feel. Use physical metaphors:
- "Warm and approachable, like a sunlit kitchen counter"
- "Clean with breathing room, not cramped"
- "Subtle depth — cards float slightly above the background"

### Prompt Rules

| Rule | Rationale |
|------|-----------|
| **One change per prompt** when editing | Stitch handles single edits more reliably than compound changes. Chain multiple `edit_screens` calls for multiple changes. |
| **One screen per generation** | Multi-screen prompts produce inconsistent results. Generate screens individually and use the consistency pattern below. |
| **Descriptive color names + hex** | Write `Warm Terracotta (#C75B3F)` not just `#C75B3F`. Descriptive names improve Stitch's color interpretation. |
| **Realistic content** | Use plausible names, prices, and copy. "Grilled Salmon — $24" not "Item 1 — $X". Realistic content produces better layouts. |
| **Specify viewport** | Always include target dimensions: `Mobile viewport: 390×844 (iPhone 14)` or `Desktop viewport: 1440×900`. |
| **No implementation details** | Describe what the user sees, not how to build it. "A card with rounded corners" not "A div with border-radius: 12px". |

## DESIGN.md Format

Every project should have a `DESIGN.md` at its docs root. This is the single source of truth for visual decisions, and its sections get injected into Stitch prompts.

### Canonical Structure

```
# DESIGN.md

## Visual Theme & Atmosphere
Physical/sensory description of the overall feel.
Use language like "daylight on stone", "warm oak shelf",
"linen tablecloth texture". Avoid abstract jargon.

## Color Palette & Roles

| Role | Name | Hex | Usage |
|------|------|-----|-------|
| Primary Background | Warm Linen | #FAF6F1 | Page and screen backgrounds |
| Surface | Light Oak | #F0E8DC | Cards, elevated panels |
| Primary Action | Terracotta | #C75B3F | CTAs, active states |
| ... | ... | ... | ... |

Every color must have a Role (what job it does), a Name
(physical/descriptive), a Hex (exact value), and a Usage
(where it appears).

## Typography Rules
Font families, size scale, weight rules, line-height ratios.

## Spacing & Radius
Base unit, spacing scale, border-radius tokens.

## Component Patterns
Reusable patterns: buttons, cards, inputs, navigation,
modals, toasts, empty states.

## Shadow & Depth
Elevation levels and their shadow definitions.
Which elements are elevated vs flat.

## Accessibility Constraints
Contrast requirements, focus indicators, touch target
minimums, reduced motion policy.
```

### Writing Style for DESIGN.md

- **Use physical, descriptive language** — "Like light oak shelving" is better than "A warm beige surface"
- **Be specific about hex values** — every color gets a hex code, no exceptions
- **Define roles, not just values** — "Primary Action" tells you when to use it; "#C75B3F" alone does not
- **Keep it scannable** — tables for colors, bullet lists for rules, headings for sections
- **Update it as designs evolve** — DESIGN.md is a living document, not a one-time artifact

## Consistency Patterns

### Feed-Forward Pattern

When generating multiple screens, use this sequence to maintain visual consistency:

1. **Generate anchor screen** — Pick the most visually complex or representative screen first. Generate it with `generate_screen_from_text` and iterate until it meets the design system.

2. **Extract design context** — Use `get_screen` on the anchor screen to retrieve its design details. This captures the specific visual decisions Stitch made (exact spacing, shadows, component rendering).

3. **Prepend to subsequent prompts** — For every following screen, include the extracted design context at the top of the prompt:
   ```
   REFERENCE DESIGN (match this visual style exactly):
   [extracted design context from anchor screen]

   NEW SCREEN:
   [5-element prompt for the new screen]
   ```

4. **Verify at end** — After generating all screens, visually compare them. If drift occurred, use `edit_screens` to bring outliers back in line with the anchor.

### DESIGN.md Injection

The Color Palette, Typography, Spacing, and Component Patterns sections from DESIGN.md must be included in every generation prompt. This is non-negotiable — Stitch has no memory between calls, so the design system must be restated each time.

**Injection format**:
```
DESIGN SYSTEM:
[paste relevant DESIGN.md sections here]

SCREEN:
[5-element prompt]
```

### Cross-Screen Verification

After generating a batch of screens:
1. List all screens with `list_screens`
2. Retrieve each with `get_screen`
3. Check for consistent: color usage, typography hierarchy, spacing rhythm, component styling
4. Use `edit_screens` to fix any drift

## Generation Strategy

### Budget Awareness

Stitch provides two generation modes with monthly limits:

| Mode | Monthly Limit | Use For |
|------|--------------|---------|
| **Standard** | 350 generations | Iteration, exploration, layout testing, rapid prototyping |
| **Experimental** | 50 generations | High-fidelity output, final mockups, presentation-quality screens |

### Strategy Rules

- **Start with Standard** — use Standard mode for all initial exploration and iteration. Switch to Experimental only for final polish.
- **Treat Stitch as an accelerator, not a final renderer** — Stitch output is a design reference and communication tool, not pixel-perfect production art. The code is the final artifact.
- **Iterate incrementally** — generate a base screen, then use `edit_screens` for targeted changes. Each edit is cheaper than a full regeneration.
- **Regenerate selectively** — if only the header is wrong, edit just the header. Don't regenerate the entire screen.
- **Batch planning** — before a generation session, list all screens