ss-tools/.specify/templates/ux-reference-template.md

#region Std.Specify.UxReference [C:3] [TYPE ADR] [SEMANTICS ux,reference,[DOMAIN]] @BRIEF UX interaction reference — persona, flows, states, recovery paths, and edge/failure matrix coverage. Drives @UX_* contract tags in Phase 1 and feeds prototype + OpenAPI generation.

Feature Branch: [###-feature-name] Created: [DATE] | Status: Draft

1. User Persona & Context

• Who is the user?: [e.g. Junior Developer, System Administrator, End User]
• What is their goal?: [e.g. Quickly deploy a hotfix, Visualize complex data]
• Context: [e.g. Running a command in a terminal on a remote server, Browsing the dashboard on a mobile device]

2. The "Happy Path" Narrative

[Write a short story (3-5 sentences) describing the perfect interaction from the user's perspective. Focus on how it feels - is it instant? Does it guide them?]

3. Interface Mockups

CLI Interaction (if applicable)

# User runs this command:
$ command --flag value

# System responds immediately with:
[ spinner ] specific loading message...

# Success output:
✅ Operation completed successfully in 1.2s
   - Created file: /path/to/file
   - Updated config: /path/to/config

UI Layout & Flow (if applicable)

Screen/Component: [Name]

• Layout: [Description of structure, e.g., "Two-column layout, left sidebar navigation..."]
• Key Elements:
  • [Button Name]: Primary action. Color: Blue.
  • [Input Field]: Placeholder text: "Enter your name...". Validation: Real-time.
• Contract Mapping:
  • @UX_STATE: Enumerate the explicit UI states that must appear later in contracts/modules.md. For complex screens, these derive from the Screen Model's @STATE declarations.
  • @UX_FEEDBACK: Define visible system reactions for success, validation, and failure
  • @UX_RECOVERY: Define what the user can do after failure or degraded state
  • @UX_REACTIVITY: Note the model-driven reactive chain: Model atoms ($state, $derived) → component props → DOM binding. For route-level data loading, use SvelteKit load() functions; $effect is for browser-side side effects only.
  • Screen Model: For screens with cross-widget logic, reference the planned [TYPE Model] (.svelte.ts file in frontend/src/lib/models/). The model declares @STATE, @ACTION, and @INVARIANT. Components bind to the model via @RELATION BINDS_TO -> [ModelId].
• States:
  • Idle/Default: Clean state, waiting for input.
  • Loading: Skeleton loader replaces content area.
  • Success: Toast notification appears top-right and state is recoverable without reload.
  • Error/Degraded: Visible failure state with explicit recovery path.

4. The "Error" Experience

Philosophy: Don't just report the error; guide the user to the fix.

Semantic Requirement: Every documented failure path here should map to @UX_RECOVERY and, where relevant, @UX_FEEDBACK in the generated component contracts.

Edge & Failure State Matrix Reference

Use the following matrix to ensure systematic coverage of failure states. Mark each as Applicable or Not Applicable (with reason). This feeds directly into /speckit.prototype state switcher and /speckit.openapi error responses.

State Class	Trigger	Applicable?	Visual/Feedback	Recovery
NET_01 — Offline	navigator.onLine == false		Offline banner	Auto-retry on reconnect
NET_02 — Timeout	>30s no response		Toast + countdown	Retry (3 attempts)
NET_03 — Retry exhausted	3 failed retries		Persistent banner	Manual retry
VAL_01 — Field validation	On blur/submit		Inline red border	Re-type
VAL_02 — Cross-field validation	On submit		Summary banner	Fix + re-submit
AUTH_01 — 401 Unauthorized	Expired token		Redirect to login	Login → redirect back
AUTH_02 — 403 Forbidden	Wrong role		Full-page explanation	Navigate to dashboard
NF_01 — 404 Not Found	Deleted resource		Full-page not found	Navigate to list
CONF_01 — 409 Concurrent edit	Version conflict		Modal: "Reload?"	Reload or discard
CONF_02 — 409 Duplicate	Idempotency key		Return existing	Transparent
422 — Server validation	Business rule		Toast with detail	Correct + re-submit
429 — Rate limited	Too many requests		Countdown timer	Wait Retry-After
5XX — Server error	Backend failure		Error section + retry	Retry button
STALE — Background update	Newer version exists		Refresh banner	Click refresh
PARTIAL — Partial load	Some rows failed		Failed row placeholder	Per-row retry
DUP_01 — Double submit	Rapid double-click		Button disabled	Normal completion
DUP_02 — Navigation interrupt	Dirty form + route		Confirm dialog	Stay or discard
LARGE — Large dataset	>1000 items		Virtual scroll	Search refinement
EMPTY — No data	No matching items		Empty state + guidance	CTA or clear filters
MALFORMED — Bad response	Backend bug		Error ID + retry	Note error ID
A11Y — Screen reader	State change		aria-live announcements	Built into transitions
RESP — Responsive	Viewport <768px		Stacked layout	Built into layout

Scenario A: [Common Error, e.g. Invalid Input]

• User Action: Enters "123" in a text-only field.
• System Response:
  • (UI) Input border turns Red. Message below input: "Please enter text only."
  • (CLI) ❌ Error: Invalid input '123'. Expected text format.
• Recovery: User can immediately re-type without refreshing/re-running.

Scenario B: [System Failure, e.g. Network Timeout]

• System Response: "Unable to connect. Retrying in 3s... (Press C to cancel)"
• Recovery: Automatic retry or explicit "Retry Now" button.

5. Tone & Voice

• Style: [e.g. Concise, Technical, Friendly, Verbose]
• Terminology: [e.g. Use "Repository" not "Repo", "Directory" not "Folder"]

#endregion Std.Specify.UxReference