mk:stitch

What This Skill Does

Generates high-fidelity UI designs from text descriptions using the Stitch AI service. Exports Tailwind/HTML, a PNG screenshot, and a structured DESIGN.md file that mk:frontend-design reads as an implementation spec.

This is a text-prompt → NEW design skill. It does not accept existing design sources (Figma URLs, mockups, screenshots) — use mk:figma or mk:frontend-design for those.

When to Use

Triggers:

• "generate a UI design from this description", "create a wireframe for"
• "design a checkout page", "mock up a dashboard from scratch"
• Rapid prototyping before implementation begins

Anti-triggers:

• Implementing a design from a Figma URL — use mk:figma
• Implementing from an existing spec, mockup, or DESIGN.md — use mk:frontend-design
• Building a full design system with component variants — use mk:ui-design-system

Prerequisites

1. API key — set STITCH_API_KEY=<your-key> in .claude/.env (get from https://stitch.withgoogle.com/settings/api)
2. SDK — cd .claude/skills/stitch/scripts && npm install (installs @google/stitch-sdk + tsx)

The skill fails closed (exit 1, no network request) if STITCH_API_KEY is unset.

Core Capabilities

• Generate — text prompt → novel UI design (screen ID + preview image URL)
• Export — screen ID → design.html (Tailwind/HTML) + design.png + DESIGN.md
• Variants — generate 1–5 design alternatives with --variants N
• Quota tracking — local 400-credit/day tracker with fallback guidance
• Security split — API call and file write are separate scripts; no step holds prompt + key + write simultaneously
• DESIGN.md handoff — structured token extraction (layout, components, colors, typography, spacing) ready for mk:frontend-design

Usage

# 1. Check quota
npx tsx .claude/skills/stitch/scripts/stitch-quota.ts check

# 2. Generate design
npx tsx .claude/skills/stitch/scripts/stitch-api-call.ts \
  generate "A modern SaaS pricing page with three tiers and annual/monthly toggle"

# 3. Export + write files (pipe API response to write step)
npx tsx .claude/skills/stitch/scripts/stitch-api-call.ts export <screen-id> --format all | \
  npx tsx .claude/skills/stitch/scripts/stitch-write-output.ts

# 4. Implement from DESIGN.md
# Activate mk:frontend-design: "Implement from tasks/designs/<plan>/<screen-id>/DESIGN.md"

Output

tasks/designs/<plan-or-repo>/<screen-id>/
├── design.html    # Semantic HTML with Tailwind CSS classes
├── design.png     # Screenshot (PNG)
└── DESIGN.md      # Design spec: layout_type, components[], colors[], typography[], spacing[]

<plan-or-repo> auto-resolves from the most recent plan in tasks/plans/, or falls back to the git repo name, then the CWD basename.

Flags

generate

Flag	Effect
--device mobile|desktop|tablet	Target device type (default: unspecified)
--variants <N>	Generate N additional design alternatives (1–5)
--project <id>	Use direct Stitch project ID
--project-name <title>	Lookup or create project by title

export

Flag	Effect
--format html|image|all	Export format (default: all)
--project <id>	Direct Stitch project ID

quota

npx tsx .claude/skills/stitch/scripts/stitch-quota.ts check      # Remaining credits
npx tsx .claude/skills/stitch/scripts/stitch-quota.ts reset      # Force reset (use after RATE_LIMITED)

Quota

Free tier: 400 credits/day (generate + variants) + 15 redesign credits/day (edit). Resets at midnight UTC. When exhausted, use mk:frontend-design for text-based design.

Security

• Fail-closed — script exits 1 before any network call if STITCH_API_KEY is unset
• Two-script boundary — stitch-api-call.ts (key + prompt, no writes) / stitch-write-output.ts (writes, no key)
• Prompt validation — length cap + injection pattern check before sending to the API
• Schema validation — API response validated against StitchResponseSchema before any file write
• CDN URL guard — download URLs checked for HTTPS + Google-domain before fetch()

Common Use Cases

• Rapid prototyping a new feature screen before implementation
• Exploring layout options for a new product page
• Generating a visual reference to align design expectations before coding
• Creating DESIGN.md tokens to feed into mk:frontend-design

Pro Tips

• Review imageUrl before exporting — show the preview image to the user and get approval; regenerate or iterate before committing to export
• Use --variants 3 for exploration — variants are more purposeful than regenerating; each still costs 1 credit
• Quota can drift — if RATE_LIMITED fires despite the tracker showing credits, run stitch-quota.ts reset; the Stitch API enforces the real limit
• Prompt specificity wins — detailed prompts ("checkout page with 3-column product grid, sticky cart sidebar, and promo code input") produce better results than generic ones
• MCP is optional — the npx tsx scripts work without MCP; see references/stitch-mcp-setup.md for the native integration

Canonical source: .claude/skills/stitch/SKILL.md