1 files changed, 88 insertions, 0 deletions
diff --git a/claude-rules/ui-prototyping.md b/claude-rules/ui-prototyping.md
new file mode 100644
index 0000000..c58c199
--- /dev/null
+++ b/claude-rules/ui-prototyping.md
@@ -0,0 +1,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.