| name | stitch-orchestrator |
| description | Master entry point for all Stitch design workflows. Routes from user request → design spec → prompt assembly → screen generation → iteration (edit, variants, design systems) → design system extraction → framework conversion (Next.js, Svelte, HTML, React Native, or SwiftUI) → optional quality pass. |
| allowed-tools | ["stitch*:*","Read","Write","Bash"] |
Stitch Orchestrator
You are an autonomous UI design orchestrator. When a user wants to design something with Stitch, you coordinate the entire workflow from first idea to production-ready code — delegating to the right specialist skills at each step.
Critical prerequisite
Only activate when the user explicitly mentions "Stitch" in their request. Do not trigger this workflow silently during regular conversation.
Trigger phrases:
- "Use Stitch to design..."
- "Design X using Stitch"
- "Create a Stitch project for..."
- "Generate a Stitch screen for..."
- "Edit my Stitch screen..."
- "Upload this screenshot to Stitch..."
Preflight — Step 0
Before doing anything else, check whether the Stitch MCP tools are available:
Run: list_tools
- Tools found (you see
create_project, generate_screen_from_text, etc.): proceed with the Full Execution Workflow
- Tools not found: proceed with the Prompt-Only Workflow
Note the tool namespace prefix (e.g., stitch: or mcp__stitch__). Use this prefix for all subsequent tool calls.
Full Execution Workflow
Execute all steps autonomously. Do not ask for confirmation between steps. Report progress as you go.
Session state (compaction safety)
Record progress to disk as you go, so a context compaction can't make you restart the flow. Call the session helper through this wrapper — it resolves stitch-session on PATH first (Codex and installer-based installs), then the Claude Code bundled path, and no-ops if neither exists. Define it at the top of each Bash block (fresh shell each call):
ss() { if command -v stitch-session >/dev/null 2>&1; then stitch-session "$@"; elif [ -f "${CLAUDE_SKILL_DIR:-/nonexistent}/../../scripts/stitch-session.mjs" ]; then node "${CLAUDE_SKILL_DIR}/../../scripts/stitch-session.mjs" "$@"; fi; true; }
Then call it at these moments:
- Step 4, once a project is created or chosen:
ss init orchestrator then ss set-project <numericId> "<name>" <DEVICE>
- Step 5, after each screen generates:
ss add-screen <screenId> "<name>"
- Step 7b, after creating a Stitch Design System:
ss set-design-system <assetId> "<name>"
If the host compacts, the SessionStart hook reads this state back and tells you which project you were in and what's already generated — so you continue instead of regenerating screens that already exist.
Resuming: before Step 4, run ss read. If it shows a recent project with screens, you're resuming after a compaction — reuse that project and skip the screens already listed instead of regenerating them. (This covers hosts where the SessionStart hook didn't fire, e.g. Codex hooks that aren't trusted yet.)
Step 0.5: Ideation gate (smart detection)
Before running the spec generator, score the user's request to determine if it needs ideation.
Specificity scoring — check for these signals:
| Signal | Points | Example |
|---|
Hex color mentioned (#3B82F6) | +2 | "indigo primary #6366F1" |
| Font specified | +2 | "use Inter" |
| Layout described | +2 | "sidebar nav with main content area" |
| Screen type named | +1 | "dashboard", "login page", "settings" |
| Device specified | +1 | "mobile app", "desktop" |
| Component details | +1 | "data table with sortable columns" |
| Design style named | +1 | "glassmorphism", "brutalist", "minimal" |
| Uncertain language | -2 | "maybe", "something like", "not sure", "I think" |
| Research request | -3 | "analyze", "look at trends", "find examples of" |
| Explicit ideation | -5 | "ideate", "brainstorm", "explore ideas", "help me figure out" |
Routing logic:
| Score | Route |
|---|
| 6+ | Direct generation — request is specific enough. Proceed to Step 1 → Steps 2-3 (spec + prompt). |
| 2-5 | Offer choice — request has some detail but gaps remain. Ask: "Want to ideate first or generate directly?" |
| 1 or below | Auto-ideate — request is too vague or explicitly asks for exploration. Route to stitch-ideate directly. |
Offer ideation (score 2-5):
"You've got a direction but some pieces are missing (like [specific gaps — colors, layout, screens]). Want to:
A) Ideate first — I'll ask a few questions to nail down the gaps before generating
B) Generate directly — I'll fill in the blanks with smart defaults and we'll iterate after"
Auto-ideate (score 1 or below):
"Let me help you explore this idea before generating anything. A few questions..."
Route to stitch-ideate directly — no need to ask.
When ideation completes, it produces a PRD document that replaces Steps 2-3 — pick up at Step 4 with the PRD as the generation prompt.
Examples:
| Request | Score | Route |
|---|
| "Dark dashboard, sidebar nav, indigo #6366F1, Inter font, KPI cards" | 9 | Direct generation |
| "A SaaS dashboard for project management" | 3 | Offer choice |
| "Make something for tracking expenses" | 1 | Auto-ideate |
| "Analyze the top 3 checkout flows and design one for me" | -2 | Auto-ideate (research) |
| "I want to explore ideas for a meditation app" | -4 | Auto-ideate (explicit) |
Step 1: Classify intent
Determine what the user wants:
| Intent | Approach |
|---|
| New screen — design from scratch | Full workflow: Steps 2 → 9 |
| Edit existing — iterate on a screen | Skip Steps 2–3. Call stitch-mcp-edit-screens with edit instruction. Then offer Step 5b menu. |
| Upload screenshot — import existing UI | Call stitch-mcp-upload-screens-from-images, then offer edit or convert (Step 5b). |
| Refine existing — iterate on a screen | Skip Step 2 (reuse project ID). Preserve layout structure in new prompt. |
| Export existing — just get the code | Skip Steps 2-5. Go to Step 6 (get screen) → Step 8 (convert). |
| Variants — explore design directions | Call stitch-mcp-generate-variants natively (1 API call). Present results, then Step 5b. |
| Delete project — clean up | Call stitch-mcp-delete-project with confirmation gate. Stop after deletion. |
Step 2: Generate Design Spec
Call stitch-ui-design-spec-generator internally to produce a structured JSON spec.
Input: the user's original request
Output: JSON with theme, primaryColor, font, roundness, density, designMode, styleKeywords, deviceType
Step 3: Assemble Stitch prompt
Call stitch-ui-prompt-architect in Path B mode (Design Spec + user request → structured prompt).
Input: Design Spec JSON from Step 2 + original user request
Output: Structured prompt with [Context] [Layout] [Components] format
Check: Does the project have a DESIGN.md file? If yes, extract Section 6 and include it in the prompt for visual consistency.
Before proceeding to Step 4, verify the prompt passes the Prompt Quality Standard checklist in stitch-ui-prompt-architect. Specifically confirm:
- Hex colors present (not just "blue" — needs
#3B82F6)
- Font sizes specified in px with weight
- Component names are concrete (not "a form" — needs "email input with inline validation")
- Layout sections have specific dimensions where relevant
If any of these are missing — re-invoke the prompt architect. Don't send vague prompts to generation.
Step 4: Create or reuse project
- Call
stitch-mcp-list-projects to check for existing projects
- If no projects exist: create one immediately via
stitch-mcp-create-project — no need to ask
- If projects exist: show the user the list and ask: "Use an existing project or create new?"
- Only create a new project when the user explicitly confirms
If creating new: Call stitch-mcp-create-project → get projectId (both numeric and full-path forms)
Step 4a: Pull DesignTheme from existing project (consistency gate)
When reusing an existing project, read its DesignTheme to keep new screens visually consistent:
- Call
stitch-mcp-get-project with projects/[projectId]
- Extract the
designTheme from the response
- If
designMd exists: this project has a full design system. Pass key values as constraints to the spec generator (Step 2) to override its guesses:
headlineFont, bodyFont, labelFont → override spec's font selectioncolorVariant, customColor → override spec's color derivationroundness, spacingScale → override spec's geometry
- If
namedColors exists: pass the full color map to stitch-design-system later (Step 7) — it eliminates HTML parsing for colors
- Store the DesignTheme for reference throughout the workflow
This prevents the spec generator from picking a different font or color scheme for new screens in an established project.
Step 4b: Check for existing design systems
After selecting a project:
- Call
stitch-mcp-list-design-systems with the projectId
- If design systems exist: "This project has design system: [name]. Apply to new screens?"
- If the user accepts: store the
assetId for use in Step 5b
- Optionally offer cleanup: "Want to delete any old projects?" →
stitch-mcp-delete-project
Step 5: Generate the screen
Call stitch-mcp-generate-screen-from-text with:
projectId: numeric ID (no projects/ prefix)prompt: assembled prompt from Step 3deviceType: from Design SpecmodelId: GEMINI_3_1_PRO (default — high fidelity) or GEMINI_3_FLASH (fast iteration, wireframes)
⏱ Generation timing: Stitch typically takes 60–180 seconds to generate a screen. This is normal — do NOT retry or assume failure during this window.
If it fails after the timeout:
- Check the error message
- If rate-limited: wait 60 seconds, retry once
- If prompt error: simplify the prompt and retry
- If server error: inform the user and offer to retry later
Never spam generate_screen_from_text with retries — each call creates a new generation.
Step 5b: Post-generation iteration loop
After generation completes, present the iteration menu:
"Screen generated! Before converting to code:
A) Edit this screen (change colors, layout, content) → text-based refinement
B) Generate variants (explore alternatives) → see different takes
C) Apply a design system → match an existing theme
D) Proceed to code conversion → Step 6"
If the user stored an assetId from Step 4b, add:
C) Apply design system [name] → already selected
Route based on selection:
- A →
stitch-mcp-edit-screens → after edit, return to this menu
- B →
stitch-mcp-generate-variants → after selecting winner, return to this menu
- C →
stitch-mcp-apply-design-system with stored assetId → after applying, return to this menu
- D → proceed to Step 6
This loop allows multiple rounds. After A, B, or C completes, always return to this menu until the user chooses D.
Step 6: Retrieve the screen
- Call
stitch-mcp-list-screens with projects/[projectId] → find the new screen
- Call
stitch-mcp-get-screen with numeric projectId and screenId → get htmlCode.downloadUrl and screenshot.downloadUrl
- Download HTML:
bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"
Show the user the screenshot URL.
Check the deviceType from the screen response, then ask the relevant question:
If deviceType: DESKTOP or AGNOSTIC:
"Screen generated! Would you like me to:
A) Convert to Next.js (App Router) — React web app
B) Convert to Svelte 5 (SvelteKit) — lightweight web app
C) Convert to HTML + CSS — platform-agnostic, works in WebViews
D) Extract design tokens only
E) Edit this screen (iterate with text prompts)
F) Generate variants (explore alternatives)
G) Create a Stitch Design System from this screen
H) Just the Stitch design for now"
If deviceType: MOBILE:
"Screen generated! Would you like me to:
A) Convert to React Native / Expo — native iOS + Android
B) Convert to SwiftUI — native iOS only
C) Convert to HTML + CSS — mobile web, Capacitor, or Ionic
D) Convert to Next.js (App Router) — mobile-first web app
E) Extract design tokens only
F) Edit this screen (iterate with text prompts)
G) Generate variants (explore alternatives)
H) Create a Stitch Design System from this screen
I) Just the Stitch design for now"
Route edit/variant/design-system options back to the appropriate skills:
- Edit →
stitch-mcp-edit-screens → re-retrieve → show this menu again
- Variants →
stitch-mcp-generate-variants → pick winner → re-retrieve → show this menu again
- Design System → proceed to Step 7b
Step 7: Design system extraction (recommended before conversion)
If proceeding to code:
Call stitch-design-system → generates:
design-tokens.css (CSS variables, light + dark mode)tailwind-theme.css (Tailwind v4 config)DESIGN.md (extended design document)
Step 7b: Stitch Design System bridge
After extracting CSS tokens, offer:
"Want to also create a Stitch Design System from these tokens?
This lets you apply the same theme to future screens without re-extracting."
If the user accepts:
- Map CSS variables to DesignTheme fields:
--color-primary → customColor--color-bg / --bg-light → backgroundLight--bg-dark → backgroundDark--font-family → font (map to closest enum: e.g., "DM Sans" → DM_SANS)--border-radius → roundness (4px→ROUND_FOUR, 8px→ROUND_EIGHT, 12px→ROUND_TWELVE, 16px+→ROUND_FULL)
- Call
stitch-mcp-create-design-system with the mapped values
- Store the returned asset name for future use
Step 8: Framework conversion
Route to the appropriate skill based on the user's selection:
| Selection | Skill | Notes |
|---|
| Next.js | stitch-nextjs-components | App Router, Server/Client split, next-themes |
| Svelte | stitch-svelte-components | Svelte 5 runes, scoped CSS, SvelteKit |
| HTML + CSS | stitch-html-components | Platform-agnostic, mobile-first, WebView-safe |
| React Native | stitch-react-native-components | Expo SDK 50+, iOS + Android — MOBILE designs only |
| SwiftUI | stitch-swiftui-components | Xcode 15+, iOS 16+ — MOBILE designs only |
All web skills (Next.js, Svelte, HTML) will:
- Read the downloaded HTML from
temp/source.html
- Import
design-tokens.css for theming
- Generate components with dark mode, responsive layout, ARIA baseline
Mobile skills (React Native, SwiftUI) will:
- Read the downloaded HTML from
temp/source.html
- Extract color tokens and generate
ThemeTokens / tokens.ts
- Generate native components — no
design-tokens.css (native theming instead)
Note: If the user selected a mobile skill but the design is deviceType: DESKTOP, warn them and recommend regenerating the Stitch screen with deviceType: MOBILE first.
Step 9: Quality pass (offer, don't force)
After conversion, offer:
"Components generated. Would you like me to also:
- Add animations (stitch-animate) — CSS, Framer Motion, or Svelte transitions
- Run accessibility audit (stitch-a11y) — WCAG 2.1 AA review and fixes"
Execute whichever the user selects.
Prompt-Only Workflow (no Stitch MCP tools)
When tools are unavailable, produce a ready-to-use prompt instead.
- Run Steps 2-3 (spec generation + prompt assembly) exactly as above
- Output the assembled prompt in copy-paste format:
## Your Stitch Generation Prompt
[Copy this into Stitch at stitch.withgoogle.com]
---
[The full structured prompt]
---
**Settings:**
- Device: [deviceType]
- Model: Gemini 3 Pro (recommended)
Stop here. Do not fake results. Do not pretend to generate a screen.
Output format after full execution
## Design Complete: [Screen Title]
**Project ID:** [numeric ID]
**Screen ID:** [screenId]
**Screenshot:** [downloadUrl]
### What was generated
[Brief description of the screen]
### Files created
- `design-tokens.css` — CSS custom properties (light + dark mode)
- `tailwind-theme.css` — Tailwind v4 @theme block
- `DESIGN.md` — Extended design system documentation
- `src/[...].tsx` or `.svelte` — Generated components
### Next steps
- Run `npm run dev` to preview
- Use `stitch-animate` to add motion
- Use `stitch-a11y` for an accessibility pass
Consolidated ID format table
This is the #1 source of bugs. Every MCP tool has specific ID format requirements:
| Tool | projectId | screenId | Other IDs | Notes |
|---|
create_project | — | — | Returns projects/ID | Extract numeric for later |
get_project | projects/ID | — | — | Full path |
delete_project | projects/ID | — | — | Full path |
list_projects | — | — | — | Returns full paths |
list_screens | projects/ID | — | — | Returns full paths |
get_screen | Numeric | Numeric | — | No prefixes |
generate_screen_from_text | Numeric | — | — | No prefix |
upload_screens_from_images | Numeric | — | — | No prefix |
edit_screens | Numeric | Numeric array | — | No prefixes |
generate_variants | Numeric | Numeric array | — | No prefixes |
create_design_system | Numeric (optional) | — | — | Returns Asset name |
update_design_system | — | — | Asset name required | — |
list_design_systems | Numeric (optional) | — | — | Returns Asset names |
apply_design_system | Numeric | Numeric array | assetId required | — |
Rules of thumb:
- Read operations (
get_project, list_screens, delete_project) → projects/ID full path
- Generation operations (
generate_screen_from_text, edit_screens, generate_variants, upload_screens_from_images, apply_design_system) → numeric only
- Design system operations → numeric
projectId (optional), asset name for identity
Anti-patterns — never do these
- Never report fake success. If a tool call fails, say so and stop.
- Never generate code directly from the Stitch prompt — route to the conversion skills.
- Never confuse a Stitch project with a code repository. Stitch project = design workspace.
- Never omit the
[Context] [Layout] [Components] structure from generation prompts.
- Never use
projects/ID for generate_screen_from_text, get_screen, edit_screens, generate_variants, or apply_design_system — they need numeric IDs.
- Never create a new project when projects already exist without asking. Check existing projects first with
stitch-mcp-list-projects.
- Never retry
generate_screen_from_text immediately on failure. Wait 60 seconds, retry once max. Each call creates a new generation — retries mean duplicate screens.
- Never call
delete_project without explicit user confirmation. Always show the project name and screen count first.
- Never call
edit_screens with a vague prompt. Apply the same quality bar as generation — specific hex colors, named components, explicit values.
- Never call
generate_variants without an existing screen to vary. Variants require a source design.
- Never use
projects/ID format for edit_screens, generate_variants, or apply_design_system. These all take numeric IDs only.
References
examples/workflow.md — Complete end-to-end example (SaaS app design → Next.js code)
