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/extracted/icons.json	ui-designer generates (manifest), implementation materializes XMLs, verify-ui audits	Icons manifest produced by download_assets.py --type icons. Drives icon-XML materialization in design-aware mode and the Icons Manifest Audit in verify-ui.
.claude/docs/{featurename}/designs/extracted/images.json	ui-designer generates (manifest), implementation materializes assets, verify-ui audits	Images manifest produced by download_assets.py --type images. Drives raster-asset materialization and the Images Manifest Audit.
.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.

Optional States & Shared State Screens

Only the success state is mandatory per feature. Loading / Failed / Empty are user-selected at design time:

• Loading / Failed — opt-in, and shared across the whole project. Project Init does not generate them; they're designed lazily by the first feature that opts in, then every later feature reuses the same IDs (stitch-project.json.sharedStateScreens.{loading,failed}.screenId).
• Empty — opt-in and only offered for list-based features; designed per-feature.
• Skipped states get no design reference: no screenshot, no token inventory. The blueprint marks them "Skipped". Implementation still handles all four UI states (Rule 4) — just without a design to match.

The selected states are recorded at stitch-project.json.features[featurename].states = { loading, failed, empty }. verify-ui audits only the states that are true.

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
# Design Artifact Detection finds the blueprint
# Implementation runs 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 Design Artifact Detection (Phase 1)
• Modifying-KMP-Feature — Design-aware Design Artifact Detection

Back to Home