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
|
#+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/<spec-name>-prototype-<N>.html=, where =<spec-name>= 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.
|
