clarify-ui — feel the app before building it

Called when a UI's experience must be judged by using it, not by reading about it. Produces docs/clarity/prototypes/<name>/index.html + ui-notes.md in the staging dir (see Paths), and registers the prototype in the preview site.

What the prototype is

• A single self-contained HTML file (inline CSS/JS, placeholder data, no build step, no network calls) that opens straight in a browser — or via the preview server.
• Behaviorally faithful to the approved behavior spec: if a behavior.yaml exists, every state, event, guard-outcome and transition is observable, and the embedded state machine mirrors the YAML 1:1 (state names identical). Actors are simulated with timers/promises; failures and cancellations must be triggerable (small dev panel: "simulate failure", "simulate slow network").
• Visually neutral: grayscale, system fonts, boxes and labels. Layout, hierarchy, copy and interaction — real. Colors, icons, animation, branding — absent.

Method

1. UI interview (batch the questions). Layout preferences? Navigation pattern? Reference apps the user likes? Density? Pet peeves? Record answers in ui-notes.md.
2. Implement the prototype. One HTML file; states rendered as the UI the user sees in that state; controls wired to events; dev panel for actor outcomes.
3. Publish. Run clarity publish — the prototype appears in the site index alongside the diagrams. Works with zero diagrams in the staging dir too (check is vacuously green; the site still builds). Never start the server yourself — that's the user-invoked clarity-preview skill. In conversation, walk the user through which flows to try, especially failure, retry and cancel paths — the conversation is the guide, the browser is the experience; don't point at files for explanation.
4. Iterate until the user explicitly approves. Two kinds of feedback:
   • Behavioral ("cancel should keep the file selected") → if a behavior.yaml exists, change it FIRST, re-validate, redraw affected views, then update the prototype. The model stays the source of truth.
   • Presentational ("search should be at the top") → change the prototype + ui-notes.md.
5. On approval: record it in ui-notes.md. What happens next (implementation, and how the prototype informs it) is the governing workflow's call.

Paths (derived, never chosen)

• All artifacts live in the staging dir <projectRoot>/docs/clarity/ — for this capability, docs/clarity/prototypes/<name>/ (clarity root shows the derived root). Never invent or negotiate other locations.
• All tools via the clarity CLI (never relative tool paths). If missing: export PATH="$HOME/.local/bin:$PATH", retry once, then STOP and report — never improvise.

Modifying existing artifacts

The prototype and ui-notes.md record presentation decisions; behavioral feedback goes through behavior.yaml first (the model is the source of truth), then the prototype is updated to match.

Fidelity checklist (verify before presenting)

• Every specified state has a distinct, labeled UI representation
• Every user-sourced event has a working control
• Every actor outcome (done/error) can be simulated from the dev panel
• Guard outcomes are demonstrable (e.g. retry limit reached → retry disabled)
• No real backend calls, no external assets, opens offline
• Grayscale only

Optional diagram

A journey (cross-module UX review: stages, actions, satisfaction scores — scores force honest UX thinking) is optional when the user wants to judge the experience across modules/stages, not just within this prototype. It must force a UX decision; otherwise skip it.

Rules

• The prototype is throwaway: production code does not reuse it; it is the layout/interaction reference.
• Never let prototype and behavior spec disagree. The spec wins — unless the user decides the behavior itself changes (then the spec changes first).