#region UxReference [C:3] [TYPE ADR] [SEMANTICS ux, reference, [DOMAIN]]
@BRIEF UX interaction reference — persona, flows, states, and recovery paths. Drives `@UX_*` contract tags in Phase 1.

**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.

### 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 UxReference