Stitch Design
by @rasimme
Official Google Stitch SDK wrapper for OpenClaw. Requires only STITCH_API_KEY. Generate UI screens from text, apply targeted edits, branch variants, export H...
clawhub install stitch-designπ About This Skill
name: stitch-design description: Official Google Stitch SDK wrapper for OpenClaw. Requires only STITCH_API_KEY. Generate UI screens from text, apply targeted edits, branch variants, export HTML/images, and track design lineage with screen aliases plus append-only event history. Stores local artifacts under the skill folder and talks only to Google Stitch endpoints needed for generation and screenshot delivery. metadata: {"openclaw": {"requires": {"anyBins": ["node", "node18", "node20", "node22"], "env": ["STITCH_API_KEY"]}, "primaryEnv": "STITCH_API_KEY", "homepage": "https://github.com/rasimme/stitch-design"}}
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.
# Install dependencies (one-time, from skill root)
cd scripts && npm install
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 shellECONNRESET / timeouts β Stitch API calls take 1-5 min; the CLI retries automaticallyCorrupt names.json β run node scripts/stitch.mjs rebuild --project to reconstruct from event logUsage
Runtime Scope
STITCH_API_KEY onlyruns/, state/, latest-screen.jsonThe CLI is at scripts/stitch.mjs. All output is JSON on stdout.
node scripts/stitch.mjs [args] [--flags]
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:
Step 2 β Generate
node scripts/stitch.mjs generate "shaped prompt" --device desktop
Typical time: 1β5 minutes. The CLI downloads HTML + PNG automatically.
Step 3 β Preview
Show the hi-res screenshot: run show β display via MEDIA: (see Image Delivery).
Step 4 β Iterate (edit or variants)
Workflow: Edit Design
Use when user wants targeted changes to an existing screen.
node scripts/stitch.mjs edit "change the header to blue, add a search bar"
--project auto-detected from latest-screen.json
Focused edits work better than vague ones. Be specific: colors, layout, components.
Workflow: Design Variants
Use when user wants to explore directions before committing.
# 3 variants, exploring freely
node scripts/stitch.mjs variants "make it feel more premium" --count 3 --range exploreMore conservative: refine only
node scripts/stitch.mjs variants "tighten the spacing" --count 2 --range refineTarget specific aspects
node scripts/stitch.mjs variants "new color direction" --aspects color_scheme,text_font
Creative ranges:
refine β small changes, stays close to originalexplore β moderate exploration (default)reimagine β radical redesignAspects (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
node scripts/stitch.mjs info
This returns all screen IDs + titles.
Step 2 β Export screenshots for each screen
node scripts/stitch.mjs image --project
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:.
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.
node scripts/stitch.mjs export --project
or just HTML:
node scripts/stitch.mjs html
or just screenshot:
node scripts/stitch.mjs image
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.edit = visual continuation of the source screen. Only the described delta changes.Recommended Workflow
1. Generate the hub screen β review it carefully
2. All further screens of the same concept β edit from the hub, not fresh generate
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:
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
Decision Tree
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
# List all projects
node scripts/stitch.mjs projectsCreate a new project
node scripts/stitch.mjs create "App Name"Show project screens
node scripts/stitch.mjs info
State Tracking
latest-screen.json (in skill root) tracks the last generated/edited screen.
edit, variants, html, image, export auto-detect project from latest-screen.json--project when neededScreen Names (Alias Registry)
Screens get auto-generated IDs like bcde81e368e24edbabd6213d9dc17b3b. Use screen names to give them memorable aliases that persist across sessions.
Naming screens
# Name during generation (recommended β naming in the flow)
node scripts/stitch.mjs generate "prompt" --name concept-aName during editing (alias follows the new screen)
node scripts/stitch.mjs edit "changes" --name concept-a --forceName an existing screen manually
node scripts/stitch.mjs name concept-a --project Add a note
node scripts/stitch.mjs name concept-a --note "Karte als Fenster, Bottom Sheet"
Looking up screens
# Show screen details via alias or screen ID (fetches live data from Stitch API)
node scripts/stitch.mjs show concept-a
node scripts/stitch.mjs show bcde81e368e24edbabd6213d9dc17b3bResolve alias to screen ID only
node scripts/stitch.mjs resolve concept-aList all named screens in a project
node scripts/stitch.mjs namesList + verify against Stitch API (checks for deleted screens)
node scripts/stitch.mjs names --verify
Managing names
# Rename
node scripts/stitch.mjs rename concept-a map-startscreenRemove
node scripts/stitch.mjs unname old-concept
Naming rules
a-z, 0-9, hyphens. Case-insensitive.concept-a, home-v2, onboarding-flow, dark-variant-3--force to overwrite an existing aliasHow it works
state/projects//names.json (rebuildable snapshot)state/projects//events.jsonl (append-only, immutable)show will report it as broken; names --verify checks all at oncenames.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.
# Show all events for an alias (creates, edits, rebinds)
node scripts/stitch.mjs history concept-bShow a specific alias revision (Nth time it was bound to a screen)
node scripts/stitch.mjs history concept-b --rev 2Walk the edit/variant lineage DAG backwards from a screen
node scripts/stitch.mjs lineage concept-b
node scripts/stitch.mjs lineage abc123def456Rebuild names.json from event log (recovery)
node scripts/stitch.mjs rebuild --project
Event types:
generate / edit / variants β screen operations (with parentScreenId, promptPreview, runDir)alias_set / alias_renamed / alias_removed β alias pointer changesvariantGroupId to group related screensAgent workflow (MANDATORY)
When generating or editing screens for the user: 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 first
3. When editing a named screen, use --name --force to keep the alias pointing to the latest version
4. After every generate/edit/variants: run show , extract screenshotUrl, display via MEDIA: (see Image Delivery section)
5. Use names at session start to see what screens already existArtifacts
Every operation saves to runs/:
| File | Content |
|---|---|
| screen.html | Full HTML/CSS/JS of the screen |
| screen.png | 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 | runs/ | Immutable per-operation receipts: thumbnail, HTML, result.json |
| Event Log | state/projects/ | Append-only chronological record of all operations |
| Alias Pointers | state/projects/ | Current named references β rebuildable from event log |
Key principles:
runs/ are artifacts (never mutated, never deleted)state/ is the mutable layer (names.json is a snapshot, events.jsonl is append-only)names.json 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)screen.png) are low-res; always use screenshotUrl + =w780 for displaystate/ and runs/ are gitignored β they are local working state, not source codeCore Rules
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 β MEDIA:. 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):
# By alias
node scripts/stitch.mjs show concept-a
By screen ID (no alias needed)
node scripts/stitch.mjs show bcde81e368e24edbabd6213d9dc17b3b
β { "screenshotUrl": "https://lh3.googleusercontent.com/...=w780", ... }
Agent workflow for image display
After every generate/edit/variants:
1. With alias (preferred): run show β extract screenshotUrl from JSON β MEDIA:
2. Without alias: run show (accepts raw screen IDs too) β same flow
3. Last resort: get screenshotUrl from runs/, append =w780, display via MEDIA:
MEDIA:https://lh3.googleusercontent.com/...=w780
URL size suffixes
Google's lh3.googleusercontent.com URLs support size parameters:
=w780 β full mobile design width (default from show)=w1440 β full desktop design width=s2000 β max 2000px on longest sideSketch-to-Design Workflow
Stitch interprets hand-drawn sketches and wireframes well. The SDK has no image upload β but the workflow is:
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 β finds the screen by title in list_screens
4. Agent uses edit or variants on that screen to refine it
Limitations
pro (Gemini 3.1 Pro) and flash (Gemini 3.0 Flash). "Redesign/NanoBanana" from the Web UI = variants --range reimaginelist_screens newest; variants use delta-based recovery by comparing screen lists before and after the call)Flags Reference
| Flag | Commands | Values | Default |
|---|---|---|---|
| --device | generate, edit, variants | desktop, mobile, tablet, agnostic | desktop for generate; inherited from source for edit/variants |
| --model | 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/ 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.
π‘ Examples
Runtime Scope
STITCH_API_KEY onlyruns/, state/, latest-screen.jsonThe CLI is at scripts/stitch.mjs. All output is JSON on stdout.
node scripts/stitch.mjs [args] [--flags]
βοΈ Configuration
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.
# Install dependencies (one-time, from skill root)
cd scripts && npm install
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 shellECONNRESET / timeouts β Stitch API calls take 1-5 min; the CLI retries automaticallyCorrupt names.json β run node scripts/stitch.mjs rebuild --project to reconstruct from event log