Stitch Design

Official Google Stitch SDK wrapper for OpenClaw. Requires only STITCH_API_KEY. Generate UI screens from text, apply targeted edits, branch variants, export H...

Security Scan

The skill's files, declared requirements, and runtime instructions are consistent with a Google Stitch SDK CLI wrapper that only needs STITCH_API_KEY and Node; nothing obvious is requesting unrelated credentials or surprising network endpoints.

Purpose & Capability

Name/description claim an official Google Stitch SDK wrapper and the package requests only a STITCH_API_KEY and Node — which matches the expected needs of a Stitch CLI. The code modules (download, artifacts, events, names, design-system) implement local artifact storage, event logging, aliasing, and restricted local design-system loading; these are coherent with the stated features (generate/edit/variants, export, local artifacts). No unrelated cloud credentials or binaries are required.

Instruction Scope

SKILL.md instructs running the bundled Node CLI (node scripts/stitch.mjs), installing Node dependencies in scripts/, and declares network access only to Google Stitch APIs and Google-hosted screenshot URLs. The code shows local writes are limited to runs/, state/, and latest-screen.json as documented. The design-system loader only reads markdown from the local design-systems/ directory and validates slugs. I saw no instructions to read other system files or to send data to endpoints outside the Stitch/CDN ecosystem.

Install Mechanism

There is no formal install spec in the registry (instruction-only), but SKILL.md requires running `cd scripts && npm install`, which will pull @google/stitch-sdk and transitive npm packages. This is expected for an SDK wrapper but introduces the usual npm-supply-chain risk (moderate). There are no arbitrary URL downloads or obscure extract/install steps in the provided files.

Credentials

Only STITCH_API_KEY is declared as required and is used as the primary credential (SDK uses X-Goog-Api-Key). No other SECRET/TOKEN/PASSWORD env vars are requested. Local state and artifacts are written under the skill's folders. The code does not appear to require unrelated credentials or config paths.

Persistence & Privilege

The skill is not force-enabled (always:false) and does not request elevated platform privileges. It persists only its own artifacts (runs/, state/, latest-screen.json) and does not modify other skills or system-wide config. Autonomous model invocation is allowed (default) but is not combined with other concerning privileges.

Assessment

This skill appears to be what it says: a Node CLI wrapper around Google Stitch that needs only STITCH_API_KEY and writes artifacts under its own folders. Before installing: 1) Confirm the STITCH_API_KEY you supply is limited for Stitch usage (do not reuse high-privilege keys); rotate it if you stop using the skill. 2) Run the `npm install` step in an environment you control (or inspect the scripts/package.json first) because it will pull @google/stitch-sdk and transitive packages. 3) If you want higher assurance, review the main CLI (scripts/stitch.mjs) before use — my assessment used the modules shown but that file is large and not fully included above. 4) Expect the agent to contact stitch.googleapis.com and Google CDN screenshot URLs and to save HTML/PNG and JSON locally under the skill directory. 5) If you have strict network/data policies, run the skill in an isolated environment or container. If you want, I can inspect the full scripts/stitch.mjs for any unexpected network endpoints or behaviors to raise confidence to high.

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 shell
• ECONNRESET / timeouts → Stitch API calls take 1-5 min; the CLI retries automatically
• Corrupt names.json → 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/, latest-screen.json
• No extra services, daemons, browser automation, or unrelated credentials required

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

node scripts/stitch.mjs <command> [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:

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

Step 2 — Generate

node scripts/stitch.mjs generate <project-id> "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 <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.

node scripts/stitch.mjs edit <screen-id> "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 <screen-id> "make it feel more premium" --count 3 --range explore

# More conservative: refine only
node scripts/stitch.mjs variants <screen-id> "tighten the spacing" --count 2 --range refine

# Target specific aspects
node scripts/stitch.mjs variants <screen-id> "new color direction" --aspects color_scheme,text_font

Creative ranges:

• refine — small changes, stays close to original
• explore — moderate exploration (default)
• reimagine — 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

node scripts/stitch.mjs info <project-id>

This returns all screen IDs + titles.

Step 2 — Export screenshots for each screen

node scripts/stitch.mjs image <screen-id> --project <project-id>

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.

node scripts/stitch.mjs export <screen-id> --project <project-id>
# or just HTML:
node scripts/stitch.mjs html <screen-id>
# or just screenshot:
node scripts/stitch.mjs image <screen-id>

---

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:

• 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

# List all projects
node scripts/stitch.mjs projects

# Create a new project
node scripts/stitch.mjs create "App Name"

# Show project screens
node scripts/stitch.mjs info <project-id>

---

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

# Name during generation (recommended — naming in the flow)
node scripts/stitch.mjs generate <project-id> "prompt" --name concept-a

# Name during editing (alias follows the new screen)
node scripts/stitch.mjs edit <screen-id> "changes" --name concept-a --force

# Name an existing screen manually
node scripts/stitch.mjs name concept-a <screen-id> --project <id>

# Add a note
node scripts/stitch.mjs name concept-a <screen-id> --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 bcde81e368e24edbabd6213d9dc17b3b

# Resolve alias to screen ID only
node scripts/stitch.mjs resolve concept-a

# List all named screens in a project
node scripts/stitch.mjs names

# List + 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-startscreen

# Remove
node scripts/stitch.mjs unname old-concept

Naming rules

• Slugs only: lowercase a-z, 0-9, hyphens. Case-insensitive.
• Examples: concept-a, home-v2, onboarding-flow, dark-variant-3
• 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.

# Show all events for an alias (creates, edits, rebinds)
node scripts/stitch.mjs history concept-b

# Show a specific alias revision (Nth time it was bound to a screen)
node scripts/stitch.mjs history concept-b --rev 2

# Walk the edit/variant lineage DAG backwards from a screen
node scripts/stitch.mjs lineage concept-b
node scripts/stitch.mjs lineage abc123def456

# Rebuild names.json from event log (recovery)
node scripts/stitch.mjs rebuild --project <id>

Event types:

• generate / edit / variants — screen operations (with parentScreenId, promptPreview, runDir)
• alias_set / 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. 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
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/<timestamp>/	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)
• 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)
• Local thumbnails (screen.png) are low-res; always use screenshotUrl + =w780 for display
• state/ and runs/ are gitignored — they are local working state, not source code

---

Core 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 <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):

# 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 <alias> → extract screenshotUrl from JSON → MEDIA:<url>
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 MEDIA:<url>

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 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. 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 list_screens
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 = variants --range reimagine
• 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
--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/<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.