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

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

```bash
# 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.

```bash
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**

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

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

```bash
# 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**

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

This returns all screen IDs + titles.

**Step 2 — Export screenshots for each screen**

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

```bash
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

```bash
# 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`