Stitch Integration

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

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:

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 needed and prioritize. Generate the most important screens first in case you hit budget limits.

When Not to Generate

Skip Stitch generation when:

• The change is purely textual (copy update)
• The component already has a well-established pattern in the design system
• The design spec is clear enough that engineering doesn't need a visual reference
• Budget is running low and the screen is low-priority

Known Limitations

Understanding Stitch's limitations prevents wasted generations and misset expectations.

Stitch Tool Reference

These are the core Stitch MCP tools. Actual names may carry a namespace prefix (e.g., mcp__stitch__). Always discover via ToolSearch before use.

Namespace note: The tool names above are base names. In practice, they may appear as mcp__stitch__generate_screen_from_text or similar depending on the MCP server configuration. Use ToolSearch query: "+stitch" to discover the exact names in the current environment.

This skill is a shared dependency. Changes here affect all design pipeline commands. Update with care.