Spec-driven UI
AIUP already drives development from vision.md to working code, but the pipeline has no step for UI/UX — /implement generates views with business logic already wired in. We propose a separate, parallel track: from use case to an approved, fully-looking, clickable prototype — before anyone writes a single line of real screen code.
Doesn't touch the existing pipeline
This track runs alongside entity modeling, other use cases, and migrations — none of them need to be finished first. It has one prerequisite: the target use case's own spec (UC-XXX.md, from core AIUP's /use-case-spec) already has to exist. It meets the AIUP core again at exactly one point: /implement starts working on UI that's already scaffolded, instead of generating it from scratch.
How it works
The diagram shows the flow — from the spec interview, through human approval of the mockup, to real code. The labels under each arrow show exactly what gets handed off at each step.
Steps 1–3 need only use_cases.puml (core AIUP /use-case-diagram); step 4 needs that specific UC's own spec (/use-case-spec) ↓
Step 1, in practice
Illustrative only — the exact question script for /ui-interview isn't written yet (see open questions below). This is the interaction pattern we're aiming for: one question at a time, multiple-choice where possible, freeform where it isn't.
$ /ui-interview
AIUPLet's define the visual style. How should the interface feel?
1 · Clean, minimal, lots of whitespace
2 · Dense, corporate, data-heavy
3 · Playful, friendly, rounded shapes
4 · Something else — describe it
You1
AIUPClean and minimal, got it. For lists of records — reservations, guests — tables or cards?
YouTables — staff need to scan many rows fast.
AIUPDo you have any reference screenshots, links, or a folder of inspiration I should look at?
YouYeah — ./inspiration/ has three screenshots I like.
AIUPGot it, reviewed all three — using them alongside your answers.
AIUPOne more: which stack should the real implementation target?
1 · React + Tailwind
2 · React + shadcn/ui
3 · Vue + Vuetify
4 · Vaadin (Java)
5 · Other — describe it
You4
→ writing docs/ui/style.md ... done
Illustrative transcript — exact question script not yet defined
Mechanism
A mockup is generated one use case at a time — following AIUP's "one UC per session" principle. So it doesn't end up feeling like a pile of disconnected documents, every screen gets two layers of navigation.
On the left: a navigation panel present on every mockup, organized into the menu sections defined by /ui-navigation's sitemap (falls back to a flat per-actor list if that step hasn't run yet). On the right: a specific action button wired to the actual target screen, taken from the "Navigation" table in the UC spec — not just to the generic menu.
Guest picks dates and party size, browses available rooms.
ReserveScope
Steps 4 and 6 accept a scope, so one command can target a single use case, several, or the whole sitemap — instead of one command per UC.
--all means something different for each command
For /ui-mockup, --all covers every use case in the sitemap — mockups are cheap to iterate and still need approval before anything real gets built. For /ui-implement, --all only covers use cases whose mockup has already passed the approval gate — batching implementation can never skip it.
This is a deliberate opt-in, not the default habit: AIUP's own guidance is one use case per session, specifically to keep token and context cost under control. Wider scopes trade that discipline for convenience.
Input
Regardless of where the visual theme comes from, the result always lands in the same format — a tokens.json file in the W3C Design Tokens (DTCG) standard — so the downstream steps never need to know its origin.
Scaling
Instead of building a generic component set up front, we start empty — each new use case adds only what it actually needs, and reuses what already exists. New entries are tiered as atoms → molecules → organisms (atomic design vocabulary) so the library doesn't rot into near-duplicates as it grows.
Open questions — to be settled during implementation planning