Stitch Design

AI-powered UI design with Google Stitch — generate, iterate, export.

Setup

Required: Node.js 18+ and STITCH_API_KEY env var.
Get a key at: https://stitch.withgoogle.com → Profile → API Keys
Configure the key in your OpenClaw skill env settings or in the shell used to run the CLI.

CODEBLOCK0

Install scope: this installs the Node dependency declared in scripts/package.json (@google/stitch-sdk) plus its npm transitive dependencies.

Troubleshooting:

• - STITCH_API_KEY not set → ensure the env var is configured in OpenClaw skill settings or shell
• INLINECODE4 / timeouts → Stitch API calls take 1-5 min; the CLI retries automatically
• INLINECODE5 → run node scripts/stitch.mjs rebuild --project <id> to reconstruct from event log

Usage

Runtime Scope

• - Network: Google Stitch API and Google-hosted screenshot URLs returned by Stitch
• Credentials: STITCH_API_KEY only
• Local writes: runs/, state/, INLINECODE10
• No extra services, daemons, browser automation, or unrelated credentials required

The CLI is at scripts/stitch.mjs. All output is JSON on stdout.

CODEBLOCK1

---

Workflow: New Design

Use when user wants to design something from scratch.

Step 1 — Shape the prompt (see references/prompt-guide.md for keywords)

Transform the user's brief into a richer prompt:

• - Add layout terms (sidebar, card grid, hero section...)
• Add visual tone (minimal, dark mode, editorial...)
• Specify device explicitly

Step 2 — Generate

CODEBLOCK2

Typical time: 1–5 minutes. The CLI downloads HTML + PNG automatically.

Step 3 — Preview

Show the hi-res screenshot: run show <alias> → display via MEDIA:<screenshotUrl> (see Image Delivery).

Step 4 — Iterate (edit or variants)

---

Workflow: Edit Design

Use when user wants targeted changes to an existing screen.

CODEBLOCK3

Focused edits work better than vague ones. Be specific: colors, layout, components.

---

Workflow: Design Variants

Use when user wants to explore directions before committing.

CODEBLOCK4

Creative ranges:

• - refine — small changes, stays close to original
• INLINECODE16 — moderate exploration (default)
• INLINECODE17 — radical redesign

Aspects (comma-separated): layout, color_scheme, images, text_font, text_content

---

Workflow: Visual Review (Browse & Pick)

Use when user wants to see existing designs and decide which to work on.

Step 1 — Get project overview

CODEBLOCK5

This returns all screen IDs + titles.

Step 2 — Export screenshots for each screen

CODEBLOCK6

Do this for each screen (or a selection). Each call saves a local thumbnail + result.json with the screenshotUrl.

Step 3 — Send images to user

For each screen: get the screenshotUrl from the image command's result.json, append =w780, and display via MEDIA:<url>.
Include screen ID + title as caption so user can reference them.

Step 4 — User picks a screen

User says "take screen 3" or "the dark one" → match to screen ID.

Step 5 — Continue with edit/variants

Use the picked screen ID for edit or variants workflows.

---

Workflow: Export

Download HTML + screenshot from an existing screen.

CODEBLOCK7

---

Multi-Screen Consistency

Rule: Always start with a Hub Screen

Related screens of a concept need a shared hub screen as their visual basis. Generate is generative — layout, colors, spacing, and typography are all invented from scratch. Edit takes the source screen as the visual basis and changes only what you describe — navigation, typography, and color palette stay consistent.

generate vs edit — the key difference:

• - generate = brand-new screen. Everything is up for grabs.
• INLINECODE33 = visual continuation of the source screen. Only the described delta changes.

Recommended Workflow

1. 1. Generate the hub screen → review it carefully
2. All further screens of the same concept → edit from the hub, not fresh INLINECODE35
3. Max 1-2 changes per edit prompt — Stitch regenerates generatively, not surgically. Too many changes = unpredictable results
4. Even elements you did NOT mention can change in an edit. Fewer changes = more stable output.

Core Rule: For multi-screen concepts, always define a hub screen first, then derive further screens via edit — never fresh generate.

Reduce to Core (Concept Phase)

During the concept phase, 3-4 consistent core screens are enough. Full screen coverage only after the concept is approved. Stitch excels at rapid exploration, not exhaustive elaboration.

---

Screen Review Loop

A systematic loop for deciding when to keep editing in Stitch vs. when to note something for post-export fixing.

4-Step Loop

Step 1 — Run generate or edit

Step 2 — Analyze the screenshot (vision model)

Check against this list:

• - Layout structure — sections in right order, correct hierarchy
• Colors — matches design system / brief
• Content — no hallucinated labels, avatars, or copy that doesn't belong
• Navigation — correct tabs, back buttons, menu items
• Design System Compliance — spacing, typography, component patterns

Step 3 — Categorize issues

Category	Examples
Stitch-fixable	Missing section, wrong layout order, major color error, wrong navigation structure
Post-Export Fix

Exact pixel spacing, icon details, typography fine-tuning, persistent content hallucinations (avatars, labels) |

Step 4 — Decide

• - Fix in Stitch → write a focused edit prompt (max 1-2 changes), go back to Step 1
• Post-export fix → note it, move on to next screen

Decision Tree

• - Stitch didn't fix it after 2 edits → note as post-export fix, move on
• Detail work (shadows, exact radii, pixel spacing) → directly note as post-export fix, don't waste edit budget
• Structural issue (section missing, navigation wrong) → Stitch edit

The user decides which external tool to use for post-export fixes — Figma, Framer, code, or any other tool. Do not prescribe a tool.

---

Planning — Feature Coverage

Before generating anything, create a feature matrix: which features appear on which screen. Only start generating once the coverage is clear. This way every subsequent generate/edit call is a deliberate execution step, not a discovery — no surprises, no forgotten features. Keep this matrix short; a simple table or bullet list per screen is enough. Three focused screens you've thought through are worth more than ten screens you discover issues with during generation.

---

Project Management

CODEBLOCK8

---

State Tracking

INLINECODE36 (in skill root) tracks the last generated/edited screen.

• - edit, variants, html, image, export auto-detect project from INLINECODE42
• Override with --project <id> when needed

---

Screen Names (Alias Registry)

Screens get auto-generated IDs like bcde81e368e24edbabd6213d9dc17b3b. Use screen names to give them memorable aliases that persist across sessions.

Naming screens

CODEBLOCK9

Looking up screens

CODEBLOCK10

Managing names

CODEBLOCK11

Naming rules

• - Slugs only: lowercase a-z, 0-9, hyphens. Case-insensitive.
• Examples: concept-a, home-v2, onboarding-flow, INLINECODE50
• Not allowed: spaces, uppercase, special characters
• Aliases are unique per project — the same alias can exist in different projects
• Use --force to overwrite an existing alias

How it works

• - Names are stored in state/projects/<projectId>/names.json (rebuildable snapshot)
• Every operation is recorded in state/projects/<projectId>/events.jsonl (append-only, immutable)
• The Stitch API remains the source of truth for screen data — local state only stores mappings and history
• If a screen is deleted in Stitch, show will report it as broken; names --verify checks all at once
• If names.json gets corrupted, run rebuild to reconstruct from the event log (pre-log aliases require a backup or manual re-naming)

Event Log & History

Every generate/edit/variants operation and every alias change is recorded as an append-only event.

CODEBLOCK12

Event types:

• - generate / edit / variants — screen operations (with parentScreenId, promptPreview, runDir)
• INLINECODE61 / alias_renamed / alias_removed — alias pointer changes
• Variants include a variantGroupId to group related screens

Agent workflow (MANDATORY)

When generating or editing screens for the user:

1. 1. Always use --name when the user has a clear concept name or purpose for the screen
2. If the user refers to a screen by name (e.g. "show me Concept A"), use show <alias> first
3. When editing a named screen, use --name <same-alias> --force to keep the alias pointing to the latest version
4. After every generate/edit/variants: run show <alias|screenId>, extract screenshotUrl, display via MEDIA:<url> (see Image Delivery section)
5. Use names at session start to see what screens already exist

---

Artifacts

Every operation saves to runs/<YYYYMMDD-HHmmss>-<operation>-<slug>/:

File	Content
INLINECODE73	Full HTML/CSS/JS of the screen
INLINECODE74

Screenshot (desktop/mobile) |
| result.json | Metadata (screenId, projectId, prompt, timestamps) |
| variant-N.html/.png | For variants commands |

---

Architecture

The skill uses a 3-layer local state model. The Stitch API is always the source of truth for screen content (HTML, screenshots).

Layer	Storage	Purpose
Artifacts	INLINECODE77	Immutable per-operation receipts: thumbnail, HTML, result.json
Event Log

state/projects/<id>/events.jsonl | Append-only chronological record of all operations |
| Alias Pointers | state/projects/<id>/names.json | Current named references — rebuildable from event log |

Key principles:

• - runs/ are artifacts (never mutated, never deleted)
• INLINECODE81 is the mutable layer (names.json is a snapshot, events.jsonl is append-only)
• INLINECODE82 can be rebuilt from events.jsonl via rebuild (complete for all alias changes recorded in the log; pre-log aliases are preserved from existing snapshot if available)
• Local thumbnails (screen.png) are low-res; always use screenshotUrl + =w780 for display
• INLINECODE88 and runs/ are gitignored — they are local working state, not source code

---

Core Rules

1. 1. MANDATORY: Read references/prompt-guide.md before your first generate/edit/variants call in a session. It contains critical prompting principles that determine output quality. For SDK details (methods, types, enums), see references/sdk-api.md.
2. Always shape prompts — Never pass the user's raw text directly to Stitch. Enrich it using the Prompt Framework (Context → Structure → Aesthetic → Constraints) from the prompt guide. Transform weak prompts into strong ones.
3. Component isolation by default — When the user asks for a component (not a full page), always add: "Design a single standalone UI component — do NOT generate a full application screen. Show it isolated on a neutral background."
4. Preview first — Show the hi-res screenshot to user before offering export
5. Visual feedback (MANDATORY) — After every generate/edit/variants, display the hi-res screenshot inline via show <alias|screenId> → MEDIA:<screenshotUrl>. See "Image Delivery" section.
6. Iteration > perfection — Follow the Anchor → Inject → Tune → Fix loop. Define what must NOT change in every edit prompt.
7. One prompt = one thing — Never combine multiple components or screens in one prompt.
8. Default values: generate defaults to --device desktop. --model uses SDK default (pro). Explicit: --count 3, --range explore. edit and variants inherit device from the source screen.
9. State awareness — Before asking the user for screen or project IDs, ALWAYS read latest-screen.json first. If it has a recent entry, use that projectId/screenId. Only ask if no state exists or the user explicitly switches context.
10. Figma export — Manual: open Stitch UI → "Copy to Figma" → paste in Figma. CLI can export HTML which also pastes into Figma
11. Hub-first for multi-screen concepts — For multi-screen concepts, always define a hub screen first, then derive further screens via edit — never fresh generate.

---

Image Delivery (MANDATORY after every generate/edit/variants)

The local screen.png in runs/ is only a low-res thumbnail (~168×512px). Full-resolution images come from the Stitch API via screenshotUrl.

How it works

The show command accepts an alias OR a raw screen ID and returns live API data with a hi-res screenshot URL (=w780 suffix appended):

CODEBLOCK13

Agent workflow for image display

After every generate/edit/variants:

1. 1. With alias (preferred): run show <alias> → extract screenshotUrl from JSON → INLINECODE109
2. Without alias: run show <screenId> (accepts raw screen IDs too) → same flow
3. Last resort: get screenshotUrl from runs/<dir>/result.json, append =w780, display via INLINECODE114

CODEBLOCK14

URL size suffixes

Google's lh3.googleusercontent.com URLs support size parameters:

• - =w780 — full mobile design width (default from show)
• INLINECODE118 — full desktop design width
• INLINECODE119 — max 2000px on longest side
• No suffix → thumbnail only (~168px wide)

Sketch-to-Design Workflow

Stitch interprets hand-drawn sketches and wireframes well. The SDK has no image upload — but the workflow is:

1. 1. User uploads sketch in Stitch Web UI (stitch.withgoogle.com)
2. User tells the agent: "I uploaded a sketch called [title]" (or just "the sketch I just uploaded")
3. Agent runs info <project-id> → finds the screen by title in INLINECODE121
4. Agent uses edit or variants on that screen to refine it

Limitations

• - No image upload via SDK — Sketches/screenshots must be uploaded in Stitch Web UI first, then refined via the skill
• Models: pro (Gemini 3.1 Pro) and flash (Gemini 3.0 Flash). "Redesign/NanoBanana" from the Web UI = INLINECODE126
• Full-screen bias — Stitch defaults to generating complete layouts. Must be explicitly overridden for component work (see Core Rules).
• Content hallucination — Stitch adds unrequested copy, labels, badges. Always have the user review generated content.
• Long operations — generate/edit/variants take 1-5 minutes. Connection drops are handled automatically via recovery polling (generate/edit retry via list_screens newest; variants use delta-based recovery by comparing screen lists before and after the call)

Flags Reference

Flag	Commands	Values	Default
INLINECODE128	INLINECODE129, edit, INLINECODE131	INLINECODE132, mobile, tablet, INLINECODE135	INLINECODE136 for generate; inherited from source for edit/INLINECODE139
INLINECODE140

generate, edit, variants | pro, flash | SDK default (pro) | | --count | variants | 1–5 | 3 | | --range | variants | refine, explore, reimagine | explore | | --aspects | variants | layout, color_scheme, images, text_font, text_content | all | | --project | all | project ID | from latest-screen.json | | --design-system | generate, edit, variants | design system name/slug | — |

Note on --design-system: Stitch supports native Design Systems (create_design_system), but the SDK does not yet allow linking them to generate/edit calls. --design-system is a workaround that loads design-systems/<name>.md from this skill folder and appends that content to your prompt. It does not accept arbitrary file paths. Once the SDK supports design_system_id in generate/edit, this flag will become obsolete.