Mk Stitch

---
name: "mk-stitch"
description: "Generate novel UI from a text prompt via Stitch AI; exports Tailwind/HTML + DESIGN.md for mk:frontend-design handoff. NOT implementing existing designs -- use mk:figma or mk:frontend-design."
---

# Stitch — AI Design Generation

Generate high-fidelity UI designs from text prompts. Export Tailwind/HTML, PNG screenshot,
and DESIGN.md for handoff to `mk:frontend-design`.

Use only for a novel, text-prompt design. Existing design sources belong to `mk:figma` or
`mk:frontend-design`.

## Setup and guard

Set `STITCH_API_KEY` in `.env`, then install the scripts once:

```bash
cd .cursor/skills/stitch/scripts && npm install
```

Run the prerequisite check before any API command; it fails before a network request if the key
or `tsx` is unavailable. Full setup, optional variables, and MCP setup: [references/stitch-setup.md](references/stitch-setup.md).

## Fail-Closed Gate

Before any script runs, verify both prerequisites:

```bash
# Key gate
[ -z "$STITCH_API_KEY" ] && { echo "[X] STITCH_API_KEY not set — add to .env"; exit 1; }

# tsx gate
npx tsx --version 2>/dev/null || { echo "[X] tsx not found — run: cd .cursor/skills/stitch/scripts && npm install"; exit 1; }
```

`stitch-api-call.ts` also checks `STITCH_API_KEY` as its first action before any Stitch SDK
call. If the key is unset the script exits 1 immediately — no network request is made.

## Quick Start

```bash
# 1. Check quota
npx tsx .cursor/skills/stitch/scripts/stitch-quota.ts check

# 2. Generate (API call only — returns JSON with screenId + imageUrl)
npx tsx .cursor/skills/stitch/scripts/stitch-api-call.ts \
  generate "A checkout page with cart summary and payment form"

# 3. Export + write files (pipe: API call → schema-validate → write to disk)
npx tsx .cursor/skills/stitch/scripts/stitch-api-call.ts export <screen-id> | \
  npx tsx .cursor/skills/stitch/scripts/stitch-write-output.ts
```

## Commands

| Task | Command / contract |
|---|---|
| Check quota | `npx tsx .cursor/skills/stitch/scripts/stitch-quota.ts check` |
| Generate | `npx tsx .cursor/skills/stitch/scripts/stitch-api-call.ts generate "<prompt>"` — returns `screenId`, `projectId`, `imageUrl`, and quota data |
| Export | `npx tsx .cursor/skills/stitch/scripts/stitch-api-call.ts export <screen-id> \| npx tsx .cursor/skills/stitch/scripts/stitch-write-output.ts` |

Show `imageUrl` and obtain user approval before exporting. Detailed flags, quota operations, and
the API/write security boundary: [references/stitch-operations.md](references/stitch-operations.md).

## Workflow

1. Check quota; if exhausted (exit 2), route to `mk:frontend-design`.
2. Generate, review the returned screenshot with the user, then export and write.
3. Handoff `DESIGN.md` to `mk:frontend-design` for implementation.

Load [references/design-to-code-pipeline.md](references/design-to-code-pipeline.md) for variants,
iteration patterns, and detailed handoff guidance.

The writer outputs the HTML, image, and `DESIGN.md` handoff under `tasks/designs/`; exact paths
and the handoff contract are in [references/stitch-operations.md](references/stitch-operations.md).

## Limitations

- **HTML/Tailwind only** — no React/Vue/Svelte export; use `mk:frontend-design` to convert
- **Non-responsive layouts** — add breakpoints during implementation
- **Static only** — no animations; add micro-interactions in code
- **Local quota tracking** — actual usage may diverge if designs are generated outside this skill

## Gotchas

- `STITCH_API_KEY` must be in `.env` — the skill fails closed (exit 1) if unset; no network call is attempted
- `tsx` must be installed (`npm install` in `scripts/`) — scripts will not run without it; install once per machine
- Local quota can drift from real Stitch usage (e.g., designs made via the Stitch web UI); if you hit `RATE_LIMITED` despite the tracker showing credits, run `stitch-quota.ts reset`
- Quota limits and paid-tier availability are volatile; load [quota-management.md](references/quota-management.md) before making a quota-based decision.
- Screen IDs returned by `generate` are stable (Tool Contract Rule 2); project name auto-detection uses git remote then CWD basename
- The optional MCP integration stores the API key in `.mcp.json` — never commit that file; the kit's `.gitignore` covers it
- `stitch-write-output.ts` validates CDN URLs against a Google-domain allowlist; if Stitch changes CDN domains, update `ALLOWED_CDN_SUFFIXES` in that script

## References

| Topic | File |
|-------|------|
| SDK API | `references/stitch-sdk-api.md` |
| MCP Setup | `references/stitch-mcp-setup.md` |
| Pipeline Patterns | `references/design-to-code-pipeline.md` |
| Quota Strategy | `references/quota-management.md` |