🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
πŸ¦€ ClawHub

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

Versionv1.2.3
Downloads1,041
Stars⭐ 2
TERMINAL
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 shell
  • ECONNRESET / timeouts β†’ Stitch API calls take 1-5 min; the CLI retries automatically
  • Corrupt names.json β†’ run node scripts/stitch.mjs rebuild --project 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  [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  "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 explore

    More conservative: refine only

    node scripts/stitch.mjs variants "tighten the spacing" --count 2 --range refine

    Target specific aspects

    node scripts/stitch.mjs variants "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 
    

    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:

  • 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


    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 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  "prompt" --name concept-a

    Name during editing (alias follows the new screen)

    node scripts/stitch.mjs edit "changes" --name concept-a --force

    Name 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 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//names.json (rebuildable snapshot)
  • Every operation is recorded in state/projects//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

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


    Artifacts

    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//events.jsonl | Append-only chronological record of all operations | | Alias Pointers | state/projects//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 β†’ 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/

    /result.json, 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 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 β†’ 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/.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.

    πŸ’‘ Examples

    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  [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 shell
  • ECONNRESET / timeouts β†’ Stitch API calls take 1-5 min; the CLI retries automatically
  • Corrupt names.json β†’ run node scripts/stitch.mjs rebuild --project to reconstruct from event log