Smart Dashboards – UX Specification

Related Technical Authority: Smart Dashboards – Technical Specification

1. Purpose

This UX specification governs the experience of the Smart Dashboards module — the role-based operational awareness layer of Primoro. It defines how live signals from across the platform are surfaced, prioritised, and turned into direct action for all staff types, on both the web portal and the staff mobile app. The primary roles served are Front-of-House (FOH), Treatment Coordinator (TCO), Practice Manager/Operator, Practitioner, and Dental Nurse.

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.
• Signal completeness — every item surfaced on a dashboard must carry an actionable destination. A signal without a direct action path must not be displayed, because an unactionable signal is noise, not information. This reflects the technical spec's rule that AlertSignals without a valid ActionLink must not be rendered (§3.4, §13.2).
• Role clarity — the dashboard a user sees is determined by their role and site, not by personal configuration. This zero-configuration stance, stated in §4.1, must be reflected in every layout decision: the interface should never imply that the user has misconfigured something by showing them the wrong view.
• Today-first — dashboards orient around what is happening now and in the immediate week. Nothing in the primary view should imply a historical or trend analysis stance; that framing belongs to the Performance Dashboard Suite (§4.2, §11).

3. Design Philosophy

Smart Dashboards embody an exception-first, action-oriented mental model. The interface assumes that if everything is on track, the user needs very little — a calm confirmation of normality. The interface comes to the foreground only when something needs attention, and when it does it must immediately hand the user a path to act. This is not a reporting surface; it is an operational cockpit.

Empty states: An empty dashboard — where all signals are on track and no tasks are outstanding — is a positive state and should be communicated as such, not as a loading failure or missing data. The empty state must reassure, not confuse. (needs UX writer input — exact messaging and iconography for the "all clear" empty state)

Error states: If a source module is unavailable and its widgets cannot load, the dashboard must degrade gracefully, displaying the remaining widgets and clearly indicating which source is temporarily unavailable. The user must never be blocked from navigating directly to source modules. This reflects the reliability non-goal in §14.

AI suggestions: In the current build, AI is not embedded in the dashboard surface (§7). When AI Guardian is enabled as an optional module in a future release, its signals will arrive as AlertSignals and must be visually distinguished from system-generated signals. See §11 of this document for the governance treatment.

Multi-step flows: The dashboard itself does not host multi-step flows. Its role is to surface a signal and hand off to the owning module for any action that requires more than a single confirmatory tap (e.g. confirming an appointment, taking a payment). Inline actions that are single-step (confirm, arrive, cancel for FOH) may be completed without leaving the dashboard view.

Undo/redo: Because Smart Dashboards is a read-only surface that launches actions owned by source modules, undo/redo is not a dashboard-layer concern. Any reversibility UX is the responsibility of the receiving module.

Read-only vs editable: The entire dashboard layer is read-only with respect to source data. The distinction the UI must communicate is between viewing a signal and acting on it — acting always launches to the owning module or triggers a governed inline action. No dashboard card should ever imply that the user can edit the underlying record directly within the dashboard.

4. Primary Surfaces

4.1 Web Portal

Who uses it: all authenticated staff roles — FOH, TCO, Practice Manager/Operator, Practitioner, Dental Nurse. Configuration of role-to-dashboard mappings is performed by Admins via the Admin Control Plane, not via the dashboard surface itself (§13.3).

The web portal dashboard is the default landing view after login (§5.1). The role-appropriate dashboard renders immediately; optional module widgets load asynchronously and must not block the primary view.

Key tasks performed here:

• Reviewing today's operational status at a glance, scoped to the user's role and authorised site(s).
• Identifying overdue, at-risk, and exceptional states using the On Track / Attention Needed / Overdue / Escalated status semantics (§2.1).
• Launching direct action on a signal — navigating to the underlying task, appointment, document, or follow-up without additional navigation (§4.3).
• Switching between sites, where the user holds authorisation for multiple sites (§13.4).
• Toggling between Today and This Week views on time-sensitive widgets (§13.4).
• FOH staff: confirming, arriving, cancelling appointments and taking payments as inline actions directly from the dashboard (§4.4).
• TCO staff: reviewing the treatment pipeline (presented → accepted → declined) and initiating conversion actions (call, email, schedule) from the dashboard (§4.5).
• Manager/Operator staff: reviewing live operational KPIs, overdue tasks, compliance and risk alerts, and multi-site roll-up where authorised (§4.6).

Layout pattern: Dashboard — a card-based layout where each DashboardCard occupies a defined region of the viewport. Optional module widgets occupy supplementary card positions that load asynchronously. The primary-signal cards must render before optional widgets.

4.2 Tablet App

The technical specification does not define a dedicated tablet surface for Smart Dashboards. The staff app (§5.2) is described as a mobile surface. Tablet usage by clinical and operational staff is not explicitly addressed in the technical spec.

(needs UX writer input — confirm whether the staff app is expected to adapt to tablet form factor, and if so, which roles use it in that context. Until confirmed, treat this surface as a mobile-first responsive layout rather than a purpose-built tablet view.)

Touch ergonomics: Touch targets ≥44×44 px on mobile/tablet; glove-friendly tap targets where clinical context applies.

4.3 Mobile App (Staff)

Who uses it: all authenticated staff roles. The staff app dashboard is the default home view after login on the mobile surface, as confirmed by Staff App Mode (§4.3 of that spec, which explicitly designates Smart Dashboards as the default post-login landing surface on mobile). This designation is authoritative: any change to the default landing surface on the staff app must be agreed with the Smart Dashboards and Staff App Mode owners jointly.

The staff app dashboard has a defined primary content contract that is distinct from the web view. The three primary signals, in fixed order, are (§5.2, §13.2 rule 9):

1. Tasks — the user's open and due task queue.
2. Updates — relevant alerts, notifications, and workflow changes since last login.
3. Rota highlights — the user's scheduled sessions and any coverage gaps relevant to their role.

Additional role-specific cards (e.g. appointment list for FOH, forms status for Practitioner) may appear below these three primary signals where screen space and role scope permit, subject to the same RBAC rules as the web surface (§5.2).

The patient mobile app does not surface Smart Dashboards (§5.3).

5. Interaction Model

5.1 Primary Flows

Flow 1: Login → role dashboard (web)

Inferred from §5.1 and §13.2 rule 1.

1. User authenticates (handled by Access Manager)
2. DashboardContext resolved: role, site(s), enabled modules
3. Role-appropriate primary dashboard cards render immediately
4. Optional module widgets load asynchronously in background
5. User lands on fully-populated dashboard (or degraded view if a source module is unavailable)

Flow 2: Login → role dashboard (staff app)

Inferred from §5.2 and §13.2 rules 9–10.

1. User authenticates (handled by Access Manager)
2. DashboardContext resolved for mobile surface
3. Tasks, Updates, and Rota highlights render as primary signals
4. Role-specific supplementary cards load below primary signals
5. User lands on home dashboard view

Flow 3: Signal → action launch

Inferred from §4.3 and §13.2 rule 3. This is the core interaction loop of the module.

1. User sees a DashboardCard or AlertSignal with a non-OnTrack status
2. User taps/clicks the signal
3. Dashboard navigates user to the actionable destination via ActionLink deeplink
4. User completes the action in the owning module (e.g. Task Manager, Appointment Manager)
5. On return/refresh, the dashboard reflects updated source-module state

Flow 4: Inline action (FOH, web)

Inferred from §4.4 inline actions: confirm, arrive, cancel, take payment.

1. FOH user sees an appointment card with a pending status
2. User selects an inline action (e.g. confirm, arrive)
3. Confirmation step shown for irreversible actions (e.g. cancel)
4. Action dispatched to Appointment Manager via the dashboard's outbound event contract
5. Card status updates to reflect new state

Flow 5: Site switching (multi-site users, web)

Inferred from §13.4 and §9.

1. Multi-site authorised user selects a different site from the site selector
2. DashboardContext re-resolved for the newly selected SiteId
3. Dashboard re-renders scoped to the selected site's data
4. No data from the previously viewed site is retained in the active view

Flow 6: Locum session expiry

Inferred from §3.4, §9, and §13.2 rule 7.

1. Locum user's access window expires mid-session (enforced by Access Manager)
2. On next dashboard refresh or interaction, session is no longer valid
3. Dashboard redirects to login screen
4. No further dashboard data is surfaced until re-authentication

5.2 State Machines (Mirror of Technical Spec § 3)

Smart Dashboards does not own a multi-state lifecycle object in the way transactional modules do. The relevant state model is the DashboardCard status, which maps directly to the four-state visibility model described in §2.1 and the DashboardCard data model in §3.2 and §13.1. The UI treatment for each state is as follows:

Entry conditions — a card's status is determined by the source module and surfaced read-only. The dashboard does not transition card states; it reflects them. The user should understand from the visual treatment alone that this card requires their attention before they interact with it.

Confirmation pattern for irreversible actions — inline actions that are irreversible (notably: cancel appointment) must present a confirmation step before dispatching the action. Single-tap confirmable actions (confirm, arrive) may proceed with a single interaction. (needs UX writer input — exact confirmation modal copy and button labels)

Locum session state — when Access Manager signals that a locum's access window has expired, the dashboard surface enters a terminal state: no further data is rendered and the redirect to login is immediate on the next user interaction or auto-refresh. No partial dashboard view is shown to an expired session.

5.3 Empty / Loading / Error / Offline States

Empty state

Occurs when a user's role-scoped dashboard has no signals requiring attention — all cards are OnTrack and the task queue is clear. This is a positive state. The view must communicate "nothing needs your attention right now" rather than implying missing data. (needs UX writer input — exact illustration, heading, and supporting copy for the "all clear" state)

An empty state also occurs on first login for a newly onboarded staff member whose source modules have not yet populated data. This variant should gently orient the user rather than show an error. (needs UX writer input — first-time empty state messaging)

Loading state

The primary dashboard cards must render immediately on login. A skeleton loader pattern should represent the card grid while data resolves, preventing layout shift. Optional module widgets, which load asynchronously, use an individual card-level skeleton or placeholder so that their deferred loading is visually contained and does not disrupt the primary view (§5.1, §13.2 rule 10).

Error state

If one or more source modules are unavailable, the corresponding widget slots must display a contained, per-card error state — not a full-page error. The error state must: (a) identify which source is unavailable, (b) indicate the data may be stale or missing, and (c) offer a direct navigation path to the source module. The rest of the dashboard must remain fully functional (§14 reliability requirement). (needs UX writer input — error card copy and CTA label)

A full-page error state should only be shown if the DashboardContext itself fails to resolve — i.e. the user's role, site, or enabled modules cannot be determined. In this case the user must be offered a way to retry or contact support. (needs UX writer input — full-page error copy)

Offline state

Smart Dashboards surfaces live source-module state and must not treat a stale local copy as authoritative (§13.2 rule 1). Accordingly, offline mode cannot provide a trusted view of operational signals. The offline state should clearly communicate that the dashboard cannot display current data, and offer the user a path to retry when connectivity is restored. (needs UX writer input — offline state messaging and retry CTA)

No dashboard data should be served from a local cache in a way that could be mistaken for live data. If cached data is displayed at all during connectivity recovery, it must be clearly labelled with a staleness indicator and the time of last successful update.

6. Component Inventory

New components introduced or extended by this module:

• DashboardCard — the primary display unit for a single metric or signal. Displays status badge, metric summary, source module attribution, and action trigger. Appears on all role dashboards on both web and staff app surfaces. Reflects the DashboardCard canonical artefact (§3.2).
• AlertSignal card — a specialised card variant for exception and risk-state notifications. Carries severity indicator, escalation state, and a mandatory ActionLink. Must not render without a valid linked destination (§3.3, §13.2 rule 3).
• Status badge — a compact indicator rendering one of four states: On Track, Attention, Overdue, Escalated. Used within DashboardCards and AlertSignal cards. Must never rely on colour alone to convey state (accessibility requirement).
• Role dashboard scaffold — the top-level layout container that arranges DashboardCards into a role-appropriate grid or stack. Accepts a DashboardContext and renders only the cards within the user's RBAC scope.
• Site selector — a control allowing multi-site authorised users to switch their active site context. Triggers DashboardContext re-resolution. Suppressed for single-site users. Appears on web portal; behaviour on staff app to be confirmed. (needs UX writer input — label and interaction pattern)
• Today / This Week toggle — a segmented control applied to time-sensitive widgets, allowing the user to scope signals to the current day or the immediate week (§13.4). Does not affect non-time-scoped cards.
• Inline action menu — a compact set of single-step action controls surfaced within FOH appointment cards (confirm, arrive, cancel, take payment). Irreversible actions within this menu trigger a confirmation step before dispatching.
• Widget skeleton / placeholder — a loading state component used within optional widget card slots during asynchronous load. Prevents layout shift while maintaining the card grid structure.

Reused from the design system:

• Toast notification — for confirmations of successfully dispatched inline actions.
• Modal / confirmation dialog — for irreversible inline action confirmation steps.
• Navigation / deeplink handler — for all ActionLink transitions to source modules.
• Avatar / role indicator — for displaying current user role in the header.

7. Visual Design Notes

• Status semantics — the four status states (On Track, Attention, Overdue, Escalated) must map to distinct semantic colour tokens from the design system (success/neutral, warning, error, critical). Colour must never be the sole differentiator; each state must also carry a text label and/or distinct icon.
• Card hierarchy — visual weight must reinforce the attention hierarchy. OnTrack cards carry the lowest visual weight; Escalated AlertSignals carry the highest. The user's eye should be drawn naturally to the highest-priority signal on the page.
• Source attribution — each DashboardCard must visually attribute its source module (e.g. from Task Manager, from Appointment Manager). This supports user trust and orientates them before they click through to the source.
• AI badge — when AI Guardian is enabled and surfaces signals as AlertSignals, those signals must carry a distinct visual marker (e.g. an AI badge or icon) to indicate AI provenance. This must not be the only distinguishing feature; a text label must accompany it (§7, §11).
• Read-only affordance — dashboard cards must not use visual affordances (e.g. text field borders, edit icons) that imply the user can modify the underlying data directly from the dashboard.
• Typography, exact colour tokens, icon set, and motion design: (needs UX writer input — align with platform-wide design system)

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.
• Status badges must not rely on colour alone — each of the four status states (On Track, Attention, Overdue, Escalated) must carry both a colour treatment and a text label or icon with an accessible name, so that colour-blind users receive the same informational signal (directly implied by the four-state status semantics in §2.1 and §3.2).
• Role-scoped suppression must not create confusing gaps — when cards or widgets are suppressed due to RBAC scope, the resulting layout must not leave unlabelled empty regions that a screen reader user might interpret as a loading error. Suppressed widget positions should simply not exist in the DOM.
• Inline action menus must be keyboard accessible and announce their available actions to screen readers, given that FOH staff rely on speed-critical interactions during patient check-in.

9. Internationalisation

• Locale-aware date/time/number formatting.
• All user-facing strings externalised.
• Layouts tolerant of 30% string-length growth (German, French).
• RTL support: requirement not specified in the technical spec. (needs UX writer input — confirm RTL requirement with product owner)
• Date/time formatting in Today / This Week toggles and appointment card timestamps must use locale-aware patterns, as the platform serves practices across potentially multiple locales. The dashboard must not hardcode date formats.

10. Cross-Module UX Touchpoints

Where this module's UX intersects with related modules:

• Appointment Manager — FOH and Practitioner dashboard cards surface appointment status drawn from Appointment Manager. Inline actions (confirm, arrive, cancel, take payment) on FOH cards dispatch to Appointment Manager. The user transitions from the dashboard card to the Appointment Manager detail view via the ActionLink when more complex action is required.
• Task Manager — Task queue cards on all role dashboards surface open tasks from Task Manager. Tapping a task card launches directly into Task Manager via ActionLink. The staff app's primary Tasks signal is the most prominent instance of this touchpoint. Action launches are emitted as outbound events to Task Manager (§6.2).
• Smart Treatment Proposals — TCO dashboard pipeline widgets (presented → accepted → declined) consume data exclusively from Smart Treatment Proposals (§4.5, §13.2 rule 8). The user transitions to Smart Treatment Proposals to act on a proposal. The dashboard must not display conversion data from any other source.
• Communication Hub — message volume and responsiveness signals surface as dashboard cards where relevant to the user's role. The dashboard does not host a messaging interface; it links through to Communication Hub via ActionLink. Push notifications and email communications triggered by dashboard action launches are routed through Communication Hub (§6.1, §12).
• Rota Manager — Rota highlights (the third primary signal on the staff app) and coverage gap signals on relevant role dashboards are drawn from Rota Manager. The user links through to Rota Manager for coverage management actions.
• Digital Forms — form completion status cards (particularly relevant to Practitioner and Nurse dashboards) are drawn from Digital Forms. Outstanding form alerts link through to Digital Forms.
• Access Manager — though not visible as a navigable surface, Access Manager's RBAC and locum/temporary-flag enforcement determines which cards and widgets are rendered. Session expiry triggered by Access Manager results in the dashboard redirect-to-login behaviour. The role and site indicator visible in the header reflects the DashboardContext resolved by Access Manager (§9).
• Audit & Compliance — audit events for dashboard access and action launches are emitted silently to Audit & Compliance. The user does not interact with this module from the dashboard, but audit visibility is surfaced through the Audit & Compliance module's own interface for authorised reviewers.
• Performance Dashboard Suite — when enabled, the Performance Dashboard Suite appends trend and analytics views to the Manager/Operator dashboard (§13.5). The transition between the CORE operational dashboard and the Performance Dashboard Suite analytics view must be visually distinct, so that users understand they have moved from a live-signal surface to a historical/analytical surface.
• Integrated Payments — payment exception cards and outstanding balance summaries are surfaced on FOH, TCO, and Manager/Operator dashboards where payment failures, PMS writeback errors, or overdue balances are present. Integrated Payments mandates that no failed payment or writeback error passes silently; the dashboard is therefore a primary visibility surface for these alerts. A payment exception card must carry an ActionLink to the relevant record in Integrated Payments. The dashboard does not host payment flows; it surfaces the exception and hands off. Manager/Operator dashboards may additionally show a rolled-up outstanding balances indicator where authorised.
• AI Assistant (Aiden) — when Aiden is enabled, it surfaces role-aware operational guidance drawn partly from Smart Dashboards alert signals (e.g. at-risk or overdue work). On surfaces where both Aiden's guidance panel and Smart Dashboards alert cards are visible simultaneously, the visual contract between the two must be unambiguous: Aiden's read-only guidance is presented in Aiden's own panel and must not be confused with a dashboard AlertSignal card. Where Aiden references a specific dashboard signal, the reference must resolve to the same ActionLink as the card itself — the user must not receive conflicting action paths from the two surfaces. Any action confirmation initiated via Aiden that relates to a dashboard signal follows Aiden's own governed confirmation flow; the dashboard card's status updates on the next refresh to reflect the outcome. (needs design alignment with the AI Assistant (Aiden) UX specification before implementation)
• AI Guardian (optional, future) — when enabled, AI Guardian surfaces risk pattern signals as AlertSignals. These must be visually distinguished from system-generated signals. Critically, AI Guardian critical Findings — operational gaps that require manager or clinical team lead attention — must be surfaced as Escalated AlertSignal cards on the Manager/Operator and relevant clinical role dashboards. Because these Findings represent AI-identified patterns rather than confirmed system states, they must carry the AI provenance badge and label described in §7 and §11. The user must always be able to distinguish an AI Guardian Finding from a system-generated operational alert. See §11 for the full governance treatment.

UX consistency rules:

• Every DashboardCard, regardless of role or source module, must carry an ActionLink. An unactionable card must not appear on any dashboard surface. This rule is absolute (§3.4, §13.2 rule 3).
• Status semantics — On Track / Attention / Overdue / Escalated — must use consistent visual treatments across all role dashboards and both surfaces (web and staff app). A card shown as Overdue on web must use the same semantic treatment as an Overdue card on staff app.
• The Today / This Week toggle, where present, must behave identically across all role dashboards on web. Its presence or absence on staff app cards should be consistent with the role scope of each card.
• Site switching (multi-site users) must always scope all visible cards to the selected site. No card from a non-selected site should be visible after a site switch.

11. Governance & Auditability

Smart Dashboards is a governance-critical surface because it presents patient-linked operational data to staff and because its RBAC enforcement determines what each user can see. The following governance treatments are required, drawn from §8 and §9 of the technical spec:

• Role and site indicator — the current user's resolved role and active site must be persistently visible in the dashboard header. For multi-site users, the active site must be clearly displayed alongside the role. This allows staff to confirm at a glance that they are viewing the correct scope, and supports audit traceability.
• RBAC suppression is silent — cards and widgets suppressed due to RBAC scope must simply not appear. The dashboard must not display "you do not have permission to see this" placeholders in the primary view, as this would expose the existence of suppressed content to unauthorised users. However, RBAC suppression events are logged to Audit & Compliance (§8).
• Locum/temporary account indicators — accounts flagged as locum or temporary by Access Manager must carry a visible session indicator so that the user and any supervising staff can confirm the access constraints are in effect. (needs UX writer input — exact treatment and placement of the locum/temporary session indicator)
• AI signal attribution — when AI Guardian is enabled and surfaces AlertSignals, each AI-sourced signal must carry a distinct visual marker (e.g. "AI-suggested" badge) so that staff can distinguish AI-generated risk alerts from system-generated operational signals. Staff must never be in doubt about whether a signal requires their judgement or is a confirmed system state (§7).
• Audit event feedback — dashboard access and action launches are logged to Audit & Compliance without requiring user interaction. The user does not need to confirm that their session is being audited, but the platform's privacy notice (surfaced elsewhere) must disclose this. No explicit "you are being audited" banner is required on the dashboard itself.
• Read-only surface declaration — because the dashboard is strictly read-only with respect to source data (§11), the visual design must not imply editability. Card designs must not use affordances associated with editable fields.
• Confirmation for irreversible inline actions — inline actions available on FOH cards (specifically: cancel appointment) are irreversible and must present a confirmation modal before dispatching. The confirmation must clearly state the consequence of the action. (needs UX writer input — exact confirmation copy, button labels, and irreversibility warning)

12. Notification & Communication Patterns

Smart Dashboards surfaces live signals as dashboard cards rather than pushing discrete notifications in most cases. However, the following notification patterns are implied by the technical spec's audit events, integration contracts, and AlertSignal model:

• In-app banner — used to communicate dashboard-level degradation events: when one or more source modules are temporarily unavailable, a persistent but dismissible banner at the top of the dashboard should inform the user that some data may be missing or stale, and which module is affected (§14 reliability requirement). This is distinct from a per-card error state and is used when the degradation is broad enough to affect the user's situational awareness.
• Toast — used to confirm the successful dispatch of inline actions from the dashboard (e.g. appointment confirmed, task marked complete). Toasts must be transient, non-blocking, and must not require user dismissal for routine confirmations. (needs UX writer input — toast copy for each inline action type)
• In-dashboard AlertSignal cards — the primary mechanism by which the module requests user attention. AlertSignal cards with Attention, Overdue, or Escalated status replace the role of push notifications for operational exceptions during an active session. They are persistent and must not auto-dismiss.
• Push notification (via Communication Hub) — not directly emitted by Smart Dashboards. However, alerts and updates delivered to the staff app's Updates primary signal may be sourced from Communication Hub. Any push notification that directs a staff member back to a dashboard signal must deep-link to the relevant card via ActionLink. Smart Dashboards must not emit push notifications directly (§6.1, §6.2).
• Email/SMS (via Communication Hub) — not emitted directly by Smart Dashboards. Where dashboard-triggered actions (e.g. a TCO initiating a conversion call or email) result in outbound communications, those are handled by Communication Hub as the owning module. Smart Dashboards does not author or send email or SMS.
• Session expiry redirect — when a locum's access window expires, the redirect to login is a system-level state change, not a notification. No toast or banner is shown; the session terminates and the user is redirected (§13.2 rule 7). (needs UX writer input — confirm whether a brief explanatory message should appear on the login screen following a session expiry redirect)

13. Role-Specific Dashboard Content

13.1 FOH Dashboard

The FOH dashboard is optimised for speed-critical operational tasks at the front desk. Its primary concern is the appointment schedule for the current day, augmented by payment exceptions where relevant.

Payment exception visibility: FOH staff must be able to see outstanding payment alerts for patients checked in or arriving on the current day. These appear as Attention or Overdue AlertSignal cards sourced from Integrated Payments, carrying an ActionLink to the relevant payment record. FOH staff must not be blocked from completing check-in actions by the presence of a payment alert, but the alert must remain visible until resolved. The dashboard must not suppress payment exceptions silently for FOH users.

13.2 TCO Dashboard

The TCO dashboard is organised around the treatment pipeline (presented → accepted → declined), with conversion action launches as the primary interaction. Data is drawn exclusively from Smart Treatment Proposals (§10).

BookingEligibility and SLA visibility: In keeping with the action-first principle (§2), the TCO dashboard must surface each pipeline record's BookingEligibility status and SLA compliance state as primary visible attributes of the pipeline card — not as detail-view-only information. A record whose eligibility window is at risk or whose SLA is approaching expiry must be presented with Attention or Overdue status accordingly, so that the TCO can prioritise conversion outreach without needing to open the detail view first. The pipeline card must carry an ActionLink that launches directly to the record in Treatment Pipeline Manager or Smart Treatment Proposals, where the full eligibility and SLA detail is available.

Payment exception visibility for TCO: Outstanding balance summaries and payment exceptions relevant to the TCO's treatment pipeline records are surfaced as supplementary AlertSignal cards, sourced from Integrated Payments. These must carry an ActionLink and must not be presented as part of the pipeline conversion flow itself — they are operationally adjacent, not conversion-blocking.

13.3 Manager/Operator Dashboard

The Manager/Operator dashboard aggregates live operational KPIs, overdue tasks, compliance and risk alerts, and — where authorised — multi-site roll-up data.

Payment exception visibility for Managers: Outstanding balances, failed payment alerts, and PMS writeback errors sourced from Integrated Payments are surfaced as dedicated AlertSignal cards on the Manager/Operator dashboard. A rolled-up outstanding balances indicator may additionally be shown where authorised, giving the Manager visibility of payment health at a practice level without requiring navigation to Integrated Payments for every individual record. All such cards carry ActionLinks.

AI Guardian critical Findings: When AI Guardian is enabled, critical Findings — representing AI-identified operational gaps requiring manager or clinical team lead attention — are surfaced as Escalated AlertSignal cards on the Manager/Operator dashboard and on relevant clinical role dashboards (e.g. Practitioner dashboard where clinical Findings apply). These cards must carry the AI provenance badge and label (§11, §7) so that staff can distinguish AI Guardian Findings from system-generated operational alerts. Findings must carry an ActionLink to the relevant detail view in AI Guardian. The dashboard surfaces the Finding as an exception signal; assessment and response are performed within AI Guardian itself.

14. Open Questions

The following questions must be resolved before this spec is promoted from draft to published. Items marked ‡ are carried over from the technical spec's open questions (§15); additional UX-specific questions follow.

• ‡ Cache freshness and staleness indicators — the technical spec notes that a cache layer may be used for core dashboard data (§14) but does not define the maximum acceptable staleness window or cache invalidation trigger. Until this is defined, the UX cannot specify when (if ever) a staleness indicator should appear on a card. What is the target cache TTL, and at what staleness threshold (if any) should the UI indicate that a card's data may not be current?
• ‡ Dashboard availability SLA and graceful degradation detail — the technical spec requires graceful degradation when source modules are unavailable (§14) but does not specify the expected degradation behaviour in detail. The UX needs to know: which cards are considered "core" (must always render) versus "optional" (can fail silently), and what is the maximum acceptable time before a degraded state banner is shown?
• ‡ Performance latency targets (web and staff app) — no P50/P95 dashboard render time targets are defined. The UX loading state design (skeleton duration, progressive reveal timing) depends on realistic latency expectations. What are the target render times for the primary dashboard view on web and staff app?
• ‡ MFA step-up for manager/admin surfaces — it is not specified whether access to Manager/Operator widgets or Admin Control Plane configuration requires MFA step-up beyond session authentication. If MFA step-up is required, the UX must design an inline challenge flow. Confirm with Access Manager and security owners.
• ‡ Patient app applicability — the technical spec explicitly states that Smart Dashboards do not surface on the patient mobile app (§5.3) but notes this may change. Confirm whether this is a permanent non-goal or deferred scope, so that this UX spec can be closed or extended accordingly.
• Tablet form factor — the technical spec describes a staff app but does not explicitly address a tablet breakpoint. Clinical staff (Practitioners, Nurses) often use tablets at chairside. Does the staff app require a purpose-built tablet layout, or is a responsive mobile-first layout sufficient? This affects the Component Inventory and touch ergonomics sections.
• Locum/temporary session indicator — the technical spec requires that locum accounts be restricted and that expired sessions redirect to login, but does not specify whether a visible session indicator (e.g. a banner or badge showing the remaining access window duration) should be shown to the locum user. Confirm the required treatment with product and Access Manager owners.
• Inline action scope on staff app — the technical spec defines inline actions (confirm, arrive, cancel, take payment) for FOH on the web portal (§4.4) but does not explicitly state which, if any, inline actions are available on the staff app dashboard. Confirm which inline actions are permitted on mobile before the staff app component inventory is finalised.
• AI Guardian signal visual language — when AI Guardian is enabled, its AlertSignals must be visually distinguished. The specific visual treatment (badge design, label copy, tooltip behaviour) is not defined in the technical spec. This requires a dedicated design pass aligned with the AI Guardian module's own UX specification.
• First-time / onboarding empty state — the technical spec does not address the experience for a newly onboarded staff member whose source modules have not yet populated data. Is there a guided onboarding state, or does the dashboard simply show the "all clear" empty state? Confirm with product.
• Aiden visual contract alignment — the interaction between Aiden's guidance panel and Smart Dashboards AlertSignal cards on shared surfaces requires a dedicated design alignment session before implementation. Confirm the visual boundary between the two surfaces and the action path consistency rules with the AI Assistant (Aiden) design owner.
• Payment exception card scope and authorisation — confirm with Integrated Payments and product owners which payment exception types are surfaced at the dashboard level for each role (FOH, TCO, Manager), and whether any payment data visibility requires additional RBAC permissions beyond the standard role assignment.