Referral Manager – UX specification

Related technical authority: Referral Manager – Technical Specification

1. Purpose

This UX spec governs the end-to-end staff experience for creating, tracking, and closing patient referrals — both outbound from the practice and inbound from external referrers. It defines how referral state, ownership, SLA risk, and AI-assisted drafting are surfaced to clinicians, treatment coordinators, receptionists, and practice managers on the Staff Web Portal. It also defines the indirect patient experience, which is delivered entirely through automated communications dispatched by Communication Hub rather than through a Referral Manager–owned patient surface.

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 — every referral list row and detail view leads with the next required action, not an abstract status label.
• Governance always visible — when AI has drafted or suggested referral content, the UI makes this unambiguous and requires explicit human approval before anything is committed or sent.
• No dead toggles — every filter, control, or action button either has an immediate effect or does not appear. Controls that are unavailable due to role or referral state are hidden or contextually disabled with a visible reason, never silently inert.
• Calm by default — SLA indicators and at-risk flags use progressive visual escalation; the interface does not cry wolf. Alerts are reserved for genuinely overdue or blocked referrals.
• Progressive disclosure — the referral list shows the minimum needed to act; full referral context, communication history, and audit trail are one click away in the Detail View.
• Ownership is always named — the technical spec §3.1 mandates OwnerID is never null on an active referral; the UI must never show a referral without a visible named owner, and every ownership gap must be surfaced as an actionable prompt.
• No referral without a record — the technical spec §13.2 rule 2 forbids referrals existing only as emails or documents; the UI reinforces this by making the governed Referral Record the only route to action, not an escape hatch to raw email.

3. Design philosophy

The technical spec §1 frames the module's purpose as eliminating referrals lost in inboxes and ensuring every referral has a named owner and next action. The design embodies a task-board mental model: every referral is a card in motion through a governed lifecycle, not a document sitting in a folder.

Empty states — an empty referral list is a positive signal, not a broken screen. The empty state should communicate that there are no active referrals matching the current filter and offer a clear route to create one or adjust the filter. (needs UX writer input — exact empty-state heading and supporting copy)

Error states — errors during state transitions (e.g. a failed attempt to send a referral) must surface the specific blocking reason and the action the user can take to resolve it, not a generic failure message.

AI suggestions — the technical spec §7 limits AI to drafting content for clinician review; the design treats AI-generated content as a proposal, not a result. AI-drafted sections appear in a visually distinct treatment (e.g. a labelled inset region) and cannot be submitted without an explicit approval action by a named clinician.

Multi-step flows — referral creation follows a linear wizard with mandatory fields enforced at each step before progression. The wizard does not allow a referral to exit Draft state without all required fields populated.

Undo / redo — the technical spec §3.2 and §3.3 state that Completed, Cancelled, and Rejected referrals may not return to an earlier state; the UI must make terminal transitions clearly irreversible, presenting an explicit confirmation step before commit. Non-terminal transitions do not require undo but are fully logged.

Read-only vs editable — referrals in terminal states (Completed, Cancelled, Rejected) are rendered read-only throughout. The audit trail and communication history remain visible but no edit controls are shown. External referrer access is always read-only except for their explicitly permitted response actions.

4. Primary surfaces

4.1 Web portal

The technical spec §5.1 names the Staff Web Portal as the primary surface for all referral management activity.

Who uses it: Clinicians, Treatment Coordinators, Receptionists / Front-of-house, Practice Managers.

Key tasks performed here:

• Viewing the Referral Dashboard with inbound / outbound separation, SLA status indicators, and named owner, per technical spec §5.1.
• Creating a new outbound Referral Record via a structured wizard, per technical spec §4.1.
• Triaging inbound referrals ingested from the shared referrals mailbox — assigning an owner and accepting, rejecting, or requesting further information, per technical spec §4.2.
• Reviewing and approving AI-drafted referral content before sending, per technical spec §4.1 and §7.
• Viewing the Referral Detail View: full context, structured documents, communication history, linked tasks, per technical spec §5.1.
• Managing the Referrer / Specialist Directory: creating, editing, and archiving entries, per technical spec §3.5.
• Reassigning referral ownership with an audit justification, per technical spec §4.1.
• Filtering the dashboard by direction, status, owner, provider, patient, and SLA status, per technical spec §13.4.

Layout pattern: The Referral Dashboard uses a list-detail layout — a filterable list pane on the left and a detail pane on the right (or full-pane on smaller viewports). Referral creation uses a wizard / stepped-form layout. The Referrer Directory uses a list-detail layout.

4.2 Tablet app

The technical spec §5.2 explicitly marks the tablet surface as undefined ("no content captured — needs definition"). No tablet-specific tasks can be responsibly inferred beyond what the web portal already covers.

Who uses it: (needs product decision — the technical spec does not define tablet users or tasks for this module)

Key tasks performed here: (needs product decision — defer to product owner)

Touch ergonomics: One-handed reach zones respected; all tap targets ≥ 48 px; glove-friendly targets where clinical context applies.

Open question: Is a tablet-optimised surface required for Referral Manager at initial build, or does the responsive web portal serve tablet users? See §13.

4.3 Mobile app (staff / patient)

The technical spec §5.3 states that patients receive automated milestone notifications dispatched by Communication Hub, and that Referral Manager does not render a direct patient UI surface. There is no patient-facing Referral Manager screen.

No staff mobile surface is described or implied in the technical spec. Staff referral management is a desktop / tablet workflow by nature of its complexity.

The patient's experience of referral progress is delivered entirely via push notifications and email / SMS dispatched by Communication Hub at referral milestones. Referral Manager owns the trigger events; Communication Hub owns the delivery surface and channel fallback.

5. Interaction model

5.1 Primary flows

Flow 1 — Create outbound referral (staff-initiated)

Derived from technical spec §4.1 and the Outbound State Machine §3.2.

Staff opens Referral Dashboard
  → selects "New outbound referral"
  → Wizard step 1: select patient (FK to patient record)
  → Wizard step 2: select receiving provider / service from Referrer Directory
                   (or create a new Directory entry inline)
  → Wizard step 3: enter referral reason (structured) + upload supporting documents
  → Wizard step 4: assign named owner (defaults to current user)
  → [Optional] AI drafts referral letter content →
       Clinician reviews AI-drafted content in labelled inset
       → approves (with logged approval action) or edits / rejects AI suggestion
  → Record saved as Draft
  → Staff reviews draft and selects "Send referral"
  → Confirmation step: "This will send the referral to [Provider]. Confirm?"
  → Record transitions to Sent → Awaiting Acceptance
  → SLA timer starts automatically
  → Communication Hub triggered for patient notification (if applicable milestone)

Flow 2 — Triage inbound referral

Derived from technical spec §4.2 and the Inbound State Machine §3.3.

Inbound email arrives at shared referrals mailbox
  → Communication Hub ingests email → Referral Manager creates Received record (idempotent)
  → Record appears on dashboard in "Awaiting Triage" queue with no owner
  → Staff selects unowned referral
  → Triage panel: assign named owner (mandatory before further action)
  → Owner reviews referral context and selects response:
      ├─ Accept → record transitions to Accepted / Assigned
      │           → assign to clinician / service
      │           → SLA timer continues
      ├─ Request more info → record transitions to Info Requested (Inbound analogue)
      │                     → response sent to external referrer via governed channel
      └─ Reject → confirmation step (irreversible)
                 → record transitions to Rejected
                 → response sent to external referrer via governed channel

Flow 3 — SLA escalation

Derived from technical spec §3.4 and §4.3.

SLA timer reaches reminder threshold
  → In-app indicator updates to "At-Risk" visual treatment on dashboard row and detail view
  → (Optional) in-app notification to named owner

SLA timer reaches overdue threshold
  → Indicator escalates to "Overdue" visual treatment
  → Escalation task created in Task Manager and linked to referral
  → Practice Manager "All Overdue Referrals" saved view surfaces the referral

Flow 4 — Approve AI-drafted referral content

Derived from technical spec §7 and §13.2 rule 7.

AI Quality Monitor surfaces AI-drafted content or missed-referral signal
  → Staff sees AI suggestion in Referral Detail View or creation wizard
      in a visually distinct labelled region (AI badge / inset)
  → Staff reviews content
      ├─ Approves → approval action logged to AuditTrail with actor + timestamp
      │             → content committed to Referral Record
      ├─ Edits → modified content committed; edit logged as human-modified AI suggestion
      └─ Rejects → rejection logged; content discarded; original field remains editable
  → No AI-drafted content may be sent without completing this approval step

Flow 5 — Manage Referrer Directory

Derived from technical spec §3.5 and §5.1.

Staff (Treatment Coordinator or Practice Manager) opens Referrer Directory
  → List view of Active entries, filterable by specialty / provider name
  → Create new entry: provider name, specialty, preferred referral method,
    governed contact endpoints → saved as Active
  → Edit existing entry: all fields editable; changes logged
  → Archive entry: entry transitions to Archived status; not deleted;
    no longer selectable in new referral creation

5.2 State machines (mirror of technical spec § 3)

Outbound referral states

Derived from technical spec §3.2.

Inbound referral states

Derived from technical spec §3.3.

SLA states

Derived from technical spec §3.4.

Terminal states (Completed, Cancelled, Rejected) must display a confirmation modal before commit, clearly stating the action is irreversible. The modal must name the referral and the patient. (needs UX writer input — exact modal heading, body copy, and confirm / cancel button labels)

5.3 Empty / loading / error / offline states

Referral Dashboard — empty state

An empty filtered view (e.g. "My Active Referrals" with no results) presents an affirming message that there are no referrals matching the current filter, with a prompt to adjust the filter or create a new outbound referral. An empty unfiltered list presents a welcoming first-use state with a create prompt. (needs UX writer input — empty-state heading and supporting copy)

Referral Dashboard — loading state

Skeleton loading pattern on the list pane; individual rows populate progressively as data loads. No full-page spinner.

Referral Detail View — loading state

Skeleton layout preserving the pane structure (header, communication history, documents, linked tasks). Progressive population section by section.

Error state — state transition failure

If a state transition fails (e.g. send referral fails due to a downstream Communication Hub outage), the UI must surface a specific, actionable error inline — not a generic failure toast. The referral must remain in its prior state. The error message must indicate whether the user should retry or contact support. (needs UX writer input — error message copy)

Error state — inbound ingestion failure

The technical spec §14 states ingestion failures must not silently drop referrals and must surface as observable errors. A persistent in-app banner on the dashboard must alert Practice Managers and Treatment Coordinators to ingestion failures, with a count of affected items and a route to investigate. (needs UX writer input — banner copy)

Offline state

Referral Manager is a web portal–primary surface; full offline operation is not expected. In a connectivity-lost scenario, the dashboard and detail views render their last-loaded state as read-only, with a clearly visible connectivity warning banner. No state transitions may be submitted while offline; the transition controls are disabled with a visible reason. (needs UX writer input — offline banner copy)

6. Component inventory

New components introduced or extended by this module:

• Referral status badge — colour-coded badge rendering the current lifecycle state of a referral; appears on list rows and the detail view header. Derived from technical spec §3.2, §3.3.
• SLA indicator — inline timer / status indicator showing On Track / At-Risk / Overdue against a referral; appears on list rows and detail view. Derived from technical spec §3.4.
• AI content inset — visually distinct labelled region within the referral creation wizard and detail view that renders AI-drafted content with an AI badge and approval / edit / reject controls. Derived from technical spec §7.
• Referral creation wizard — multi-step form component enforcing mandatory fields at each step before progression; wraps patient selection, provider selection, reason entry, document upload, and owner assignment. Derived from technical spec §4.1.
• Triage panel — structured action panel within the inbound referral detail view for assigning an owner and selecting an accept / info-request / reject response. Derived from technical spec §4.2.
• Referrer Directory entry form — create / edit form for governed Referrer Directory entries including active / archived status toggle. Derived from technical spec §3.5.
• Escalation task badge — linked badge on overdue referrals indicating an escalation task exists in Task Manager; tapping navigates to the linked task. Derived from technical spec §3.4.
• Ingestion failure banner — persistent in-app banner surfacing shared mailbox ingestion errors to authorised roles. Derived from technical spec §14.

Reused from the design system:

• Data table / filterable list
• Detail side pane / drawer
• Confirmation modal
• Toast notification
• Form field with programmatic label
• Filter bar with multi-select chips
• Skeleton loader
• Breadcrumb navigation

7. Visual design notes

• Typography: (needs UX writer input — heading scale and body scale to be defined by the design system; no specific values inferred from the technical spec)
• Colour: Semantic colour usage is driven by the SLA and state badge system. At minimum: neutral for on-track / draft states; amber / warning for At-Risk, Info Requested, Awaiting Triage, and unowned referrals; red / error for Overdue and Rejected; green / positive for Accepted, Scheduled; muted / resolved for Completed and Cancelled. Exact tokens are owned by the design system.
• Iconography: Icon set to be defined by the design system. Icons must never appear without a visible label or programmatic accessible name. Sizing must respect touch-target minimums on tablet.
• Motion: Transitions used only for state badge changes and pane open / close. Nothing is animated in a way that could distract clinical users mid-task. All motion must respect prefers-reduced-motion.

8. Accessibility & inclusivity

The module MUST meet WCAG 2.2 AA. Specifically:

• Text contrast ≥ 4.5:1 (normal text) / ≥ 3:1 (large text).
• 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 (Windows), VoiceOver (macOS / iOS), and TalkBack (Android).
• The AI content inset must be announced to screen readers with a clear label indicating AI-generated origin, so users relying on assistive technology are not misled about the provenance of the content. Derived from technical spec §7 AI governance requirements.
• SLA status indicators must not rely solely on colour to convey urgency; At-Risk and Overdue states must carry a text or icon label alongside the colour treatment. Derived from technical spec §3.4 and WCAG 1.4.1 Use of Colour.
• Terminal-state confirmation modals must receive keyboard focus on open and trap focus until dismissed. Derived from technical spec §3.2 / §3.3 irreversible transition rules.

9. Internationalisation

• Locale-aware date / time / number formatting throughout.
• All user-facing strings externalised to translation keys; no hard-coded copy in components.
• Layouts tolerant of 30% string-length growth for languages such as German and French.
• RTL support: required — platform default.
• SLA timer displays must use locale-aware duration formatting (e.g. "3 days", "2 hrs") rather than raw timestamps, to remain meaningful across locales. Derived from technical spec §3.4 SLA lifecycle.

10. Cross-module UX touchpoints

Derived from technical spec §6 and §10.

• Communication Hub — Referral Manager surfaces the communication history captured by Communication Hub within the Referral Detail View (read-only). When a state transition triggers a patient notification, the UI confirms that a notification will be dispatched by Communication Hub — the user does not configure the notification directly in Referral Manager. Inbound email ingestion originates in Communication Hub; the staff experience of the resulting Received referral record begins in Referral Manager's triage queue.

• Task Manager — escalation tasks created by Referral Manager appear as linked badges on overdue referral rows and in the Referral Detail View. Tapping a linked task badge opens the task in Task Manager (or a Task Manager drawer surface, if supported). Task completion signals from Task Manager update the referral's linked-task status in the detail view without requiring staff to navigate back manually.

• Access Manager — the user's current role and active permissions are reflected in which actions are visible and enabled on the Referral Dashboard and Detail View. Users with insufficient permissions do not see controls they cannot use; the interface does not present disabled buttons without explanation. Role and permission management itself is done in Access Manager, not in Referral Manager.

• AI Quality Monitor — AI-drafted content and missed-referral signals surfaced in Referral Manager originate from AI Quality Monitor. The UX must make the AI origin of any suggestion visible and auditable at all times. Staff do not interact with AI Quality Monitor directly; its signals appear as contextual prompts or AI insets within the referral workflow.

• Performance Dashboards — Referral Manager emits read-only metrics to Performance Dashboards but does not display dashboards or KPI charts itself. Staff who need to view referral KPIs navigate to Performance Dashboards; there is no embedded analytics surface within Referral Manager.

• Audit & Compliance — the Referral Detail View includes an accessible, read-only audit trail panel showing all state transitions, ownership changes, communication events, and AI content decisions, with actor identity and timestamps. The full audit log is exportable. Staff do not interact with the Audit & Compliance module directly; the trail is rendered within Referral Manager's own detail view.

UX consistency rules:

• Action buttons that trigger state transitions (Send, Accept, Reject, Cancel) appear as primary actions in a consistent position on the Detail View — bottom-right on web — to distinguish them from secondary navigation actions. Derived from the action-first principle and the role-gated action model in technical spec §9.
• All cross-module navigation (to Task Manager, to Performance Dashboards) opens in a way that preserves the user's place in Referral Manager — either via a drawer, a new tab, or a clearly labelled breadcrumb back. Staff must never lose their referral context when following a linked signal.

11. Governance & auditability

Derived from technical spec §7 (AI boundaries), §8 (Audit & Compliance), and §9 (Access Control).

• AI-drafted content is visually distinct from human-authored content at all times — rendered in a labelled inset with an explicit AI badge. The approval, edit, or rejection of AI content is a named, logged action; the UI makes this step mandatory and non-skippable before the content can be committed.
• All audit-significant actions — state transitions, ownership reassignments, terminal-state changes, AI content approvals, and document uploads — require an explicit confirmation step. The confirmation modal names the action, the referral, and the patient, and makes the audit consequence clear. (needs UX writer input — confirmation modal copy for each action type)
• The current user's role and the scope of their access (e.g. "Treatment Coordinator — [Practice Name]") are visible in the portal header at all times, consistent with Access Manager providing role assertions.
• Read-only states (terminal referrals, external referrer view, archived Directory entries) are visually distinct from editable states — no edit controls are rendered, and a clear read-only label or banner is present.
• The Referral Detail View includes a persistent, collapsible audit trail panel showing every logged event (state transitions, ownership changes, communications, AI decisions) with actor identity and timestamp. This panel is always available without leaving the detail view, surfacing governance without requiring a separate audit application.
• Manual SLA overrides, if permitted (see open question §13), must present a mandatory justification field before commit, and the justification must be written to the AuditTrail. The UI must not allow a silent SLA pause.

12. Notification & communication patterns

Derived from technical spec §2.1, §4.3, §6.2, and §13.2 rule 9.

• In-app banner — Used for persistent, role-targeted alerts that require staff attention before they can act effectively. Specifically: shared mailbox ingestion failures (surfaced to Practice Managers and Treatment Coordinators); connectivity-lost state (all users). Banners persist until the condition resolves; they are not dismissable while the underlying issue remains active.
• Toast — Used for transient confirmations of completed staff actions: successful referral send, successful ownership reassignment, successful document upload, successful Directory entry save. Toasts are brief, non-blocking, and do not require dismissal.
• Push notification (via Communication Hub — not direct) — Referral Manager emits milestone events to Communication Hub, which dispatches push notifications to patients at configured referral milestones (e.g. referral sent, accepted, completed). Referral Manager does not dispatch push notifications directly and does not own the push channel or fallback logic.
• Email / SMS (via Communication Hub — not direct) — Patient email and SMS notifications at referral milestones are dispatched by Communication Hub on receipt of Referral Manager's state-change events. Responses from external referrers arrive via the shared referrals mailbox, also governed by Communication Hub's ingestion layer. Referral Manager does not send email or SMS directly.
• In-app escalation signal — When a referral reaches Overdue status and an escalation task is created in Task Manager, the referral's dashboard row and detail view update to surface the Overdue indicator and the linked escalation task badge. This is a passive visual update, not an active notification push, consistent with the calm-by-default principle.

13. Open questions

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

1. Tablet surface scope — Is a tablet-optimised layout required for Referral Manager at initial build? If so, which roles use it and which tasks must it support? The technical spec does not define tablet usage for this module. (needs product decision)

2. Manual SLA override UX — If manual SLA override is permitted (technical spec open question 2), the UI must include a mandatory justification field and a confirmation step. The exact governance pattern needs agreement between product, compliance, and UX. (needs product decision before UX can be finalised)

3. External referrer portal UX — The technical spec (§13.5) identifies a future lightweight external referrer portal as a named extension. If brought into scope, this surface requires its own UX treatment — authentication, scoped referral view, and structured accept / info-request / decline actions. (deferred — needs product decision on scope and timeline)

4. Scheduled sub-state and appointment linkage — The Scheduled sub-state in both state machines implies a link to an appointment record. If this links to an Appointment Manager module, the UX handoff pattern (how staff navigate between referral and appointment, and back) needs defining. (depends on technical spec open question 7 — Appointment Manager integration contract)

5. Confirmation modal copy — Irreversible transition modals (Reject, Cancel, Complete) need finalised copy for the heading, body, and button labels. (needs UX writer input for each transition type)

6. Empty-state and error-state copy — All empty states, error states, and offline banners need final microcopy. (needs UX writer input)

7. AI content inset — exact visual specification — The AI inset component needs a finalised visual treatment (border style, badge label, icon) consistent with the platform design system's AI governance patterns. (needs design system alignment)

8. "My Active Referrals" default view scope — The technical spec (§13.4) defines this as scoped to the authenticated user's OwnerID. UX needs to confirm whether this default view is the first thing every role sees on login, or whether different roles have different landing views (e.g. Practice Managers land on "All Overdue Referrals"). (needs product decision)