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 stops and tells you to set it up.

What It Produces

Artifact	Path
Shared project config	.claude/docs/_project/stitch-project.json
Per-state screenshots	.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

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

Workflow

[USER INVOKES]
   │
   ├─ Project Init (only if stitch-project.json missing or incomplete)
   │     └ Creates shared Stitch project, design system, and shared Loading/Failed 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, write blueprint
   │
   └ [USER APPROVES DESIGN] → blueprint saved → DONE

Project Init (one-time per repo)

Run /ui-designer without a feature name when .claude/docs/_project/stitch-project.json doesn't exist or initState.completedAt is null. It creates:

• The shared Stitch project
• The shared design system (Tailwind config) from the KMPilot color/typography rules
• The shared Loading and Failed state screens (every feature reuses these IDs)

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 is a prerequisite — Phase 0 checks for stitch-project.json; if absent, you must run Project Init first.
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.

Error Handling

Error	Action
Stitch MCP not available	Stop, ask to configure the MCP server
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}
Loading: designs/{featurename}_loading.png (shared)
Failed: designs/{featurename}_failed.png (shared)
Project config: .claude/docs/_project/stitch-project.json

| State   | Screenshot |
|---------|------------|
| Success | designs/{featurename}.png |
| Loading | designs/{featurename}_loading.png (shared) |
| Failed  | designs/{featurename}_failed.png (shared) |
| Empty   | designs/{featurename}_empty.png |

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

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

To verify the implementation against the design:
- /verify-ui {featurename}

See Also

• Design-Pipeline — full design → implement → verify flow
• Verify-UI — what the audit checks
• Creating-KMP-Feature — design-aware Phase 0.5
• Modifying-KMP-Feature — design-aware step 2.5

Back to Skills