Design Pipeline

Design Pipeline

KMPilot pairs UI design and implementation through a three-skill pipeline that communicates through a single artifact — the Compose Implementation Blueprint — and a single config file.

┌────────────────┐    ┌────────────────────┐    ┌─────────────┐
│  /ui-designer  │ ─▶ │ /creating-kmp or   │ ─▶ │ /verify-ui  │
│                │    │ /modifying-kmp     │    │             │
│ Stitch design  │    │ (design-aware     │    │ HTML ↔ Code │
│ → blueprint    │    │ mode)             │    │ token audit │
└────────────────┘    └────────────────────┘    └─────────────┘
       │                       │                       │
       ▼                       ▼                       ▼
  stitch-project.json   blueprintConsumed=true   features[*].verification

Each skill is independently invocable — no skill calls another skill. You drive the pipeline.

The Blueprint Contract

File	Owner	Role
.claude/docs/_project/stitch-project.json	ui-designer (init), all three skills (update)	Single source of truth for Stitch projectId, shared state-screen IDs, per-feature screen IDs, design-system ID, blueprintConsumed flag, and verification record.
.claude/docs/{featurename}/designs/{featurename}_blueprint.md	ui-designer writes, implementation skills read	The Compose Implementation Blueprint: Pre-Implementation Contract (Color Audit + Component Overrides) + Component Tree + Post-Implementation Checklist.
.claude/docs/{featurename}/designs/extracted/stitch_{state}.html	ui-designer downloads, verify-ui reuses	Raw Stitch HTML for success / loading / failed / empty states. Stitch URLs are single-use, so files are persisted.
.claude/docs/{featurename}/designs/extracted/tokens_{state}.md	ui-designer extracts, verify-ui reuses	Token inventory produced by extract_tokens.py (Tailwind class → dp/sp/color/% conversion).
.claude/docs/{featurename}/designs/{featurename}_audit.md	verify-ui	Audit report (mismatch blocks only, no OK rows).

blueprintConsumed lifecycle

1. ui-designer writes a new blueprint → sets features[featurename].blueprintConsumed = false.
2. Implementation skill (/creating-kmp-feature or /modifying-kmp-feature) detects the unconsumed blueprint, enters design-aware mode, implements the design, and finally sets blueprintConsumed = true.
3. verify-ui does not read the blueprint's token data — by the time it runs, the blueprint has done its job; the audit's design ground truth is the HTML. The one blueprint section verify-ui consults is the Component Overrides table in Pre-Implementation Contract.

Design-Aware Mode

When an implementation skill (/creating-kmp-feature or /modifying-kmp-feature) starts, it runs a Design Artifact Detection step:

Blueprint file?	blueprintConsumed	Mode
Yes	false	Design-aware — blueprint drives UI layer
Yes	true	Normal mode
No	N/A	Normal mode

In design-aware mode the implementation skill:

1. Updates XTheme.kt — adds every missing M3 color role from the blueprint's Color Audit to both XLightColors and XDarkColors.
2. X-Component Constraint Check — for every X-component the blueprint uses, reads the full source file of the matching X*.kt, catalogs defaultMinSize, hardcoded padding, default colors, and decides each override resolution before writing code.
3. Implements the blueprint's Component Tree using MaterialTheme.colorScheme.* (never raw Color() hex).
4. Walks the Post-Implementation Checklist in the blueprint before declaring done.
5. Marks blueprintConsumed: true in stitch-project.json.

Shared State Screens

ui-designer Project Init creates shared Loading and Failed screens once per project. Every feature reuses these IDs — there's only one Loading screen and one Failed screen for the entire project. The IDs live at stitch-project.json.sharedStateScreens.{loading,failed}.screenId.

Cross-Screen Chrome Consistency

When designing a new feature, ui-designer snapshots the existing approved features' chrome (top app bar, bottom nav, screen background) and injects a "Shared Conventions" block into the Stitch generation prompt. The chrome only changes if the user explicitly asks for it.

End-to-End Example

# 1. Design
/ui-designer myfeature
# user approves designs in Stitch
# → .claude/docs/myfeature/designs/myfeature_blueprint.md
# → stitch-project.json: features.myfeature.blueprintConsumed = false

# 2. Implement
/creating-kmp-feature
# Phase 0.5 detects the blueprint
# Phase 3 implements design-aware
# → stitch-project.json: features.myfeature.blueprintConsumed = true

# 3. Verify
/verify-ui myfeature
# HTML ↔ Code token audit + X-components compliance
# → .claude/docs/myfeature/designs/myfeature_audit.md
# → stitch-project.json: features.myfeature.verification = { verified: true, ... }

Why It's Decoupled

Each skill is a self-contained tool with a clear contract on the shared artifacts. You can:

• Skip ui-designer for features without a custom design.
• Re-run creating-kmp-feature later against the same blueprint (re-set blueprintConsumed: false).
• Run verify-ui after every modification without re-running design.
• Mix and match — the design pipeline is opt-in.

See Also

• UI-Designer — Phase-by-phase Stitch workflow
• Verify-UI — Token audit + X-components compliance details
• Creating-KMP-Feature — Design-aware Phase 0.5
• Modifying-KMP-Feature — Design-aware step 2.5

Back to Home