Proposal (parked): prototype-first design flow with Claude Design

[rterakedis]

Proposal: a prototype-first design flow for leanwheel (Claude Design era)

Status: assessment only — no skill, stub, or guide has been modified. Drafted 2026-08-01.
Origin: Project post-mortem — early SwiftUI mockups were built, then largely discarded once the
real data model (Core Data/CloudKit optionals, @fetchrequest reactivity, navigation state,
empty/error states) arrived. Durable outputs were the flow map and DESIGN.md; the prototype code
was not. The costly mistake was high fidelity arriving before information architecture had
hardened.

---

1. Verified capability baseline

Every capability claim below is sourced. Anything the docs don't establish is marked UNVERIFIED.

Claude Design (claude.ai surface, Anthropic Labs research preview)

Per Anthropic's announcement:

• Inputs: text prompts, images and documents (DOCX/PPTX/XLSX), codebase references, and a
  web-capture tool that grabs elements from a live site.
• Outputs: interactive prototypes (real HTML/CSS/JS, per
  VentureBeat)
  with shareable links ("organization-scoped sharing"); exports to Canva, PDF, PPTX, or
  standalone HTML.
• Design systems: "Claude builds a design system for your team by reading your codebase and
  design files," then applies it to subsequent projects; multiple systems supported.
• Handoff: "When a design is ready to build, Claude packages everything into a handoff bundle
  that you can pass to Claude Code with a single instruction." The bundle's format and contents
  are UNVERIFIED — no public doc enumerates what's in it.
• Fidelity controls: inline comments, direct text edits, "adjustment knobs" for spacing/color/
  layout. A dedicated wireframe-fidelity mode is UNVERIFIED — low-fi appears to be prompt
  discipline ("wireframe only, grayscale, no polish"), not a product switch.
• Availability: Pro, Max, Team, Enterprise (research preview; Enterprise needs admin
  enablement) — so the maintainer's Pro plan qualifies. Research-preview status matters for §6.

DesignSync (Claude Code side) — verified first-hand from the tool schema

The DesignSync tool exists in Claude Code today; its schema was inspected directly while writing
this proposal (stronger evidence than blog posts). What it actually is:

• A design-system project sync tool, "to keep a local component library in sync with a Claude
  Design project — incrementally, one component at a time, never as a wholesale replace," paired
  with a /design-sync skill.
• Read: list_projects (filtered to design-system-type projects the user can write to),
  get_project, list_files, get_file (≤256 KiB/file).
• Write: plan-gated — finalize_plan locks exact paths + a local source dir, then
  write_files/delete_files against that plan. Component preview cards via @dsCard markers.
• What it is not: a prototype importer. list_projects returns only
  PROJECT_TYPE_DESIGN_SYSTEM projects; a flow prototype living in a regular design project has
  no documented programmatic read path from Claude Code. The "handoff bundle" quoted above is
  a separate, claude.ai-initiated mechanism whose receiving-side mechanics are UNVERIFIED.

Third-party writeups (skills-hub.ai,
aicatchup.com) describe the
two-way loop consistently with the schema: pull the design system into design work, push built
components back. Treat those as corroboration, not authority.

Correction to the candidate flow's framing: "Claude Code has a DesignSync tool on the
receiving side [of the handoff bundle]" is half-true. DesignSync receives/pushes design
systems (token + component libraries). Nothing verified today lets a leanwheel skill fetch a
clickable flow prototype and diff against it.

---

2. The candidate flow, restated against leanwheel's shape

Candidate step	Nearest leanwheel artifact today
1. JTBD → flows → screen inventory as TEXT	/ux Step 4 Discovery (IA probe, protagonist walk) → EXPERIENCE.md flows
2. Wireframe-fidelity clickable prototypes to test flows	/ux Step 5 "Visual aids" (static inline HTML mocks — no click-testing today)
3. Raise fidelity → extract/refresh DESIGN.md	/ux Step 6 "Write spines"
4. (Swift) SwiftUI spikes for platform-idiom-risk screens	no home — closest is the Apple preset's HIG checklist [OPEN] items
5. Production views; prototypes as SPEC, not code	/create-story Design Contract → /dev-story → /design-verify

Two observations before the per-surface verdicts:

Leanwheel already has the human-driven-external-step pattern, and it's the right one. The
framework never pretends the agent can do what only the human can. Precedents: the epic-boundary
manual test pass (the boundary report instructs the human, waits, and /harvest-findings
later harvests the artifact the human produced); the MODEL SWITCH GATE (hard stop, human
acts in the UI, types "ready"); /epic-flywheel's commit-authorization ask. The pattern is
always: instruct → pause → harvest a durable artifact. A Claude Design pass fits this exactly:
the skill tells the human what to prompt and what to bring back, pauses, then harvests the
findings into DESIGN.md/EXPERIENCE.md. What the skill must never do is narrate pretend-driving a
claude.ai surface it cannot touch.

Step 1 needs no new artifact. A separate docs/ux/flows.md would create a second flow
document competing with EXPERIENCE.md — the same two-concepts problem the repo already killed
twice (smoke-suite vs flow; --screen vs --route). /ux Discovery already does
text-first IA ("walk a named protagonist through a real session"; "IA closes when every stated
need has a surface"). The candidate's step 1 is a sequencing discipline inside /ux, not a file.

---

3. Per-surface assessment

3.1 /ux — INTEGRATE (the load-bearing change)

This is where the entire candidate flow lands. /ux Step 5 already renders static HTML mocks "on
demand" to help the user decide; Claude Design is the escalation of that same move — from
look at a layout to click through a flow — and it arrives before Step 6 writes the spines,
which is exactly where an existing project needed it.

Sketch of the delta (extend Step 5; current text: "Render inline HTML when it would help the
user decide… Keep mocks simple — layout and color intent, not pixel-perfect production UI"):

Step 5b — Prototype pass (optional, human-driven, Claude Design)

When IA is non-trivial (≥4 surfaces, or any flow with branching/state the user is unsure
about), offer one click-testable prototype pass before writing spines. This runs on
claude.ai/design — a surface the user drives, not you. Instruct, pause, harvest:

1. Instruct. Give the user a paste-ready prompt: the flow list + screen inventory from
   Discovery, with an explicit fidelity cap — "wireframe fidelity: grayscale boxes and real
   copy, no color, no polish". High fidelity before IA hardens anchors everyone on pixels;
   the prototype's job is to falsify the flow map, nothing else.
2. Pause. "Click through it (share the link with anyone who'll use this). Come back with:
   flows that broke, screens missing/merged, copy that confused." Wait.
3. Harvest. Fold findings into the IA (Discovery notes / .decision-log.md). Only once
   flows survive click-testing, raise fidelity in Claude Design if useful — then Step 6
   extracts tokens/decisions into DESIGN.md as usual. Record the prototype's share link in
   EXPERIENCE.md under the flows it tested, marked reference, not contract.

The prototype is a thinking tool. Its durable outputs are the corrected flow map and the
DESIGN.md/EXPERIENCE.md that Step 6 writes. Prototype HTML is never imported as code. (Apple
platform: the prototype answers flow/IA/density/copy questions only — platform idiom is
resolved by Step 5c, not by a web mock.)

Plus, for the Apple preset only (candidate step 4):

Step 5c — Platform-idiom spikes (Apple preset, optional)

A web prototype cannot answer navigation feel, sheet/detent behavior, iPad
sidebarAdaptable, or Dynamic Type. If a screen's HIG checklist rows are [OPEN] because
of platform feel, propose a throwaway SwiftUI spike for that screen only: hardcoded data,
no persistence, never merged, deleted after the [OPEN] items resolve. Most projects need
zero or one.

Why this fits leanwheel: /ux runs a handful of times per project (create + occasional
update/validate), so its per-line token cost is the cheapest of any skill in this proposal; the
step is offered, not mandatory (no ceremony — trivial IA skips it, matching the
stateful/simple scaling precedent in /create-story); and it changes no artifact contract —
DESIGN.md/EXPERIENCE.md remain the only things downstream skills read.

Recorded as a deliberate divergence in .claude/skills/CLAUDE.md under the existing ### ux
entry (upstream BMAD has no equivalent; survives sync by the normal mechanism).

3.2 /next — REJECT (new state detection), with a narrow DEFER

The proposed state — "flows exist but untested / DESIGN.md missing" — decomposes into:

• DESIGN.md missing: row 5 already routes prd + UI surfaces + no DESIGN.md → /ux. Since the
  prototype pass lives inside /ux (§3.1), this routing already delivers the user to it. No
  change needed.
• Flows exist but untested: /next is deterministic by design — "existence checks +
  frontmatter greps only… never read planning-doc contents." "Untested" is not a file-presence
  fact; detecting it would require either reading EXPERIENCE.md (breaks the zero-token rule) or a
  new stamp (a third marker alongside readiness-check/retro:, written by a human-driven step
  the agent can't observe completing). A marker that exists to route to an optional step fails
  the "exactly one NEXT" discipline.

DEFER: if a future /ux divergence writes a cheap machine-readable line (e.g.
prototype-tested: {date|skipped} in EXPERIENCE.md frontmatter), row 5 could grow a one-line
optional branch at near-zero cost. Evidence bar: two or more real projects where the prototype
pass was skipped and that skip caused rework /next could have prevented.

3.3 Flywheels (/epic-flywheel, /story-flywheel) — REJECT

A existing project's "JTBD / convergence mapping precedes IA-touching epics" rule does not belong in the
flywheels, for three reasons:

1. The gate already exists, upstream of the flywheels, at the right choke point.
   /check-readiness Check 9 blocks: UI stories with no EXPERIENCE.md surface coverage
   (blocker), unresolved [OPEN] HIG items (blocker for affected stories), non-final design
   status (warning), missing tokens (blocker). That is "do tested flows + DESIGN.md exist for
   the screens this epic adds?" — enforced once per phase at planning time, where fixing it is
   cheap, rather than re-litigated at every epic start.
2. Flywheel gates are deterministic; this one isn't. Every epic-flywheel boundary gate is a
   zero-token shell check or a short recorded-block read. "Are these flows tested?" is a
   judgment call. Putting a judgment gate at epic start would be the first non-deterministic gate
   in the loop — and the epic-context-cache episode showed the gates that work are [ -f … ]
   checks, not vibes.
3. The project-convention channel already carries it. An existing project's rule lives in that project's
   CLAUDE.md — put there by exactly the mechanism leanwheel prescribes (/retrospective Q7
   promotes conventions into project CLAUDE.md). A convention proven on one project graduates to
   the framework when it recurs; one data point is a project rule, not a framework rule.

Small INTEGRATE adjacent to this (optional): one warning-grade clause appended to Check 9 —
"Flows for this epic's new surfaces were click-tested (prototype reference in EXPERIENCE.md) or
explicitly skipped — silent omission = warning." Two lines, warning not blocker, loaded only in
/check-readiness (1–2 runs per phase). This gives the maintainer the audit trail without gating
anything.

3.4 /design-verify — DEFER

Could it verify against a Claude Design prototype or handoff bundle? Not today, honestly:

• No programmatic path. From the DesignSync schema (verified first-hand): Claude Code can
  read files only from design-system-type projects. A flow prototype in a regular design
  project is not listable or fetchable. The handoff bundle's contents are UNVERIFIED — there is
  nothing documented for /design-verify to diff against.
• It would create a second source of truth. /design-verify compares rendered UI against
  DESIGN.md tokens and EXPERIENCE.md states — the contract. Verifying against prototype pixels
  makes the prototype a parallel contract, which is precisely the project lesson inverted:
  prototypes are thinking tools; the spec of record is the spines. (The candidate flow's step 5
  phrase "prototypes treated as SPEC" is resolved the same way: the prototype is spec-shaped
  input to the spines, and a human-readable reference thereafter — see §3.5 — never the machine
  contract.)

Evidence that would reopen this: Anthropic documents the handoff bundle format and it
contains machine-readable tokens/states (not just HTML); or DesignSync grows a read path to
prototype projects. Then the cheap move is a ### Design Contract provenance line, not a new
verification source.

One genuinely useful DesignSync fit worth naming (out of this proposal's scope): pushing a
leanwheel project's docs/ux/components-built.md inventory to a Claude Design design-system
project, so future prototypes are built from the real components. That is what the tool is
actually for. DEFER until a real project wants it; it would be a new composable op, not a change
to existing skills.

3.5 /create-story Design Contract — INTEGRATE (two lines)

If EXPERIENCE.md records a prototype link for a story's surfaces (§3.1 harvest step), the Design
Contract extraction should carry it:

Sketch — add to "Design contract extraction (UI stories with docs/ux/)" item 2's extraction
list:

• A prototype reference, if EXPERIENCE.md records one for these surfaces — as a link labeled
  reference, not contract: tokens and states above are what dev implements and
  design-verify checks; the prototype is for human orientation only.

Cost discipline: /create-story is the highest-multiplier skill in this proposal (runs once per
story, and its extracted contract is re-read by dev + review). Two lines in the skill, one line
in the emitted contract, and only when a prototype reference exists. The subordination clause is
the important part — it prevents a dev session or reviewer from treating prototype HTML as
authoritative over tokens.

3.6 Track differences and stubs — REJECT new stubs; guidance rides /ux presets

Where Swift and web genuinely diverge:

	Swift track	Web track (Astro/Hugo/app)
What the prototype answers	flow, IA, density, copy, visual direction	nearly everything — same medium as the product
What it can't answer	navigation feel, sheets/detents, sidebarAdaptable, Dynamic Type	little; mainly perf budget + real content behavior
Extra step	Step 5c SwiftUI spikes (idiom-risk screens only)	none — but note the temptation below

The right carrier for this divergence is the /ux platform presets, which is where every
other per-track design rule already lives (Apple preset HIG rules, SSG performance-budget rules).
Step 5c is the Swift-track guidance; the web track needs only one caution line in the web/SSG
presets: "Claude Design emits generic HTML/CSS — its markup is not Astro/Hugo template code and
its styles are not your token system; the handoff is a reference like any prototype, and Step 6's
DESIGN.md remains the contract." Direct HTML reuse is the web-track version of
fidelity-too-early: tempting because the medium matches, wrong because the durable artifact is
still the token system.

Why not docs/setup/* stubs (refresh-swift/refresh-web outputs): those files carry
externally-sourced platform facts on a research-refresh cycle (Baseline CSS, Swift
concurrency, HIG mechanics) — content /refresh-* re-derives from gold-standard sources and
docs-sync DRIFT is forbidden to touch. "Prototype before IA hardens" is process, has no
external source to refresh against, and would be the only process content in those files. It
belongs in the skill that runs the process. Also: stubs load into dev sessions
(/dev-story step 4 routing) — dev sessions never need prototyping guidance, so stub placement
would pay tokens at exactly the wrong time. REJECT; revisit only if a platform fact emerges
(e.g. Apple publishes prototype-to-SwiftUI tooling worth documenting — then it's refresh-swift
material by nature).

---

4. Constraint check

• Token economy: total proposed core-skill delta ≈ 30 lines, all in low-frequency skills
  (/ux, /check-readiness) except two lines in /create-story. Nothing added to flywheels,
  dev-story, code-review, or stubs — the per-story hot path stays flat. Estimates in §5b.
• Stack-agnostic core, per-track in presets: the only track-specific text (Step 5c, web
  caution line) lives inside /ux's existing preset blocks, matching how every current
  per-track rule is carried.
• No activation ceremony: every proposed step is offered on a signal (non-trivial IA,
  [OPEN]-for-idiom items, existing prototype reference) and skippable in one line. No new
  commands, no new required artifacts, no new markers.
• Upstream-BMAD sync survival: all three INTEGRATE items are divergences to existing entries
  in .claude/skills/CLAUDE.md (### ux, ### create-story, ### check-readiness) — the same
  recording mechanism every prior divergence uses. Upstream BMAD has no Claude Design equivalent
  to collide with.
• Research-preview risk (the one real argument for waiting): Claude Design is an Anthropic
  Labs preview; its mechanics may churn. Mitigation baked into the sketches: all
  product-specific content sits in the human-facing instruction text of one optional step, and
  no skill depends on any Claude Design mechanism programmatically (that's why §3.2 and §3.4 are
  REJECT/DEFER). If the product changes, one step's prose changes; nothing structural does.

---

5. Shortlist, costs, open questions

5a. Ranked shortlist (if only these were made)

1. /ux Step 5b prototype pass + Step 5c Apple spikes (§3.1) — the whole project lesson
   lands here or nowhere: low-fi click-testing before spines are written, via the established
   instruct → pause → harvest pattern. Everything else in this proposal is reinforcement.
2. /create-story prototype-reference line (§3.5) — two lines that keep the prototype
   visible to humans downstream while explicitly subordinating it to the token contract;
   prevents the "prototype as second source of truth" failure mode from ever starting.
3. /check-readiness Check 9 click-tested warning (§3.3) — the audit trail without a gate;
   makes a silent skip visible once per phase at near-zero cost.

5b. Estimated token cost per affected skill

Skill	Delta	Rough cost/invocation*	Invocations/project	Verdict on cost
/ux	+22–28 lines	~300–400 tok	2–4	negligible — cheapest possible home
/create-story	+2–3 lines (+1 line in emitted contracts)	~40 tok	once per story (15–40)	the multiplier to watch; kept minimal
/check-readiness	+2 lines	~30 tok	1–2 per phase	negligible
/next, flywheels, /design-verify, stubs	0	0	—	deliberately untouched

*Rule of thumb ~13–15 tok/line of skill prose; loaded only when that skill is invoked.

5c. Open questions for the maintainer

1. Is the pause worth it on your solo projects? The prototype pass shines when a share link
   gets clicked by someone who isn't the author. Solo, the honest question is whether
   click-testing your own wireframes falsifies flows better than /ux's protagonist walk
   already does. If not, Step 5b's offer threshold should be stricter (multi-user flows only?).
2. Wireframe fidelity is prompt discipline, not a verified product mode. If Claude Design
   resists staying low-fi (UNVERIFIED either way), does the anchoring guard need stronger
   wording, or is "grayscale boxes, real copy" enough in practice? One project-successor trial
   would answer this.
3. Adopt now or after the preview stabilizes? The sketches are churn-resistant (§4), but if
   you'd rather not reference a Labs product by name in a shipped skill, Step 5b can be written
   product-neutrally ("any clickable-prototype tool; currently Claude Design") at the cost of a
   little vagueness.
4. The DesignSync component-library push (§3.4, out of scope here): worth a future
   composable op that publishes components-built.md + tokens to a design-system project so
   later prototypes use your real components? That's the verified, durable half of the two-way
   loop — but it earns its place only when a real project runs the prototype pass twice.
5. Retro checkbox or not? Should /retrospective's Next Epic Readiness ask "did this epic's
   UI surfaces exist in EXPERIENCE.md before dev, or were they improvised?" — the retro-side
   mirror of Check 9. Left out of the shortlist because it's a second copy of an existing gate,
   and the epic-context-cache episode taught that unowned retro checkboxes rot.

---

Sources

• Introducing Claude Design by Anthropic Labs — capabilities, handoff-bundle quote, availability
• VentureBeat — Anthropic launches Claude Design — HTML/CSS/JS output
• DesignSync tool schema, inspected first-hand in Claude Code (2026-08-01) — sync semantics, project-type restriction, plan gating
• skills-hub.ai — /design-sync two-way bridge, aicatchup.com — design-sync workflow — corroboration only
• Claude Design tutorial (claude.com), Claude Help Center — Get started with Claude Design — general usage reference

[rterakedis]

I would argue these are Open questions for anyone using Leanwheel-Skills:

1. Is the pause worth it on your solo projects? The prototype pass shines when a share link
   gets clicked by someone who isn't the author. Solo, the honest question is whether
   click-testing your own wireframes falsifies flows better than /ux's protagonist walk
   already does. If not, Step 5b's offer threshold should be stricter (multi-user flows only?).
2. Wireframe fidelity is prompt discipline, not a verified product mode. If Claude Design
   resists staying low-fi (UNVERIFIED either way), does the anchoring guard need stronger
   wording, or is "grayscale boxes, real copy" enough in practice? One project-successor trial
   would answer this.
3. Adopt now or after the preview stabilizes? The sketches are churn-resistant (§4), but if
   you'd rather not reference a Labs product by name in a shipped skill, Step 5b can be written
   product-neutrally ("any clickable-prototype tool; currently Claude Design") at the cost of a
   little vagueness.
4. The DesignSync component-library push (§3.4, out of scope here): worth a future
   composable op that publishes components-built.md + tokens to a design-system project so
   later prototypes use your real components? That's the verified, durable half of the two-way
   loop — but it earns its place only when a real project runs the prototype pass twice.
5. Retro checkbox or not? Should /retrospective's Next Epic Readiness ask "did this epic's
   UI surfaces exist in EXPERIENCE.md before dev, or were they improvised?" — the retro-side
   mirror of Check 9. Left out of the shortlist because it's a second copy of an existing gate,
   and the epic-context-cache episode taught that unowned retro checkboxes rot.