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)

# 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"]

3.0 KiB Raw Blame History