diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 69b10ca..c699a77 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -4,7 +4,7 @@ "name": "gabelul" }, "metadata": { - "description": "Design superpowers for Claude Code — 35 skills that teach your agent to ideate, research trends, generate multi-screen UIs with Stitch MCP, iterate with design systems, and ship to Next.js, Svelte, React, React Native, SwiftUI, or HTML.", + "description": "Your agent designs terrible UI. stitch-kit wires it into Google Stitch MCP and teaches it the whole pipeline — ideation, research, multi-screen generation, design systems, and shipping to Next.js, Svelte, React, React Native, SwiftUI, or HTML.", "version": "1.11.0" }, "plugins": [ diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index b12a35d..d668b11 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "stitch-kit", - "description": "Design superpowers for Claude Code — 35 skills that teach your agent to ideate, research, generate, iterate, and ship beautiful UIs using Google Stitch MCP.", + "description": "Your agent designs terrible UI. stitch-kit wires it into Google Stitch MCP and teaches it the whole pipeline — ideation, screen generation, design systems, and production components across 7 frameworks.", "version": "1.11.0", "author": { "name": "gabelul" diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 3f3fb7c..9e95d6d 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "stitch-kit", "version": "1.11.0", - "description": "Design superpowers for Codex — skills that ideate, generate, and ship UIs with Google Stitch MCP, with compaction-resilient session state.", + "description": "Your agent designs terrible UI. stitch-kit wires it into Google Stitch MCP and teaches it the whole pipeline — ideation, screen generation, design systems, production components. Survives compaction with session state on disk.", "author": { "name": "gabelul" }, diff --git a/.github/assets/showcase-destiny.png b/.github/assets/showcase-destiny.png new file mode 100644 index 0000000..2bbfe73 Binary files /dev/null and b/.github/assets/showcase-destiny.png differ diff --git a/.github/assets/showcase-ghostwork.png b/.github/assets/showcase-ghostwork.png new file mode 100644 index 0000000..639d96d Binary files /dev/null and b/.github/assets/showcase-ghostwork.png differ diff --git a/.github/assets/showcase-hostguard.png b/.github/assets/showcase-hostguard.png new file mode 100644 index 0000000..e819fe2 Binary files /dev/null and b/.github/assets/showcase-hostguard.png differ diff --git a/.github/assets/showcase-vault.jpg b/.github/assets/showcase-vault.jpg new file mode 100644 index 0000000..33778f1 Binary files /dev/null and b/.github/assets/showcase-vault.jpg differ diff --git a/.gitignore b/.gitignore index 2aa60c1..2ad19f5 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,6 @@ node_modules/ # snapshots). Runtime state, never source — and the snapshots can contain # conversation content, so it stays out of git. .stitch/ + +# Local agent orchestration state (oh-my-claudecode) — never ship this +.omc/ diff --git a/README.md b/README.md index 9f81193..7112553 100644 --- a/README.md +++ b/README.md @@ -2,49 +2,72 @@ stitch-kit — design superpowers for AI coding agents

-# stitch-kit — Design superpowers for AI coding agents | Google Stitch MCP plugin +# stitch-kit -I built this because I got tired of watching Claude Code generate UIs that look like a government form from 2004. Gray boxes, blue buttons, zero taste. Meanwhile, Google's [Stitch](https://stitch.withgoogle.com) generates genuinely beautiful, pixel-perfect screens from text — but it's just a raw MCP tool sitting there, and no coding agent knows how to use it properly. +**Your coding agent writes decent code and designs terrible UI. stitch-kit fixes the second half — it wires agents into [Google Stitch](https://stitch.withgoogle.com) (text prompts → genuinely beautiful screens) and teaches them to drive it properly.** -So I taught them. - -stitch-kit is 35 skills that give AI coding agents actual design intelligence. Not "here's a prompt, good luck" — real ideation, visual research, prompt engineering that produces quality output, multi-screen batch generation, design systems, iteration loops, and conversion to production framework components. The whole pipeline from "I have a vague idea" to shippable code. +I built this because I got tired of watching Claude Code generate UIs that look like a government form from 2004. Gray boxes, blue buttons, zero taste. Meanwhile Stitch generates pixel-perfect screens from text — but it's a raw MCP tool sitting there, and no coding agent knows how to use it well. -Your agent goes from design-blind to design-competent. You describe what you want (or just brainstorm out loud), and the agent researches trends, proposes 3 design directions with real color palettes and typography, generates a full PRD, creates up to 10 screens in Stitch in one shot, iterates until it looks right, and converts to Next.js, Svelte, React, React Native, SwiftUI, or HTML. +So I taught them. -Works in Claude Code, Codex CLI, and any agent that speaks MCP. +All four of these came out of stitch-kit. Different briefs, genuinely different results — not one template with the hue rotated. + + + + + + + + + + + + + + + + + + +
Ghostwork ops dashboard — monospace source health matrix, transport lane utilisation, live job queueHostGuard compliance dashboard — serif headings on warm cream, property alerts, activity timeline
Ops console · monospace, dense tables, industrial lightCompliance SaaS · serif on warm cream, generous whitespace
Destiny Lantern chart screen — midnight blue and gold, display serif with CJK typographyDocument scanner mobile screen — dark capture UI with orange framing over a live camera view
Astrology app · midnight and gold, serif + CJK typeMobile capture · dark UI over live camera, orange framing
+ + --- -## Install +> **Needs Google Stitch access.** Everything here runs through Stitch, so sort that out first — sign in at [stitch.withgoogle.com](https://stitch.withgoogle.com) with any Google account, then grab an API key from [settings](https://stitch.withgoogle.com/settings). +> +> No waitlist, no invite, free to use as of mid-2026. There are monthly generation limits, and Google has signalled paid tiers are coming — so treat the free allowance as generous-but-finite rather than unlimited. -### Quick install (recommended) +## Install ```bash npx @booplex/stitch-kit ``` -One command. It auto-detects your setup (Claude Code, Codex CLI, or both), installs the agent + skills, configures Stitch MCP, and tells you if anything's missing. +Detects every supported client you have installed — Claude Code, Codex CLI, OpenCode, Crush, Cursor, VS Code, Gemini CLI — and wires up whatever each one supports. See [Works with](#works-with) for what that means per client. -```bash -npx @booplex/stitch-kit update # update to latest -npx @booplex/stitch-kit status # check what's installed -``` - -After installing, sign in at [stitch.withgoogle.com](https://stitch.withgoogle.com) to complete Google auth. - -### Claude Code plugin (optional, adds skills) - -The NPX installer sets up the agent and MCP. For the full skill set (ideation, prompt engineering, design systems, iteration, conversion), also install the plugin inside Claude Code: +Then, inside Claude Code, add the skills: ```bash /plugin marketplace add https://github.com/gabelul/stitch-kit.git /plugin install stitch-kit@stitch-kit ``` -The agent works standalone with MCP tools, but skills add structured workflows that make the output noticeably better. +Two steps, not one — the npx installer handles the agent and MCP wiring, the plugin adds the 35 skills. The agent works without them, but the skills are what make the output good. -### Manual setup (if you prefer) +```bash +npx @booplex/stitch-kit update # update to latest +npx @booplex/stitch-kit status # check what's installed +```
Claude Code — manual steps @@ -87,6 +110,28 @@ Use `$stitch-kit` to activate the agent or `$stitch-orchestrator` for the full p --- +## Works with + +The installer detects what you've got and wires up whatever that client supports. Not every agent takes skills, so here's the honest breakdown rather than a logo wall: + +| Client | Stitch MCP | Agent | Skills | +|--------|:----------:|:-----:|:------:| +| Claude Code | ✅ | ✅ | ✅ via plugin | +| Codex CLI | ✅ | ✅ | ✅ | +| OpenCode | ✅ | ✅ | ✅ | +| Crush | ✅ | — | ✅ | +| Cursor | ✅ | — | — | +| VS Code | ✅ | — | — | +| Gemini CLI | via extension | — | — | + +**Skills** are the structured workflows — ideation, prompt engineering, ID-safe MCP wrappers, framework conversion. **Agent** is the Stitch-aware persona that knows the full toolset. **MCP only** means you get Stitch wired into the client and can drive it by hand, but none of the design intelligence — which is most of the point, so the top three are where this actually shines. + +Gemini CLI handles MCP through its own extension system rather than a config file, so the installer points you at `gemini extensions list` instead of writing config for you. + +Check what you've got with `npx @booplex/stitch-kit status`. + +--- + ## What actually happens when you use it

@@ -103,7 +148,21 @@ Without stitch-kit, your agent sends Stitch a half-baked prompt, gets confused b 4. **Ship real code** — Convert to production components with dark mode, TypeScript, design tokens, and ARIA. Not "here's some JSX, figure it out" — proper Server/Client component split, theme integration, accessibility baked in. -There's also an agent definition (`agents/stitch-kit.md`) for both Claude Code and Codex — a Stitch-aware agent that knows the full skill set and doesn't hallucinate MCP tool names (which happens more than you'd think). +--- + +## Ship to any framework + +Once your design is ready, pick your target: + +| Target | Skill | What you get | +|--------|-------|-------------| +| Next.js 15 App Router | `stitch-nextjs-components` | Server/Client split, `next-themes`, TypeScript strict | +| Svelte 5 / SvelteKit | `stitch-svelte-components` | Runes API, scoped CSS, built-in transitions | +| Vite + React | `stitch-react-components` | `useTheme()` hook, Tailwind, no App Router overhead | +| HTML5 + CSS | `stitch-html-components` | No build step — PWA, WebView, Capacitor ready | +| shadcn/ui | `stitch-shadcn-ui` | Radix primitives, token alignment with Stitch palette | +| React Native / Expo | `stitch-react-native-components` | iOS + Android, `useColorScheme`, safe areas | +| SwiftUI | `stitch-swiftui-components` | iOS 16+, `@Environment(\.colorScheme)`, 44pt targets | --- @@ -113,15 +172,13 @@ There's also an agent definition (`agents/stitch-kit.md`) for both Claude Code a stitch-kit architecture — 5 layers, 35 skills

-Five layers. I didn't build 35 skills for fun — each layer exists because agents consistently fail at something specific with Stitch. +Five layers, 35 skills. Each layer exists because agents fail at something specific with Stitch, and the failures are different enough that one skill can't cover them. -**The ID format thing deserves its own callout.** `generate_screen_from_text` wants `"3780309359108792857"`. `list_screens` wants `"projects/3780309359108792857"`. Pass the wrong one and you get a cryptic error. This is the #1 reason agents fail with raw Stitch MCP, and it's the reason I built 14 wrapper skills instead of letting agents call the API directly. +**The ID format thing deserves its own callout.** `generate_screen_from_text` wants `"3780309359108792857"`. `list_screens` wants `"projects/3780309359108792857"`. Pass the wrong one and you get a cryptic error. This is the #1 reason agents fail with raw Stitch MCP, and it's why there are 14 wrapper skills instead of letting agents call the API directly. Details → [docs/architecture.md](docs/architecture.md) ---- - -## Skill anatomy +### Skill anatomy ``` skills/[skill-name]/ @@ -167,22 +224,6 @@ stitch-kit has 35. It covers the full pipeline: conversational ideation with web --- -## Ship to any framework - -Once your design is ready, pick your target: - -| Target | Skill | What you get | -|--------|-------|-------------| -| Next.js 15 App Router | `stitch-nextjs-components` | Server/Client split, `next-themes`, TypeScript strict | -| Svelte 5 / SvelteKit | `stitch-svelte-components` | Runes API, scoped CSS, built-in transitions | -| Vite + React | `stitch-react-components` | `useTheme()` hook, Tailwind, no App Router overhead | -| HTML5 + CSS | `stitch-html-components` | No build step — PWA, WebView, Capacitor ready | -| shadcn/ui | `stitch-shadcn-ui` | Radix primitives, token alignment with Stitch palette | -| React Native / Expo | `stitch-react-native-components` | iOS + Android, `useColorScheme`, safe areas | -| SwiftUI | `stitch-swiftui-components` | iOS 16+, `@Environment(\.colorScheme)`, 44pt targets | - ---- - ## Full skill reference All 35 skills with descriptions, layers, and the ID format table → [docs/skills-index.md](docs/skills-index.md) diff --git a/docs/dev-docs/troubleshooting.md b/docs/dev-docs/troubleshooting.md index 557e3d9..4cad969 100644 --- a/docs/dev-docs/troubleshooting.md +++ b/docs/dev-docs/troubleshooting.md @@ -93,3 +93,22 @@ A "we stepped on this landmine so you don't have to" reference for stitch-kit. N **Files:** `hooks/hooks.json`, `.codex-plugin/plugin.json`, `skills/stitch-ideate/SKILL.md`, `skills/stitch-orchestrator/SKILL.md` **Lesson:** On Codex, a hook existing isn't a hook running. Design the feature to degrade to a skill-level self-check when hooks aren't trusted. + +## Screenshot `downloadUrl` silently serves a 512px thumbnail + +**Symptom:** `list_screens` / `get_screen` report a screen as `2560x2048`, but downloading its `screenshot.downloadUrl` gives you a 512px image. No error, no warning — just a thumbnail wearing the metadata of a full-resolution asset. Easy to ship a blurry gallery without noticing. + +**Root cause:** Stitch serves screenshots from `lh3.googleusercontent.com`, which applies a default size cap when the URL carries no size parameter. The `width`/`height` fields in the API response describe the *source* screen, not what the URL returns. + +**Fix:** Append a size parameter to the `downloadUrl`. `=s0` returns the original; `=w1600` / `=s2560` / `=w2560-h2048` all work for a bounded fetch. + +```bash +curl -sL -o screen.png "${DOWNLOAD_URL}=s0" # original resolution +curl -sL -o screen.png "${DOWNLOAD_URL}=w1200" # bounded width +``` + +Project-level `thumbnailScreenshot.downloadUrl` behaves the same way, but it's a genuine thumbnail — for full-resolution output, go through the screen, not the project. + +**Files:** any skill that retrieves screenshots — `skills/stitch-mcp-get-screen/`, `skills/stitch-mcp-list-screens/` + +**Lesson:** Dimensions in an API response describe the resource, not the transfer. When a CDN sits in front of an asset, check what actually came down the wire — `file` on the result takes two seconds and catches this immediately. diff --git a/package.json b/package.json index 4e429ca..5b30ff7 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@booplex/stitch-kit", "version": "1.11.0", - "description": "Design superpowers for AI coding agents — 35 skills that teach agents to ideate, generate, iterate, and ship production UIs using Google Stitch MCP. Works with Claude Code, Codex CLI, and any MCP-compatible agent.", + "description": "Your coding agent designs terrible UI. stitch-kit wires it into Google Stitch MCP and teaches it the whole pipeline — ideation, screen generation, design systems, production components. Claude Code, Codex, OpenCode, Crush, Cursor, VS Code, Gemini CLI.", "bin": { "stitch-kit": "./bin/stitch-kit.mjs", "stitch-session": "./scripts/stitch-session.mjs" @@ -21,27 +21,32 @@ "LICENSE" ], "keywords": [ - "stitch", - "stitch-mcp", - "google-stitch", - "ui-design", + "agent-skills", "ai-design", - "text-to-ui", "claude-code", "claude-code-plugin", "codex-cli", - "mcp", - "mcp-tools", - "model-context-protocol", + "coding-agent", + "crush", + "cursor", "design-agent", - "agent-skills", + "design-system", "design-to-code", "figma-alternative", + "gemini-cli", + "google-stitch", + "mcp", + "mcp-tools", + "model-context-protocol", "nextjs", - "svelte", + "opencode", "react-native", + "stitch", + "stitch-mcp", + "svelte", "swiftui", - "design-system", + "text-to-ui", + "ui-design", "ui-generation" ], "author": "gabelul",