Financial Insights – UX Specification

Related Technical Authority: Financial Insights – Technical Specification

1. Purpose

This UX specification governs the staff-facing experience of the Financial Insights module — the surfaces through which practice owners, managers, and providers understand how money is earned, collected, delayed, and distributed across their practice. It defines the interaction model for dashboards, insight cards, cashing-up, and associate statement workflows. The primary roles served are practice owners, practice managers, designated cashiers, and (in a limited read-only capacity) associate providers.

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
• Insight before action — because Financial Insights is a read-and-analyse layer that explicitly must not execute financial actions (technical spec §2.2), the UI must always present data and analysis first and gate any consequential action (acknowledgement, verification, approval) behind a deliberate, visible step rather than embedding it in the data view itself.
• Audit confidence — because every state transition, AI suggestion, and approval action is audit-logged (technical spec §8), the UI must make governance actions feel weighty and traceable — confirmation steps must clearly name the actor, the action, and its irreversibility where applicable.
• Human in the loop, visibly so — the technical spec §7 prohibits AI from auto-resolving, auto-acknowledging, or auto-archiving any Insight Card; the UI must never create the impression that the system has acted on behalf of the user — human action must always be visually attributable.

3. Design Philosophy

Financial Insights is an analytical confidence layer, not a transaction interface. Its mental model is a trusted morning briefing: surfaces should feel settled and informative by default, escalating attention only when something genuinely needs a human decision.

Empty states should be constructive. Because signal ingestion from multiple modules (technical spec §6.1) may take time on first setup, empty states should explain what data is expected, where it comes from, and what — if anything — the user needs to do to enable it. (Exact empty-state copy needs UX writer input.)

Error states must always name the source and offer a next step. Because data arrives from multiple upstream modules (Integrated Payments, PMS, Subscriptions Manager, Appointment Manager, HR & People Manager — technical spec §6.1), an error state should indicate which source failed and whether the displayed totals are partial, rather than showing a generic failure message.

AI suggestions are visually distinct from verified data at all times. An AI-generated explanation on an Insight Card is never presented as a system finding — it is presented as a suggested interpretation awaiting human review. The human's decision to accept, modify, or dismiss is always recorded.

Multi-step flows (cashing-up, statement approval) are wizard-style: one decision per screen, with clear back-navigation where state has not yet been committed. Irreversible steps (verification, approval) must show a confirmation modal naming the actor and action.

Read-only vs editable surfaces are unambiguous. The technical spec §3.7 makes Provider Statements immutable once Approved; the UI must change the editing affordance visibly at that state boundary — e.g. inputs become static values and an edit button is absent, not just disabled.

Undo/redo is not available for governed transitions (verify, approve, export, distribute). Because state transitions are audit-logged and immutable per technical spec §8, the design stance is to prevent accidental commitment through clear confirmation rather than to offer undo after the fact.

4. Primary Surfaces

4.1 Web Portal

The technical spec §5.1 names the web portal as the primary delivery surface for all Financial Insights features, and states that all RBAC-gated approval and adjustment actions are performed exclusively through the web portal.

Who uses it: Practice owners, practice managers, designated cashiers, group/multi-site managers, associate providers (limited read-only earnings view where enabled).

Key tasks performed here:

• Viewing the Financial Insights dashboard: headline metric cards (revenue, collected, outstanding, deposits, subscriptions) with configurable trend lines — technical spec §4.2.
• Drilling down from a summary metric to the underlying Financial Signals, with filters by date range, site, provider, and payment method — technical spec §4.2 and §13.4.
• Reviewing, acknowledging, and acting on Insight Cards, including AI-generated explanatory text — technical spec §4.3 and §3.5.
• Completing the daily cashing-up workflow: entering counted cash, recording variance notes, and submitting for verification — technical spec §4.4.
• Verifying a cash reconciliation record submitted by another user (two-person integrity) — technical spec §3.6 and §9.
• Reviewing, adjusting, approving, exporting, and distributing Provider Statements — technical spec §4.5 and §3.7.
• Accessing group / multi-site views with side-by-side site comparisons and a consolidated vs per-site toggle — technical spec §4.2.
• Viewing a personal read-only earnings summary (providers only, where enabled by practice configuration) — technical spec §4.5.

Hygiene subscription signals on the dashboard: The dashboard MUST surface hygiene-subscription revenue as a distinct financial signal category. Active subscriber metrics (total active subscribers, revenue collected in period) and payment-exception signals (payment failures, failed direct debit retries, fulfilment exceptions) generated by Hygiene Subscriptions are material to daily financial reporting and MUST be included in the headline metrics and drill-down signal list. Practice managers and finance roles rely on these signals to reconcile recurring revenue. Where a payment failure or fulfilment exception is flagged, the dashboard MUST surface it as a Financial Signal and, where anomaly detection triggers, as an Insight Card — with the source module identified as Hygiene Subscriptions in the SourceModuleReference field of the Signal drill-down panel. (See also: Cross-Module UX Touchpoints, §10.)

Product Shop revenue and refund signals: Where Product Shop is active, completed-order revenue and refund transactions generated by Product Shop MUST be ingested as Financial Signals and surfaced in the dashboard. Refund transactions MUST be shown with their reason code visible in the Signal drill-down panel so that cashiers and managers can distinguish product refunds from other deductions during daily cashing-up. Where a Product Shop refund affects a provider's earnings allocation, it MUST be reflected in the Provider Statement line items with a clear label indicating its origin. The dashboard MUST NOT aggregate Product Shop revenue and clinical revenue into an undifferentiated total without offering a per-source breakdown in the drill-down view. (See also: Cross-Module UX Touchpoints, §10.)

Layout pattern: Dashboard layout for the main financial overview (headline metric cards + trend lines); list-detail for Insight Cards and Provider Statements; wizard/step-form for cashing-up and statement approval flows — inferred from the feature set described in technical spec §4.2–4.5.

4.2 Tablet App

The technical spec §5.2 explicitly notes that no content was captured for the tablet surface and flags this as an open question (technical spec §15, question 1). No tablet-specific capability is asserted in the technical spec.

Who uses it: (to be determined — see Open Questions)

Key tasks performed here:

• (No tablet tasks can be specified until the tablet surface scope is resolved — see Open Questions.)

Touch ergonomics: one-handed reach zones considered; glove-friendly tap targets ≥48 px; all interactive controls ≥44×44 px touch target.

Note: Until the open question on tablet scope (technical spec §15, question 1) is resolved, this section should be treated as a placeholder. It is possible that Financial Insights has no tablet surface in the initial delivery.

4.3 Mobile App (Patient or Staff)

The technical spec §5.3 explicitly states that Financial Insights exposes no surfaces in the patient mobile app. No staff mobile surface is described anywhere in the technical spec.

Not applicable. Financial Insights has no patient-facing mobile surfaces. A staff mobile surface is not described in the technical spec and should not be designed without a corresponding technical decision.

5. Interaction Model

5.1 Primary Flows

Flow 1 — Financial dashboard review

Inferred from technical spec §4.2 — dashboards and reporting capability.

Start: User navigates to Financial Insights in the web portal
  │
  ├─ Dashboard loads with headline metric cards
  │    (revenue / collected / outstanding / deposits / subscriptions)
  │    (including hygiene subscription revenue and Product Shop order revenue
  │     where those modules are active)
  │
  ├─ User applies filters (date range / site / provider / payment method)
  │
  ├─ User selects a metric card or trend point
  │    └─ Drill-down opens to underlying Financial Signals list
  │         └─ User reviews signal detail
  │              └─ Returns to dashboard (breadcrumb / back)
  │
  └─ End: User has reviewed financial position for the selected scope

Flow 2 — Insight Card review and acknowledgement

Inferred from technical spec §3.5 and §4.3 — Insight Card state machine and generation rules.

Start: User sees an Insight Card (Generated state) in the Insight Cards list
  │
  ├─ User opens the card
  │    ├─ Card displays: category, severity, AI-generated explanation (if present),
  │    │   recommended follow-up action, supporting data snapshot
  │    │
  │    ├─ User acknowledges the card
  │    │    └─ Confirmation step: "You are acknowledging this insight as reviewed."
  │    │         Card transitions: Generated → Acknowledged
  │    │
  │    ├─ [Optional] User raises a follow-up task
  │    │    └─ Confirmation step before task is created in Task Manager
  │    │         Card transitions: Acknowledged → Action Created
  │    │
  │    └─ User resolves the card (only available after Acknowledged)
  │         └─ Confirmation step: irreversible; actor and timestamp recorded
  │              Card transitions: Acknowledged (or Action Created) → Resolved → Archived
  │
  └─ End: Insight Card is Archived; audit trail complete

Flow 3 — Daily cashing-up

Inferred from technical spec §4.4 and §3.6 — cashing-up workflow and Cash Reconciliation state machine.

Start: Cashier opens the cashing-up screen for their site and date
  │    (daily cash summary card is surfaced automatically — technical spec §4.4)
  │
  ├─ Cashier enters counted cash total
  │    ├─ System shows expected total (read-only) and calculated variance
  │    │
  │    ├─ If variance = 0:
  │    │    └─ Submit for verification (no notes required)
  │    │         Record state: Cash Recorded → Awaiting Verification
  │    │
  │    └─ If variance ≠ 0:
  │         └─ Variance notes field becomes mandatory before submission
  │              Record state: Cash Recorded → Awaiting Verification
  │
  ├─ Second authorised user (≠ cashier) opens the pending verification
  │    ├─ System blocks verification if the current user = entry author
  │    │    └─ Error shown; *(error message needs UX writer input)*
  │    │
  │    ├─ Verifier reviews expected, counted, variance, and notes
  │    │
  │    ├─ If variance within threshold:
  │    │    └─ Verifier confirms → Verified (Balanced) or Verified (Variance Logged)
  │    │
  │    └─ If variance exceeds configured threshold:
  │         └─ System automatically escalates to Task Manager
  │              Record state → Escalated
  │              Escalation task visible in Task Manager
  │
  └─ End: Record is Verified or Escalated; audit trail complete

Flow 4 — Provider Statement approval and distribution

Inferred from technical spec §3.7, §4.5, and §9 — Associate Statement state machine, provider earnings workflow, and RBAC table.

Start: System generates a Draft Provider Statement from aggregated signals
  │    State: Draft Generated
  │    (signals may include clinical production, Product Shop allocations,
  │     and deductions; payroll-ready data exported from HR & People Manager
  │     is consumed at this stage — see Flow 5)
  │
  ├─ Manager/Owner opens statement for review
  │    State: Under Review
  │    ├─ Line items displayed (production, deductions)
  │    ├─ Adjust action available (pre-approval only, RBAC-gated)
  │    │
  │    └─ Approve action (RBAC-gated: Manager / Owner)
  │         └─ Confirmation modal: "Approving this statement locks its content."
  │              State: Approved — line items become immutable
  │
  ├─ Export to accounting system (only available in Approved state)
  │    └─ Confirmation step; export destination displayed
  │         State: Exported to Accounting
  │
  └─ Distribute to associate (only available in Approved state)
       └─ Confirmation step; delivery method displayed
            State: Distributed
  │
  └─ End: Statement Distributed; audit trail complete

Flow 5 — HR payroll export to Provider Statement reconciliation

Inferred from HR & People Manager spec §4.5 — payroll period locking and payroll-ready CSV export — and the Provider Statement workflow in technical spec §3.7 and §4.5.

Start: HR & People Manager exports a payroll-ready data file for a locked
  │    payroll period (initiated in HR & People Manager, not here)
  │
  ├─ Financial Insights ingests the payroll export as a set of Financial Signals
  │    ├─ Signals are tagged with SourceModuleReference = "HR & People Manager"
  │    │   and the relevant payroll period
  │    │
  │    ├─ Dashboard reflects ingested payroll cost signals in the period view
  │    │
  │    └─ Provider Statements for the relevant period are updated to reflect
  │         payroll-derived figures (e.g. salaried associate earnings)
  │
  ├─ If the ingested payroll data conflicts with existing statement line items:
  │    └─ An Insight Card (reconciliation exception) is generated
  │         ├─ Category: reconciliation; severity: warning or critical
  │         └─ Recommended action: review in HR & People Manager and re-export
  │              (Financial Insights does not allow payroll figures to be
  │               corrected here — users are redirected to HR & People Manager)
  │
  └─ End: Payroll signals visible in dashboard and reflected in Provider Statements;
          any exceptions surfaced as Insight Cards with audit trail

The UI MUST make clear at the Provider Statement review step which line items originate from the HR payroll export, using the SourceModuleReference label "HR & People Manager" and the locked payroll period identifier. Where a payroll-derived figure cannot be adjusted within Financial Insights, the adjust control for that line item MUST be replaced with a redirect affordance ("Manage in HR & People Manager") rather than being silently disabled.

5.2 State Machines (Mirror of Technical Spec § 3)

Insight Card states

Mirrored from technical spec §3.5.

Cash Reconciliation states

Mirrored from technical spec §3.6.

Provider Statement states

Mirrored from technical spec §3.7.

5.3 Empty / Loading / Error / Offline States

Financial dashboard

• Empty state: No signals have been ingested yet from source modules. Show which integrations are expected and their connection status. Prompt the admin to verify integration configuration if relevant — inferred from technical spec §6.1 multi-source ingestion. (Copy needs UX writer input.)
• Loading state: Skeleton screens for metric cards and trend lines; progressive load so the headline metrics appear before drill-down data — inferred from the near-real-time dashboard performance requirement in technical spec §14. Spinner is avoided in favour of skeleton layout.
• Error state: Display which source module's data is missing or stale (e.g. "Payments data last updated 3 hours ago — figures may be incomplete"). Provide a refresh action. Do not show totals without indicating they may be partial — inferred from multi-source signal ingestion in technical spec §6.1 and the observability requirement in §14. (Error label copy needs UX writer input.)
• Offline state: Because Financial Insights is a web portal surface with no offline data model described in the technical spec, the offline state should clearly communicate that data cannot be loaded and the user should restore connectivity. Previously-loaded data must not be presented as current. (Offline message copy needs UX writer input.)

Insight Cards list

• Empty state: (Copy needs UX writer input — e.g. "No insights to review" vs "No anomalies detected for this period" — needs UX writer decision.)
• Loading state: Skeleton cards list.
• Error state: Name the failure (e.g. insight generation service unavailable) and provide a retry action — inferred from technical spec §14 observability. (Copy needs UX writer input.)
• Offline state: Last-loaded cards may be displayed as read-only with a staleness indicator; no state transitions (acknowledge, resolve) permitted offline.

Cashing-up workflow

• Empty state: Daily cash summary card shown for the site/date but no entry has been made yet — technical spec §4.4. Show the expected cash total and a clear call to action to begin entry. (Copy needs UX writer input.)
• Loading state: Skeleton for expected total and reconciliation form.
• Error state: If variance notes are not entered when variance ≠ 0, inline field validation error before submission is permitted — technical spec §13.2 rule 4. (Validation copy needs UX writer input.)
• Offline state: Cash entry should be blocked offline; the two-person integrity rule cannot be safely enforced without a live session.

Provider Statements list

• Empty state: (Copy needs UX writer input — e.g. no statements generated for the selected period.)
• Loading state: Skeleton list rows.
• Error state: Export or distribution failure should surface the destination, the failure reason where available, and a retry action — inferred from audit requirement in technical spec §8. (Copy needs UX writer input.)
• Offline state: Read-only view of previously loaded statement data; approval, export, and distribution actions blocked.

6. Component Inventory

New components introduced or extended by this module:

• Insight Card component — displays category, severity, AI-generated explanation (distinctly badged), recommended action, supporting data snapshot, and state-appropriate action controls (acknowledge / raise task / resolve). Appears in the Insight Cards list and as a notification prompt in the web portal — technical spec §3.2 and §4.3.
• Headline metric card — displays a single financial metric (revenue / collected / outstanding / deposits / subscriptions) with a trend indicator and drill-down affordance — technical spec §4.2.
• Cash reconciliation form — step-form accepting expected total (read-only), counted total (user input), computed variance (read-only), and mandatory variance notes field (conditionally required). Includes two-person verification step with actor attribution — technical spec §4.4 and §3.6.
• Provider Statement detail view — itemised line-item display with state-gated controls (adjust pre-approval; approve; export; distribute). Line items render as read-only once Approved — technical spec §3.7 and §4.5.
• AI insight badge — a persistent visual marker on any AI-generated text within an Insight Card, distinguishing it from verified system data. Includes disclosure of AI involvement — technical spec §7 and §2.1.
• Consolidated / per-site toggle — switches the group-level dashboard between an aggregated consolidated view and a side-by-side per-site comparison, preserving the active drill-through context — technical spec §4.2.
• Signal drill-down panel — displays the underlying Financial Signals list for a selected metric, with source module reference, amount, timestamp, and correction flag — technical spec §3.1 and §4.2.
• Variance escalation notice — in-context alert on a Cash Reconciliation record when it has transitioned to Escalated state, with a link to the corresponding task in Task Manager — technical spec §3.6 and §4.4.

Reused from the design system:

• Date range picker (preset: today / this week / this month / custom)
• Filter bar (multi-select: site, provider, payment method, severity)
• Confirmation modal (used for all irreversible transitions)
• Toast notification (used for non-critical operation confirmations)
• In-app banner (used for warning and critical severity alerts)
• Skeleton loader
• Breadcrumb navigation (for drill-down return paths)
• State/status badge
• Data table with sortable columns
• PDF export trigger control

7. Visual Design Notes

• Typography: (needs UX writer input — heading scale, body scale, and monospace usage for financial figures to be defined in the design system application for this module)
• Colour: Semantic colour is required for Insight Card severity: informational, warning, and critical must be visually distinct using the design system's semantic colour tokens — technical spec §3.2. Cash Reconciliation variance states (balanced vs variance logged vs escalated) must be distinguishable. AI-generated content must carry a distinct visual treatment, not using the same colour as verified system data — technical spec §7. Exact colour tokens to be confirmed against the design system; no hex values specified here.
• Iconography: Icon set to be confirmed; icons must never appear without a visible label or accessible text alternative. Sizing to follow design system guidance.
• Motion: Transitions used only for state changes that benefit from visual continuity (e.g. skeleton to content). Governance actions (confirmation modals, state transitions) must not use decorative animation. All motion must be suppressible via prefers-reduced-motion.

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

Module-specific accessibility considerations:

• Financial figures (currency amounts, variances, totals) must not convey meaning through colour alone — e.g. a negative variance must be indicated by a sign and/or label, not only by red text — inferred from the variance and severity display requirements in technical spec §3.2 and §3.3.
• The AI insight badge must have an accessible text alternative explaining what AI involvement means in context, not just a visual icon — technical spec §7 and WCAG 2.2 AA non-text content criterion.
• The two-person integrity confirmation step in cashing-up must be clearly described to screen readers, including which user is performing which role — technical spec §3.6 and §9.
• State badges (Approved, Verified, Escalated, etc.) must be announced to screen readers as part of the record's accessible description, not only as a visual overlay — technical spec §3.5–3.7.

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 required for initial delivery — to be confirmed if scope expands
• Currency amounts must be formatted using the locale-aware currency formatter consistent with the CurrencyCode field on Financial Signals (technical spec §3.1). The display must respect both the currency symbol and locale-specific number grouping and decimal conventions — e.g. GBP in en-GB formatting as the expected baseline for initial delivery.
• Date ranges displayed in dashboards and statements must use locale-aware date formats and must not use ambiguous numeric date formats (e.g. MM/DD/YYYY) — inferred from the date-range filter requirement in technical spec §13.4 and GDPR data accuracy obligations referenced in §14.

10. Cross-Module UX Touchpoints

Where this module's UX intersects with related modules:

• Task Manager — when a user raises a follow-up task from an Insight Card (Action Created state), or when an escalated cash reconciliation triggers an automatic task, the user is given a direct link to the created task in Task Manager. The task creation confirmation step in Financial Insights names the task and its destination. Return navigation from Task Manager back to the originating Insight Card or reconciliation record should be preserved via deep link — technical spec §6.2 and §3.5–3.6.
• Communication Hub — critical-severity Insight Card alerts are delivered to authorised staff via Communication Hub as notification prompts. Financial Insights does not manage the notification delivery itself; it emits an event to Communication Hub. The notification prompt in the web portal links directly to the relevant Insight Card — technical spec §5.4 and §6.2.
• Performance Dashboards — Financial Insights produces the outbound aggregated data feed consumed by Performance Dashboards. The user-facing boundary is that executive/consolidated views live in Performance Dashboards, not here. Where a user would naturally want to see the executive summary, the web portal should provide a clear navigational signpost to Performance Dashboards rather than duplicating that presentation layer — technical spec §2.2 and §4.6.
• Integrated Payments — Financial Insights consumes payment and balance signals from Integrated Payments. Discrepancies surfaced in Financial Insights cannot be corrected here; the UI must direct users to Integrated Payments (or the PMS) to resolve source-level discrepancies, with a clear message explaining the boundary — technical spec §6.3 and §11.
• Access Manager — RBAC enforcement affects which controls are visible and active at every screen. The current user's role and active permissions should be transparently surfaced, particularly at approval and verification steps, so users understand why a control is or is not available to them — technical spec §9 and §2.1.
• Subscriptions Manager, Appointment Manager, HR & People Manager, PMS — these are inbound signal sources only. The UX does not present direct navigation to these modules from within Financial Insights, but the Signal drill-down panel should show the SourceModuleReference for each Financial Signal, with a human-readable label identifying the originating module — technical spec §3.1.
• Hygiene Subscriptions — Financial Insights consumes recurring revenue signals, payment failure events, and fulfilment exception signals from Hygiene Subscriptions. These signals MUST be identifiable in the Signal drill-down panel by their SourceModuleReference label ("Hygiene Subscriptions"). Payment failures and fulfilment exceptions that breach anomaly thresholds will generate Insight Cards; the recommended follow-up action on such cards MUST direct the user to Hygiene Subscriptions to investigate the subscriber account, since Financial Insights cannot modify subscription or mandate data. Where the Hygiene Subscriptions integration is inactive or its signal feed is stale, the dashboard error state MUST name Hygiene Subscriptions as the affected source rather than displaying a generic data-unavailable message.
• Product Shop — Financial Insights consumes completed-order revenue signals and refund transactions from Product Shop. In the Signal drill-down panel, Product Shop signals MUST carry a SourceModuleReference label of "Product Shop" and MUST display the refund reason code where present, so that cashiers can distinguish product refunds from clinical adjustments during cashing-up. Where a Product Shop refund affects a provider's earnings allocation, the corresponding Provider Statement line item MUST be labelled with its Product Shop origin. Discrepancies in Product Shop order or refund data MUST NOT be corrected within Financial Insights; the UI MUST redirect users to Product Shop with a clear boundary message.
• Lab Manager — Financial Insights consumes lab cost signals derived from approved Lab Invoices. When a lab invoice is approved within Lab Manager, the resulting cost signal is ingested as a Financial Signal (SourceModuleReference: "Lab Manager") and will appear in the dashboard drill-down and, where relevant, as a deduction line in Provider Statements. Where a lab invoice approval triggers an anomaly (e.g. cost exceeds expected range), Financial Insights MUST generate an Insight Card for the relevant manager. The recommended follow-up action on such cards MUST direct the user to Lab Manager to review the underlying invoice, since lab invoice data cannot be adjusted within Financial Insights. Where the Lab Manager signal feed is unavailable, the dashboard error state MUST identify Lab Manager as the affected source.
• Smart Treatment Proposals — Financial Insights MAY surface proposal engagement metrics (proposals sent, acknowledged, accepted) as signals to help practice managers correlate treatment proposal conversion rates with revenue impact. Where these signals are available, they MUST be clearly labelled as originating from Smart Treatment Proposals (SourceModuleReference: "Smart Treatment Proposals") and presented as informational context in the dashboard rather than as transactional financial figures. Proposal acceptance and associated revenue realisation are distinct events; the UI MUST not conflate a proposal being accepted with revenue being collected — the corresponding payment signal from Integrated Payments remains the authoritative revenue event. (Whether proposal engagement signals are included in the initial delivery is subject to the integration contract with Smart Treatment Proposals — see Open Questions.)
• HR & People Manager — Financial Insights consumes payroll-ready data exported from HR & People Manager following payroll period locking (HR & People Manager spec §4.5). These signals appear as Financial Signals with SourceModuleReference "HR & People Manager" and are reflected as line items in Provider Statements for the relevant period. Where the HR payroll export introduces a figure that conflicts with an existing statement line item, Financial Insights MUST generate a reconciliation-exception Insight Card rather than silently overwriting the existing figure. Provider Statement line items derived from the HR payroll export MUST display the locked payroll period identifier and MUST NOT expose an adjust control within Financial Insights; instead, the UI MUST present a redirect affordance ("Manage in HR & People Manager") so that corrections are made at source before re-export.

UX consistency rules:

• Approval and verification actions must always require a deliberate confirmation modal; they must never be triggered by a single click without a review step — consistent with the audit and governance requirements in technical spec §8.
• AI-generated content must be visually distinct from system-generated and user-entered content across every surface — technical spec §7. This treatment must be consistent whether the AI badge appears on an Insight Card, a trend summary, or a suggested follow-up action.
• State badges must use consistent naming and visual treatment across Insight Cards, Cash Reconciliation Records, and Provider Statements — all three objects have distinct state machines (technical spec §3.5–3.7) but share the same governance visual language.
• Action buttons always appear bottom-right on tablet, top-right on web (to be confirmed against suite-wide layout standards).

11. Governance & Auditability

The following governance treatments are all directly implied by the audit and AI boundary requirements in technical spec §7 and §8.

• AI suggestions are visually distinct from user actions: Any AI-generated explanation on an Insight Card carries a persistent AI badge. The badge must remain visible even after the user has acknowledged the card, so that the audit trail is visually supported. AI-generated text is never presented without this marker.
• Audit-significant actions show a confirmation step: The following actions must each present a confirmation modal before committing: acknowledging an Insight Card; raising a follow-up task; resolving an Insight Card; entering and submitting a cash reconciliation; verifying a cash reconciliation; approving a Provider Statement; exporting a Provider Statement; distributing a Provider Statement. Each modal must name the actor (current user), the action, and — where the transition is irreversible — make that irreversibility explicit. (Exact modal copy needs UX writer input.)
• The current user's role and active permissions are visible: Because RBAC determines which controls are available at every step — particularly verification (must not be the entry author), approval (Manager/Owner only), and provider earnings visibility (configuration-dependent) — the UI must surface the user's active role and, where a control is unavailable, explain why in plain language rather than silently hiding it — technical spec §9.
• Read-only states are visually distinct from editable: Provider Statement line items must render as static values (not greyed-out inputs) once the statement is in Approved state — technical spec §3.7. Cash Reconciliation expected totals are always read-only. The visual language of read-only must not look like a disabled editable field.
• Correction signals are surfaced: Because Financial Signals are immutable and corrections are represented as new offsetting signals (technical spec §3.1 and §13.2 rule 1), the drill-down panel should display correction signals with a clear "correction" indicator, including a reference to the original signal — so users understand they are seeing the corrected picture and can trace back to the original.
• Escalation is visible and traceable: When a cash reconciliation is in Escalated state, the UI must show the escalation trigger (variance amount, threshold breached) and link directly to the Task Manager escalation task — technical spec §3.6.
• Audit history is a first-class UI surface: Consistent with the Admin Control Plane's principle that audit must be visible and queryable without database access, Financial Insights MUST provide an in-product audit history view accessible from within the operational console. This view MUST allow authorised roles (practice owners, practice managers, Finance Admins) to query the audit log for any governed action — Insight Card acknowledgements and resolutions, cash reconciliation submissions and verifications, Provider Statement approvals, exports, and distributions — filtered by actor, date range, record type, and site, without requiring database or back-end access. The audit history view is not a reporting surface; it is a governance surface. It MUST display: the actor's name and role at the time of the action, the action taken, the record affected (with a link to the record), the timestamp, and — where the action was irreversible — a clear indicator of that irreversibility. Audit history records MUST be read-only; no action taken from the audit history view may modify a record. (The specific RBAC gating for audit history access is subject to confirmation from Access Manager — see Open Questions.)

12. Notification & Communication Patterns

The following patterns are inferred from technical spec §5.4 and §6.2.

• In-app banner: Used for warning- and critical-severity Insight Cards surfaced as notification prompts to authorised staff in the web portal — technical spec §5.4. Banners should be dismissible but logged as seen; dismissal does not constitute acknowledgement of the underlying Insight Card.
• Toast: Used for non-critical operation confirmations: e.g. cash reconciliation submitted successfully, Provider Statement export dispatched, Insight Card acknowledged. Toasts are transient and do not require user action.
• Push notification: Not directly emitted by Financial Insights. Critical Insight Card alerts are delivered as events to Communication Hub, which owns push delivery — technical spec §6.2. Financial Insights must not implement push notification logic independently.
• Email/SMS: Not directly emitted by Financial Insights. Where email or SMS notification is required for critical alerts or statement distribution, this is routed via Communication Hub — technical spec §6.2. Financial Insights emits the event; Communication Hub owns the delivery channel and template.
• Task-based notification: Escalated cash reconciliations and anomaly alerts that result in task creation appear as tasks in Task Manager, visible to the relevant authorised users. This is the primary mechanism for ensuring critical issues requiring action are not missed — technical spec §3.6 and §6.2.

13. Open Questions

The following UX decisions cannot be resolved without additional input from the product owner, engineering, or partner module teams. This spec must not be promoted from draft to published until these are resolved.

1. Tablet surface scope — The technical spec is silent on whether any Financial Insights capability (e.g. read-only dashboard, Insight Card list) is exposed on the tablet app. Section 4.2 of this spec is a placeholder until this is answered. (Technical spec open question §15.1.)

2. Cash variance escalation threshold — default and configuration scope — The escalation threshold is described as "configured" but no default value is stated, and it is unclear whether it is configurable per site or only per practice. The cashing-up workflow UX must communicate the active threshold to the cashier at the point of entry. (Technical spec open question §15.2.)

3. Provider earnings summary — default state and who can toggle it — The read-only personal earnings summary is available "where enabled by practice configuration." The UX must know whether this is on or off by default and which roles can change it, because this determines whether the feature is shown to providers by default or requires an explicit opt-in step that practice staff must take. (Technical spec open question §15.3.)

4. Accounting system export — integration mechanism and in-scope systems — The export flow (Provider Statement → Exported to Accounting) cannot be fully specified until the accounting integration mechanism is defined (e.g. direct API, file download, OAuth). The confirmation step for export must name the destination and mechanism; this is currently a placeholder. (Technical spec open question §15.4.)

5. Performance Dashboards feed — update cadence and schema version ownership — The outbound feed is a first-class integration contract, but the cadence (real-time / micro-batch / scheduled) and schema versioning process are unresolved. This affects whether the Financial Insights dashboard should surface a "feed last updated" timestamp or a staleness warning. (Technical spec open question §15.5.)

6. MFA requirements for sensitive operations — The technical spec delegates MFA policy to Access Manager but does not confirm which Financial Insights operations (provider statement approval, cash verification) will be gated behind MFA. The UX must handle the MFA challenge flow coherently within the approval wizard — this cannot be designed until the Access Manager decision is confirmed. (Technical spec open question §15.6.)

7. Correction signal UX — The technical spec defines correction signals (immutable, with corrects_signal_id reference — §3.1 and §13.2 rule 1) but does not describe whether users can initiate a correction from the UI or whether corrections are always system- or admin-initiated. The drill-down panel design depends on this: if user-initiated corrections are permitted, the panel needs a correction action; if not, it needs a clear redirect to the appropriate system. (Implied by technical spec §4.1 — the module MAY accept manual correction signals initiated by an authorised user.)

8. Empty state copy and severity colour palette — The severity levels (informational / warning / critical) applied to Insight Cards require a confirmed colour palette from the design system before the component can be fully specified. (Needs design system confirmation and UX writer input for all empty-state copy strings.)

9. Smart Treatment Proposals engagement signals — initial delivery scope — It is unresolved whether proposal conversion metrics (proposals sent, acknowledged, accepted) will be included in the Financial Insights signal feed in the initial delivery. The cross-module touchpoint with Smart Treatment Proposals (§10) is specified conditionally; this question must be resolved before the dashboard metric card set can be finalised. (Requires confirmation from the Smart Treatment Proposals and Financial Insights product owners.)

10. Audit history view — RBAC gating — The audit history surface described in §11 requires confirmation from Access Manager of which roles are permitted to query the full audit log vs a scope-limited view (e.g. a practice manager may only see their own site's records). This affects the filter options and the data visible in the audit history view. (Requires confirmation from Access Manager team.)