Aftercare Manager – UX Specification

Related Technical Authority: Aftercare Manager – Technical Specification

1. Purpose

This UX specification governs the experience delivered by the Aftercare Manager module across all surfaces where aftercare instructions are created, delivered, monitored, and resolved. It serves three primary roles: patients (and their authorised carers) who receive and interact with post-treatment guidance; clinical and administrative staff who manage the template library, monitor follow-up progress, and respond to escalations; and compliance roles who need visibility of audit records. The specification ensures that every design decision supports the module's goal of turning aftercare into a proactive, governed stage of the patient journey rather than an unmanaged afterthought.

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.

Audit trail never hidden — every state transition that carries governance weight (delivery, escalation, resolution) must be inspectable by authorised roles without navigating away from the record. Inferred from the technical spec's §8 requirement that all audit log entries are immutable, exportable, and cover every state transition and interaction.

AI contribution always attributed — whenever Aiden has participated in a patient interaction, that participation is visually marked before a staff member acts on or resolves the record. Inferred from the technical spec's §7 AI boundaries and §8 audit requirements for AI inputs and outputs.

Carer context always surfaced — wherever a carer is the interacting user, the interface makes the dual-attribution context (patient + carer) visible so staff never lose sight of whose health record is at stake. Inferred from the technical spec's §2.1, §3.1, and §8 dual-attribution requirements.

3. Design Philosophy

The Aftercare Manager embeds a care-continuation mental model: the module presents itself not as an administrative tool but as the continuation of the appointment, picking up exactly where clinical contact ended. This informs every surface decision. Inferred from the technical spec's §1 statement that aftercare should be "a governed, proactive stage of the patient journey rather than an afterthought."

Empty states: An empty aftercare list for a patient means no instructions have yet been delivered — not that the patient is healthy or that nothing is needed. Empty states must be neutral and informative ("No aftercare instructions yet") rather than celebratory. Inferred from the technical spec's §13.2 rule that non-delivery events must be logged and surfaced, not silently dropped.

Error states: Delivery failures are a patient-safety concern, not a routine system error. The error state for a failed delivery must surface the failure visibly to staff and offer a clear recovery action (re-issue or contact patient), not merely log it silently. Inferred from technical spec §14 reliability and §13.2 rule 2.

AI suggestions: Aiden's outputs are always presented as AI-generated and structurally distinct from staff-authored content. Staff reviewing an escalated record must be able to distinguish, at a glance, which parts of the conversation were Aiden's responses and which were patient or staff messages. Inferred from technical spec §7 AI boundaries and §8 audit requirements for AI interaction logging.

Multi-step flows: Manual issuance, bulk issuance, and template editing are multi-step operations that carry audit and versioning consequences. These flows use a wizard or stepped pattern with explicit confirmation before write operations commit, so that accidental publishes and template overwrites cannot occur. Inferred from technical spec §4.2, §4.3, and §13.2 rule 11.

Undo / redo: Because delivered instructions and audit log entries are immutable, the module cannot offer undo on delivery, escalation, or resolution. Where a write is irreversible, the UI must signal this clearly before the user confirms. A re-issuance flow (with its own audit entry) is the correction mechanism, not undo. Inferred from technical spec §3.2 state machine rules and §8 immutability requirement.

Read-only vs editable surfaces: Delivered Aftercare Instructions are read-only to patients (they cannot edit their own instructions). Template editing is restricted to admin roles. Escalated conversations are read-only to all except the authorised clinical role to whom the conversation is routed. State is always visually distinguished from editability. Inferred from technical spec §9 access control table and §3.2 state machine rules.

4. Primary Surfaces

4.1 Web Portal

Who uses it: clinical and administrative staff (practice managers, clinicians, receptionists), and compliance/admin roles who access audit logs. Inferred from technical spec §5.2 and §9 access control table.

Key tasks performed here:

• Manage the aftercare template library — create, edit (triggering a version bump), and map templates to treatment types. Inferred from technical spec §5.2 and §13.3.
• Monitor the live dashboard of active Aftercare Instructions, filtered by delivery status, follow-up status, escalation state, AI vs. human involvement, origin, and date range. Inferred from technical spec §5.2 and §13.4.
• Review and respond to escalated conversations, seeing full prior AI interaction, patient responses, and treatment history alongside the record. Inferred from technical spec §5.2.
• Manually issue or re-issue aftercare instructions outside the appointment-completion flow. Inferred from technical spec §4.2.
• Perform bulk issuance to a defined patient cohort with attribution and confirmation. Inferred from technical spec §4.3.
• View and export audit logs (compliance and admin roles only). Inferred from technical spec §8 and §9.
• Configure practice-level settings: follow-up timing rules, escalation thresholds, staff routing rules for escalated conversations, and family/carer delivery settings. Inferred from technical spec §13.3.
• View AI Guardian findings surfaced alongside the relevant Aftercare Instruction record (when AI Guardian is enabled). Inferred from technical spec §5.2 and §13.5.

Layout pattern: list-detail for the instruction dashboard (filterable list on the left or top, instruction detail and conversation context on the right or below); form/wizard for template creation and bulk issuance; single-pane for configuration surfaces. Inferred from the nature of the data described in technical spec §5.2 and §13.4.

4.2 Tablet App

Who uses it: clinical staff in surgery who need in-surgery reference to aftercare guidance. Inferred from technical spec §5.3.

Key tasks performed here:

• Read-only review of active Aftercare Instructions for a patient, where tablet access is permitted by role. Inferred from technical spec §5.3.
• Reference aftercare guidance during or immediately after a treatment consultation. Inferred from technical spec §5.3 "in-surgery reference" language.

Touch ergonomics: tap targets ≥48 px for all interactive controls; the surface is read-only for the majority of users, so the primary affordance is legibility rather than form input. Inferred from technical spec §5.3 read-only scope and standard clinical-tablet ergonomics implied by the suite context.

4.3 Mobile App (Patient)

Who uses it: patients accessing their own post-treatment instructions; authorised carers (guardians) accessing instructions on behalf of a dependant via a Family Profiles session. Inferred from technical spec §5.1 and §2.1.

Key tasks performed here:

• Read delivered Aftercare Instructions at any time after delivery, with persistent access that is never revoked except under documented data-retention policy. Inferred from technical spec §5.1 and §13.2 rule 3.
• Ask questions and raise concerns within the aftercare conversation thread, with Aiden providing AI-first responses. Inferred from technical spec §5.1 and §4.4.
• Respond to automated follow-up check-in messages within the same thread as the original instruction. Inferred from technical spec §5.1.
• View carer-delegated instructions where the patient is a dependant and delivery has been made to a guardian's Family Profiles session. Inferred from technical spec §5.1 carer delivery paragraph.

5. Interaction Model

5.1 Primary Flows

Flow 1 — Appointment-driven automatic delivery (primary)

This flow is inferred from technical spec §4.1 and §13.2 rule 1.

1. Appointment Manager emits an Appointment Completed event carrying treatment type(s).
2. Aftercare Manager identifies the matching aftercare template for the treatment type.
3. If a template match is found: the Aftercare Instruction is created (state: Prepared), then immediately delivered to the patient via Communication Hub (state: Delivered). Delivery timestamp is logged.
4. If no template match is found: a non-delivery event is logged against the appointment record. (See Open Question 1 regarding whether an active staff alert is also raised.)
5. Patient opens the instruction on the mobile app → state transitions to Viewed.
6. Automated follow-up check-in dispatches per the configured schedule → state transitions to Follow-Up Triggered.
7. Patient responds; Aiden handles the response → state transitions to AI-Handled.
8. If Aiden's confidence, sentiment monitoring, or keyword detection exceeds an escalation threshold → state automatically transitions to Escalated; full conversation context is preserved; Task Manager receives a staff follow-up task; Communication Hub escalation thread is created.
9. Authorised clinical staff reviews the escalated record, responds as a named individual, and marks the record Resolved.

flowchart TD
    A([Appointment Completed event]) --> B{Matching template found?}
    B -- No --> C[Log non-delivery event]
    B -- Yes --> D[Create Aftercare Instruction\nState: Prepared]
    D --> E[Deliver via Communication Hub\nState: Delivered]
    E --> F{Patient opens instruction?}
    F -- Yes --> G[State: Viewed]
    F -- No --> E2[Delivery confirmation logged;\npatient not yet viewed]
    G --> H[Follow-up check-in dispatched\nState: Follow-Up Triggered]
    H --> I{Patient responds?}
    I -- Yes --> J[Aiden handles response\nState: AI-Handled]
    J --> K{Escalation threshold met?}
    K -- No --> L[AI closes interaction;\noutcome logged]
    K -- Yes --> M[State: Escalated\nFull context preserved\nTask Manager notified]
    M --> N[Authorised staff responds\nas named individual]
    N --> O[State: Resolved]

Flow 2 — Manual issuance by authorised staff

Inferred from technical spec §4.2.

1. Staff selects "Issue aftercare manually" from the web portal.
2. Staff selects patient, treatment type, and applicable template version.
3. Staff reviews instruction content (read-only at this step).
4. Staff confirms issuance — confirmation step makes clear this action is attributable and logged.
5. Aftercare Instruction is created (origin: Manual) and delivered; acting staff member is recorded.
6. Flow continues as steps 5–9 of Flow 1.

Flow 3 — Template create / edit

Inferred from technical spec §3.3, §4.2, and §13.2 rule 11.

1. Admin-role staff navigates to the template library.
2. To create: staff initiates a new template via a stepped form — content, treatment-type mappings, delivery rules, follow-up behaviour.
3. To edit: staff selects an existing template. The interface makes clear that saving an edit creates a new template version; prior versions are retained and remain accessible for audit.
4. Staff previews the template before publishing.
5. Staff confirms publish — a version bump is applied; the event is logged with the acting user.

Flow 4 — Bulk issuance

Inferred from technical spec §4.3 and §13.2.

1. Authorised staff initiates bulk issuance from the web portal.
2. Staff defines the patient cohort. (Cohort definition mechanism is an open question — see Open Question 4.)
3. Staff selects the aftercare template and version to issue.
4. Staff reviews a summary: cohort size, template name and version, acting user identity.
5. Confirmation step — the UI makes clear this action is irreversible, attributable, and will be logged in full.
6. Bulk dispatch proceeds; progress is surfaced to the authorising user.

Flow 5 — Carer-delegated access (patient is a dependant)

Inferred from technical spec §5.1 carer paragraph, §2.1, §3.1, and §8; and from Family Profiles UX §4.3 delegated-context-always-explicit principle.

1. Carer accesses the mobile app via their Family Profiles session as an authorised guardian.
2. Aftercare Instruction for the dependant is visible under the dependant's profile, not the carer's own record.
3. The instruction view opens with a persistent, prominent identity banner — clearly stating the patient's name and (where applicable) date of birth — so the carer is never in any doubt about whose instruction they are reading. The banner remains visible throughout the session; it must not be dismissable. Inferred from the Family Profiles principle that delegated context must always be explicit when a guardian is acting on behalf of a linked dependant.
4. The instruction itself carries a labelled notice clarifying that the carer is responsible for ensuring the guidance is followed on behalf of the patient — for example, administering post-treatment care, observing for symptoms, or attending a follow-up appointment. This responsibility notice is distinct from the clinical instruction content and uses plain language. (needs UX writer input — exact responsibility-notice copy) Inferred from Family Profiles UX §4.3 and the patient-safety intent of aftercare delivery.
5. Carer may read the instruction and interact with Aiden on behalf of the dependant. Within the conversation thread, any message sent by the carer is labelled "sent by [Carer name] on behalf of [Patient name]" so that the thread is unambiguous in both the patient-facing and staff-facing views.
6. All interactions carry dual attribution (PatientId + CarerId) in the audit log.
7. If escalation occurs, the escalated record visible to staff shows both patient and carer identity as distinct, labelled fields; the escalation panel highlights which messages in the prior thread were sent by the carer and which would have been direct patient interactions.
8. If the carer switches back to their own profile during the same session, the aftercare instructions for the dependant are no longer visible until the carer explicitly re-selects the dependant's profile. The UI must make the active profile context unambiguous at all times, including during any mid-session profile switch. Inferred from §10 (Cross-Module UX Touchpoints — Family Profiles) and the "carer context always surfaced" principle.

5.2 Document Hub Integration

Aftercare Instructions are documents in the sense governed by Document Hub: they have a lifecycle state, are delivered to specific recipients, and require acknowledgement tracking. The following interaction behaviours align the Aftercare Manager's delivery flows with Document Hub's single-source-of-truth and acknowledgement-surfacing model. Inferred from Document Hub UX spec requirements that all document lifecycle states, active shares, access permissions, and acknowledgements are always visible and audit-logged.

Lifecycle state alignment: Each Aftercare Instruction's state (Prepared, Delivered, Viewed, Follow-Up Triggered, AI-Handled, Escalated, Resolved) maps onto Document Hub's broader document lifecycle. Where Document Hub surfaces a document status to an authorised staff member, the status shown MUST reflect the current AftercareState, not a stale snapshot. Any state change within Aftercare Manager that has a Document Hub counterpart (e.g. delivery, first view) MUST propagate to Document Hub's record for the same document within the same transaction, so that the two systems never show contradictory states.

Active share visibility: When an Aftercare Instruction has been delivered to a carer on behalf of a dependant, Document Hub's active-shares view for that document MUST show both the patient record and the carer's Family Profiles session as distinct active recipients, not a single merged entry. Staff accessing Document Hub for a compliance review must be able to see exactly who holds access to a given instruction and in what capacity. Inferred from Document Hub's mandate that all active shares and access permissions are always visible.

Acknowledgement tracking: Document Hub requires that patient (or carer) acknowledgement of a document is recorded and surfaced. Within Aftercare Manager, the Viewed state transition (triggered when the patient or carer first opens the instruction) serves as the acknowledgement event. This event MUST be written to Document Hub's acknowledgement log as well as to Aftercare Manager's own audit log, so that compliance roles interrogating Document Hub receive a complete picture without needing to cross-reference Aftercare Manager separately. Where a carer acknowledges on behalf of a dependant, the acknowledgement record in Document Hub carries dual attribution (PatientId + CarerId) consistent with §5.1 Flow 5 step 6 above.

Staff visibility of Document Hub state: On the staff web portal instruction detail view, a read-only Document Hub status indicator MUST be present, showing whether the instruction has been acknowledged and whether any access anomalies have been flagged by Document Hub. This indicator is informational only; staff cannot alter Document Hub state from within Aftercare Manager. If Document Hub surfaces a sharing or access anomaly for an instruction (e.g. access by an unrecognised session), this MUST appear as a distinct, labelled notice in the instruction detail view — it must not be visually confused with an escalation alert, a follow-up status, or an AI Guardian finding.

Immutability consistency: Document Hub's immutability requirements for delivered documents are consistent with Aftercare Manager's own rule that delivered instructions are read-only. The UI MUST NOT offer any edit affordance on a delivered instruction on any surface, and any attempt to route an edit through Document Hub's version-control mechanism must be treated as a new-version issuance with its own audit entry, not as a modification of the delivered record. Inferred from Document Hub's version-control model and technical spec §3.2.

5.3 State Machines (Mirror of Technical Spec § 3)

The following state treatments are inferred from the Aftercare Instruction state machine defined in technical spec §3.2.

The transition from any state back to Prepared is blocked once Delivered is reached; the UI must not offer this as an option. Inferred from technical spec §3.2 rule "An Aftercare Instruction MUST NOT return to Prepared once it reaches Delivered."

An escalated record cannot be resolved by patient or carer interaction alone; the "Mark resolved" control must only be available to authorised clinical roles. Inferred from technical spec §3.2.

5.4 Empty / Loading / Error / Offline States

Patient mobile app — instruction list

• Empty state: "No aftercare instructions yet" — shown when no instructions have been delivered. Neutral tone; no call to action unless the patient has a pending appointment. Inferred from technical spec §5.1 persistent access requirement. (needs UX writer input — exact empty-state copy)
• Loading state: Skeleton card layout while instruction content loads, matching the shape of a delivered instruction card. Inferred from persistent-access requirement implying the content may load from remote.
• Error state: Inline error with a retry action if instruction content cannot be loaded. Because patients have a right to re-read their instructions at any time, a failed load must offer a clear path to retry and, if persistent, surface a contact prompt. Inferred from technical spec §14 availability and §13.2 rule 3. (needs UX writer input — error copy and contact prompt)
• Offline state: Previously loaded instructions should be readable offline (cached). New check-in responses cannot be submitted without connectivity; the UI should make this clear with a calm inline notice rather than a blocking error. Inferred from technical spec §14 availability and the patient-facing nature of the surface.

Staff web portal — instruction dashboard

• Empty state: "No active aftercare instructions match your filters" when filters return no results; "No aftercare instructions yet" when the practice has not yet delivered any. Neutral; offer a clear filter-reset action. Inferred from technical spec §13.4 filtering requirement.
• Loading state: Skeleton list rows while the dashboard data loads. Inferred from the dashboard nature of §5.2.
• Error state: Inline error banner at the top of the dashboard if data cannot be loaded, with a retry action and a note that the issue has been logged. Escalated records failing to load are a priority error and must be surfaced with higher visual weight than a general load failure. Inferred from technical spec §14 reliability requirement. (needs UX writer input — error banner copy)
• Offline state: The staff web portal is not expected to operate offline; a full-screen offline notice with a retry action is appropriate. Inferred from web portal nature and the real-time escalation routing requirements in technical spec §6.

Staff web portal — template library

• Empty state: "No templates yet — create your first aftercare template to enable automatic delivery." Paired with a clear primary action. Inferred from technical spec §4.1 requirement that delivery only occurs when a matching template exists. (needs UX writer input — exact copy)
• Loading / error / offline: Standard patterns as above.

6. Component Inventory

New components introduced or extended by this module:

• Aftercare instruction card — summary card displaying treatment type, delivery state badge, viewed indicator, follow-up status, and escalation flag. Appears in the patient mobile app instruction list and the staff web portal dashboard. Inferred from technical spec §5.1, §5.2, and §13.4.
• Aftercare conversation thread — a persistent threaded view combining the original instruction content, automated follow-up messages, Aiden (AI) responses (visually distinct), and patient replies. Appears in the patient mobile app and in the staff escalation detail view. Inferred from technical spec §5.1, §5.2, and §3.1 ConversationId field.
• AI-attributed message bubble — a message bubble variant with an AI badge (visual indicator that this response was generated by Aiden, not a staff member). Appears within the aftercare conversation thread. Inferred from technical spec §7 AI boundaries and §8 AI interaction audit requirements.
• Escalation alert panel — a high-visibility panel surfacing an escalated record to staff, including trigger reason, timestamp, full prior conversation, patient and carer identity (where applicable), and the "Mark resolved" action. Appears on the staff web portal dashboard and instruction detail view. Inferred from technical spec §5.2 and §3.2 escalation rules.
• Template version history row — a read-only row in the template editor showing prior versions with their version identifier, created-by, and created-at values. Supports audit inspection without navigating away. Inferred from technical spec §3.3 and §13.2 rule 11.
• Delivery status indicator — a compact label or badge showing the current AftercareState, used both on instruction cards and within the detail view. Inferred from technical spec §3.2 state machine and §13.4 filtering views.
• Non-delivery notice — an inline notice shown on the relevant appointment record (surfaced via the Appointment Manager integration context) and on the staff dashboard, indicating that no template matched a completed appointment. Includes a prompt to issue manually or create a template. Inferred from technical spec §4.1 and §13.2 rule 2. (See Open Question 1 on whether this also generates an active task.)
• Dual-attribution identity block — a compact display within an escalated instruction record showing both patient name/ID and carer name/ID as distinct entities, preventing confusion between guardian and patient identity. Inferred from technical spec §2.1, §3.1, §8, and §13.2 rule 7.
• Bulk issuance confirmation summary — a pre-commit summary panel in the bulk issuance wizard showing cohort size, template name and version, and acting user, before the irreversible dispatch is confirmed. Inferred from technical spec §4.3.
• Audit log viewer — a read-only, filterable, exportable log view for compliance and admin roles, showing all state-transition and interaction events for an Aftercare Instruction. Inferred from technical spec §8 and §9.
• Follow-up schedule display — a read-only timeline or list showing scheduled, triggered, and responded follow-up events for a given instruction. Appears in the staff instruction detail view. Inferred from technical spec §3.1 FollowUpSchedule field and §13.4.
• Carer identity banner — a persistent, non-dismissable banner displayed at the top of an Aftercare Instruction view when a carer is accessing the instruction on behalf of a dependant. Displays the patient's name and date of birth prominently; includes a plain-language responsibility notice. Appears on the patient mobile app only. Inferred from Family Profiles UX §4.3 delegated-context-always-explicit principle and §5.1 Flow 5.
• Document Hub status indicator — a read-only inline indicator within the staff web portal instruction detail view, showing Document Hub acknowledgement state and surfacing any access anomalies flagged by Document Hub. Distinct in visual treatment from escalation alerts, follow-up status indicators, and AI Guardian findings. Inferred from §5.2 Document Hub Integration.

Reused from the design system:

• Form fields and validation patterns (used in template create/edit wizard and manual issuance form)
• Filterable data table (used for the staff instruction dashboard and template library)
• Confirmation modal (used for irreversible actions: manual delivery, template publish, bulk issuance, resolve escalation)
• Toast notification (used for non-blocking confirmations: template saved, instruction issued)
• In-app banner (used for escalation alerts and non-delivery notices requiring staff attention)
• Skeleton loader (used across all loading states)
• Badge / status chip (used for AftercareState values throughout)

7. Visual Design Notes

• Colour — semantic usage: The escalated state requires a high-attention semantic colour (error/warning register) to ensure it is not missed on the staff dashboard. AI-attributed content uses a distinct neutral-cool tint or border style to differentiate it from human-authored messages. Resolved state uses a low-contrast neutral to recede from active work. Specific hex values and design tokens are outside the scope of this UX spec. Inferred from technical spec §3.2 escalation requirements and §7 AI attribution requirements.
• Iconography: The AI badge on Aiden-generated messages must include a label as well as an icon — icon-only is not sufficient where governance is at stake. Escalation-state badges must not rely on colour alone; a distinct icon or text label must accompany any colour signal. Inferred from §7 AI boundaries and WCAG 2.2 non-colour-dependence principle.
• State legibility on mobile: On the patient mobile app, the instruction state (delivered, viewed, follow-up pending) should be expressed through typographic weight and a brief status label rather than colour alone, to support users with colour vision deficiency. Inferred from accessibility and technical spec §5.1.
• Typography, specific colour tokens, animation timing, and icon set selection: (needs UX writer input — align with Primoro design system)
• Motion: Transitions into the escalation alert panel may use a brief entrance animation to draw attention, but must respect prefers-reduced-motion. AI-typed response animations (if used in the conversation thread) must also be suppressible. Inferred from accessibility requirements and the high-attention nature of escalation.

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 (Windows), VoiceOver (iOS/macOS), and TalkBack (Android).

AI content must be announced to screen readers: Aiden-generated messages in the conversation thread must carry an accessible label identifying them as AI-generated (e.g. via aria-label or visible text), so screen reader users are never unaware that a response was machine-authored rather than from a practice team member. Inferred from technical spec §7 AI attribution requirements.

Escalation alerts must be announced: When a new escalation surfaces on the staff portal, it must be communicated to assistive technology via an appropriate live region, so staff using screen readers are not reliant on visual scanning alone. Inferred from technical spec §5.2 escalation dashboard requirement.

Dual-attribution identity block must not conflate names: The patient and carer names displayed in an escalated record must be programmatically distinct (separate labelled elements), not visually concatenated in a way that could be ambiguous to a screen reader. Inferred from technical spec §8 dual-attribution requirement.

Carer identity banner must be announced on session entry: When a carer navigates into a dependant's Aftercare Instruction, the carer identity banner (§6) must be announced by assistive technology as a live region update, so that screen reader users are made aware of the delegated context without having to navigate back to the top of the page. Inferred from Family Profiles UX §4.3 delegated-context-always-explicit principle and the "carer context always surfaced" core principle.

Plain-language instructions on the patient mobile app: The aftercare instruction content is clinical guidance for patients in a post-treatment state. Reading-level guidance for content authors should be included in the template editor to encourage accessible content. This is an authoring concern, not a rendering concern. Inferred from technical spec §1 "clear, treatment-linked instructions" goal. (needs UX writer input — reading-level guidance for template authors)

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 specified in the technical spec. (needs product input — confirm whether RTL locales are in scope for this module at MVP tier.)

Follow-up timestamps displayed to patients must honour the patient's locale and timezone, not the practice's server timezone, to avoid confusing recovery guidance timing. Inferred from technical spec §3.1 timestamp fields and the patient-facing delivery surface in §5.1.

Template content localisation is not addressed in the technical spec; if multi-language content is required, the template model will need extension. (needs product input — is multi-language template content in scope?)

10. Cross-Module UX Touchpoints

Where this module's UX intersects with related modules:

• Appointment Manager — the primary trigger for automatic aftercare delivery originates in Appointment Manager (Appointment Completed event). From the staff web portal perspective, a non-delivery notice may surface within or alongside the appointment record view, offering the option to issue manually. On escalation, Aftercare Manager may recommend a follow-up appointment, which routes back to Appointment Manager. The patient should experience these as a continuous journey, not as two disconnected modules. Inferred from technical spec §6.1, §6.2, and §10.
• Communication Hub — the aftercare conversation thread is delivered through Communication Hub, but the UX context remains the Aftercare Manager. The patient must not feel they have left aftercare and entered a generic messaging surface. Staff responding to an escalated conversation do so within the Aftercare Manager's escalation panel, not a separate communications inbox. The distinction between aftercare-thread messages (owned here) and general practice communications (owned by Communication Hub) must be visually clear to avoid confusion. Inferred from technical spec §2.2, §6.1, §6.2, and §11.
• Task Manager — on escalation, a staff follow-up task is created in Task Manager. The staff user should be able to navigate from the task (in Task Manager) to the escalated Aftercare Instruction record without losing context. A deep link or contextual reference from the task to the instruction record is required. Inferred from technical spec §6.2.
• Family Profiles — carer access to a dependant's aftercare is mediated by Family Profiles. From the patient mobile app UX, a carer switching between their own profile and a dependant's profile must find aftercare instructions clearly scoped to the correct individual. The UI must make the active profile context unambiguous at all times, including during any mid-session profile switch; the carer identity banner (§6) activates immediately on entry to a dependant's instruction and deactivates on return to the carer's own profile. Inferred from technical spec §5.1, §6.1, and §8.
• Access Manager — role-based access determines which controls are visible and active on every surface. Staff whose access has been revoked must find all Aftercare Manager surfaces inaccessible immediately; no stale session should show them actionable controls. The current user's role context should be derivable from the Access Manager session. Inferred from technical spec §6.1, §9, and §13.2 rule 10.
• AI Guardian — when AI Guardian is enabled, its findings referencing an AftercareId surface within the Aftercare Manager staff view alongside the relevant instruction record. The visual treatment must make clear that an AI Guardian finding is a separate analytical signal, not a patient message or an Aiden response. Inferred from technical spec §5.2 and §13.5.
• Document Hub — Aftercare Instructions are governed documents whose lifecycle state, active shares, and acknowledgements must remain consistent with Document Hub's records. The staff instruction detail view surfaces a Document Hub status indicator (§6) as a read-only signal; any access anomaly flagged by Document Hub is shown as a distinct notice, visually separate from escalation alerts and AI Guardian findings. State changes in Aftercare Manager that have Document Hub counterparts (delivery, first view/acknowledgement) propagate to Document Hub within the same transaction. Inferred from Document Hub UX spec requirements and §5.2 Document Hub Integration.
• Audit & Compliance — the audit log viewer within Aftercare Manager surfaces events that are written to Audit & Compliance. For compliance roles, the export function must produce an output consistent with whatever format Audit & Compliance defines as its standard. Inferred from technical spec §6.2 and §8.

UX consistency rules:

• Escalation-state records are always surfaced at the top of any list or dashboard view, regardless of chronological sort order, so staff cannot miss an outstanding escalation by scrolling. Inferred from the urgency implied by technical spec §3.2 and §5.2 escalation requirements.
• AI-attributed messages use the same visual treatment (AI badge + distinct bubble style) whether viewed on the patient mobile app or in the staff portal escalation detail — the same event must look like the same type of thing on every surface. Inferred from technical spec §7 and §8.
• Action buttons for irreversible operations (deliver, bulk issue, resolve) always appear with a confirmation modal before committing; this pattern must be consistent across web portal and tablet. Inferred from technical spec §3.2 and §4.2–§4.3 audit requirements.

11. Governance & Auditability

AI suggestions (Aiden responses) are visually distinct from human-authored messages at all times. The AI badge and distinct message bubble style must be present in the conversation thread on both patient-facing and staff-facing surfaces. A staff member reviewing an escalated record must be able to tell immediately which parts of the prior conversation were Aiden and which were patient messages. Inferred from technical spec §7 AI boundaries and §8 AI audit requirements.

Audit-significant actions require an explicit confirmation step before they are committed. Actions in scope: manual delivery of an instruction, bulk issuance, template publish (with version bump), and marking an escalated record as Resolved. The confirmation step must name the acting user and state that the action will be recorded. Inferred from technical spec §4.2, §4.3, §3.2, and §8.

The current user's role and active permissions are not surfaced as a persistent UI element by this module directly — this is governed by Access Manager. However, where a control is unavailable due to role restrictions (e.g. only an authorised clinical role may mark Resolved), the UI must indicate that the action requires a specific role rather than silently hiding the control. Inferred from technical spec §9 and the "no dead toggles" principle.

Read-only states are visually distinct from editable states throughout. On the tablet surface (read-only for all users), no edit affordances appear. On the staff web portal, delivered instruction records are read-only in their content body; only the state-transition controls and response fields are actionable. Inferred from technical spec §5.3 tablet read-only requirement and §3.2 state rules.

Every Aftercare Instruction detail view must provide access to the audit log for the record, restricted by role. Compliance and admin roles see the full log; clinical roles see state-transition events relevant to patient care; other roles see only their own contributions. Inferred from technical spec §8, §9, and §13.4.

Non-delivery events — where no template matched a completed appointment — must be surfaced visibly in the staff dashboard and on the relevant appointment context, not buried in a raw audit log. The non-delivery notice must offer a clear next action. Inferred from technical spec §4.1 and §13.2 rule 2.

Guardian identity in all escalated records is shown as a distinct, labelled field alongside the patient identity. The UI must never merge or concatenate these or present them in a way that implies they are the same person. Inferred from technical spec §8 dual-attribution requirement.

12. Notification & Communication Patterns

The following patterns are inferred from the audit events, escalation behaviour, and integration contracts defined in technical spec §4, §5, §6, and §8. All messages that leave the Aftercare Manager's own surfaces are routed via Communication Hub, never directly.

• In-app banner (staff web portal): Surfaced for escalation alerts requiring staff attention, and for non-delivery notices where no template matched a completed appointment. Banners persist until the staff member takes an action (responds to escalation, dismisses or investigates non-delivery). Inferred from technical spec §5.2 escalation dashboard and §4.1 non-delivery logging.
• Toast (staff web portal): Used for non-blocking confirmations: template saved, instruction issued successfully, resolution confirmed. Toasts auto-dismiss. Inferred from the need to confirm write operations without blocking the staff workflow.
• In-app notification (patient mobile app): Triggered when a new Aftercare Instruction is delivered, and when an automated follow-up check-in is sent. Delivered within the patient app's notification surface. Inferred from technical spec §5.1 follow-up check-in behaviour.
• Push notification (via Communication Hub — not directly): Used to alert the patient that a new aftercare instruction has been delivered or a follow-up check-in requires their response. Push delivery is routed through Communication Hub. Inferred from technical spec §6.2 outbound to Communication Hub and §5.1.
• In-app escalation alert (patient mobile app): When a conversation is escalated to the practice team, the patient should receive a calm, informative notification that a member of the team will be in touch, without causing alarm. The message must not reveal escalation threshold details. Inferred from technical spec §3.2 escalation state and the calm-by-default principle. (needs UX writer input — exact patient-facing escalation notice copy)
• Email / SMS (via Communication Hub — not directly): May be used for aftercare delivery confirmation or follow-up prompts where the patient has a preference for non-app communication, routed entirely through Communication Hub. This module does not own the delivery mechanism. Inferred from technical spec §6.2 outbound to Communication Hub.
• Task notification (via Task Manager): On escalation, the staff follow-up task created in Task Manager generates its own notification within that module's surfaces. Aftercare Manager does not own this notification; it only emits the event. Inferred from technical spec §6.2 outbound to Task Manager.

13. Open Questions

The following questions must be resolved before this UX spec is promoted from draft to published. They are aligned with the open questions in the Aftercare Manager Technical Specification.

1. Non-delivery active alert vs. passive logging: When no template matches a completed appointment, technical spec §4.1 mandates logging but leaves unresolved whether an active staff alert or task is also generated. The UX treatment differs significantly: passive logging means a non-delivery notice is only visible when a staff member looks at the relevant record, whereas an active alert or task pushes the issue into the staff workflow. Resolution is required before the non-delivery notice component can be fully specified. (Mirrors Technical Spec Open Question 1.)

2. Default follow-up schedules: The follow-up timing configuration surface (§13.3) and the follow-up schedule display component cannot be populated with meaningful defaults until default follow-up intervals per treatment type are defined. Empty or unconfigured follow-up schedules must be handled gracefully in the UI, but the out-of-the-box experience depends on this decision. (Mirrors Technical Spec Open Question 2.)

3. Escalation threshold defaults and tuning UI: The escalation thresholds for AI confidence, sentiment, and keyword detection are configurable (§13.3), but no default values or ranges are specified. The configuration UI for these thresholds cannot be fully designed (appropriate input types, ranges, validation, and guidance copy) until initial defaults and permitted ranges are defined. (Mirrors Technical Spec Open Question 3.)

4. Bulk issuance cohort definition mechanism: The bulk issuance flow (Flow 4 in this spec) requires a cohort definition step. It is unresolved whether cohort definition is owned by Aftercare Manager (requiring a patient-selection or filter UI) or by another module (in which case Aftercare Manager receives a pre-defined cohort). The UX of the bulk issuance wizard depends on this ownership decision. (Mirrors Technical Spec Open Question 4.)

5. Multi-site template override policy: The tablet and web portal surfaces for template management cannot fully express the relationship between group-level and site-level templates until it is resolved whether individual sites may override group templates and under what conditions. If site-level overrides are permitted, the template library view must indicate provenance (group vs. site) and the edit flow must enforce appropriate constraints. (Mirrors Technical Spec Open Question 5.)

6. (needs UX writer input — confirm whether RTL locale support is required at MVP tier, as this affects layout investment for the patient mobile app and staff web portal.)

7. (needs UX writer input — confirm whether multi-language aftercare template content is in scope at MVP, as this affects the template create/edit form design.)

8. (needs UX writer input — define the patient-facing copy for the escalation notice on the mobile app: the message must be calm and informative without disclosing AI confidence thresholds or clinical detail.)

9. Carer responsibility notice copy: Flow 5 step 4 and the carer identity banner component both require a plain-language responsibility notice making clear that the carer is accountable for acting on the instruction on the dependant's behalf. The exact wording must be agreed with a UX writer and reviewed by a clinical content owner before this notice is implemented. (needs UX writer input and clinical content review)

10. Document Hub state propagation contract: §5.2 specifies that delivery and acknowledgement events propagate from Aftercare Manager to Document Hub within the same transaction. The precise API contract and failure-handling behaviour (e.g. what happens if Document Hub is unavailable at the moment of delivery) must be agreed between the Aftercare Manager and Document Hub technical owners before the Document Hub status indicator component can be fully specified. (needs cross-module technical resolution)