Using stitch

Using Google Stitch for UI Design

Use Google Stitch MCP to generate, iterate on, and preview UI designs during brainstorming. Stitch produces real visual designs that the user can review and fine-tune in their browser using Stitch's web UI.

Prerequisites

This skill applies ONLY when mcp__stitch__* tools are present in your available tools. If they are not available, skip this skill entirely and fall back to the Visual Companion or text-only brainstorming.

If running under "Claude Code" consider using the built-in Skill(skill: "design") instead - ask the user for their preference. If the user decides to use Skill(skill: "design") follow that skill instead of this skill.

Process Flow

digraph stitch_flow {
    "Stitch MCP tools available?" [shape=diamond];
    "Use Visual Companion or\ntext-only brainstorming" [shape=doublecircle];
    "Running in Claude Code?" [shape=diamond];
    "Ask user: use built-in\ndesign skill?" [shape=box];
    "User chose built-in\ndesign skill?" [shape=diamond];
    "Use built-in design skill" [shape=doublecircle];
    "Check existing projects\n(list_projects)" [shape=box];
    "Relevant project exists?" [shape=diamond];
    "Load project context\n(get_project, list_screens,\nlist_design_systems)" [shape=box];
    "Ask user: visual preferences" [shape=box];
    "Create project\n(create_project)" [shape=box];
    "Create design system\n(create + update)" [shape=box];
    "Generate screens\n(generate_screen_from_text)" [shape=box];
    "Tell user to preview\nin Stitch browser" [shape=box];
    "User feedback?" [shape=diamond];
    "Edit screens or\ngenerate variants" [shape=box];
    "Design approved" [shape=doublecircle];

    "Stitch MCP tools available?" -> "Use Visual Companion or\ntext-only brainstorming" [label="no"];
    "Stitch MCP tools available?" -> "Running in Claude Code?" [label="yes"];
    "Running in Claude Code?" -> "Ask user: use built-in\ndesign skill?" [label="yes"];
    "Running in Claude Code?" -> "Check existing projects\n(list_projects)" [label="no"];
    "Ask user: use built-in\ndesign skill?" -> "User chose built-in\ndesign skill?";
    "User chose built-in\ndesign skill?" -> "Use built-in design skill" [label="yes"];
    "User chose built-in\ndesign skill?" -> "Check existing projects\n(list_projects)" [label="no"];
    "Check existing projects\n(list_projects)" -> "Relevant project exists?";
    "Relevant project exists?" -> "Load project context\n(get_project, list_screens,\nlist_design_systems)" [label="yes"];
    "Relevant project exists?" -> "Ask user: visual preferences" [label="no"];
    "Load project context\n(get_project, list_screens,\nlist_design_systems)" -> "Generate screens\n(generate_screen_from_text)";
    "Ask user: visual preferences" -> "Create project\n(create_project)";
    "Create project\n(create_project)" -> "Create design system\n(create + update)" ;
    "Create design system\n(create + update)" -> "Generate screens\n(generate_screen_from_text)";
    "Generate screens\n(generate_screen_from_text)" -> "Tell user to preview\nin Stitch browser";
    "Tell user to preview\nin Stitch browser" -> "User feedback?";
    "User feedback?" -> "Edit screens or\ngenerate variants" [label="changes needed"];
    "User feedback?" -> "Design approved" [label="approved"];
    "Edit screens or\ngenerate variants" -> "Tell user to preview\nin Stitch browser";
}

Step 1: Check Existing Projects

Before creating anything, check if relevant Stitch projects already exist:

1. Call list_projects (no filter needed — defaults to owned projects)
2. If a project matches the current work, use get_project to load details, then list_screens and list_design_systems to understand existing design state
3. If an existing project and design system fit, skip to screen generation

Step 2: Gather Visual Preferences (New Projects Only)

Before creating a new project, ask the user about their visual preferences. Ask these as focused questions (one at a time, per brainstorming skill rules):

Question	Maps to	Options
What is the purpose/audience of this app?	designMd	Open-ended — informs overall design direction
Light or dark mode?	colorMode	LIGHT, DARK
Primary brand color?	customColor	Hex color, e.g. "#2563eb"
Color feel?	colorVariant	MONOCHROME, NEUTRAL, TONAL_SPOT, VIBRANT, EXPRESSIVE, FIDELITY, CONTENT, RAINBOW, FRUIT_SALAD
Typography style?	headlineFont, bodyFont	Modern sans-serif (Inter, DM Sans, Geist), Classic serif (Noto Serif, EB Garamond, Literata), Geometric (Montserrat, Sora, Space Grotesk), Humanist (Nunito Sans, Rubik, Plus Jakarta Sans)
Corner style?	roundness	Sharp (ROUND_FOUR), Medium (ROUND_EIGHT), Rounded (ROUND_TWELVE), Pill (ROUND_FULL)
Target device?	deviceType	MOBILE, DESKTOP, TABLET, AGNOSTIC

If the user has no strong preferences, propose sensible defaults based on the app's purpose and get confirmation.

Step 3: Create Project and Design System

1. Call create_project with a descriptive title
2. Call create_design_system with the gathered preferences:
   • Set projectId from the created project
   • Fill all required theme fields: colorMode, headlineFont, bodyFont, roundness, customColor
   • Use designMd for freeform design instructions (app purpose, audience, style notes)
   • Set optional color overrides if user specified secondary/tertiary colors
3. Immediately call update_design_system after creation — this is required to apply it and make it visible in the UI

Step 4: Generate Screens

Use generate_screen_from_text to create screens:

• Set modelId to GEMINI_3_1_PRO (current best model; GEMINI_3_PRO is deprecated)
• Write detailed prompts describing the screen's purpose, layout, and content
• Set deviceType to match the user's target
• Be patient: generation can take a few minutes. Do NOT retry on timeout — the generation may still succeed. Use get_screen to check later if the call fails with a connection error.
• Handle output_components: if the response contains suggestions, present them to the user. If they accept one, call generate_screen_from_text again with the accepted suggestion as the prompt.

Step 5: Preview and Iterate

After generating screens, tell the user:

"Screens have been generated in Stitch. Please open your project at stitch.withgoogle.com to preview the designs. You can also fine-tune them directly in the Stitch editor."

Note: Sometimes Stitch does not refresh properly after MCP-initiated changes. If you don't see the latest designs, try refreshing the page or reopening the project.

Screen Names: title vs label

Stitch stores two different names for a screen, in two different objects. Getting this wrong silently maps user feedback to the wrong screen.

What	Where it lives	Who sets it
title	list_screens → screens[].title	Stitch, auto-generated. Rewritten whenever the model generates or edits the screen.
label	get_project → screenInstances[].label	The user, by renaming on the canvas. Absent if never renamed.

When the user refers to a screen by name and they have edited the name, they mean the label. Always resolve it with get_project — list_screens structurally cannot show it.

Auto-titles are not just different, they are often actively misleading. Real example:

User's label	Stitch's title for the same screen
Comments Desktop V4 ACC	Comments - Dashboard with Annotated Updates
Responders - V4 - ACC	Responders - Public Reply Only Refined

Matching on title would have selected the wrong screen in both cases. Note also that several distinct screens frequently share one identical auto-title (e.g. three screens all titled "Responders - Keyword Management Mobile"), so titles are not unique and cannot be used as keys.

Resolving a user-named screen to its files

The two calls hold different halves of what you need, so join them on the screen id:

1. get_project → find the instance whose label matches the user's name.
2. Take its sourceScreen field (projects/{p}/screens/{screenId}) — not the instance id. They usually coincide, but a duplicated instance gets a suffixed id (<id>-1784652056734) whose sourceScreen points at a different screen entirely.
3. list_screens → find that screenId; use its htmlCode.downloadUrl and screenshot.downloadUrl to fetch the mockup.

Also present in screenInstances: hidden: true marks screens hidden on the canvas (usually superseded iterations), and entries with type: "DESIGN_SYSTEM_INSTANCE" are the design-system swatch, not screens — skip both.

Tip: have the user tag accepted screens

On a long design session, ask the user to mark approved screens with a consistent token in the rename (e.g. an ACC suffix). You can then filter screenInstances[].label for it and reliably pull exactly the approved set, instead of re-asking which screen was which.

Remember, when using Stitch's UI user has no way to see screen IDs.

Editing Existing Screens

Use edit_screens when the user wants modifications:

• Requires projectId, selectedScreenIds (array), and a prompt describing the changes
• Get screen IDs from list_screens if needed

Generating Variants

Use generate_variants to explore design alternatives:

• variantOptions.creativeRange: REFINE (subtle tweaks), EXPLORE (balanced, default), REIMAGINE (radical alternatives)
• variantOptions.aspects: focus on specific elements — LAYOUT, COLOR_SCHEME, IMAGES, TEXT_FONT, TEXT_CONTENT (or leave empty for all)
• variantOptions.variantCount: 1-5 variants (default 3)

Present variants to the user and let them pick favorites or mix elements.

Applying Design Systems

Use apply_design_system to restyle existing screens with a different design system:

• Requires projectId, assetId (from list_design_systems), and selectedScreenInstances
• Screen instances come from get_project, NOT list_screens — use the instance id and sourceScreen fields

Quick Reference

Tool	When to use
list_projects	Find existing projects
create_project	Start new design work
get_project	Load project details, screen instances, and the user's own screen names (screenInstances[].label)
list_screens	See all screens in a project
get_screen	Get details of one screen, or verify generation succeeded
generate_screen_from_text	Create new screen from description
edit_screens	Modify existing screens
generate_variants	Create design alternatives
create_design_system	Set up visual theme (always call update after)
update_design_system	Apply/modify design system
list_design_systems	Find existing design systems
apply_design_system	Restyle screens with a design system

Common Mistakes

Mistake	Fix
Retrying generate_screen_from_text on timeout	Don't retry — use get_screen to check if it succeeded
Using GEMINI_3_PRO model	Use GEMINI_3_1_PRO — 3 Pro is deprecated
Creating design system without calling update after	Always call update_design_system immediately after create_design_system
Using screen IDs from list_screens for apply_design_system	Use screen instance IDs from get_project
Generating screens without establishing a design system first	Set up the design system first so screens are consistent
Skipping existing project check	Always check list_projects first to avoid duplicating work
Reading list_screens titles as the user's screen names	Those are Stitch's auto-generated descriptions. User renames live in get_project → screenInstances[].label
Matching a user-mentioned screen by title	Titles are non-unique and often misleading; resolve via label, then join on screen id
Using a screenInstances[].id as the screen id	Use sourceScreen; duplicated instances have suffixed ids pointing at a different screen
Concluding renames "didn't sync" when they don't appear	They never appear in list_screens by design — check get_project before assuming a sync bug