stitch-kit 1.5.0

package/skills/stitch-orchestrator/SKILL.md

@@ -0,0 +1,337 @@
+---
+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.
+
+### 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
+
+1. Call `stitch-mcp-list-projects` to check for existing projects
+2. **If no projects exist:** create one immediately via `stitch-mcp-create-project` — no need to ask
+3. **If projects exist:** show the user the list and ask: "Use an existing project or create new?"
+4. 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 4b: Check for existing design systems
+
+After selecting a project:
+
+1. Call `stitch-mcp-list-design-systems` with the projectId
+2. If design systems exist: "This project has design system: **[name]**. Apply to new screens?"
+3. If the user accepts: store the `assetId` for use in Step 5b
+4. 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 3
+- `deviceType`: from Design Spec
+- `modelId`: `GEMINI_3_PRO` (default) or `GEMINI_3_FLASH` (if user wants fast iteration)
+
+> ⏱ **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:
+> 1. Check the error message
+> 2. If rate-limited: wait 60 seconds, retry once
+> 3. If prompt error: simplify the prompt and retry
+> 4. 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
+
+1. Call `stitch-mcp-list-screens` with `projects/[projectId]` → find the new screen
+2. Call `stitch-mcp-get-screen` with numeric projectId and screenId → get `htmlCode.downloadUrl` and `screenshot.downloadUrl`
+3. 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:
+1. 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`)
+2. Call `stitch-mcp-create-design-system` with the mapped values
+3. 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.
+
+1. Run Steps 2-3 (spec generation + prompt assembly) exactly as above
+2. 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)

package/skills/stitch-orchestrator/examples/workflow.md

@@ -0,0 +1,173 @@
+# End-to-End Workflow Example
+
+## Scenario: Designing a SaaS analytics app
+
+**User:** "Use Stitch to design a dashboard for my SaaS analytics tool. I want a clean, modern look with indigo as the primary color."
+
+---
+
+### Step 0: Preflight
+*Orchestrator runs `list_tools`*
+
+Found: `stitch:create_project`, `stitch:generate_screen_from_text`, `stitch:list_screens`, `stitch:get_screen`
+Namespace: `stitch:`
+
+→ Proceed with Full Execution Workflow.
+
+---
+
+### Step 1: Classify intent
+New screen from scratch → full workflow.
+
+---
+
+### Step 2: Design Spec generation
+*Orchestrator calls `stitch-ui-design-spec-generator`*
+
+Input: "SaaS analytics tool, clean modern, indigo primary"
+
+Output:
+```json
+{
+  "theme": "LIGHT",
+  "primaryColor": "#6366F1",
+  "font": "DM Sans",
+  "roundness": "Medium",
+  "density": "COMPACT",
+  "designMode": "HIGH_FIDELITY",
+  "styleKeywords": ["Clean", "Modern", "SaaS", "Structured"],
+  "deviceType": "DESKTOP"
+}
+```
+
+---
+
+### Step 3: Prompt assembly
+*Orchestrator calls `stitch-ui-prompt-architect` in Path B mode*
+
+Output:
+```
+Desktop High-Fidelity analytics dashboard for a SaaS platform. Clean modern aesthetic. Light mode. Background: White (#ffffff). Primary: Indigo (#6366F1). Font: DM Sans.
+
+Left sidebar navigation (200px): Logo top-left, nav items (Overview, Revenue, Users, Reports, Settings) with icons, user avatar + name at bottom. Top bar: Page title 'Overview', date range picker, notification bell, 'Export CSV' button.
+
+KPI row: 4 cards — MRR ($48,200, +8.3% MoM, green arrow), Active Users (3,847, +12%), Churn Rate (1.9%, -0.4%), Avg Revenue Per User ($12.54). Line chart: 'Revenue Growth' spanning last 12 months, indigo primary line with subtle fill. Two-column bottom: 'Top Plans' horizontal bar chart left, 'Recent Signups' table right (avatar, name, plan, date).
+```
+
+---
+
+### Step 4: Create project
+*Orchestrator calls `stitch-mcp-create-project`*
+
+```json
+{ "name": "create_project", "arguments": { "title": "SaaS Analytics Dashboard" } }
+```
+
+Result: `{ "name": "projects/3780309359108792857" }`
+
+- Full name: `projects/3780309359108792857`
+- Numeric ID: `3780309359108792857`
+
+---
+
+### Step 5: Generate screen
+*Orchestrator calls `stitch-mcp-generate-screen-from-text`*
+
+```json
+{
+  "name": "generate_screen_from_text",
+  "arguments": {
+    "projectId": "3780309359108792857",
+    "prompt": "[assembled prompt from Step 3]",
+    "deviceType": "DESKTOP",
+    "modelId": "GEMINI_3_PRO"
+  }
+}
+```
+
+---
+
+### Step 6: Retrieve screen
+*Orchestrator calls `stitch-mcp-list-screens`, then `stitch-mcp-get-screen`*
+
+list_screens: `{ "projectId": "projects/3780309359108792857" }`
+→ Found screen: `88805abc123def456`
+
+get_screen: `{ "projectId": "3780309359108792857", "screenId": "88805abc123def456" }`
+→ Returns `htmlCode.downloadUrl` and `screenshot.downloadUrl`
+
+Download HTML:
+```bash
+bash scripts/fetch-stitch.sh "$htmlCode_downloadUrl" "temp/source.html"
+```
+
+Orchestrator shows screenshot URL to user and asks framework preference.
+User selects: **A) Convert to Next.js**
+
+---
+
+### Step 7: Design system extraction
+*Orchestrator calls `stitch-design-system`*
+
+Reads `temp/source.html` → extracts colors, fonts, spacing.
+
+Generates:
+- `design-tokens.css` with light/dark mode CSS variables
+- `tailwind-theme.css` with `@theme` block
+- `DESIGN.md` with Section 6 Stitch copy-paste block
+
+---
+
+### Step 8: Framework conversion
+*Orchestrator calls `stitch-nextjs-components`*
+
+Reads `temp/source.html` + `design-tokens.css`
+
+Generates:
+- `src/data/mockData.ts` — extracted KPI values, chart data
+- `src/components/Sidebar.tsx` — Server Component
+- `src/components/TopBar.tsx` — Client Component (date picker interaction)
+- `src/components/KPICard.tsx` — Server Component
+- `src/components/RevenueChart.tsx` — Client Component (chart interaction)
+- `src/components/SignupsTable.tsx` — Server Component
+- `app/dashboard/page.tsx` — Route entry composing all components
+
+---
+
+### Step 9: Quality pass
+Orchestrator offers animations + a11y. User selects animations.
+
+*Orchestrator calls `stitch-animate`*
+
+Adds to components:
+- `RevealOnScroll` wrapper around KPI cards (staggered fade-up, 60ms delay each)
+- Chart fade-in transition on mount
+- Card hover lift effect (CSS micro-interaction)
+- `prefers-reduced-motion` override in `globals.css`
+
+---
+
+### Final output
+
+```
+## Design Complete: SaaS Analytics Dashboard
+
+**Project ID:** 3780309359108792857
+**Screen ID:** 88805abc123def456
+
+### Files created
+- design-tokens.css
+- tailwind-theme.css
+- DESIGN.md
+- src/data/mockData.ts
+- src/components/Sidebar.tsx
+- src/components/TopBar.tsx
+- src/components/KPICard.tsx
+- src/components/RevenueChart.tsx
+- src/components/SignupsTable.tsx
+- app/dashboard/page.tsx
+
+### Next steps
+- Run `npm run dev` to preview
+- Use `stitch-a11y` for an accessibility pass before launching
+```