Edit template: Ux

Module placeholders: module_name, slug, tier, suite, suite_slug, license, lifecycle_stage, summary, related_modules_yaml, today, url_path.
Project terminology (set in /admin/terminology): primary_user_singular, primary_user_plural, secondary_user_singular, secondary_user_plural, business_setting, integration_partner, governance_authority, core_object, service_provider_role, service_admin_role, sensitive_data_kind. Use any of these as {{ placeholder_name }}.

---
module: "{{ module_name }}"
slug: {{ slug }}
version: "1.0"
doc_type: ux
tier: {{ tier }}
suite: "{{ suite }}"
suite_slug: {{ suite_slug }}
license: {{ license }}
lifecycle_stage: {{ lifecycle_stage }}
related_modules: {{ related_modules_yaml }}
source_file: "modules/{{ slug }}/v1.0-ux.md"
last_updated: "{{ today }}"
status: "draft"
---

# {{ module_name }} – UX Specification

Status: Draft

Related Technical Authority: {{ module_name }} – Technical Specification

## 1. Purpose

> 2-3 sentences describing why this UX spec exists, what user experience it governs,
> and the primary roles it serves.

## 2. Core UX Principles (Non-Negotiable)

These principles take precedence over visual preferences. If a design choice conflicts
with a principle below, the principle wins.

- **Action-first** — users see the action they need next, not abstract status displays
- **Governance always visible** — when AI is involved, users always know what AI did and
  what they're confirming
- **No dead toggles** — every UI control either does something or doesn't appear
- **Calm by default** — the interface gets out of the way; alerts are reserved for
  things that genuinely need attention
- **Progressive disclosure** — advanced detail is one click away, not always-on
- (add module-specific principles)

## 3. Design Philosophy

> The mental model the design embodies. What is this module's stance on:
> empty states, error states, AI suggestions, multi-step flows, undo/redo,
> read-only vs editable surfaces.

## 4. Primary Surfaces

### 4.1 Web Portal

Who uses it: (Owners / Managers / Clinicians / Front-of-house)

Key tasks performed here:

- (task 1)
- (task 2)

Layout pattern: (single-pane / split-pane / dashboard / list-detail / form / wizard)

### 4.2 Tablet App

Who uses it: (clinical staff in surgery / decon staff / receptionists)

Key tasks performed here:

- (task 1)

Touch ergonomics: (one-handed reach, glove-friendly tap targets ≥48px, etc.)

### 4.3 Mobile App (Patient or Staff)

Who uses it: (patients / staff in transit)

Key tasks performed here:

- (task 1)

## 5. Interaction Model

### 5.1 Primary Flows

> Diagram each major user flow: where it starts, where it ends, where it can branch.
> Use either Mermaid diagrams or numbered step-by-step sequences.

### 5.2 State Machines (Mirror of Technical Spec § 3)

How each state transition is represented in the UI:

- entry conditions visible before the transition
- confirmation pattern for irreversible transitions
- visual treatment of each state (colour, badge, position)

### 5.3 Empty / Loading / Error / Offline States

Every screen MUST define:

- the empty state (what does a user see before there's any data?)
- the loading state (skeleton / spinner / progressive)
- the error state (what action can the user take?)
- the offline state (what's still possible without connectivity?)

## 6. Component Inventory

New components introduced or extended by this module:

- (component name) — (purpose, where it appears)

Reused from the design system:

- (component name)

## 7. Visual Design Notes

- Typography: (heading scale, body scale, monospace usage)
- Colour: (semantic colour usage — success, warning, error, info, brand)
- Iconography: (icon set, sizing, never icon-only without label)
- Motion: (where transitions are used, what's never animated)

## 8. Accessibility & Inclusivity

The module MUST meet WCAG 2.2 AA. Specifically:

- Text contrast ≥4.5:1 (normal) / ≥3:1 (large)
- All interactive controls reachable via keyboard
- Focus states visible
- Form fields have programmatic labels
- ARIA used only where native semantics are insufficient
- Touch targets ≥44×44 px on mobile/tablet
- Motion can be reduced via `prefers-reduced-motion`
- Screen reader tested on (NVDA / VoiceOver / TalkBack)

## 9. Internationalisation

- Locale-aware date/time/number formatting
- All user-facing strings externalised
- Layouts tolerant of 30% string-length growth (German, French)
- RTL support: (required / not required)

## 10. Cross-Module UX Touchpoints

Where this module's UX intersects with related modules:

- **Module X** — (where the user transitions from this module to that one, and back)
- **Module Y** — (shared component or pattern)

UX consistency rules:

- (e.g. "Action buttons always appear bottom-right on tablet, top-right on web")

## 11. Governance & Auditability

How the UI surfaces governance:

- AI suggestions are visually distinct from user actions (e.g. dotted border, AI badge)
- Audit-significant actions show a confirmation step
- The current user's role and active permissions are visible in the header
- Read-only states are visually distinct from editable

## 12. Notification & Communication Patterns

How this module asks for user attention:

- In-app banner (where, for what)
- Toast (what kinds of confirmations)
- Push notification (delivered via Communication Hub — NOT directly)
- Email/SMS (also via Communication Hub)

## 13. Open Questions

> UX decisions to resolve before this spec is promoted from `draft` to `published`.

- (open question)
- (open question)

Cancel