Generating Stitch Screens

Generating Stitch Screens

Orchestrate screen generation in Google Stitch using MCP tools. Reads authored prompt files, sends each section to Stitch for generation, and fetches resulting images and code.

Prerequisites

Requires Stitch MCP server (@_davideast/stitch-mcp). If MCP tools are not available, display:

Stitch MCP is not configured.
Run /stitch-setup for guided setup, or see the plugin README for manual configuration.

Never fail silently. Always inform the user if MCP is unavailable.

Typically invoked via /stitch-generate or after prompt authoring with MCP available.

Quick Start

1. Read prompt file from design-intent/google-stitch/{feature}/prompt-v{N}.md 2. Parse sections by --- separators, extracting <!-- Layout: --> and <!-- Component: --> markers 3. Create or select project via MCP (create_project / list_projects) 4. Generate screens — for each section: call generate_screen_from_text with prompt text 5. Fetch images — for each screen: call fetch_screen_image at full resolution, save to {feature}/exports/ (see WORKFLOW.md for URL transformation) 6. Fetch code (optional) — call fetch_screen_code, save to {feature}/code/ 7. Extract design context (optional) — call extract_design_context, save design DNA 8. Report — project URL, screen list, file paths

Output Structure

design-intent/google-stitch/{feature}/
├── prompt-v{N}.md              <- Source prompts
├── exports/                    <- Generated images
│   ├── {layout-name}.png
│   ├── {component-1}.png
│   └── {component-2}.png
├── code/                       <- Generated code (optional)
│   ├── {layout-name}/
│   └── {component-1}/
└── design-dna.md               <- Extracted design context (optional)

Section Parsing

Prompt files use --- separators with HTML comment labels:

<!-- Layout: Analytics Dashboard -->
[layout prompt text]

---

<!-- Component: KPI Metrics -->
[component prompt text]

---

<!-- Component: Revenue Chart -->
[component prompt text]

Parse each section independently. Use the label text as the screen name in Stitch.

Error Handling

• Partial failure: If some screens fail to generate, continue with remaining sections and report failures
• Generation timeout: Wait, then retry once. If still pending, report and suggest checking Stitch directly
• Empty result from fetch: Generation may still be in progress — wait briefly and retry

Workflow Details

See WORKFLOW.md for detailed steps, error handling, and retry logic.

Examples

See EXAMPLES.md for end-to-end generation scenarios.

Troubleshooting

See TROUBLESHOOTING.md for MCP-specific issues.

Generating Stitch Screens — Examples

Example 1: Basic Single-Prompt Generation

Input: User has a single-component prompt file.

Prompt File: design-intent/google-stitch/login/prompt-v1.md

<!-- Component: Login Form -->
Design a login form for a web app.
Include: centered card with logo, email input field, password input field, "Sign In" button, "Forgot password?" link below, "Don't have an account? Sign up" link at bottom.
Style: clean, modern, centered layout, Ocean Blue (#005A8D) primary button, rounded inputs, subtle card shadow.
Optimize for mobile-first, full keyboard navigation.

Generation Flow: 1. Parse: 1 section found — Component: Login Form 2. Create project: "Login Design" 3. Generate: generate_screen_from_text with login form prompt 4. Fetch: fetch_screen_image -> exports/login-form.png

Output:

Stitch Generation Complete

Project: Login Design
Feature: login/

Screens (1/1):
  1. Component: Login Form -> exports/login-form.png

Directory:
  design-intent/google-stitch/login/
  ├── prompt-v1.md
  └── exports/
      └── login-form.png

---

Example 2: Multi-Prompt File (Layout + Components)

Input: Dashboard prompt file with layout and 3 components.

Prompt File: design-intent/google-stitch/dashboard/prompt-v1.md

<!-- Layout: Analytics Dashboard -->
Design a web dashboard page for SaaS analytics overview.
[...layout prompt...]

---

<!-- Component: KPI Metrics -->
Design metric cards displaying key performance indicators.
[...component prompt...]

---

<!-- Component: Revenue Chart -->
Design an interactive line chart for monthly revenue tracking.
[...component prompt...]

---

<!-- Component: Subscription Activity -->
Design a subscription activity table showing recent changes.
[...component prompt...]

Generation Flow: 1. Parse: 4 sections found (1 layout + 3 components) 2. Create project: "Dashboard Design" 3. Generate screens sequentially:

   [1/4] Generating: Layout: Analytics Dashboard...
   [2/4] Generating: Component: KPI Metrics...
   [3/4] Generating: Component: Revenue Chart...
   [4/4] Generating: Component: Subscription Activity...

4. Fetch images for all 4 screens

Output:

Stitch Generation Complete

Project: Dashboard Design
Feature: dashboard/

Screens (4/4):
  1. Layout: Analytics Dashboard        -> exports/analytics-dashboard.png
  2. Component: KPI Metrics             -> exports/kpi-metrics.png
  3. Component: Revenue Chart           -> exports/revenue-chart.png
  4. Component: Subscription Activity   -> exports/subscription-activity.png

Directory:
  design-intent/google-stitch/dashboard/
  ├── prompt-v1.md
  └── exports/
      ├── analytics-dashboard.png
      ├── kpi-metrics.png
      ├── revenue-chart.png
      └── subscription-activity.png

---

Example 3: Split File Generation (Part Files)

Input: Admin panel with 8 prompts split across 2 files.

Files:

• admin-panel/prompt-v1-part1.md (6 prompts)
• admin-panel/prompt-v1-part2.md (2 prompts)

Generation Flow: 1. Detect part files in feature directory 2. Process part1 first (6 screens), then part2 (2 screens) 3. All exports saved to same exports/ directory

Output:

Stitch Generation Complete

Project: Admin Panel Design
Feature: admin-panel/

Screens (8/8) from 2 part files:

Part 1 (prompt-v1-part1.md):
  1. Layout: Admin Panel                -> exports/admin-panel.png
  2. Component: Navigation Sidebar      -> exports/navigation-sidebar.png
  3. Component: Dashboard Overview      -> exports/dashboard-overview.png
  4. Component: User Management Table   -> exports/user-management-table.png
  5. Component: Role Permissions Matrix -> exports/role-permissions-matrix.png
  6. Component: System Settings Form    -> exports/system-settings-form.png

Part 2 (prompt-v1-part2.md):
  7. Component: Audit Logs Viewer       -> exports/audit-logs-viewer.png
  8. Component: Notification Center     -> exports/notification-center.png

Directory:
  design-intent/google-stitch/admin-panel/
  ├── prompt-v1-part1.md
  ├── prompt-v1-part2.md
  └── exports/
      ├── admin-panel.png
      ├── navigation-sidebar.png
      ├── dashboard-overview.png
      ├── user-management-table.png
      ├── role-permissions-matrix.png
      ├── system-settings-form.png
      ├── audit-logs-viewer.png
      └── notification-center.png

---

Example 4: Generation from Raw Text (/stitch-generate)

User runs:

/stitch-generate "landing page for SaaS product"

Flow: 1. Detect raw text input (not a file path) 2. Invoke authoring-stitch-prompts skill to author prompt file 3. Skill creates: design-intent/google-stitch/landing/prompt-v1.md 4. Parse authored prompt (3 sections: layout + hero + feature grid) 5. Generate screens via MCP 6. Fetch images

Output:

Stitch Generation Complete

Authored: design-intent/google-stitch/landing/prompt-v1.md
Project: Landing Design
Feature: landing/

Screens (3/3):
  1. Layout: Landing Page    -> exports/landing-page.png
  2. Component: Hero Section -> exports/hero-section.png
  3. Component: Feature Grid -> exports/feature-grid.png

Directory:
  design-intent/google-stitch/landing/
  ├── prompt-v1.md
  └── exports/
      ├── landing-page.png
      ├── hero-section.png
      └── feature-grid.png

---

Example 5: Generation with Code Fetching

User runs:

/stitch-generate @design-intent/google-stitch/dashboard/prompt-v1.md

User requests: "Also fetch the generated code"

Additional Step: After image fetching, code is also fetched for each screen.

Output:

Stitch Generation Complete

Project: Dashboard Design
Feature: dashboard/

Screens (4/4):
  1. Layout: Analytics Dashboard        -> exports/analytics-dashboard.png
  2. Component: KPI Metrics             -> exports/kpi-metrics.png
  3. Component: Revenue Chart           -> exports/revenue-chart.png
  4. Component: Subscription Activity   -> exports/subscription-activity.png

Code fetched for all screens.

Directory:
  design-intent/google-stitch/dashboard/
  ├── prompt-v1.md
  ├── exports/
  │   ├── analytics-dashboard.png
  │   ├── kpi-metrics.png
  │   ├── revenue-chart.png
  │   └── subscription-activity.png
  └── code/
      ├── analytics-dashboard/
      ├── kpi-metrics/
      ├── revenue-chart/
      └── subscription-activity/

---

Example 6: Partial Failure with Retry Guidance

Input: 4-screen dashboard prompt file.

Generation Flow: 1. Screens 1-2 generate successfully 2. Screen 3 fails (timeout) 3. Screen 4 generates successfully 4. Retry screen 3 — still fails

Output:

Stitch Generation: 3/4 screens

Succeeded:
  1. Layout: Analytics Dashboard        -> exports/analytics-dashboard.png
  2. Component: KPI Metrics             -> exports/kpi-metrics.png
  4. Component: Subscription Activity   -> exports/subscription-activity.png

Failed:
  3. Component: Revenue Chart           -> Error: Generation timeout after retry

To retry failed screens, run:
  /stitch-generate @design-intent/google-stitch/dashboard/prompt-v1.md

Or generate the specific component manually in Stitch using the prompt from the file.

Generating Stitch Screens — Troubleshooting

MCP Tools Not Detected

Symptom: Skill reports "Stitch MCP is not configured" even though you believe it should be set up.

Causes:

• MCP server not configured in .mcp.json
• Stitch API access not approved (403 errors)
• Node.js/npx not available in PATH

Fix: 1. Run /stitch-setup for guided verification 2. Check that Node.js is installed: node --version 3. Verify MCP is configured: claude mcp list 4. If not configured, add to your project's .mcp.json (see plugin README) 5. Restart Claude Code to reload MCP servers

Note: Stitch API requires preview/allowlist access from Google. If you get 403 errors, you need to request access before MCP will work.

---

Authentication Failed

Symptom: list_projects or generate_screen_from_text returns authentication error.

Causes:

• Google Cloud ADC credentials expired
• No credentials configured
• Wrong Google account authenticated

Fix: 1. Refresh credentials:

   gcloud auth application-default login

2. Verify the correct account:

   gcloud auth list

3. Ensure your account has access to Google Stitch / AI Studio

---

Generation Timeout

Symptom: generate_screen_from_text hangs or returns timeout error.

Causes:

• Complex prompt requiring longer processing
• Stitch service under heavy load
• Network connectivity issues

Fix: 1. Wait and retry — generation can take 30-60 seconds for complex prompts 2. Simplify the prompt (fewer components, shorter description) 3. Check Stitch service status at stitch.withgoogle.com 4. Try generating directly in the Stitch web UI to isolate the issue

---

No Screens Created

Symptom: generate_screen_from_text succeeds but returns no screen ID or empty result.

Causes:

• Prompt text too short or vague for Stitch to process
• Invalid prompt format (non-UI content)
• Project quota exceeded

Fix: 1. Validate prompt format — ensure it follows Stitch conventions (directive sentence + bullets + style cues) 2. Check prompt length — minimum ~20 words for meaningful generation 3. Try the prompt text directly in the Stitch web UI 4. Check project quotas in Google Cloud console

---

fetch_screen_image Returned Empty

Symptom: Image fetch returns empty or null after successful generation.

Causes:

• Generation still in progress (image not yet rendered)
• Screen generation failed silently
• Temporary Stitch backend issue

Fix: 1. Wait 5-10 seconds and retry the fetch 2. Check screen status via get_project to see if generation completed 3. Try fetching from the Stitch web UI directly 4. If persistent, regenerate the screen

---

STITCH_PROJECT_ID Not Set

Symptom: Skill creates a new project every time instead of reusing an existing one.

Causes:

• STITCH_PROJECT_ID environment variable not configured
• Variable set in wrong shell profile

Fix: 1. Set the variable:

   export STITCH_PROJECT_ID="your-project-id"

2. Add to shell profile (~/.zshrc, ~/.bashrc) for persistence 3. Find your project ID via list_projects or from the Stitch web UI URL 4. Run /stitch-setup to verify the configuration

---

Prompt File Parsing Errors

Symptom: Skill can't find sections in prompt file or generates wrong number of screens.

Causes:

• Missing --- separators between sections
• Missing or malformed HTML comment labels
• Extra content outside of labeled sections

Fix: 1. Verify prompt file format:

   <!-- Layout: Name -->
   [prompt text]

   ---

   <!-- Component: Name -->
   [prompt text]

2. Ensure --- is on its own line (no leading/trailing spaces) 3. Ensure HTML comments use exact format: <!-- Layout: Name --> or <!-- Component: Name --> 4. Re-author the prompt using /prompt to ensure correct formatting

---

Code Fetch Returns Unexpected Format

Symptom: fetch_screen_code returns code in unexpected structure or language.

Causes:

• Stitch generates code based on its own interpretation
• Multiple framework options available

Fix: 1. Code fetching is best-effort — Stitch determines the output format 2. Review generated code and adapt as needed 3. Use extract_design_context instead for design tokens and patterns 4. The primary value is in the generated images, not the code

---

Rate Limiting

Symptom: MCP calls return rate limit errors after multiple rapid generations.

Causes:

• Too many API calls in short succession
• Project-level generation limits

Fix: 1. Wait the indicated cooldown period before retrying 2. For large batches (>6 screens), expect natural delays between part files 3. Check Google Cloud quotas for your project 4. Consider generating in smaller batches if consistently hitting limits

Generating Stitch Screens — Workflow

Step 1: Verify MCP Availability

Before any generation, confirm Stitch MCP tools are accessible.

Check for Required Tools

Look for these MCP tools:

• generate_screen_from_text (required)
• fetch_screen_image (required)
• create_project (required)
• list_projects (required)
• fetch_screen_code (optional — code fetching)
• extract_design_context (optional — design DNA extraction)

If Tools Not Found

Display setup message and stop:

Stitch MCP is not configured.

To set up:
  1. Run /stitch-setup for guided setup
  2. Or manually configure MCP (see plugin README)

Note: Stitch API requires preview/allowlist access from Google.

Do not proceed with generation. Do not attempt workarounds.

---

Step 2: Locate and Read Prompt File

Input Sources

1. Direct file path: Read from provided path 2. Feature name: Look in design-intent/google-stitch/{feature}/ for latest version 3. From authoring skill: Use newly created prompt file path

Version Resolution

If only feature name provided: 1. Scan design-intent/google-stitch/{feature}/prompt-v*.md 2. Select highest version number 3. If part files exist, process all parts sequentially

---

Step 3: Parse Prompt Sections

Parsing Algorithm

1. Split file content by --- separator lines 2. For each section: a. Look for HTML comment label: <!-- Layout: {name} --> or <!-- Component: {name} --> b. Extract label type (Layout or Component) and name c. Extract prompt text (everything after the label, trimmed) 3. Build ordered list of {type, name, prompt_text} entries

Edge Cases

• No labels found: Treat entire file as single prompt, use filename as screen name
• Empty sections: Skip sections with no prompt text after the label
• Part files: Process part1 first, then part2, etc. in order

---

Step 4: Create or Select Stitch Project

Project Naming

Derive project name from feature:

• Feature slug dashboard -> Project name Dashboard Design
• Feature slug admin-panel -> Project name Admin Panel Design
• Convert kebab-case to Title Case, append "Design"

Project Selection

1. Call list_projects 2. Search for project matching derived name (case-insensitive) 3. If match found: use existing project ID 4. If no match: call create_project with derived name

STITCH_PROJECT_ID Override

If STITCH_PROJECT_ID environment variable is set, use it directly instead of creating/searching.

---

Step 5: Generate Screens

Generation Loop

For each parsed section (in order):

1. Call generate_screen_from_text with:

• project_id: from Step 4
• prompt: section's prompt text
• name: section's label name (e.g., "Analytics Dashboard", "KPI Metrics")

2. Store returned screen ID 3. Log progress: Generating: {type}: {name}...

Error Handling per Section

• API error: Log error, skip section, continue with next
• Rate limit: Wait indicated duration, retry once
• Timeout: Mark as pending, continue with next, retry at end

Progress Reporting

After each successful generation:

[{N}/{total}] Generated: {type}: {name}

---

Step 6: Fetch Screen Images

Fetch Loop

For each successfully generated screen:

1. Call fetch_screen_image with screen ID 2. If image returned:

• Save to design-intent/google-stitch/{feature}/exports/{slugified-name}.png
• Log: Saved: exports/{slugified-name}.png

3. If image empty/not ready:

• Wait 3 seconds
• Retry fetch once
• If still empty: log warning, continue

File Naming

Convert screen names to file-safe slugs:

• "Analytics Dashboard" -> analytics-dashboard.png
• "KPI Metrics" -> kpi-metrics.png
• Lowercase, hyphens for spaces, strip special characters

URL Transformation for Full Resolution

Screenshot URLs from Google's image CDN (lh3.googleusercontent.com) return compressed thumbnails by default. To get full resolution images, append size parameters to the URL.

Transformation steps:

1. Extract screen dimensions from API response (width, height) 2. Append =s{width} to the screenshot URL 3. Download the transformed URL

Example:

Original:    https://lh3.googleusercontent.com/aida/AOf...Fn4
Transformed: https://lh3.googleusercontent.com/aida/AOf...Fn4=s2560

Result:

• Without parameter: ~12KB thumbnail (blurry)
• With =s2560: ~80KB full resolution (2560×2048)

Google Image URL Parameters:

Use the screen's reported width from the API response for best results.

---

Step 7: Fetch Screen Code (Optional)

Only if user requested code extraction or /stitch-generate was used.

Code Fetch Loop

For each generated screen:

1. Call fetch_screen_code with screen ID 2. Save to design-intent/google-stitch/{feature}/code/{slugified-name}/ 3. Organize by file type if multiple files returned

---

Step 8: Extract Design Context (Optional)

If user accepts design context extraction:

1. Call extract_design_context with project ID 2. Save result to design-intent/google-stitch/{feature}/design-dna.md 3. This captured context can be used to improve future prompt generation

---

Step 9: Report Results

Success Report

Stitch Generation Complete

Project: {name} ({URL})
Feature: {feature}/

Screens ({success}/{total}):
  1. Layout: {name}      -> exports/{slug}.png
  2. Component: {name}   -> exports/{slug}.png
  3. Component: {name}   -> exports/{slug}.png

Directory:
  design-intent/google-stitch/{feature}/
  ├── prompt-v{N}.md
  ├── exports/
  │   ├── {slug-1}.png
  │   └── {slug-2}.png
  └── code/ (if fetched)

Partial Failure Report

If some screens failed:

Stitch Generation: {success}/{total} screens

Succeeded:
  1. Layout: {name}      -> exports/{slug}.png
  2. Component: {name}   -> exports/{slug}.png

Failed:
  3. Component: {name}   -> Error: {message}
  4. Component: {name}   -> Error: {message}

Retry failed screens:
  /stitch-generate @{prompt-file-path}

Complete Failure Report

If no screens generated:

Stitch Generation Failed

No screens were generated. Common causes:
  - Authentication expired: run `gcloud auth application-default login`
  - Project quota exceeded: check Google Cloud console
  - Invalid prompts: review prompt file format

Run /stitch-setup to verify your configuration.