76 lines
3.0 KiB
Markdown
76 lines
3.0 KiB
Markdown
# UX Reference: [FEATURE NAME]
|
|
|
|
**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`
|
|
* **`@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 expected Svelte rune bindings with `$state`, `$derived`, `$effect`, `$props`
|
|
* **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.
|
|
|
|
### 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"]
|