#+TITLE: Proposal — UI/UX prototype process for specs with a non-trivial UI #+AUTHOR: Craig Jennings (via archsetup session) #+DATE: 2026-07-05 * Intro / why this is coming to you Working the timer-panel spec in archsetup, we found the right way to settle a UI design: research first, then build a handful of full working prototypes, then iterate one to a final — all before committing GTK code. It worked well enough that Craig wants it as a standing part of the spec process for any spec whose deliverable has a non-trivial UI. This is the write-up, proposed for the rulesets layer (spec-create / spec-review, or a new =ui-prototyping= rule — your call on placement). Worked example living now in archsetup: =docs/specs/2026-07-02-timer-panel-spec.org= plus =docs/prototypes/2026-07-02-timer-panel-prototype-{1,2,3}.html=. The spec's "Prototype iterations" subsection and its new design decisions show the shape in practice. * The process ** 1. Trigger — non-trivial UI only Applies when a spec's deliverable is a real UI: a panel, a multi-control surface, a visual layout with interacting parts. Not a single dialog, a CLI flag, or a one-off prompt. If "which of these layouts is right?" can't be answered from a sentence, it qualifies. ** 2. Research first — during brainstorming, before prototyping Before any prototype, survey how existing and best-in-class tools solve the same UX and functionality (the category's well-regarded apps, prior art, conventions users already expect). Feed the findings into the spec's Goals and Design so the UX and functionality are understood *before* a single prototype. Prototyping blind wastes iterations re-deriving what a 20-minute survey would have told you. Cite the sources in the spec. ** 3. Brainstorm the UX + functionality in the spec Informed by the research, write the goals, the interactions, and the functional surface into the spec. This is the "what and why" the prototypes will make real. ** 4. Prototype — ~5 initial directions, then iterate to a final Build about five *distinct directions* (genuinely different layouts / interaction models, not variations of one) as full working prototypes over one shared engine, in the project's design language. Pick a direction, then iterate *that one* across numbered passes to the final design. Each meaningful pass is saved as its own numbered prototype so the design history is walkable. ** 5. Full working prototypes, not mockups The prototypes must be *functional* — real state, real controls, real behavior — so decisions are made against how it feels to use, not against a picture. A static mockup hides the interaction problems that only surface when you drive it. ** 6. Naming + location =docs/prototypes/-prototype-.html=, where == is the spec's dated slug (dropping the =-spec= suffix) and =N= is the iteration number. E.g. for =2026-07-02-timer-panel-spec.org= → =2026-07-02-timer-panel-prototype-1.html=, =-2.html=, =-3.html=. ** 7. Link from the spec; keep old iterations in history The spec links the *final* prototype in its design section, and keeps links to *every* prior iteration in a "Prototype iterations" subsection under the status heading — newest last — so the design's evolution is walkable from the spec. ** 8. Decisions get written down once seen working A design decision is recorded in the spec's Decisions only after it's been seen working in a prototype. "Resolved live through the prototype iteration" — the prototype is the evidence. * Suggested placement (your value gate decides) - =spec-create=: for a non-trivial-UI spec, add a "research → brainstorm → prototype (5 directions → iterate)" step, and require the "Prototype iterations" subsection. - =spec-review=: for a non-trivial-UI spec, verify the prototype process ran — research cited, final prototype linked, iterations in history, decisions backed by a prototype. - Or a standalone =claude-rules/ui-prototyping.md= that both workflows point at. Not prescribing which — sending the content and the worked example; apply the rulesets value gate and place it where it fits.