busya
d874a4dca6
Add prototype/openapi/validate/resume commands, wire edge-failure matrix into UX, enforce traceability + validation gates, mandate C4/C5 belief-runtime verification. Rework 038-dashboard-scenario-model artifacts: applicability, structured edge cases, 24-class UX state matrix, interactive HTML prototype, standardized OpenAPI 3.1 (7 ops), full RTM with coverage gate, 56-task backlog, and PASS validation report.
108 lines
6.0 KiB
Markdown
108 lines
6.0 KiB
Markdown
#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)
|
|
|
|
```bash
|
|
# 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
|