UI Designer

UI Designer Skill

Design UI screens in Google Stitch and produce a Compose Implementation Blueprint plus persisted HTML + token inventories. ui-designer is a design-only skill — it never writes Compose code or invokes another skill.

Invocation:

/ui-designer                # one-time project init
/ui-designer myfeature      # design (or resume) a feature

Requires:

• The Stitch MCP server. If it's not configured the skill runs a guided setup and stops — you must configure it and restart Claude Code before continuing.
• Python 3 on PATH. A tooling preflight (python3 --version) runs before any other work; the skill extracts design tokens via extract_tokens.py and generates the icons/images manifests via download_assets.py. If Python 3 is missing the skill stops with install instructions.

What It Produces

Artifact	Path
Shared project config	.claude/docs/_project/stitch-project.json
Per-state screenshots (selected states only)	.claude/docs/{featurename}/designs/{featurename}_{state}.png
Design spec	.claude/docs/{featurename}/designs/{featurename}.md
Compose Implementation Blueprint	.claude/docs/{featurename}/designs/{featurename}_blueprint.md
Raw HTML per state	.claude/docs/{featurename}/designs/extracted/stitch_{state}.html
Token inventories per state	.claude/docs/{featurename}/designs/extracted/tokens_{state}.md
Icons manifest	.claude/docs/{featurename}/designs/extracted/icons.json
Images manifest	.claude/docs/{featurename}/designs/extracted/images.json

The blueprint references project-wide rules (patterns.md, m3-colors.md, X_COMPONENTS_CATALOG.md) rather than restating them.

Workflow

[USER INVOKES]
   │
   ├─ Tooling Preflight (python3 --version) — must pass first
   │
   ├─ Project Init (auto-runs if stitch-project.json missing or initState.completedAt null)
   │     └ Creates shared Stitch project + design system. Does NOT create shared screens.
   │
   ├─ Phase 0: Preflight
   │     └ Verify MCP, resolve feature context, register or resume the feature in the shared project
   │
   ├─ Phase 1: Design
   │     └ Generate / iterate screens, export approved designs as screenshots,
   │       extract HTML + tokens, generate icons/images manifests, write blueprint
   │
   └ [USER APPROVES DESIGN] → blueprint saved → DONE

Project Init (one-time per repo)

Runs automatically when .claude/docs/_project/stitch-project.json doesn't exist or initState.completedAt is null — Phase 0 preflight bootstraps it. You may also run /ui-designer without a feature name to trigger it explicitly. It creates:

• The shared Stitch project
• The shared design system (Tailwind config) discovered from the project's XTheme.kt color/typography roles

It does NOT create the shared Loading/Failed screens. Those are designed lazily by the first feature that opts into them (Phase 1), then reused by every later feature. See Design-Pipeline → Optional States.

Critical Rules

1. User confirmation required after Phase 1 (design approval).
2. All design changes go through Stitch — never edit designs outside the Stitch MCP tools.
3. Screenshots live at .claude/docs/{featurename}/designs/ (committed, visible to user).
4. Single config architecture — all Stitch state lives in stitch-project.json. There are no per-feature stitch.json files.
5. Stitch MCP is mandatory — stop and ask the user to configure it if missing.
6. Blueprint is the handoff artifact — contains Pre-Implementation Contract + Post-Implementation Checklist. Consumed via blueprintConsumed flag.
7. blueprintConsumed lifecycle — ui-designer sets false when saving; implementation skills set true after consuming.
8. M3 Color Roles Only — every color must map to an M3 role defined in XTheme.kt's XLightColors/XDarkColors. The Color Audit identifies missing roles and lists them in the blueprint's Pre-Implementation Contract.
9. Project Init auto-runs when needed — Phase 0 checks for stitch-project.json; if absent or initState.completedAt is null, Init runs automatically, then Phase 0 resumes. You can also invoke it explicitly with no feature-name argument.
10. Cross-Screen Chrome Consistency — shared chrome (top app bar style, bottom nav, screen background) is captured from existing approved features and injected as a "Shared Conventions" block unless you explicitly ask for different chrome.
11. Optional states — user-selected, lazily designed — only success is mandatory. Loading/Failed are opt-in and shared (designed lazily by the first opter-in, reused thereafter). Empty is opt-in and offered only for list-based features. Selections are stored at features[featurename].states; skipped states get no screenshot, no token inventory, and a "Skipped" marker in the blueprint.

Error Handling

Error	Action
Stitch MCP not available	Run the guided setup, then stop — the user must configure the MCP server and restart Claude Code before the skill can continue
Stitch generation times out / connection reset	Do NOT retry — the generation often succeeded server-side. Open https://stitch.withgoogle.com/projects/{projectId} in browser to trigger sync, then list_screens finds the new screen.
Generation fails with non-timeout error	Retry with refined prompt, max 3 attempts
Stitch project not found	Auto-create
stitch-project.json not found	Run Project Init first (no feature name argument)

Completion Report

## UI Designer Complete: {FeatureName}

Stitch Project ID: {projectId} (shared)
Design System ID: {designSystemAssetId}
Project config: .claude/docs/_project/stitch-project.json

# One row per SELECTED state only — Success always; others only if states.{state} == true
| State   | Screenshot |
|---------|------------|
| Success | designs/{featurename}.png |
| Loading | .claude/docs/_shared/designs/loading.png (shared) |  ← only if states.loading
| Failed  | .claude/docs/_shared/designs/failed.png (shared)  |  ← only if states.failed
| Empty   | designs/{featurename}_empty.png                    |  ← only if states.empty

States selected: success[, loading][, failed][, empty]
States skipped (no design reference): {list, or "none"}

Design spec: designs/{featurename}.md
Blueprint:   designs/{featurename}_blueprint.md
blueprintConsumed: false

## Next Steps
- New feature       → /creating-kmp-feature {featurename}
- Existing feature  → /modifying-kmp-feature {featurename}
- Then verify       → /verify-ui {featurename}

See Also

• Design-Pipeline — full design → implement → verify flow
• Verify-UI — what the audit checks
• Creating-KMP-Feature — design-aware Design Artifact Detection
• Modifying-KMP-Feature — design-aware Design Artifact Detection

Back to Skills