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 .codex/.env, then install the scripts once:

cd .agents/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.

Fail-Closed Gate

Before any script runs, verify both prerequisites:

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

# tsx gate
npx tsx --version 2>/dev/null || { echo "[X] tsx not found — run: cd .agents/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

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

# 2. Generate (API call only — returns JSON with screenId + imageUrl)
npx tsx .agents/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 .agents/skills/stitch/scripts/stitch-api-call.ts export <screen-id> | \
  npx tsx .agents/skills/stitch/scripts/stitch-write-output.ts

Commands

Task	Command / contract
Check quota	npx tsx .agents/skills/stitch/scripts/stitch-quota.ts check
Generate	npx tsx .agents/skills/stitch/scripts/stitch-api-call.ts generate "<prompt>" — returns screenId, projectId, imageUrl, and quota data
Export	npx tsx .agents/skills/stitch/scripts/stitch-api-call.ts export <screen-id> | npx tsx .agents/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.

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 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.

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 .codex/.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 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 .codex/.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