Rewards Manager – UX Specification

Related Technical Authority: Rewards Manager – Technical Specification

1. Purpose

This UX specification governs the patient and staff experience of Primoro's behaviour-led loyalty module. It covers the patient-facing rewards journey in the mobile app and the staff-facing operational surfaces in the web portal and tablet app — ensuring that every interaction with points, referrals, redemptions, charity donations, and recognition layers is legible, trustworthy, and free of unnecessary friction. The primary roles it serves are authenticated patients managing their own rewards account and practice staff operating the Rewards & Referrals Management Dashboard.

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.

Trust over transaction — because the technical spec explicitly frames the module as "behaviour-led, trust-first" and prohibits cash rewards or discount-driven marketing, the UI must never present points as a financial instrument. Earned points are shown as recognition, not currency. (Technical spec §1)

Opt-out is a first-class action — per the technical spec's requirement that patient opt-out be supported and honoured immediately (§8, §14), the option to leave the rewards programme must always be discoverable without requiring staff assistance.

Reward-clinical separation — the UI must never place rewards information adjacent to clinical recommendations in a way that could appear to incentivise a clinical decision. This mirrors the technical spec's prohibition on clinical bias (§8).

3. Design Philosophy

The mental model is a personal recognition record rather than a points wallet. Patients encounter their rewards account as a record of positive moments — attended appointments, completed recall, plan participation — not as a balance to be maximised. This guards against the discount-driven framing the technical spec explicitly rejects (§1).

Empty states signal potential rather than absence. A patient who has not yet earned any points sees an explanation of how recognition works and which actions they can take, not a blank ledger. A staff dashboard with no pending redemptions is a positive state and should read as such.

Error states distinguish between patient-recoverable errors (e.g. attempting to redeem more points than available) and system errors (e.g. earn processing temporarily unavailable). The technical spec's graceful-degradation requirement (§14) means read-only balance display must remain available even when real-time processing is degraded — the UI should surface this distinction honestly.

AI suggestions are visually and semantically distinct from confirmed facts. Following the AI boundaries in §7 of the technical spec, every AI-surfaced insight on the staff dashboard is presented as a suggestion requiring human review, never as a completed action. The AI badge and the confirmation step are not optional.

Multi-step flows (redemption, refer-a-friend initiation, manual adjustment) use a wizard or stepped-form pattern with a clear summary and a final confirmation step. Irreversible actions — confirmed redemption, manual adjustment once authorised — show an explicit "this cannot be undone" statement before the terminal step.

Undo/redo is not available on points transactions because the technical spec mandates append-only immutable ledgers (§3.1, §3.2). Corrections are handled via auditable manual adjustments, not UI-level undo. The interface should make this clear at the point of irreversibility.

Read-only vs editable surfaces are visually distinct throughout. Patient views of their own ledger are always read-only except for initiating a redemption or opt-out. Staff views of a patient's rewards summary within the patient record are read-only except for explicitly role-gated actions (manual adjustment, staff-assisted redemption). The current user's permission level governs which controls appear.

4. Primary Surfaces

4.1 Web Portal

Who uses it: Practice administrators, practice managers, and front-of-house staff. (Technical spec §10.2, §9)

Key tasks performed here:

• Viewing a patient's rewards summary (balance, recent earn and redemption events, active entitlements) within the patient record. (Technical spec §10.2)
• Operating the Rewards & Referrals Management Dashboard — reviewing rewards overview metrics, navigating the referral state pipeline, monitoring pending redemptions, and reviewing charity donation summaries. (Technical spec §11)
• Performing staff-assisted redemption for patients at the point of care when Integrated Payments is not enabled. (Technical spec §4.2, §10.2)
• Performing manual point adjustments (restricted role only), including mandatory reason entry and re-authentication or elevated session confirmation. (Technical spec §9, §17.2)
• Initiating staff-led outreach via Communication Hub for referrals that have stalled or for rewards that have not been redeemed. (Technical spec §5.3, §11.2)
• Configuring practice-level reward rules via the Admin Control Plane (eligible earning behaviours, redemption types, referral caps, charity partners, recognition layer on/off, nudge timing, NHS exclusion override). (Technical spec §17.3)
• Exporting audit logs for compliance inspection (administrator or compliance role only). (Technical spec §8, §9)
• Reviewing and acting on AI-surfaced insights on the dashboard (AI badge always visible; human decision always required). (Technical spec §7)

Layout pattern: The Rewards & Referrals Dashboard uses a dashboard pattern with a metrics summary strip at the top (total points issued, redeemed, outstanding; active entitlements; pending redemptions; charity donations) and a tabbed or sectioned lower region for Rewards Overview, Referral Pipeline, and Charity giving. The patient-record rewards summary uses a list-detail panel embedded within the wider patient record layout. Configuration screens use a form pattern. (Technical spec §11, §10.2)

4.2 Tablet App

Who uses it: Front-of-house and reception staff at the point of care. (Technical spec §10.3)

Key tasks performed here:

• Viewing a patient's current points balance and active entitlements to support an assisted redemption conversation at the point of care. (Technical spec §10.3)
• Confirming a staff-assisted redemption where the patient wishes to apply a reward credit at the time of treatment or checkout. (Technical spec §4.2, §4.3)

Touch ergonomics: Glove-friendly tap targets ≥48 px. The assisted-redemption confirmation action must be reachable with one hand and placed in the lower-right of the screen to respect natural thumb reach. The tablet view is intentionally a reduced scope of the full web portal dashboard — full dashboard access is via the web portal only. (Technical spec §10.3)

4.3 Mobile App (Patient)

Who uses it: Authenticated patients managing their own rewards account. (Technical spec §10.1)

Key tasks performed here:

• Viewing their points balance and full transaction history. (Technical spec §10.1)
• Browsing available redemption options enabled by the practice and initiating a redemption. (Technical spec §10.1, §4.2)
• Generating, sharing (via WhatsApp, SMS, email, copy-link, or QR), and tracking the progress of their personal referral link. (Technical spec §5.1, §10.1)
• Viewing tier status, badges, and milestones if the practice has enabled the optional recognition layer. (Technical spec §4.4, §10.1)
• Opting out of the rewards programme. (Technical spec §10.1, §8)
• Donating points to a charity configured by the practice, including providing Gift Aid eligibility information if applicable. (Technical spec §6)

The mobile app is the primary surface for patient rewards interaction per the technical spec (§10.1). The layout pattern is list-detail for transaction history and referral tracking, with a wizard pattern for redemption, referral sharing, and charity donation flows.

5. Interaction Model

5.1 Primary Flows

Flow 1 — Patient views balance and redeems a reward (mobile)

Derived from technical spec §10.1, §3.5, §3.6, §4.2.

1. Patient opens Rewards section in the mobile app
   → Sees current points balance and a summary of available redemption options
     (only types enabled by the practice are shown)

2. Patient selects a redemption option
   → Progressive disclosure: sees the points cost, entitlement description,
     and any eligibility conditions

3. Patient confirms intent to redeem
   → System checks: sufficient balance? Redemption type enabled?
     If yes → proceed; if no → error state with explanation (see §5.3)

4. Redemption confirmation screen
   → Summary: points to be deducted, entitlement to be granted,
     statement that this action cannot be undone
   → *(needs UX writer input — exact confirmation label and microcopy)*

5. Patient confirms
   → Points deducted atomically; Redemption state moves to Confirmed
   → Success state: entitlement active, updated balance shown
   → Communication Hub triggers a confirmation notification

6. Patient sees updated balance and transaction entry in history

Flow 2 — Patient generates and shares a referral link (mobile)

Derived from technical spec §5.1, §3.3, §3.4, §10.1.

1. Patient opens Refer a Friend section
   → Sees their unique referral link and current referral pipeline summary
     (how many referrals at each stage)

2. Patient selects a share channel
   → Options: WhatsApp / SMS / email / copy-link / QR code
   → System records share channel and timestamp (Referral state → Shared)

3. Patient sees referral card with share preview
   → *(needs UX writer input — referral invitation copy and value proposition)*

4. After sharing, patient returns to referral tracking view
   → Shows Referral state on the pipeline: Shared / Invite Viewed /
     Registered / Booked / Attended / Reward Issued / Reward Redeemed
   → Read-only pipeline; no patient action required until Reward Issued

5. When Reward Issued
   → Patient receives notification via Communication Hub
   → Balance updated; new transaction entry visible

Flow 3 — Staff reviews referral pipeline and initiates follow-up (web portal)

Derived from technical spec §11.2, §5.3, §10.2, §7.

1. Staff opens Rewards & Referrals Dashboard → Referral Pipeline tab
   → Sees all referrals segmented by state, filterable by channel,
     date range, and individual patient

2. Staff reviews stalled referrals
   → AI Aiden surfaces an insight badge on referrals stalling at a
     consistent stage (e.g. "Invite Viewed but not booked — 12 referrals")
   → AI insight is visually distinct (AI badge); no action is taken
     without staff decision

3. Staff selects a stalled referral to drill into detail
   → Sees: share channel, timestamps, consent status for follow-up,
     current state in the pipeline

4. Staff initiates outreach via Communication Hub
   → Communication Hub handles delivery; action is logged against
     the referral record

5. Staff dismisses or acts on the AI insight
   → Human decision (accepted / dismissed) is logged in the audit trail

Flow 4 — Staff performs a manual point adjustment (web portal, restricted role)

Derived from technical spec §9, §17.2 rule 6, §8, §4.3.

1. Staff navigates to patient rewards summary within the patient record
   → Manual Adjustment action is visible only to users with the
     required restricted role; absent for all others

2. Staff selects Manual Adjustment
   → Re-authentication or elevated session confirmation required
     (governed by Access Manager policy)

3. Staff enters:
   → Points delta (positive or negative)
   → Mandatory reason note (empty note → submission blocked)
   → *(needs UX writer input — field labels and validation microcopy)*

4. Confirmation screen
   → Summary of adjustment, patient name, points delta, reason note
   → Statement that the adjustment is irreversible and audit-logged
   → *(needs UX writer input — confirmation label)*

5. Staff confirms
   → Reward Transaction committed; ledger updated
   → Audit log entry created with actor ID, timestamp, reason note
   → Success state shown; patient balance updated in view

Flow 5 — Patient donates points to charity (mobile)

Derived from technical spec §6, §10.1, §3.2.

1. Patient opens Rewards section → Donate to Charity option
   → Only visible if the practice has configured at least one charity partner

2. Patient selects a charity from the practice's configured list
   → Sees points-to-donation conversion information
   → *(needs UX writer input — donation value framing and charity description)*

3. If Gift Aid is applicable: patient is prompted to confirm eligibility
   → *(needs UX writer input — Gift Aid declaration microcopy)*
   → Gift Aid eligibility captured and logged

4. Patient enters points amount and confirms donation
   → Confirmation screen: charity name, points to donate, Gift Aid status
   → Statement that donation is irreversible

5. Patient confirms
   → Donation logged as Reward Transaction (type: donation)
   → Communication Hub triggers confirmation notification
   → Updated balance shown

Flow 6 — Rewards Manager exposes reward signals to Loyalty Insights and processes handoff requests (web portal / system boundary)

Derived from technical spec §12.1, §12.2, §2.1; Loyalty Insights §4.1, §3.3.

This flow describes the UX boundary between Rewards Manager and Loyalty Insights. It is primarily a staff-facing and system-boundary concern: Loyalty Insights consumes read signals emitted by Rewards Manager, and may initiate handoff actions that land a staff user inside the Rewards Manager dashboard. No patient-facing UI is involved.

1. Loyalty Insights reads reward transaction data and referral pipeline state
   → Rewards Manager exposes reward transaction summaries (earn events,
     redemption events, donation events, adjustment events) and the full
     referral state pipeline as readable signals via the integration
     contract (Technical spec §12.1)
   → These signals feed the reward-impact analytics and referral
     effectiveness views inside Loyalty Insights
   → Rewards Manager does not render programme-level cohort or trend
     analysis; that responsibility belongs to Loyalty Insights entirely
     (see §10, Cross-Module UX Touchpoints)

2. Loyalty Insights surfaces a reward-impact or referral-effectiveness insight
   to a staff user and offers a handoff action
   → The handoff is a deep link or context-passing action that brings
     the staff user into the Rewards Manager dashboard at a specific
     record (e.g. a referral record, a patient rewards summary, or a
     pending redemption queue)
   → On arrival, Rewards Manager renders the relevant surface in its
     normal state; no special "arrived via Loyalty Insights" chrome is
     required, though the staff user's navigation breadcrumb should
     make the entry point legible

3. Staff user reviews the record inside Rewards Manager
   → All normal role-gating applies: the staff user sees only the
     controls they are permitted to use, regardless of the handoff
     source
   → If the handoff referenced a specific referral, the referral
     pipeline component is scrolled to and visually highlighted on
     load so the staff user does not need to search for the relevant
     record
   → *(needs UX writer input — highlighted-record treatment and
       any contextual banner copy explaining the Loyalty Insights
       handoff origin, if a banner is deemed useful)*

4. Staff user takes action or navigates away
   → Any action taken (e.g. initiating outreach, updating a referral
     state) follows the standard Rewards Manager confirmation and
     audit-logging patterns; the handoff origin does not alter these
     → Rewards Manager logs the outcome of completed handoff actions
     in the audit trail (Technical spec §12.2)
   → If the staff user navigates away without acting, no state change
     occurs; the highlighted record returns to its default visual state

UX boundary note: Rewards Manager is the system of record for individual patient reward transactions, referral records, and operational pending-action queues. Loyalty Insights is the system of record for programme-level cohort analysis and trend reporting. Staff users wanting aggregate reward-impact analytics are directed to Loyalty Insights; staff users wanting individual patient records or operational actions stay in Rewards Manager. This boundary must be reflected in any in-product navigation or contextual help copy. (Technical spec §12.1, §12.2, §2.1)

5.2 State Machines (Mirror of Technical Spec §3)

Referral state machine

Derived from technical spec §3.4.

Staff may perform a manual state override only from an authorised role; doing so opens a modal requiring a reason note before the override is committed. The override is visually flagged in the referral history as a manual action (staff actor, timestamp, reason). (Technical spec §3.4 rules)

States are displayed in a horizontal or vertical pipeline component on both the patient mobile app (simplified) and the staff dashboard (full detail with timestamps and channel data). (Technical spec §11.2)

Redemption state machine

Derived from technical spec §3.5, §3.6.

A Confirmed redemption cannot be reversed in the UI except through a manual adjustment flow. Attempting to reverse a Confirmed redemption outside that flow produces a clear error state explaining the path forward. (Technical spec §3.6 rules)

5.3 Empty / Loading / Error / Offline States

Every screen state below is derived from the data surfaces and non-functional requirements in technical spec §10, §14.

Patient rewards home (mobile)

• Empty state: Patient has no transactions yet. Show an explanatory panel describing how points are earned (attendance, recall, plan participation) with a clear prompt towards the next eligible action. No blank ledger table. (needs UX writer input — empty-state headline and body copy)
• Loading state: Skeleton loader showing balance card and transaction list shape. Points balance reads MUST return within 500 ms at P95 (§14); skeleton should clear quickly in normal conditions.)
• Error state: If balance cannot be retrieved, show a non-alarmist inline message with a retry action. Do not show a stale balance as if it were current. (needs UX writer input — error message copy)
• Offline state: Per the graceful-degradation requirement (§14), the last-known balance and recent transaction history may be displayed from cache with a clear "last updated" timestamp and a banner indicating the app is offline. Redemption initiation is blocked while offline.)

Staff Rewards & Referrals Dashboard (web portal)

• Empty state: No rewards activity yet — show a summary of which earning behaviours and redemption types are configured and a link to the Admin Control Plane. Framed as "programme not yet active" rather than a broken state.) (needs UX writer input)
• Loading state: Progressive skeleton loader on each dashboard card. Metrics cards load independently so partial data is useful.)
• Error state: Per-card error treatment with retry; the overall dashboard chrome remains intact so staff can still navigate to other sections.)
• Offline / degraded state: A persistent banner indicates that real-time data is unavailable. Previously loaded data is labelled with its fetch timestamp. Write actions (redemption confirmation, manual adjustment) are disabled with an explanation.)

Manual adjustment form

• Empty state: Not applicable — form is always initiated by a user action.
• Loading / submission state: Submit button enters a loading state; the form is locked to prevent double submission. Atomic failure (§17.2 rule 3) returns the form to an editable error state without partial commit.)
• Error state: Inline validation on reason note (cannot be empty) and points delta (cannot result in sub-zero balance). Server-side rejection surfaces a clear explanation and does not clear the form.)

Referral tracking (mobile)

• Empty state: Patient has not yet shared a referral. Show the share prompt prominently with channel options.) (needs UX writer input)
• Loading state: Skeleton pipeline component.
• Error state: If referral state cannot be fetched, show last known state with a staleness indicator and retry option.)

6. Component Inventory

New components introduced or extended by this module:

• Points balance card — compact display of current balance (points earned, redeemed, available), used on the patient mobile home and within the patient record in the web portal. (Technical spec §10.1, §10.2)
• Transaction history list — immutable, append-only timeline of earn, redeem, adjustment, and donation events with type badge, points delta, trigger label, and timestamp. Patient mobile and staff patient-record view. (Technical spec §3.1, §3.2)
• Referral pipeline component — horizontal or vertical state pipeline showing referral progress through all eight states (§3.4), with timestamps and channel data visible on staff view and a simplified version on patient mobile. Used in both the mobile app and the web dashboard.)
• Redemption wizard — stepped form for patient-initiated or staff-assisted redemption: option selection → eligibility check → summary and confirmation. Web portal and mobile app. (Technical spec §3.5, §3.6, §4.2)
• AI insight card — a visually distinct card used on the staff dashboard to surface AI Aiden suggestions. Always carries an AI badge; includes accept/dismiss actions that are audit-logged. Never appears on patient surfaces. (Technical spec §7)
• Referral share sheet — channel selector (WhatsApp / SMS / email / copy-link / QR) used to generate and share the referral link, recording channel and timestamp on share. Patient mobile app only. (Technical spec §5.1)
• Recognition layer widget — optional display of tier indicator, badges, and milestone progress. Visible only if the practice has enabled the recognition layer; absent otherwise (no dead toggles). Patient mobile app. (Technical spec §4.4)
• Charity donation wizard — stepped form for points-to-charity conversion including charity selection, optional Gift Aid declaration, and irreversible confirmation step. Patient mobile app. (Technical spec §6)
• Manual adjustment modal — restricted-role form for staff entering a points delta, mandatory reason note, and elevated re-authentication, with audit-logged confirmation step. Web portal only. (Technical spec §9, §17.2)
• Dashboard metrics strip — summary row of aggregate metrics (total points issued, redeemed, outstanding; active entitlements; pending redemptions; charity summaries) at the top of the Rewards & Referrals Dashboard, each metric clickable through to underlying records. (Technical spec §11.1)

Reused from the design system:

• Date-range filter control
• Tabbed navigation
• Skeleton loader
• Confirmation modal (with irreversibility warning variant)
• Form field with inline validation
• Toast notification
• In-app banner (persistent and dismissible variants)
• Badge / status pill (configurable colour and label)
• Empty state illustration container

7. Visual Design Notes

Points and transactions: Points values should use a consistent numeric format that is locale-aware (see §9). The visual hierarchy should lead with the available balance as the most prominent number on the patient view, with earned/redeemed totals subordinate. (Technical spec §3.1)

Colour: Semantic colour usage follows platform defaults. The recognition layer (tiers, badges) should use visually distinct but non-alarming colours — these are positive states, not statuses requiring attention. Redeemed/cancelled/voided states use a neutral palette to avoid confusion with error states. (Technical spec §4.4)

AI insight cards: Visually distinct from regular data cards — a consistent AI badge or icon, and a visual treatment (e.g. secondary background, distinct border style) that makes it immediately clear this is a suggestion, not confirmed data. Exact treatment (needs UX writer input). (Technical spec §7)

Referral pipeline: States should progress visually left-to-right (or top-to-bottom on mobile). Completed states use a positive/success treatment; current state uses an active/highlighted treatment; future states are muted. Manual override events in the history should be visually flagged. (Technical spec §3.4)

Iconography: Icon set follows platform defaults. Icons must never appear without a visible text label on patient-facing screens. On staff dashboard, icons in the metrics strip may be used alongside labels but not instead of them.)

Motion: State transitions in the referral pipeline may use a subtle progression animation. Confirmation modals and irreversibility warnings should not animate in a way that draws attention away from the warning text. prefers-reduced-motion must be respected throughout. (Technical spec §14)

• Typography: (follows platform design system defaults — needs design system reference)
• Colour: (follows platform semantic colour tokens — needs design system reference)

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

Referral pipeline component: The pipeline state component must provide screen reader–accessible labels for each state, including the current active state and any manual override flags. Visual-only pipeline progress (colour or icon alone) is not sufficient. (Technical spec §3.4)

AI insight cards: The AI badge must have an accessible text alternative (e.g. aria-label or visually hidden text) so screen reader users understand these are AI-generated suggestions, not confirmed system data. (Technical spec §7)

Manual adjustment re-authentication: If re-authentication triggers a modal or step-up flow, focus management must move correctly into and back out of that flow. (Technical spec §9)

Recognition layer: Tier and badge visuals must not rely on colour alone to convey meaning. Badge labels must be programmatically accessible. (Technical spec §4.4)

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 (platform default)

Points values: Points totals and deltas are numeric and must use locale-appropriate number formatting (thousands separators, decimal conventions). They should not be formatted as currency, consistent with the module's non-cash positioning. (Technical spec §1, §4.2)

Charity and Gift Aid: Gift Aid is a UK-specific regulatory concept. If the platform is deployed in non-UK locales, Gift Aid capture fields must be conditionally shown only where applicable. (Technical spec §6, open question §18.2)

Recognition layer labels: Tier names (e.g. Bronze / Silver / Gold) are practice-configurable; the UI must treat these as externalised strings rather than hard-coded copy to support localisation and practice customisation. (Technical spec §4.4, §17.3)

10. Cross-Module UX Touchpoints

Where each touchpoint below is listed, the integration contract is stated in technical spec §12 and §13.

• Appointment Manager — Earn events are triggered by attendance confirmation from Appointment Manager. The patient sees a new points entry in their transaction history shortly after an appointment; there is no in-module UI for the trigger itself. If earn processing is delayed, the patient mobile app should surface a "points pending" state rather than appearing to have missed an event. (Technical spec §12.1, §14)

• Recall & Reconnect — Recall compliance confirmation from Recall & Reconnect triggers earn events. UX handoff is the same pattern as Appointment Manager — a new transaction entry appears in the patient ledger view. No cross-module navigation is required from within Rewards Manager. (Technical spec §12.1)

• Care Plan Subscriptions / Hygiene Subscriptions — Active participation status from these modules triggers earn events. The patient transaction history entry should display the trigger type (e.g. "Care Plan participation") using the TriggerEvent label from the Reward Transaction. (Technical spec §12.1, §3.2)

• Product Shop — Purchase confirmations from Product Shop trigger earn events. When product redemptions are enabled, the Redemption wizard in Rewards Manager emits fulfilment instructions to Product Shop; the patient's redemption confirmation screen should set accurate expectations about fulfilment timelines, which are owned by Product Shop not Rewards Manager. (Technical spec §12.1, §12.2)

• Communication Hub — All patient-facing notifications (earn confirmation, redemption confirmation, referral reward issuance, nudges to referred individuals, expiring reward alerts) are delivered via Communication Hub. Rewards Manager does not send notifications directly. The UX must not imply immediacy for notification delivery that Communication Hub does not guarantee. (Technical spec §12.2, §2.2)

• Integrated Payments — When Integrated Payments is enabled, reward credits may be applied automatically at checkout. From the patient perspective, this appears as a deduction on their invoice rather than a manual redemption step. The Rewards Manager UI should reflect the resulting Confirmed redemption and updated balance after the checkout event. When Integrated Payments is not enabled, the staff-assisted redemption flow on the tablet and web portal is the fallback path. (Technical spec §4.2, §4.3, §12.2)

• Loyalty Insights — Loyalty Insights may initiate handoffs referencing Rewards Manager records. From a staff UX perspective, insights surfaced via Loyalty Insights may link back to specific referral or redemption records in the Rewards Manager dashboard. Rewards Manager logs the outcome of these handoffs. The UX boundary is clear: Loyalty Insights surfaces programme-level cohort analysis; Rewards Manager surfaces individual patient and operational records. (Technical spec §12.1, §12.2, §2.1)

• Performance Dashboards — Aggregate reward, referral, and charity metrics are emitted to Performance Dashboards for programme-level reporting. Within Rewards Manager itself, the dashboard shows operational records and pending actions, not programme analytics. A staff user wanting cohort or trend analysis is directed to Performance Dashboards. (Technical spec §12.2, §2.2)

• Access Manager — Role and permission resolution for all read, write, and adjust operations is synchronous via Access Manager. The Rewards Manager UI must not show controls to users who lack the required role; role-gated actions (manual adjustment, audit export, admin configuration) are absent from the UI entirely for users without the relevant permission rather than shown as disabled. (Technical spec §9, §12.1)

UX consistency rules:

• Action buttons for write operations (confirm redemption, submit adjustment, initiate outreach) appear bottom-right on mobile and tablet, top-right on web portal — consistent with platform-wide conventions.
• AI insight cards always appear in a dedicated section or clearly delineated region of the staff dashboard, never interspersed with confirmed operational data without visual distinction.
• The referral pipeline component uses the same state labels and visual progression on both the patient mobile app (simplified) and the staff dashboard (full detail) to ensure consistent vocabulary across surfaces.

11. Governance & Auditability

All governance requirements below are derived from technical spec §7, §8, §9, and §17.2.

AI suggestions are visually distinct from user actions. Every AI Aiden insight surfaced on the staff dashboard carries a persistent AI badge. The insight card's visual treatment (background, border, or icon) must differ from data cards showing confirmed system facts. Staff must take an explicit action (accept or dismiss) before any follow-up occurs; the decision is logged. (Technical spec §7)

Audit-significant actions show a confirmation step. The following actions display a confirmation modal with a summary and an irreversibility statement before committing: redemption confirmation, manual point adjustment, charity donation, manual referral state override, patient opt-out. (Technical spec §3.4, §3.6, §8)

The current user's role and active permissions are visible in the header. Role-gated controls (manual adjustment, audit export, admin configuration) are absent from the UI for users without the required permission. There are no greyed-out or disabled "ghost" controls for actions the current user cannot perform. (Technical spec §9)

Read-only states are visually distinct from editable states. Patient transaction history and referral history are always read-only. Staff views of a patient rewards summary are read-only except for explicitly role-gated actions. Read-only fields use a visually distinct treatment (e.g. non-editable field styling) so users do not attempt to edit them. (Technical spec §10.1, §10.2)

Manual adjustments are permanently surfaced in the transaction history. The reason note, actor, and timestamp of every manual adjustment are visible in the transaction history to any staff user with read access. There is no mechanism to hide or suppress a manual adjustment entry. (Technical spec §8, §17.2 rule 6)

Audit log export. The audit log export action is accessible only to users with the administrator or compliance role. The export triggers a download or a delivery mechanism appropriate to log volume; the action is itself logged. (Technical spec §8, §9)

Opt-out visibility. When a patient has opted out of the rewards programme, their record in the staff dashboard and patient record view carries a clear opt-out indicator. Earn events are suppressed immediately. Existing transaction history remains visible to staff in the audit record. (Technical spec §17.2 rule 8, §8)

12. Notification & Communication Patterns

All notifications listed below are delivered via Communication Hub. Rewards Manager emits trigger events only; it does not send notifications directly. (Technical spec §2.2, §12.2)

In-app banner (persistent): - Shown when earn processing is temporarily degraded and the displayed balance may not be fully current — includes a "last updated" timestamp and a brief explanation. Dismissible once processing recovers. - Shown when the patient has opted out and is viewing a read-only balance record, to confirm their opt-out is active. (Technical spec §14, §8)

In-app banner (informational, dismissible): - Shown to staff on the dashboard when real-time data is unavailable and the displayed figures are from a cached fetch. (Technical spec §14)

Toast (transient, auto-dismissing): - Redemption confirmed — brief success confirmation with updated balance. - Manual adjustment submitted — brief confirmation with adjustment summary. - Referral link copied to clipboard. - Outreach action logged successfully. (Technical spec §3.6, §5.3)

Push notification (via Communication Hub — not direct): - Reward earned — triggered on earn event confirmation. - Referral reward issued — triggered when Referral state reaches Reward Issued. - Expiring reward alert — triggered when a reward entitlement approaches expiry (if configured by practice). - Redemption confirmed — triggered on Redemption state Confirmed. (Technical spec §12.2, §4.2)

Email / SMS (via Communication Hub — not direct): - Referral invitation shared to referred individual (email or SMS per selected channel). - Consent-gated nudge to referred individual who has not yet booked. - Charity donation confirmation (if configured by practice). - Reward programme welcome message on first earn event (if configured by practice). (Technical spec §5.1, §5.3, §6, §12.2)

No notification may be sent without the relevant consent having been captured — particularly for referred individuals who are not yet registered patients. The UI must not offer staff an outreach action for a referred individual where consent_captured is false on the Referral record. (Technical spec §5.3, §3.3)

13. Open Questions

Items 1–5 below are carried forward directly from the technical spec's open questions (§18) as they have direct UX implications. Items 6–9 are UX-specific questions arising from this synthesis.

1. Nudge consent model — The technical spec does not define where or how consent for follow-up messaging is captured for non-registered referred individuals. Until this is resolved, the UX for the referral share flow cannot be fully specified — specifically, whether the consent capture step sits within Rewards Manager, Appointment Manager, or a standalone landing page. (Technical spec §18.1) (Decision required before referral nudge flows can be finalised.)

2. Gift Aid data fields and regulatory jurisdiction — The technical spec flags Gift Aid eligibility capture but does not specify the required data fields or the jurisdictions in which it applies. The charity donation wizard cannot be fully specified until this is resolved. (Technical spec §18.2) (Requires legal/compliance sign-off.)

3. Duplicate account detection signals — The technical spec mandates duplicate account detection for abuse prevention but does not define the detection algorithm. If detection triggers a UI-visible state (e.g. referral rejected or flagged for staff review), the UX treatment for that state needs defining once the detection approach is known. (Technical spec §18.3)*

4. NHS treatment exclusion definition in mixed practices — The definition of "NHS treatment" in a mixed NHS/private practice context is unresolved. This affects how the points balance card and transaction history handle excluded events — whether they appear as "not eligible" entries or are suppressed entirely. (Technical spec §18.4) (Needs product decision before earn-event UX is finalised.)

5. Referral cap default value — No recommended default is specified. If the practice has not configured a cap, the referral share sheet may need to surface a contextual explanation to patients about eligibility limits or lack thereof. (Technical spec §18.5) (Needs a safe default before the referral flow can be fully specified.)

6. "Points pending" state treatment — When an earn event is triggered but processing is briefly delayed (within the 2-second SLA in §14), should the patient see an immediate optimistic update or wait for server confirmation? The optimistic path risks showing an incorrect balance if the event fails; the pessimistic path may feel unresponsive. (Needs product and engineering alignment.)

7. Tier and badge labelling — The recognition layer uses practice-configurable tier names. Should Rewards Manager provide a default set of tier labels (e.g. Bronze / Silver / Gold as cited in the technical spec) that practices can override, or is the configuration entirely freeform? This affects how empty-state and onboarding copy for the recognition layer can be written. (Needs product decision.)

8. Staff dashboard saved filter views — The technical spec states that saved filter views must be persistable per staff user (§17.4). The UX for creating, naming, and managing saved filters has not been specified. (Needs UX writer and design input before dashboard build.)

9. Loyalty Insights handoff highlighted-record treatment — When a staff user arrives in Rewards Manager via a Loyalty Insights handoff deep link, the target record should be visually highlighted on load (see Flow 6, §5.1). The exact visual treatment for this highlight state, its duration, and whether a contextual banner explaining the handoff origin is shown have not been specified. (Needs design and UX writer input before the Loyalty Insights integration is built.)