stitch-kit 1.5.0

package/docs/mcp-schemas/list_projects.json

@@ -0,0 +1,136 @@
+{
+  "name": "list_projects",
+  "description": "Lists all Stitch projects accessible to the user. By default, it lists projects owned by the user.\n\n**Input Requirements:**\n\n1.  **`filter` (string - OPTIONAL):** Filter for projects to list. Defaults to \"view=owned\" if not provided. The enum values are:\n    *   `\"view=owned\"`: To list only projects owned by the user.\n    *   `\"view=shared\"`: To list only projects shared with the user.\n",
+  "arguments": {
+    "type": "object",
+    "properties": {
+      "filter": {
+        "description": "Optional. AIP-160 filter. Supported: `view=owned` (default) or `view=shared`.",
+        "type": "string"
+      }
+    },
+    "description": "Request message for ListProjects."
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "projects": {
+        "description": "Projects sorted by update time (most recent first).",
+        "items": { "$ref": "#/$defs/Project" },
+        "type": "array"
+      }
+    },
+    "$defs": {
+      "DesignTheme": {
+        "description": "The theme of the design.",
+        "properties": {
+          "backgroundDark": { "type": "string" },
+          "backgroundLight": { "type": "string" },
+          "colorMode": {
+            "enum": ["COLOR_MODE_UNSPECIFIED", "LIGHT", "DARK"],
+            "type": "string"
+          },
+          "customColor": { "type": "string" },
+          "description": { "type": "string" },
+          "font": {
+            "enum": [
+              "FONT_UNSPECIFIED",
+              "BE_VIETNAM_PRO", "EPILOGUE", "INTER", "LEXEND", "MANROPE",
+              "NEWSREADER", "NOTO_SERIF", "PLUS_JAKARTA_SANS", "PUBLIC_SANS",
+              "SPACE_GROTESK", "SPLINE_SANS", "WORK_SANS", "DOMINE",
+              "LIBRE_CASLON_TEXT", "EB_GARAMOND", "LITERATA", "SOURCE_SERIF_FOUR",
+              "MONTSERRAT", "METROPOLIS", "SOURCE_SANS_THREE", "NUNITO_SANS",
+              "ARIMO", "HANKEN_GROTESK", "RUBIK", "GEIST", "DM_SANS",
+              "IBM_PLEX_SANS", "SORA"
+            ],
+            "type": "string"
+          },
+          "preset": { "type": "string" },
+          "roundness": {
+            "description": "ROUND_TWO is deprecated/unused.",
+            "enum": ["ROUNDNESS_UNSPECIFIED", "ROUND_TWO", "ROUND_FOUR", "ROUND_EIGHT", "ROUND_TWELVE", "ROUND_FULL"],
+            "type": "string"
+          },
+          "saturation": { "description": "1–4", "format": "int32", "type": "integer" }
+        },
+        "type": "object"
+      },
+      "File": {
+        "properties": {
+          "downloadUrl": { "type": "string" },
+          "name": { "type": "string" }
+        },
+        "type": "object"
+      },
+      "Project": {
+        "description": "A project is a single app.",
+        "properties": {
+          "backgroundTheme": { "type": "string" },
+          "createTime": { "format": "date-time", "readOnly": true, "type": "string" },
+          "designTheme": { "$ref": "#/$defs/DesignTheme", "readOnly": true },
+          "deviceType": {
+            "enum": ["DEVICE_TYPE_UNSPECIFIED", "MOBILE", "DESKTOP", "TABLET", "AGNOSTIC"],
+            "readOnly": true,
+            "type": "string"
+          },
+          "metadata": { "$ref": "#/$defs/ProjectMetadata" },
+          "name": {
+            "description": "Identifier. Format: projects/{project}",
+            "type": "string",
+            "x-google-identifier": true
+          },
+          "origin": {
+            "enum": ["ORIGIN_UNSPECIFIED", "STITCH", "IMPORTED_FROM_GALILEO"],
+            "readOnly": true,
+            "type": "string"
+          },
+          "projectType": {
+            "enum": [
+              "PROJECT_TYPE_UNSPECIFIED", "TEXT_TO_UI", "TEXT_TO_UI_PRO",
+              "TEXT_TO_UI_PRO_IMAGE_SPACE", "IMAGE_TO_UI", "IMAGE_TO_UI_PRO", "PROJECT_DESIGN"
+            ],
+            "type": "string"
+          },
+          "readTime": { "format": "date-time", "readOnly": true, "type": "string" },
+          "screenInstances": {
+            "items": { "$ref": "#/$defs/ScreenInstance" },
+            "readOnly": true,
+            "type": "array"
+          },
+          "thumbnailScreenshot": { "$ref": "#/$defs/File" },
+          "title": { "type": "string" },
+          "updateTime": { "format": "date-time", "readOnly": true, "type": "string" },
+          "visibility": {
+            "enum": ["VISIBILITY_UNSPECIFIED", "PUBLIC", "PRIVATE"],
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "ProjectMetadata": {
+        "properties": {
+          "isRemixed": { "type": "boolean" },
+          "userRole": { "enum": ["ROLE_UNSPECIFIED", "OWNER", "READER"], "type": "string" }
+        },
+        "type": "object"
+      },
+      "ScreenInstance": {
+        "properties": {
+          "groupId": { "type": "string" },
+          "groupName": { "type": "string" },
+          "height": { "format": "int32", "type": "integer" },
+          "hidden": { "type": "boolean" },
+          "id": { "type": "string" },
+          "label": { "type": "string" },
+          "sourceScreen": { "description": "Format: projects/{project}/screens/{screen}", "type": "string" },
+          "variantScreenInstance": { "$ref": "#/$defs/ScreenInstance" },
+          "width": { "format": "int32", "type": "integer" },
+          "x": { "format": "int32", "type": "integer" },
+          "y": { "format": "int32", "type": "integer" }
+        },
+        "type": "object"
+      }
+    },
+    "description": "Response message for ListProjects."
+  }
+}

package/docs/mcp-schemas/list_screens.json

@@ -0,0 +1,56 @@
+{
+  "name": "list_screens",
+  "description": "Lists all screens within a given Stitch project.\n\n**Input Requirements (CRITICAL):**\n\n1.  **`project_id` (string - MANDATORY):** The name of the project to retrieve. This must be in the format `projects/{project_id}`.\n",
+  "arguments": {
+    "type": "object",
+    "properties": {
+      "projectId": {
+        "description": "Required. The project ID to list screens for. Format: projects/{project_id}",
+        "type": "string",
+        "x-google-identifier": true
+      }
+    },
+    "required": ["projectId"],
+    "description": "Request message for ListScreens."
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "screens": {
+        "description": "The screens for the given project.",
+        "items": { "$ref": "#/$defs/Screen" },
+        "type": "array"
+      }
+    },
+    "$defs": {
+      "File": {
+        "properties": {
+          "downloadUrl": { "description": "FIFE base URL for images.", "type": "string" },
+          "name": { "description": "Format: projects/{project}/files/{file}", "type": "string" }
+        },
+        "type": "object"
+      },
+      "Screen": {
+        "description": "A screen generated by the agent.",
+        "properties": {
+          "deviceType": {
+            "enum": ["DEVICE_TYPE_UNSPECIFIED", "MOBILE", "DESKTOP", "TABLET", "AGNOSTIC"],
+            "type": "string"
+          },
+          "height": { "type": "string" },
+          "htmlCode": { "$ref": "#/$defs/File" },
+          "name": {
+            "description": "Identifier. Format: projects/{project}/screens/{screen}",
+            "type": "string",
+            "x-google-identifier": true
+          },
+          "screenshot": { "$ref": "#/$defs/File" },
+          "title": { "readOnly": true, "type": "string" },
+          "width": { "type": "string" }
+        },
+        "type": "object"
+      }
+    },
+    "description": "Response message for ListScreens."
+  }
+}

package/docs/mcp-schemas/update_design_system.json

@@ -0,0 +1,32 @@
+{
+  "name": "update_design_system",
+  "description": "Updates an existing Stitch Design System's theme, tokens, or guidelines.\n",
+  "arguments": {
+    "type": "object",
+    "properties": {
+      "designSystem": {
+        "description": "Required. Asset wrapper with name + updated fields. Full replacement, not merge.",
+        "type": "object",
+        "properties": {
+          "name": { "description": "Required. Asset name from create or list (e.g., assets/ds_abc123).", "type": "string" },
+          "displayName": { "type": "string" },
+          "theme": { "description": "Updated DesignTheme object.", "type": "object" },
+          "designTokens": { "type": "string" },
+          "styleGuidelines": { "type": "string" }
+        },
+        "required": ["name"]
+      }
+    },
+    "required": ["designSystem"],
+    "description": "Request message for UpdateDesignSystem."
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "name": { "type": "string" },
+      "displayName": { "type": "string" },
+      "designSystem": { "type": "object" }
+    },
+    "description": "Updated Asset response."
+  }
+}

package/docs/mcp-schemas/upload_screens_from_images.json

@@ -0,0 +1,52 @@
+{
+  "name": "upload_screens_from_images",
+  "description": "Uploads one or more images into a Stitch project as new screens. Supports PNG, JPEG, WebP, and GIF formats.\n\n**Input Requirements:**\n1. **`projectId` (string - MANDATORY):** Numeric ID only — no `projects/` prefix.\n2. **`images` (array - MANDATORY):** Array of image objects with base64 content and MIME type.\n",
+  "arguments": {
+    "type": "object",
+    "properties": {
+      "projectId": {
+        "description": "Required. Numeric project ID only — do NOT include 'projects/' prefix.",
+        "type": "string"
+      },
+      "images": {
+        "description": "Required. Array of images to upload.",
+        "type": "array",
+        "items": {
+          "$ref": "#/$defs/ImageUpload"
+        }
+      }
+    },
+    "required": ["projectId", "images"],
+    "description": "Request message for UploadScreensFromImages.",
+    "$defs": {
+      "ImageUpload": {
+        "description": "An image to upload as a screen.",
+        "properties": {
+          "fileContentBase64": {
+            "description": "Base64-encoded image data. No data: URI prefix.",
+            "type": "string"
+          },
+          "mimeType": {
+            "description": "MIME type of the image.",
+            "enum": ["image/png", "image/jpeg", "image/webp", "image/gif"],
+            "type": "string"
+          }
+        },
+        "required": ["fileContentBase64", "mimeType"],
+        "type": "object"
+      }
+    }
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "outputComponents": {
+        "description": "Array of output components with session information.",
+        "type": "array"
+      },
+      "projectId": { "type": "string" },
+      "sessionId": { "type": "string" }
+    },
+    "description": "Response message for UploadScreensFromImages."
+  }
+}

package/docs/prd-to-stitch-workflow.md

@@ -0,0 +1,137 @@
+# PRD → Stitch Workflow
+
+How to go from a Product Requirements Document (or a rough idea) to production-ready components using this plugin.
+
+---
+
+## Input formats
+
+The plugin accepts three levels of input richness:
+
+| Input | Best path |
+|-------|-----------|
+| Full PRD document (feature overview, page list, key interactions) | PRD-driven workflow (all steps) |
+| Rough description ("a SaaS dashboard with analytics") | Spec-first workflow (Steps 1–2, then generate) |
+| Existing Stitch design (you already have project/screen IDs) | Export-only (skip to Step 4) |
+
+---
+
+## PRD structure that works best with Stitch
+
+You don't need a perfect PRD — but these sections improve output quality:
+
+| PRD section | How it's used |
+|-------------|---------------|
+| **Feature overview / domain** | Informs theme, color, and style (e.g. "healthcare" → clean + trustworthy, "creative tool" → bold + colorful) |
+| **Page / screen list** | Determines how many Stitch screens to generate and in what order |
+| **Key interactions** | Drives navigation type (tab bar vs. stack), form complexity, state handling (loading, error) |
+| **Visual / brand preferences** | Feeds directly into `stitch-ui-design-spec-generator` and `stitch-ui-prompt-architect` |
+
+---
+
+## Full PRD-driven workflow
+
+### Step 1 — Design Spec (`stitch-ui-design-spec-generator`)
+
+**Input:** PRD or user request
+**Output:** JSON design spec
+
+```json
+{
+  "theme": "LIGHT",
+  "primaryColor": "#6366F1",
+  "font": "modern sans-serif",
+  "roundness": "medium",
+  "density": "comfortable",
+  "designMode": "HIGH_FIDELITY",
+  "deviceType": "DESKTOP",
+  "styleKeywords": ["clean", "professional", "data-rich"]
+}
+```
+
+### Step 2 — Stitch Prompt (`stitch-ui-prompt-architect`)
+
+**Input:** Design Spec JSON + specific page/screen request
+**Output:** Structured `[Context] [Layout] [Components]` prompt
+
+For a PRD with multiple screens, run this step once per screen.
+
+### Step 3 — Create Project (`stitch-mcp-create-project`)
+
+Create a single Stitch project for all screens from this PRD. One project = one design system.
+
+### Step 4 — Generate Screens (`stitch-mcp-generate-screen-from-text`)
+
+Generate each screen defined in the PRD's page list. Do them sequentially to avoid race conditions.
+
+For design consistency across screens: after generating the first screen, run `stitch-design-system` to extract tokens, then include the token summary in every subsequent prompt.
+
+### Step 5 — Retrieve Assets (`stitch-mcp-get-screen`)
+
+For each screen: get `htmlCode.downloadUrl` + `screenshot.downloadUrl`. Download via:
+
+```bash
+bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/screen-name.html"
+```
+
+### Step 6 — Extract Design Tokens (`stitch-design-system`)
+
+Run once after the first screen is downloaded. Generates:
+- `design-tokens.css` — CSS variables for light + dark mode
+- `tailwind-theme.css` — Tailwind v4 `@theme` block
+- `DESIGN.md` — extended design system documentation
+
+Use the `DESIGN.md` Section 6 in all subsequent Stitch prompts to maintain consistency.
+
+### Step 7 — Convert to Code
+
+Choose your output target:
+
+**Web:**
+- `stitch-nextjs-components` — Next.js 15 App Router
+- `stitch-svelte-components` — Svelte 5 / SvelteKit
+- `stitch-react-components` — Vite + React (simpler, no App Router)
+- `stitch-html-components` — HTML5 + CSS (PWA, WebView, Capacitor)
+
+**Mobile:**
+- `stitch-react-native-components` — Expo, iOS + Android
+- `stitch-swiftui-components` — SwiftUI, iOS only
+
+**Enrich with:**
+- `stitch-shadcn-ui` — add shadcn/ui components to React output
+- `stitch-animate` — animations and transitions
+- `stitch-a11y` — WCAG 2.1 AA audit and fixes
+
+### Step 8 (Multi-page) — Iterate with `stitch-loop`
+
+For sites with 5+ screens, use the baton-passing loop instead of manual repetition:
+
+```
+DESIGN.md → next-prompt.md → stitch-loop → integrate → update next-prompt.md → repeat
+```
+
+---
+
+## Quick reference: which skill for which task
+
+| Task | Skill |
+|------|-------|
+| "Turn this PRD into a design" | `stitch-orchestrator` → handles all steps |
+| "I need a color palette" | `docs/color-prompt-guide.md` → pick a palette |
+| "Make 3 design directions" | `stitch-ui-design-variants` |
+| "Keep all screens consistent" | `stitch-design-system` first, then include `DESIGN.md` in every prompt |
+| "Build 10+ pages" | `stitch-loop` |
+| "Add forms and dialogs" | `stitch-shadcn-ui` (React) |
+| "Check accessibility" | `stitch-a11y` |
+| "Make a walkthrough video" | `stitch-remotion` |
+
+---
+
+## Common mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Generating all screens before extracting tokens | Run `stitch-design-system` after screen 1; use DESIGN.md in all subsequent prompts |
+| Different visual styles across screens | Include DESIGN.md Section 6 in every Stitch prompt |
+| Using `projects/ID` format with `generate_screen_from_text` | Use numeric ID only — see `mcp-naming-convention.md` |
+| Converting a DESKTOP design to React Native | Always check `deviceType` from `get_screen` response; regenerate with MOBILE if needed |

package/docs/skills-index.md

@@ -0,0 +1,108 @@
+# stitch-kit Skills Index
+
+Quick reference — all 34 skills organized by layer and stage.
+
+**Layers:**
+- **Orchestrator** — entry point that coordinates other skills
+- **Brain** — design logic, spec generation, prompt engineering
+- **Execution** — Stitch MCP tool wrappers
+- **Conversion** — Stitch HTML → framework components
+- **Quality** — design tokens, animation, accessibility
+- **Meta** — skills for extending the plugin
+
+---
+
+## Full skills table
+
+| Skill | Description | Layer | Stage |
+|-------|-------------|-------|-------|
+| `stitch-orchestrator` | End-to-end workflow: request → spec → prompt → generate → iterate → retrieve → convert → quality | Orchestrator | All |
+| `stitch-ui-design-spec-generator` | User request / PRD → structured Design Spec JSON (theme, color, font, device, density) | Brain | Design input |
+| `stitch-ui-prompt-architect` | Two paths: Path A (vague → enhanced) or Path B (spec + request → `[Context][Layout][Components]`) | Brain | Design input |
+| `stitch-ui-design-variants` | Generate 3 alternative prompt variants for A/B design exploration. Native API detection for `generate_variants` when available. | Brain | Variants |
+| `stitch-ued-guide` | Visual vocabulary, layout patterns, aesthetic styles, device constraints, color structure | Brain | Reference |
+| `stitch-mcp-create-project` | Create a new Stitch project → extract numeric project ID | Execution | Setup |
+| `stitch-mcp-list-projects` | List Stitch projects (owned or shared) | Execution | Discovery |
+| `stitch-mcp-get-project` | Get project metadata (uses `projects/ID` format) | Execution | Discovery |
+| `stitch-mcp-delete-project` | Permanently delete a Stitch project (uses `projects/ID` format, requires confirmation) | Execution | Cleanup |
+| `stitch-mcp-generate-screen-from-text` | Text → UI screen (core Stitch generation — numeric ID only) | Execution | Generate |
+| `stitch-mcp-upload-screens-from-images` | Import screenshots/mockups as new screens (numeric ID, base64 images) | Execution | Generate |
+| `stitch-mcp-edit-screens` | Edit existing screens with text prompts — the iteration tool (numeric IDs) | Execution | Iterate |
+| `stitch-mcp-generate-variants` | Generate design variants with creativity/aspect controls (numeric IDs) | Execution | Iterate |
+| `stitch-mcp-list-screens` | List all screens in a project (uses `projects/ID` format) | Execution | Retrieve |
+| `stitch-mcp-get-screen` | Get screen HTML + screenshot + dimensions (numeric IDs for both) | Execution | Retrieve |
+| `stitch-mcp-create-design-system` | Create a reusable Stitch Design System from theme tokens | Execution | Design Systems |
+| `stitch-mcp-update-design-system` | Update an existing design system (requires asset `name`) | Execution | Design Systems |
+| `stitch-mcp-list-design-systems` | List available design systems (optional project filter) | Execution | Design Systems |
+| `stitch-mcp-apply-design-system` | Apply a design system to screens (numeric IDs + assetId) | Execution | Design Systems |
+| `stitch-nextjs-components` | Stitch HTML → Next.js 15 App Router components (TypeScript, dark mode, ARIA) | Conversion | Web |
+| `stitch-svelte-components` | Stitch HTML → Svelte 5 / SvelteKit (runes, scoped CSS, transitions) | Conversion | Web |
+| `stitch-html-components` | Stitch HTML → platform-agnostic HTML5 + CSS (PWA, WebView, Capacitor) | Conversion | Web |
+| `stitch-react-components` | Stitch HTML → Vite + React (TypeScript, no App Router, simpler than Next.js) | Conversion | Web |
+| `stitch-shadcn-ui` | Add shadcn/ui components to React apps (discovery, install, customization) | Conversion | Web |
+| `stitch-react-native-components` | Stitch HTML → React Native / Expo (cross-platform iOS + Android) | Conversion | Mobile |
+| `stitch-swiftui-components` | Stitch HTML → SwiftUI (native iOS, Xcode 15+) | Conversion | Mobile |
+| `stitch-remotion` | Stitch screenshots → walkthrough video (Remotion, transitions, overlays) | Conversion | Video |
+| `stitch-loop` | Iterative multi-page building: baton (next-prompt.md) → generate → integrate → update baton | Conversion | Multi-page |
+| `stitch-design-md` | Analyze Stitch project → natural-language `DESIGN.md` with color palette, typography, atmosphere, and Section 6 Stitch prompt snippets | Quality | Design docs |
+| `stitch-design-system` | Extract design tokens → `design-tokens.css` (light + dark), `tailwind-theme.css`, `DESIGN.md` | Quality | Tokens |
+| `stitch-animate` | Add purposeful animation (CSS keyframes, Framer Motion, Svelte transitions, reduced-motion) | Quality | Animation |
+| `stitch-a11y` | WCAG 2.1 AA audit and fixes (semantic HTML, ARIA, keyboard, focus, contrast, images) | Quality | Accessibility |
+| `stitch-setup` | Install Stitch MCP + stitch-kit plugin (Claude Code / Codex CLI setup guide) | Meta | Setup |
+| `stitch-skill-creator` | Factory for creating new Stitch skills (SOP, naming, template generator) | Meta | Extension |
+
+---
+
+## By output target
+
+### Web apps
+Next.js, Svelte, HTML, Vite+React, shadcn/ui
+
+### Mobile apps
+React Native (iOS + Android), SwiftUI (iOS only)
+
+### Multi-page sites
+`stitch-loop` — iterative baton-passing pattern
+
+### Video
+`stitch-remotion` — walkthrough from screenshots
+
+---
+
+## ID format quick reference
+
+This is the most common source of bugs when calling Stitch MCP tools directly:
+
+| Tool | projectId format | screenId format | Other IDs |
+|------|-----------------|----------------|-----------|
+| `create_project` | Returns `projects/NUMERIC_ID` | — | — |
+| `list_projects` | — | — | — |
+| `get_project` | `projects/NUMERIC_ID` | — | — |
+| `delete_project` | `projects/NUMERIC_ID` | — | — |
+| `generate_screen_from_text` | **Numeric only** | — | — |
+| `upload_screens_from_images` | **Numeric only** | — | — |
+| `edit_screens` | **Numeric only** | **Numeric array** | — |
+| `generate_variants` | **Numeric only** | **Numeric array** | — |
+| `list_screens` | `projects/NUMERIC_ID` | — | — |
+| `get_screen` | **Numeric only** | **Numeric only** | — |
+| `create_design_system` | **Numeric only** (optional) | — | Returns Asset `name` |
+| `update_design_system` | — | — | Asset `name` required |
+| `list_design_systems` | **Numeric only** (optional) | — | Returns Asset names |
+| `apply_design_system` | **Numeric only** | **Numeric array** | `assetId` required |
+
+**Rules of thumb:**
+- **Read operations** (`get_project`, `list_screens`, `delete_project`) → `projects/ID` full path
+- **Generation/mutation** (`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
+
+See `mcp-naming-convention.md` for full details.
+
+---
+
+## References
+
+- `mcp-naming-convention.md` — ID format rules
+- `mcp-schemas/` — Formal JSON Schema definitions for all 14 Stitch MCP tools (fonts, roundness, componentRegions, outputComponents, variantOptions, designSystems)
+- `color-prompt-guide.md` — 8 ready-to-use color palettes for Stitch prompts
+- `tailwind-reference.md` — Tailwind utility class reference for conversions
+- `prd-to-stitch-workflow.md` — PRD-driven design workflow