1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
# 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/<spec-name>-prototype-<N>.html`, where `<spec-name>` 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.
|
