Care Plan Subscriptions – UX Specification

Related Technical Authority: Care Plan Subscriptions – Technical Specification

1. Purpose

This UX specification governs the end-user experience for Care Plan Subscriptions — Primoro's in-house membership and capitation engine. It covers the interfaces through which practice staff configure and administer care plan tiers, manage members, and track outcomes; and the interfaces through which patients discover, enrol in, and monitor their care plan benefits. The primary roles served are Practice Administrators, Care Plan Coordinators, Receptionists, Clinicians, and Patients.

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.
• Entitlement clarity — a patient or staff member should never have to wonder whether a service is covered, why it isn't, or when it will be. Entitlement status, unlock dates, and reason codes are always surfaced in plain language rather than buried in plan documentation. Inferred from the technical spec's requirement to expose status, unlock_date, payments_required, and reason_code to both Appointment Manager and the patient mobile app (§10.3, §11.3).
• Billing trust — any change that affects what a patient pays, or when, must be explained before it takes effect, not after. Proration, price changes at renewal, and suspension events must be communicated proactively and in plain English. Inferred from §11.5, §11.6, and the failed-payment notification requirements in §6.2.
• Irreversibility is conspicuous — actions that cannot be undone (mid-term cancellation, plan version publish, entitlement model change) require an explicit confirmation step with a clear summary of consequences. Inferred from the technical spec's requirement for permission-gated, audit-logged overrides in §3.4 and §9.

3. Design Philosophy

Mental model: A care plan is a living contract between practice and patient. The UI treats it as such — it is never a simple toggle or a hidden setting. Every surface that touches a care plan shows the patient what they have paid for, what they have used, and what comes next.

Empty states: When a practice has no care plan tiers configured, the plan management screen should explain the value of setting one up and offer a direct path to plan creation rather than showing a blank table. When a patient has no plan, the mobile app surfaces a contextual prompt to explore available plans — not a blank card. (needs UX writer input — specific empty-state headline and supporting copy)

Error states: Errors in this module almost always have financial or clinical consequences. Error messages must say what went wrong, what the current state of the record is, and what the user can do next. Generic "something went wrong" patterns are not acceptable here.

AI suggestions: AI-generated prompts (enrolment or upgrade recommendations surfaced to staff; plain-language explanations of plan options) are visually distinct from user-initiated actions and from confirmed data. They carry an explicit AI badge and require human acceptance before any system state changes. AI cannot auto-enrol, auto-cancel, or auto-apply overrides. Inferred from §7.

Multi-step flows: Enrolment, plan creation, and mid-term override actions are all multi-step wizards. Each step shows its position in the overall flow, allows backward navigation without data loss (where the step has not triggered an irreversible action), and summarises the completed steps before final confirmation.

Undo/redo: State changes that are audit-logged and potentially irreversible (mid-term cancellation, plan version publish) do not support undo within the UI; instead, the confirmation step is the safety gate. This aligns with the technical spec's requirement for immutable audit trails (§8). Reversible in-session edits (plan tier configuration before publishing) do support discard/cancel.

Read-only vs editable surfaces: Historical plan versions, signed contracts, and audit logs are always read-only. Active plan configuration is editable only by authorised roles. Member records show clearly whether a field is live-editable or display-only.

4. Primary Surfaces

4.1 Web Portal

Who uses it: Practice Administrators, Care Plan Coordinators, Receptionists, Clinicians — drawn from the access control table in §9 and the staff dashboard requirements in §11.1.

Key tasks performed here:

• Create, version, and publish care plan tiers (Practice Administrator only) — from §4.1, §9, §18.3.
• Configure billing cadence, pricing, eligibility rules, waiting periods, entitlement models, and booking windows — from §4.1, §4.2, §4.3, §18.3.
• Enrol a patient in a plan via staff-assisted enrolment — from §5.2.
• View the member dashboard: active members, upcoming renewals, failed payments, suspension status, unused and missed entitlements — from §11.1.
• View and action the Care Plan Outcomes Dashboard: patients captured from appointments, follow-up state, overdue follow-ups, next action owner — from §12.4.
• Apply permission-gated staff overrides (mid-term cancellation, entitlement model change) with mandatory justification — from §3.4, §9.
• View and export the audit log — from §8, §9.
• View signed contracts stored in Document Hub — from §5.2, §8.
• View family entitlements for plan members — from §11.4.
• View analytics and KPI dashboards: subscription revenue, entitlement utilisation, profitability by plan type, renewal outcomes — from §14.1.
• Configure Digital Forms Workflow integration and Campaign Manager integration at practice level — from §12.1, §18.3.

Layout pattern: List-detail for member management and the outcomes dashboard; dashboard for KPI and analytics views; wizard for plan creation and enrolment; form for individual plan tier configuration. Inferred from the range of tasks and data volumes described in §11.1, §12.4, §14.1.

4.2 Tablet App

Who uses it: Clinicians and Receptionists within the appointment workflow — from §11.2.

Key tasks performed here:

• Complete the Care Plan Advisory step during qualifying appointment workflows (New Patient Exam, Exam, Scale & Polish) — from §11.2.
• View whether the current patient is on a care plan and, if so, which plan and tier — from §11.2.
• Record whether a plan was discussed, which plan was recommended, and the patient's response (Interested / Declined / Deferred) — from §11.2.
• View the recall interval for plan members (locked; not editable within the workflow) — from §11.2, §10.2.
• View real-time entitlement status for the current appointment's service type in booking context — from §10.3.

Touch ergonomics: The Care Plan Advisory step sits within the appointment workflow, which is a clinical surface. Tap targets must be ≥48 px. The recall interval lock state must be visually unambiguous — the field appears but is non-interactive and carries a visible lock indicator with a short explanation of why it is locked. Inferred from the strict rule in §11.2 that clinicians must not be able to change the recall interval for active plan members.

4.3 Mobile App (Patient)

Who uses it: Patients — the mobile app is identified as the primary enrolment channel and the primary ongoing engagement surface for plan members (§11.3, §12.3).

Key tasks performed here:

• Enrol in a care plan (primary channel): browse available plan tiers, set up a Direct Debit mandate via GoCardless, review and e-sign the plan Terms & Conditions — from §5.2, §11.3.
• View care plan status and tier summary — from §11.3.
• View real-time entitlement balances in plain language — from §11.3.
• View the Family Entitlements View: all family members under the plan, entitlement model (pooled or per-member), used vs remaining balances — from §11.4.
• View waiting-period status and unlock dates for entitlements that are not yet available — from §11.3, §4.2.
• View Upcoming Changes Banners when future plan changes are scheduled — from §11.5.
• View proration explanations in plain English where applicable — from §11.6.
• Receive and act on recall reminders linked to entitlement due dates — from §11.3, §10.2.
• Receive and act on follow-up prompts to complete enrolment if interested but not yet signed up — from §12.3.

4.4 Module Boundary: Care Plan Subscriptions vs Hygiene Subscriptions

Both modules use the word "subscription", but they represent fundamentally different commercial and clinical relationships. This boundary must be reflected in UX copy, information architecture, and staff training materials to prevent confusion across both staff and patient-facing surfaces.

Care Plan Subscriptions (this module) is a membership-tier model: a patient joins a named care plan tier, pays a recurring fee, and in return receives a defined set of clinical entitlements (examinations, hygiene visits, emergency appointments) over a plan year. The patient–practice relationship is a contractual membership backed by a GoCardless Direct Debit mandate and a signed Terms & Conditions document. The primary value exchange is guaranteed access to preventive clinical services at a predictable cost.

Hygiene Subscriptions is a consumables supply relationship: a patient subscribes to receive physical consumable products (for example, toothbrush heads or dental care items) on a recurring basis. It does not confer clinical entitlements or create a membership record in the Care Plan Subscriptions state machine.

UX implications of this boundary:

• The plan browse and enrolment surfaces in the patient mobile app MUST clearly present care plan tiers as clinical membership plans, not as product subscriptions. The terms "plan", "membership", and "clinical benefits" are preferred over the generic "subscription" on patient-facing copy. (needs UX writer input — specific copy guidance)
• Staff-facing screens (member dashboard, patient record Care Plan tab) MUST visually and structurally separate care plan membership status from any Hygiene Subscriptions fulfilment status. They may co-exist in a patient record but must never be presented in the same component or labelled with shared terminology that conflates the two.
• When navigating the portal, the Care Plan section and any Hygiene Subscriptions section MUST be distinct navigation items with distinct iconography. They MUST NOT share a common "Subscriptions" parent label in the navigation hierarchy without a clear differentiating sub-label.
• The mental models above MUST be reflected in any onboarding, help text, or tooltip copy that explains what a care plan is to a new patient or new staff member.

5. Interaction Model

5.1 Primary Flows

Flow 1: Staff creates a new care plan tier (Web Portal)

Inferred from §4.1, §18.3, §3.1.

Start: Practice Administrator selects "Create new plan" on plan management screen
  │
  ├─ Step 1: Define plan basics — name, tier label, billing cadence (monthly / annual)
  │
  ├─ Step 2: Set pricing — price per billing period, proration rules
  │
  ├─ Step 3: Define included entitlements — service type, visits per year, booking window
  │
  ├─ Step 4: Set eligibility rules — qualifying exam / hygiene visit window
  │
  ├─ Step 5: Set waiting-period and contribution rules — payments required before each entitlement unlocks
  │
  ├─ Step 6: Set entitlement model — pooled or per-member (with practice-level controls applied)
  │
  ├─ Step 7: Review summary — all configuration shown; user confirms or returns to edit
  │
  ├─ Publish action → plan version 1 created; becomes selectable for enrolment
  │
  └─ End: Plan appears in active plan list; version history begins

(needs UX writer input — step labels, button copy, confirmation modal copy for publish action)

Flow 2: Staff-assisted patient enrolment (Web Portal)

Inferred from §5.1, §5.2, §18.2.

Start: Staff selects patient record; navigates to Care Plan tab; selects "Enrol in plan"
  │
  ├─ Eligibility check — system validates qualifying exam and hygiene visit on record
  │   ├─ Not met → enrolment blocked; eligibility reason surfaced; flow ends
  │   └─ Met → proceed
  │
  ├─ Step 1: Select plan tier from available published plans
  │
  ├─ Step 2: Review plan terms — pricing, entitlements, waiting periods, billing date
  │
  ├─ Step 3: Direct Debit mandate setup (GoCardless-hosted or embedded flow)
  │
  ├─ Step 4: Patient reviews and e-signs Terms & Conditions
  │
  ├─ Confirmation → membership record created with status `pending_enrolment`
  │   → status transitions to `active` once mandate confirmed by GoCardless and T&Cs signed
  │
  └─ End: Member appears in active member list; signed contract stored in Document Hub

(needs UX writer input — eligibility block message, confirmation modal copy)

Flow 3: Patient self-enrolment (Mobile App)

Inferred from §5.2, §11.3, §18.2.

Start: Patient opens Care Plan section in mobile app; selects "Explore plans"
  │
  ├─ Browse available plan tiers — name, tier, price, included entitlements summarised
  │
  ├─ Patient selects a plan → detailed view: full entitlement list, waiting periods, T&Cs link
  │
  ├─ Patient selects "Join this plan"
  │
  ├─ Direct Debit mandate setup (GoCardless flow)
  │
  ├─ Review and e-sign Terms & Conditions
  │
  ├─ Confirmation screen — plan active summary, first payment date, entitlement unlock schedule
  │
  └─ End: Plan status card visible in app; signed contract accessible; recall reminders scheduled

(needs UX writer input — plan browse card copy, confirmation screen copy)

Flow 4: Clinician completes Care Plan Advisory step (Tablet App)

Inferred from §11.2, §12.2, §12.3.

Start: Clinician opens appointment for qualifying appointment type (Exam, Scale & Polish, etc.)
  │
  ├─ Care Plan Advisory step appears before recall interval screen
  │
  ├─ Patient IS on a care plan?
  │   ├─ Yes → recall interval displayed as locked; field non-interactive; lock indicator shown
  │   │         Clinician views entitlement status for this appointment type
  │   │         No discussion capture required; step marked complete
  │   │
  │   └─ No → Clinician prompted to discuss plan options with patient
  │             Clinician records: Discussed? (Yes / No)
  │                                Recommended plan (dropdown of published tiers, or None)
  │                                Patient decision: Interested / Declined / Deferred
  │             Step marked complete
  │
  ├─ If patient decision = Interested → follow-up task and Communication Hub thread created
  │   (by Communication Hub / Task Manager; not by this module directly)
  │
  └─ End: Appointment workflow continues; Digital Forms capture logged with timestamp,
          practitioner, and patient identifiers

(needs UX writer input — advisory step heading, lock indicator label, decision option labels)

Flow 5: Staff applies mid-term cancellation override (Web Portal)

Inferred from §3.4, §4.4, §9 — permission-gated, audit-logged, irreversible.

Start: Practice Administrator views member record; selects "Cancel plan (mid-term)"
  │
  ├─ Permission check — only Practice Administrator role may proceed
  │
  ├─ Warning screen — consequences summarised: benefits cease, no refund of prepaid period,
  │   action is irreversible and will be audit-logged
  │
  ├─ Mandatory justification field — free-text, required
  │
  ├─ Confirmation modal — actor name, timestamp, justification echoed back; requires explicit confirm
  │
  ├─ Membership status → `cancelled`; audit record written with actor ID, timestamp, justification
  │
  └─ End: Member record shows Cancelled status; outbound events emitted to Recall & Reconnect,
          Rewards Manager, Loyalty Insights

(needs UX writer input — warning screen copy, confirmation modal copy, justification field placeholder)

Flow 6: Patient views entitlement status including waiting-period lock (Mobile App)

Inferred from §11.3, §10.3, §4.2.

Start: Patient opens their Care Plan in the mobile app
  │
  ├─ Plan summary card: plan name, tier, status, renewal date
  │
  ├─ Entitlement list — per entitlement type (examination, hygiene, emergency):
  │   ├─ Available → visits used / remaining shown; next due date shown
  │   ├─ Not Yet Available → plain-language reason; unlock date and/or payments remaining shown
  │   ├─ Exhausted → visits used = total; next plan year date shown
  │   └─ Missed → booking window passed; forfeited; informational only
  │
  ├─ Family Entitlements View accessible from this screen
  │
  └─ End: Patient has full picture of current coverage without contacting the practice

5.2 State Machines (Mirror of Technical Spec § 3.4)

The following UI treatments mirror the CarePlanMembership state machine defined in technical spec §3.4.

Entitlement status values defined in technical spec §3.5 are surfaced as follows:

5.3 Loyalty Insights Enablement Visibility

Care Plan Subscriptions emits plan membership and payment-currency signals that Loyalty Insights uses as optional input to its loyalty score calculations (§10.6). This creates a visibility contract that the UX must honour in both directions.

When Care Plan Subscriptions is enabled: The module emits plan status events (enrolment, suspension, cancellation, lapse) to Loyalty Insights as background data feeds. No direct patient-facing UX is required within this module for that data flow; the Loyalty Insights module owns any loyalty-profile display that references plan longevity or payment-currency status.

When Care Plan Subscriptions is not enabled at a practice: Loyalty Insights will surface a configuration-choice indicator in its own staff-facing UI (per Loyalty Insights' own design philosophy) explaining that the Care Plan signal category is absent because the module is not licensed or enabled — not because data is missing. Care Plan Subscriptions itself has no UI obligation in this scenario, but the cross-module contract must be documented here so that both modules handle the absent-signal case gracefully rather than surfacing misleading empty states.

Staff-facing implication: Where a staff member views a patient's loyalty profile (in Loyalty Insights or a combined patient record view) and sees that no care plan signal is contributing, the explanation displayed by Loyalty Insights SHOULD be consistent with the enablement state of Care Plan Subscriptions. The Care Plan Subscriptions module MUST emit a clear enablement status indicator (enabled / disabled at practice level) that Loyalty Insights can consume to distinguish "no plan data because the patient has no plan" from "no plan data because the module is not active". This is an integration contract; the exact mechanism is to be defined between the two module owners.

(To be confirmed: the specific event or configuration flag through which Care Plan Subscriptions communicates its enablement state to Loyalty Insights — see Open Questions §13 item 5 regarding the Campaign Manager event contract as an analogous cross-module signal question.)

5.4 Empty / Loading / Error / Offline States

The following requirements are derived from the module's surfaces and data dependencies described throughout the technical spec.

Plan management screen (Web Portal)

• Empty: Practice has no plan tiers configured. Surface explanation of value and a direct "Create your first plan" action. (needs UX writer input — empty-state headline and supporting copy)
• Loading: Skeleton rows for the plan list table.
• Error: Plan list could not be fetched. Surface error with retry action and timestamp of last successful load.
• Offline: Read-only cached view of last-fetched plan list with an offline indicator. Plan creation and publishing require connectivity.

Member dashboard (Web Portal)

• Empty: No members enrolled yet. Surface prompt to either enrol the first patient or share the patient enrolment link. (needs UX writer input)
• Loading: Skeleton rows for member list; skeleton cards for KPI counters.
• Error: Member data unavailable. Surface error with retry; indicate which filters were active.
• Offline: Not available; display offline indicator and advise staff to use cached data cautiously.

Care Plan Advisory step (Tablet App)

• Empty (patient not on plan): Advisory step shown as designed; no empty state applies.
• Loading: Entitlement status payload is fetched in real time from Care Plan Subscriptions (§10.3). A brief skeleton or spinner within the step is shown while the payload loads. The workflow must not block the clinician for longer than the target p95 latency (to be confirmed — see Open Questions §13 item 3).
• Error: If the entitlement status payload cannot be fetched, the step surfaces a clear warning that plan status is temporarily unavailable and that the appointment should be treated as chargeable until status is confirmed. This aligns with the fail-open/fail-closed question in Open Questions §13 item 1; the UI treatment must be confirmed once that product decision is made.
• Offline: Advisory step displays last-known entitlement status with a prominent staleness indicator and timestamp. Recall interval lock remains enforced.

Patient mobile app — Care Plan section

• Empty (no plan): (needs UX writer input — copy for the "no active plan" state, with path to explore plans)
• Loading: Skeleton card for plan summary; skeleton rows for entitlement list.
• Error: Plan data temporarily unavailable. Surface plain-language message and retry option; do not show stale entitlement balances without indicating they may be out of date.
• Offline: Display last-cached plan status and entitlement balances with a clear offline/staleness indicator. Enrolment and Direct Debit setup require connectivity.

Care Plan Outcomes Dashboard (Web Portal)

• Empty: No Digital Forms captures yet for this period. (needs UX writer input)
• Loading: Skeleton rows.
• Error: Dashboard data unavailable; surface retry with last-fetch timestamp.
• Offline: Not available; display offline indicator.

6. Component Inventory

New components introduced or extended by this module:

• Plan tier card — displays plan name, tier label, billing cadence, price, and included entitlements summary. Used in the patient mobile app plan browse flow and in staff plan management. Inferred from §5.2, §11.3.
• Entitlement status row — displays a single entitlement type with status indicator, visits used/remaining, next due date, and (when status is not_yet_available) unlock date and payments remaining in plain language. Used in the mobile app care plan view, the staff member record, and the Family Entitlements View. Inferred from §10.3, §11.3, §11.4.
• Family entitlements panel — groups entitlement status rows by family member; shows entitlement model (pooled / per-member) and, for pooled plans, shared allowance and per-member usage. Accessible from plan summary and booking flows. Inferred from §11.4.
• Upcoming changes banner — persistent informational banner surfaced on care plan dashboards, appointment booking flows, and renewal journeys. States what is changing, when, and whether action is required. Inferred from §11.5.
• Proration explanation block — inline plain-English explanation of a billing adjustment: why it is happening, how pricing or entitlements are being adjusted, and whether it applies now or at renewal. Used in-app, in renewal summaries, and in plan documentation. Inferred from §11.6.
• Recall interval lock indicator — non-interactive display of the locked recall interval within the appointment workflow on the tablet app. Carries a visible lock icon and a short explanation of why the field is not editable. Inferred from §11.2.
• Care Plan Advisory step widget — structured step within the appointment workflow for recording discussion, recommendation, and patient decision. Contains discussion toggle, plan recommendation dropdown, and patient decision selector. Inferred from §11.2, §12.2.
• Membership status badge — compact badge showing current membership state (pending enrolment / active / suspended / pending renewal / cancelled / lapsed) with appropriate colour treatment. Used throughout member records and dashboards. Inferred from §3.4, §11.1.
• Care Plan Outcomes Dashboard — list-detail view showing appointment-captured care plan outcomes per patient, follow-up state, next action owner, and overdue follow-ups. Integrates with task assignment and Communication Hub message history. Inferred from §12.4.
• Override confirmation modal — two-step confirmation pattern used for irreversible permission-gated actions (mid-term cancellation, plan version publish, entitlement model change). Includes mandatory justification field, summary of consequences, and echoed actor/timestamp. Inferred from §3.4, §9.
• AI suggestion card — visually distinct card (AI badge, differentiated border treatment) used to surface AI-generated enrolment or upgrade prompts to staff. Requires explicit accept or dismiss; carries visible AI attribution. Inferred from §7.

Reused from the design system:

• Data table (filterable, sortable) — used for member list, plan list, audit log. Inferred from §11.1, §18.4.
• Wizard / stepper — used for plan creation, patient enrolment, and mid-term override flows. Inferred from §4.1, §5.2.
• Toast notification — used for non-critical confirmations (plan saved, entitlement updated). Inferred from §12 Notification patterns.
• In-app banner — used for suspension alerts, upcoming changes, proration notices. Inferred from §11.5, §11.6, §6.2.
• Form fields with programmatic labels — used throughout plan configuration and enrolment wizards. Inferred from §18.3.
• Read-only field display — used for locked fields (recall interval, historical plan versions, signed contracts). Inferred from §11.2, §4.1.

7. Visual Design Notes

• Typography: (needs UX writer input — heading and body scale decisions are outside the scope of this spec)
• Colour: Semantic colour is required for membership status badges and entitlement status indicators. Success/active treatment for active and available states; warning treatment for pending_enrolment, pending_renewal, and not_yet_available states; error/alert treatment for suspended and failed-payment indicators; neutral/muted treatment for cancelled, lapsed, exhausted, and missed states. Exact colour values are deferred to the design system. Inferred from §3.4, §3.5.
• Iconography: A lock icon is required for the recall interval lock indicator in the tablet appointment workflow (§11.2). An AI badge or icon is required for AI suggestion cards (§7). Status icons for entitlement states (available, locked, exhausted, missed) should never be icon-only; they must always be paired with a visible label or status text.
• Motion: (needs UX writer input — animation and transition decisions are deferred to the design system; no motion is required by the technical spec)

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

Additional requirements specific to this module:

• The recall interval lock indicator on the tablet app must be perceivable by screen reader users — the lock state and reason must be communicated programmatically, not conveyed by colour or icon alone. Inferred from §11.2.
• Entitlement status indicators must not rely on colour alone to convey state (available / not yet available / exhausted / missed); each state must have a distinct text label or icon-plus-label pairing. Inferred from §11.3, §3.5.
• The mandatory justification field in override confirmation modals must have a programmatic label and must surface inline validation errors accessibly. Inferred from §3.4, §9.
• The GoCardless Direct Debit mandate setup step (embedded or redirected) must be reviewed for accessibility compliance as part of enrolment flow testing. This is a third-party surface; any known accessibility limitations must be documented. Inferred from §5.2, §6.1.
• The technical spec references WCAG 2.1 AA for patient-facing surfaces (§19). This UX spec targets WCAG 2.2 AA across all surfaces as the stronger requirement.

9. Internationalisation

• Locale-aware date/time/number formatting
• All user-facing strings externalised
• Layouts tolerant of 30% string-length growth (German, French)
• RTL support: not explicitly required by the technical spec. To be confirmed if multi-jurisdiction billing rules (noted as a future extension in §18.5) bring RTL locales into scope.
• Currency display must use locale-aware formatting; all price-per-period values and proration amounts must respect locale currency symbol and decimal conventions. Inferred from §6.1, §11.6.
• Date display for unlock_date, next_entitlement_due_date, plan_end_date, and next_renewal_date must use locale-aware formats in all patient-facing surfaces. Inferred from §11.3, §11.5.

10. Entitlements, Usage & Recall Alignment

This section governs the detailed UX behaviour when entitlement checks intersect with appointment booking and recall workflows. It expands on the cross-module touchpoints described in §10 and aligns with Appointment Manager's constraint-visibility principle, which requires that every booking constraint — including care plan entitlement failures — must be explained to the user at the point at which it is encountered, not merely indicated.

10.1 Entitlement Failure Messaging in Appointment Booking

When a patient attempts to book an appointment for a service type that is covered by their care plan and the entitlement check returns a non-available status, the booking surface (owned by Appointment Manager, consuming the entitlement payload from this module) MUST surface an explanation that is:

• Specific — it identifies which entitlement is affected (e.g. "Your Scale & Polish entitlement") rather than presenting a generic "not covered" message.
• Actionable — it tells the patient or staff member what they can do next: wait until the unlock date, make additional payments, book at standard fee, or contact the practice.
• Sourced from this module's reason codes — the reason_code field in the entitlement status payload MUST be translated into plain English by the consuming surface. This module is responsible for defining the canonical plain-language mapping for each reason code; Appointment Manager is responsible for rendering it. The reason code–to–copy mapping table is to be agreed between the two module owners. (needs UX writer input — plain-language reason code copy)

The four entitlement status values each have a distinct constraint-visibility treatment:

When the entitlement status payload cannot be fetched (network failure or service unavailability), the booking surface falls back to the fail-open/fail-closed behaviour determined by the product decision in Open Questions §13 item 1. Whichever behaviour is chosen, the constraint message MUST inform the user that entitlement status is temporarily unavailable and explain the consequence (either "treated as covered pending confirmation" or "treated as chargeable until confirmed"). A generic error message without this context is not acceptable.

10.2 Recall Interval Lock — Cross-Surface Consistency

The recall interval for active plan members is locked by this module (cadence_locked = true) and must be presented consistently across all surfaces that display it:

• Tablet appointment workflow — locked field with lock indicator and reason label (see §4.2 and §6 recall interval lock indicator component).
• Web portal member record — recall interval displayed as read-only with a note explaining it is governed by the patient's active care plan. Staff may view it but may not edit it while the membership is active.
• Recall & Reconnect — the locked cadence is consumed by Recall & Reconnect, which does not offer interval-change options to plan members. From the patient's perspective in the mobile app, the next recall date is simply presented as their next due date without a visible lock; the lock concept is staff-facing only.

The lock indicator reason label used on the tablet and in the web portal MUST be identical in wording. (needs UX writer input — lock reason label copy)

11. Cross-Module UX Touchpoints

Where this module's UX intersects with related modules:

• Appointment Manager — at the point of diary booking, the booking interface consumes the entitlement status payload from Care Plan Subscriptions and surfaces coverage status, plain-language unlock reasons, and the option to defer or proceed at standard fee. The patient does not leave the booking flow; entitlement information is presented inline. Constraint visibility and reason-code-to-copy translation requirements are detailed in §10.1. Inferred from §10.3, §13.2.
• Recall & Reconnect — recall reminders surfaced to plan members link back to the patient's entitlement due dates owned by Care Plan Subscriptions. The recall interval lock (cadence_locked) prevents Recall & Reconnect from offering interval changes to plan members. From the patient's perspective this is seamless; the locked interval simply appears as their next recall date. Inferred from §10.4, §11.3.
• Integrated Payments — when a Direct Debit payment fails, the resulting staff-facing task and payment exception view are owned by Integrated Payments, not this module. The staff member transitions from a suspended membership record in Care Plan Subscriptions to the payment exception in Integrated Payments; the membership record should provide a contextual link or reference to the exception. Inferred from §6.2, §15.
• Communication Hub — all outbound patient notifications (payment failure alert, renewal reminder, recall reminder, follow-up prompt after Digital Forms capture) are delivered via Communication Hub. Care Plan Subscriptions triggers these via events; it does not own the notification surface. From the patient's perspective, notifications arrive in the channel Communication Hub delivers (app-first, with email/SMS fallback). Inferred from §6.2, §12.3, §13.2.
• Digital Forms Workflow — when Digital Forms is enabled, the clinician-facing appointment form surfaces care plan status and captures discussion outcomes. The UX continuity requirement is that the advisory capture step in Digital Forms is visually consistent with the Care Plan Advisory step in the tablet appointment workflow, since they serve the same purpose. Inferred from §12.1, §12.2, §11.2.
• Document Hub — signed contracts are stored in Document Hub and must be accessible to both patient (via the mobile app) and staff (via the web portal). The UX touchpoint is a "View your signed plan agreement" link within the membership record and the patient's care plan screen, which opens or downloads the stored document. Inferred from §5.2, §8.
• Rewards Manager — patients who are active plan members and whose payments are current will accrue points governed by Rewards Manager. The care plan screen in the mobile app may contextually surface points-accrual status if Rewards Manager exposes a display signal; however, Care Plan Subscriptions does not own that display. Inferred from §10.5, §2.2.
• Loyalty Insights — no direct patient-facing UX touchpoint; the integration is a background data feed. Staff-facing loyalty profile information (where surfaced by Loyalty Insights) may reference plan longevity data originating from this module. This module MUST emit a clear enablement status indicator that Loyalty Insights can use to distinguish "patient has no plan" from "Care Plan Subscriptions is not active at this practice" (see §5.3). Inferred from §10.6.
• Campaign Manager — patients who are eligible but not enrolled may receive marketing communications triggered by signals emitted from this module. This is a background integration; the patient-facing touchpoint is the campaign content itself, which is owned by Campaign Manager. Inferred from §11.7, §13.2.
• Task Manager — follow-up tasks created by Communication Hub in response to Digital Forms captures (patient interested, not yet enrolled) appear in Task Manager. Staff completing these tasks may link back to the Care Plan Outcomes Dashboard in this module. Inferred from §12.3, §12.4.
• Access Manager — the current user's role and active permissions are visible in the portal header per platform standard. Permission-gated actions (mid-term cancellation, plan version publish) are suppressed from the UI entirely for roles that do not hold the required permission, rather than shown as disabled. Inferred from §9.
• Finance Module — subscription income and GoCardless fees are logged to Finance Module; no direct patient-facing UX touchpoint. Staff financial reporting surfaces are owned by Finance Module but will reference plan and member data from this module. Inferred from §6.3, §13.2.

UX consistency rules:

• The membership status badge must use consistent colour semantics and label text wherever it appears — member list, member record, Care Plan Outcomes Dashboard, and patient mobile app. Inferred from the cross-surface nature of membership status in §11.1, §11.3, §12.4.
• Entitlement status language and icons must be identical in the mobile app (patient-facing) and the web portal (staff-facing), so that patients and staff are looking at the same picture when discussing coverage. This consistency extends to the Appointment Manager booking surface, which consumes the same entitlement status values and must render them using the same plain-language descriptions. Inferred from §10.3, §11.3.
• The "upcoming changes" banner pattern must be visually consistent across the web portal, mobile app, and any appointment booking surface where it appears. Inferred from §11.5.

12. Governance & Auditability

The following treatments are derived from the governance and audit requirements in §7, §8, §9, and §18.2.

• AI suggestions (enrolment or upgrade prompts surfaced to staff) are visually distinct from confirmed data and user-initiated actions. They carry an explicit AI badge and a differentiated border or background treatment. The staff member must explicitly accept or dismiss the suggestion before any system state changes. Accepting an AI suggestion that leads to a system action still requires the normal confirmation step for that action. Inferred from §7.
• Audit-significant actions (mid-term cancellation, plan version publish, entitlement model change) present a confirmation step that summarises the action, its consequences, and the fact that it will be recorded with the current user's name and timestamp. The user cannot complete the action without acknowledging this. Inferred from §3.4, §8, §9.
• The current user's role and active permissions are visible in the portal header per platform standard. This is particularly important on screens where permission-gated actions (override, publish) are available, so that users understand their authority level. Inferred from §9.
• Read-only states are visually distinct from editable states. Historical plan versions, signed contracts, and audit logs are always presented in a read-only surface treatment. Locked fields (recall interval in the tablet workflow) carry an explicit lock indicator rather than simply being greyed out. Inferred from §4.1, §8, §11.2.
• All audit log entries are surfaced in a read-only, exportable view in the web portal. The log shows actor, timestamp, action type, and any justification text for overrides. It cannot be filtered away or deleted from within the UI. Inferred from §8, §9.
• Where AI suggestions were surfaced and then accepted or rejected, this is recorded in the audit log and may be visible to Practice Administrators in the audit view. Inferred from §8.

13. Notification & Communication Patterns

All outbound notifications are delivered via Communication Hub; Care Plan Subscriptions does not send messages directly. The following patterns are inferred from §6.2, §10.2, §11.3, §11.5, §12.3, and §13.2.

• In-app banner (patient mobile app): Surfaced when the patient's plan is suspended due to a failed payment; when an upcoming change (price, entitlements, age band) is scheduled; and when a proration adjustment is pending. Each banner links to the relevant detail screen. Banners persist until the underlying condition is resolved or the patient acknowledges the change.
• In-app banner (web portal — staff): Surfaced on the member record when a membership is suspended, lapsed, or has an overdue follow-up. Surfaced on the plan management screen when a plan version change is pending publication.
• Toast: Used for non-critical confirmations in the web portal — plan tier saved, enrolment completed, entitlement model updated. Toasts are transient and do not require user dismissal.
• Push notification (via Communication Hub — NOT directly): Delivered to patients for: payment failure alert; upcoming renewal reminder; recall reminder linked to entitlement due date; follow-up prompt to complete enrolment after a Digital Forms capture where the patient expressed interest. (needs UX writer input — notification copy for each trigger type)
• Email / SMS (via Communication Hub — NOT directly): Used as fallback channels for patients not engaged via the mobile app. Triggers are the same as push notifications; channel selection and suppression rules are governed by Communication Hub configuration. (needs UX writer input — email/SMS template copy)
• Follow-up suppression: Follow-up notifications to patients who expressed plan interest (Digital Forms capture) are automatically suppressed once enrolment is completed, as required by §12.3. This suppression must be visible to staff in the Care Plan Outcomes Dashboard so they do not manually chase already-enrolled patients.

14. Open Questions

The following questions must be resolved before this spec is promoted from draft to published. Items 1–8 are carried over from the technical spec's open questions (§20) where they have direct UX implications; items 9–12 are UX-specific.

1. Fail-open vs fail-closed on GoCardless delay: If the entitlement status payload cannot be fetched at the point of booking, should the appointment booking surface treat the entitlement as available (fail-open) or unavailable and chargeable (fail-closed)? This determines the error-state copy and the default treatment in the Care Plan Advisory step. (Product decision required — see technical spec §20 item 1)

2. MFA for sensitive overrides: Which specific actions (mid-term cancellation, plan version publish, entitlement model change) will require MFA at the UI level? This affects the confirmation flow design. (To be confirmed against Access Manager's MFA policy — see technical spec §20 item 2)

3. Entitlement status payload latency: What is the maximum acceptable p95 latency for the entitlement status response to Appointment Manager? This determines the loading-state treatment within the appointment workflow. (To be defined during engineering design — see technical spec §20 item 3)

4. Lapsed re-enrolment flow: The state machine defines lapsed as a terminal state requiring a new CarePlanMembership. Is there a defined re-enrolment UX flow for lapsed patients in the mobile app and web portal, and does it require a fresh eligibility check presentation? (Design required — see technical spec §20 item 8)

5. Campaign Manager event contract: The integration is listed as optional; no event contract is defined. If Campaign Manager is enabled, what does the patient-facing experience look like when they receive a campaign triggered by their eligibility signal? Is there a consistent treatment for campaign-origin enrolment journeys? (Product decision required — see technical spec §20 item 5)

6. Saved views in staff dashboards: Is user-defined saved-view functionality in scope for the initial build? If so, the member dashboard and outcomes dashboard component inventory needs a saved-view picker component. (Scoping decision required — see technical spec §20 item 6)

7. GoCardless embedded vs redirect enrolment: The technical spec requires Direct Debit mandate setup via GoCardless but does not specify whether this is an embedded iframe/widget within the Primoro enrolment flow or a redirect to a GoCardless-hosted page. This has significant UX implications for the enrolment flow continuity and accessibility review. (Technical and product decision required)

8. Family plan: who can view other family members' entitlements? The Family Entitlements View is required but the technical spec does not define consent or visibility rules for individual family members viewing each other's entitlement usage. This is a privacy and UX design question. (Product and DPO input required)

9. Patient-facing plan naming: The technical spec allows practices to define their own plan names and tiers. Is there any platform-level guidance on naming that the enrolment UI should validate or suggest? (needs UX writer input and product decision)

10. Renewal journey — patient action required vs auto-renewal: The pending_renewal state may require patient action or may be fully automatic. The notification copy, banner content, and renewal summary screen differ significantly between these two cases. The UX for each path needs to be designed. (Product decision required — confirm default renewal behaviour)

11. Proration explanation placement in enrolment wizard: Should proration explanations appear as an inline step in the enrolment wizard (for patients joining mid-billing-period) or only in the confirmation screen and follow-up documentation? (UX decision required)

12. Accessibility review of GoCardless mandate step: The Direct Debit mandate setup surface (whether embedded or redirected) involves a third-party component. A formal accessibility assessment of that surface is required before the enrolment flow can be declared WCAG 2.2 AA compliant. (Engineering and QA action required)

13. Reason code–to–copy mapping table: §10.1 requires a canonical plain-language mapping for each entitlement status reason code, to be agreed between Care Plan Subscriptions and Appointment Manager module owners. This table must be produced before either module's enrolment or booking flows can be copy-reviewed. (Joint module owner action required — needs UX writer input)

14. Loyalty Insights enablement status signal: §5.3 requires this module to emit a practice-level enablement status indicator that Loyalty Insights can consume to distinguish "patient has no plan" from "module not active". The specific event or configuration flag mechanism is to be agreed between the two module owners. (Joint module owner action required)