# UI Prototyping for Specs Applies to: `**/*` (any spec whose deliverable has a non-trivial UI) How to settle a UI design before committing implementation code: research the category, brainstorm the UX in the spec, build a handful of full working prototypes, then iterate one to a final. The prototype is the evidence a design decision is recorded against. Discovered building archsetup's timer-panel spec, promoted here so any UI-bearing spec follows the same shape. ## When this applies — non-trivial UI only The process fires 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. The test: if "which of these layouts is right?" can't be answered from a sentence, it qualifies. A spec with no UI, or a trivial one, skips this rule entirely. ## The process ### 1. Research first — during brainstorming, before any prototype Before building anything, survey how existing and best-in-class tools solve the same UX: the category's well-regarded apps, prior art, the conventions users already expect. Feed the findings into the spec's Goals and Design so the UX is understood before a single prototype exists. Prototyping blind wastes iterations re-deriving what a 20-minute survey would have told you. Cite the sources in the spec. ### 2. Brainstorm the UX 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 make real. ### 3. Prototype — ~5 distinct directions, then iterate one to final Build about five genuinely different directions — distinct layouts and 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. Save each meaningful pass as its own numbered prototype so the design history is walkable. ### 4. 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 rather than against a picture. A static mockup hides the interaction problems that only surface when you drive it. ### 5. Naming and location `docs/prototypes/-prototype-.html`, where `` is the spec's dated slug with the `-spec` suffix dropped, and `N` is the iteration number. For `docs/specs/2026-07-02-timer-panel-spec.org`, the prototypes are `docs/prototypes/2026-07-02-timer-panel-prototype-1.html`, `-2.html`, `-3.html`. ### 6. Link from the spec; keep every iteration 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. ### 7. Decisions get recorded once seen working A design decision moves into the spec's Decisions only after it has been seen working in a prototype. "Resolved live through the prototype iteration" — the prototype is the evidence, not an argument on the page. ## How the spec workflows hook in - **spec-create**: for a non-trivial-UI spec, add the "research → brainstorm → prototype (5 directions → iterate)" step before the design is treated as settled, and require the "Prototype iterations" subsection under the status heading. - **spec-review**: for a non-trivial-UI spec, verify the process ran — research cited, final prototype linked, iterations present in history, and each UI design decision backed by a prototype rather than asserted. Both workflows point here rather than restating the process, so the rule stays the single source of truth. ## Why A UI design argued on paper is a guess. Five working directions surface the interaction problems a mockup hides, and iterating one of them to a final makes the tradeoffs concrete before any production code is written. Recording each decision only once it's been seen working keeps the spec honest: the Decisions section documents what the prototype proved, not what the author hoped.