diff options
| author | Craig Jennings <c@cjennings.net> | 2026-07-11 02:02:45 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2026-07-11 02:02:45 -0500 |
| commit | 53f6ce69cab812b57985b992709d894c5077ffb3 (patch) | |
| tree | 30fc105166143186d97691b1eb12da46cc2a54df /.ai/workflows/spec-create.org | |
| parent | 99bd213002f2bd24192d15ff9ae69a0379b2f5be (diff) | |
| download | rulesets-53f6ce69cab812b57985b992709d894c5077ffb3.tar.gz rulesets-53f6ce69cab812b57985b992709d894c5077ffb3.zip | |
docs(spec): add UI-prototyping process for non-trivial-UI specs
For a spec whose deliverable is a real UI, a design argued on paper is a guess. New claude-rules/ui-prototyping.md: research the category first, brainstorm the UX in the spec, build ~5 distinct working prototypes over one engine, iterate one to a final, and record a UI decision only once it's been seen working in a prototype. spec-create gains the step for non-trivial-UI specs. spec-review gates on it: research cited, final prototype linked, iterations in history, decisions backed by a prototype. Prototypes live at docs/prototypes/<spec-name>-prototype-<N>.html.
Worked example: archsetup's timer-panel spec and its three prototypes.
Diffstat (limited to '.ai/workflows/spec-create.org')
| -rw-r--r-- | .ai/workflows/spec-create.org | 2 |
1 files changed, 2 insertions, 0 deletions
diff --git a/.ai/workflows/spec-create.org b/.ai/workflows/spec-create.org index e590540..39758a0 100644 --- a/.ai/workflows/spec-create.org +++ b/.ai/workflows/spec-create.org @@ -47,6 +47,8 @@ Capture, in this order: ** Phase 2 — Design, alternatives, decisions 1. *Design* — overview first, then detail. Write the reasoning as *prose, not bullet dumps* — prose exposes weak logic that bullets let you hide. Use bullets only for genuinely enumerable lists. When the thing has an interface, use the *two-altitude* split (Rust RFC): explain it once for a user/caller, once for an implementer. + + *Non-trivial UI.* When the deliverable is a real UI (a panel, a multi-control surface, an interacting visual layout — not a single dialog, a CLI flag, or a one-off prompt), the design isn't settled on the page. Run the research → ~5 distinct working-prototype directions → iterate-one-to-final process in =claude-rules/ui-prototyping.md= before treating the UI design as done, and add a =Prototype iterations= subsection under the spec's status heading linking every iteration (final linked in the design section). A UI design decision moves to =DONE= only once it's been seen working in a prototype. 2. *Alternatives considered* — the load-bearing section authors skip and reviewers need most. For each option, force a why-not with the MADR grammar: "Good, because… / Bad, because… / Neutral, because…". Even one rejected option, with the reason, beats presenting one path as inevitable. 3. *Decisions* — capture each real choice as an org =TODO= task carrying an inline mini-ADR (Nygard's spine): - The heading is =** TODO <Decision name>=. It flips to =DONE= when the decision-maker agrees with the call; until then it stays =TODO=. |