Access Manager – UX specification

Related technical authority: Access Manager – Technical Specification

1. Purpose

This UX specification governs every user-facing surface through which identity, authentication, and access control are managed within the Primoro platform. It serves practice administrators and ACP-level identities who provision, modify, and revoke user access; it also governs the authentication and session experiences of staff, locums, patients, and external parties across every Primoro surface. Because Access Manager underpins every other module, the patterns defined here set a platform-wide baseline for how access state, permissions, and governance are made visible to users.

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 are confirming. This is reinforced by the technical spec §7, which makes Access Manager the explicit enforcement point for all AI-initiated requests; the UI must reflect that boundary clearly.
• No dead toggles — every UI control either does something or does not appear. The technical spec §4.4 states that permission toggles alter real enforcement at API, UI, and document-category level; a toggle that appears but has no downstream effect is prohibited.
• 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.
• Revocation is irreversible and surfaced as such — The technical spec §3.5 defines Revoked as a terminal state that cannot return to Active without a new, audited provisioning action; the UI must communicate this finality before the action is confirmed.
• Every action is attributed — The technical spec §2.1 and §13.2 Rule 1 prohibit shared, generic, or anonymous logins; the UI must make the acting identity and its role visible at all times, reinforcing that every action is permanently attributable.
• Enforcement is silent until it matters — The technical spec §13.2 Rule 7 requires that unauthorised records are omitted from lists and search results entirely; the UI must not expose the existence of records a user cannot access, but must provide meaningful feedback when access is denied to something the user directly requests.

3. Design philosophy

The technical spec positions Access Manager as a foundational enforcement layer — every other module depends on it, yet most users should rarely be conscious of it. The design embodies a "trusted infrastructure" mental model: access decisions happen silently and correctly in the background; the UI surfaces them only when a user needs to act or when governance demands visibility.

Empty states. A user list or audit log that is genuinely empty (e.g. a new practice with no provisioned users) should surface a clear prompt to create the first user, not a blank screen. Filtered views that return no results must distinguish "nothing matches your filter" from "you have no data at all".

Error states. Authentication failures (§8.1) must be presented in plain language without revealing which specific credential element failed, to avoid aiding credential-stuffing attacks. RBAC enforcement denials (e.g. a user attempting to access a record outside their scope) must show a clear, non-technical message with a suggested next step — for example, contacting their practice administrator — rather than a raw HTTP error.

AI suggestions. Access Manager does not itself surface AI suggestions to end users; it gates what AI Assistant (Aiden) may surface. However, the audit log must make AI-initiated access decisions visually distinguishable from human-initiated ones (see §11).

Multi-step flows. Destructive or irreversible actions — leaver revocation, suspension, guardian access removal — require an explicit confirmation step. The confirmation must state precisely what will happen, to whom, and that it is immediate and irreversible where applicable (§3.5, §5.3).

Undo / redo. Revocation and suspension cannot be undone from within the same flow; the technical spec §3.5 prohibits returning a Revoked user to Active without a new provisioning action. The UI must not offer an undo affordance for these transitions. Suspension may be lifted by returning the user to Active via a distinct, audited action.

Read-only vs editable surfaces. Audit logs (§8.1) are immutable and must always render as read-only with no edit affordances visible. User records are editable only by permitted actors (§9); for all other roles, the same record must render as read-only with no inline edit controls shown.

4. Primary surfaces

4.1 Web portal

The web portal is the primary administrative surface for Access Manager, inferred from the technical spec §9, §13.3, and §2.1, which describe a Practice Administrator and ACP-level identity managing user provisioning, role configuration, session settings, and audit log review.

Who uses it: Practice administrators; ACP-level identities; managers (within their site scope, for read access to user records and access history).

Key tasks performed here:

• Provision a new user (staff, locum, external party, or patient-adjacent account), assigning a core role type and optional custom role. (§5.1, §9)
• Modify a user's role assignment or permission override. (§5.2, §9)
• Suspend or revoke a user (leaver workflow). (§5.3, §9)
• Configure SSO provider, MFA rules, and session timeout values. (§13.3)
• Create and manage custom role labels and permission toggles per module and document category. (§4.4, §13.3)
• Review and export the audit log, filtering by role, status, site, device, and event type. (§8, §13.4)
• Manage guardian, proxy, and family access grants and revocations. (§4.2, §13.3)
• Extend or override locum access expiry, with audited confirmation. (§6, §9)
• View a user's own access record (self-service read). (§9)

Layout pattern: List-detail for user management (left-hand filterable user list; right-hand detail pane showing identity, role, status, session history, and access history); separate full-pane views for audit log, role configuration, and practice settings. Inferred from the filtering and views described in §13.4 and the configuration surfaces in §13.3.

4.2 Tablet app

In-practice tablets are named as a delivery surface in §10. Access Manager governs device-context (shared vs. personal) on tablets and must enforce appropriate session behaviour on this surface.

Who uses it: Clinical and front-of-house staff using shared in-practice tablets during patient-facing workflows. (§10)

Key tasks performed here:

• Authenticate for a session on a shared device, with appropriate idle timeout enforced. (§4.3, §4.1)
• Receive a mid-session role scope update without being required to log out and back in, where the change does not constitute a suspension or revocation. (§4.3)
• Be force-logged out immediately upon suspension or leaver revocation. (§3.5, §4.3)

Touch ergonomics: Glove-friendly tap targets ≥48 px; one-handed reach considered for primary authentication controls (e.g. PIN / biometric prompt). The shared-device context means the authentication prompt must be easy to invoke between users without requiring navigation; a prominent "sign out / switch user" affordance is required at all times on shared-device sessions. (§4.3)

4.3 Mobile app (staff and patient)

Both Staff App Mode and Patient App are named delivery surfaces in §10. Access Manager governs authentication and session scope on both.

Who uses it:

• Staff using the Staff App Mode on personal mobile devices. (§10, §4.1)
• Patients authenticating via the Patient App, including family, guardian, and proxy account holders. (§10, §4.2)

Key tasks performed here:

• Authenticate via SSO (staff) or passwordless OTP / password + biometrics (patients). (§4.1, §4.2)
• Complete MFA challenge where required (mandatory for ACP identities; configurable for standard staff). (§4.1)
• Receive mid-session permission scope updates seamlessly. (§4.3)
• Be force-logged out immediately upon suspension or leaver revocation. (§3.5)
• Patients: initiate or review guardian/proxy access grants where the practice and patient consent permits. (§4.2)

5. Interaction model

5.1 Primary flows

Flow 1 — Provision a new staff user (joiner)

Inferred from the technical spec §5.1 and §9.

1. Administrator navigates to Users > New user.
2. Selects UserType = Staff.
3. Enters required identity fields (name, email, site).
4. Selects CoreRoleType from the five defined types
   (FOH | TCO | Practitioner | DentalNurse | Manager).
5. Optionally assigns a CustomRoleId.
6. Chooses authentication method (SSO provider or local login).
7. Reviews summary screen showing role, permissions summary,
   and delivery surfaces the user will access.
8. Confirms. Access Manager provisions the account (Status = Active)
   and logs a CreatedBy event.
9. User immediately has access across all delivery surfaces.

(needs UX writer input — confirmation screen summary copy and success toast message)

Flow 2 — Leaver revocation

Inferred from the technical spec §5.3, §3.5, and §13.2 Rule 10.

1. Administrator locates the user record (via search or user list).
2. Selects "Revoke access" action.
3. Confirmation modal surfaces — states: user's name, current role,
   that all active sessions will be force-terminated immediately,
   and that this action cannot be undone without a new provisioning step.
4. Administrator confirms.
5. Access Manager sets Status = Revoked, force-terminates all active
   sessions, and logs the event.
6. User list updates immediately to reflect Revoked status.
7. No undo affordance is offered.

(needs UX writer input — confirmation modal heading, body copy, and destructive action button label)

Flow 3 — Staff authentication (SSO path)

Inferred from the technical spec §4.1.

1. User navigates to a Primoro surface or is redirected on session expiry.
2. Selects SSO provider (Microsoft Entra ID or Google Workspace),
   or is auto-routed if the practice has a single configured provider.
3. Completes SSO flow in the provider's interface.
4. If ACP-level: MFA challenge is mandatory; cannot be bypassed.
5. If standard staff and practice has enabled MFA: MFA challenge presented.
6. On success: session issued with RoleScopeId embedded; user lands
   on their role-mapped dashboard.
7. On failure: non-specific error message presented; failed attempt logged.

(needs UX writer input — error message copy for failed authentication)

Flow 4 — Patient authentication (passwordless OTP path)

Inferred from the technical spec §4.2.

1. Patient opens the Patient App or Patient Portal.
2. Enters registered contact detail (email or mobile number).
3. OTP sent via Communication Hub.
4. Patient enters OTP.
5. On success: session issued; patient lands on their record.
6. On failure: non-specific error message; failed attempt logged.

(needs UX writer input — OTP entry screen microcopy and error states)

Flow 5 — Mid-session role scope update (staff)

Inferred from the technical spec §4.3.

1. Administrator changes a staff user's role assignment or permission
   override while that user has an active session.
2. Access Manager propagates the updated RoleScopeId to all active
   sessions within the platform-defined propagation window.
3. Affected user's surface refreshes available actions and visible
   records without requiring logout.
4. If the change restricts access, content the user was viewing
   that is now out of scope becomes inaccessible; a non-alarmist
   inline message explains that their access has been updated.
5. If the change constitutes a suspension or revocation, the user
   is force-logged out immediately (see Flow 2).

(needs UX writer input — inline access-update notification copy)

Flow 6 — Custom role configuration

Inferred from the technical spec §4.4 and §13.3.

1. ACP-level identity navigates to Settings > Roles & permissions.
2. Selects an existing core role type to customise, or creates
   a new custom role label mapped to a core role type.
3. Toggles module access and document-category visibility.
   Each toggle shows its current state and the enforcement level
   it affects (API / UI / document category).
4. Platform prevents any toggle combination that would bypass
   a fundamental security tier; such combinations are disabled
   with an explanatory tooltip.
5. Saves. All changes are audited immediately.
6. Affected active sessions receive propagated scope update.

(needs UX writer input — security-tier restriction tooltip copy)

Flow 7 — Audit log review and export

Inferred from the technical spec §8 and §13.4.

1. Administrator navigates to Audit > Access log.
2. Applies filters: role, status, site, device, event type.
3. Browses immutable log entries; no edit affordances are shown.
4. Selects date range and event types for export.
5. Exports log in machine-readable format.

(needs UX writer input — export confirmation and format-selection copy)

Flow 8 — HR-driven joiner / mover / leaver handoff

Inferred from the technical spec §5.1, §5.3, and the HR & People Manager spec §4.3, which defines onboarding and offboarding as core HR workflows that drive access provisioning and revocation.

1. HR & People Manager completes an onboarding or offboarding
   workflow step that requires an access change (e.g. new starter
   record approved, or leaver confirmed in HR).
2. Access Manager receives the trigger from HR & People Manager
   and surfaces a pending action to the Practice Administrator:
   — For a joiner: a pre-populated "New user" provisioning task
     appears in the user list, carrying identity fields sourced
     from the HR record (name, role, site, start date).
   — For a mover: a pre-populated "Role change" task appears
     against the existing user record, indicating the new role
     or site assignment from HR.
   — For a leaver: a pre-populated "Revoke access" task appears
     against the user record, carrying the HR-confirmed leaving date.
3. The administrator reviews the pre-populated details, amends
   if necessary (e.g. selecting the correct CoreRoleType or
   CustomRoleId for a joiner), and confirms the action.
4. Access Manager executes the provisioning, role-change, or
   revocation as per the relevant flow (Flow 1, the role-change
   path, or Flow 2 respectively) and logs the event, including
   a reference to the originating HR workflow record.
5. A confirmation notice is shown to the administrator, and any
   follow-up tasks in Task Manager are surfaced inline
   (see §10, Task Manager).
6. If the HR trigger arrives but no administrator action is taken
   within a practice-configured window, an escalation banner
   is surfaced on the Access Manager home screen until the
   pending action is resolved.

Key UX principles for this flow: - The HR-sourced identity data is displayed as read-only pre-filled content, clearly labelled as "sourced from HR & People Manager", so the administrator understands its provenance and can confirm or override it. - The administrator always performs the final confirmation step; HR & People Manager does not silently provision or revoke access. The handoff is a notification and a pre-population, not an automatic execution. - The HR workflow reference is included in the Access Manager audit log entry so the full chain of accountability — from HR decision to access change — is traceable in a single record.

(needs UX writer input — pending action banner copy, HR-sourced field label copy, and escalation notice copy)

5.2 State machines (mirror of technical spec §3.5)

The following states and transitions are drawn directly from the User State Machine defined in the technical spec §3.5.

State badges must be visible in both the user list (compact) and the user detail pane (prominent). Colour alone must not be the sole differentiator; each state must also carry a text label to satisfy accessibility requirements (§8).

5.3 Empty / loading / error / offline states

Empty states

• User list — no users provisioned yet: surface a primary action prompt to create the first user. Do not show a blank table. (§5.1)
• Audit log — no events matching current filter: distinguish "no results for this filter" (offer to clear filters) from "no audit events exist" (which should never occur in a live practice and may itself warrant a warning). (§8)
• Custom roles list — no custom roles configured: surface a prompt to create a custom role, explaining that the practice is currently using core role defaults. (§4.4)

Loading states

• User list and audit log use skeleton rows (not a spinner) to prevent layout shift while data loads. Given the technical spec's NFR that RBAC checks must not introduce perceptible lag (§14), loading states should be brief; skeletons are a graceful fallback, not the expected experience. (§14)
• Authentication screens use an inline progress indicator on the submit control rather than a full-screen spinner, so the user retains context. (§4.1, §4.2)

Error states

• Authentication failure: plain-language message without revealing which specific field failed; log entry created; option to retry or contact administrator. (§8.1, §4.1)
• RBAC enforcement denial (e.g. user directly requests a URL for a record outside their scope): clear, non-technical message; suggest contacting a practice administrator; do not expose the existence of the record. (§13.2 Rule 7)
• Permission propagation failure: if a mid-session scope update cannot be confirmed within the platform-defined window, the surface must fail safely — reverting to the previous (more restrictive) scope or prompting re-authentication — never silently granting expanded access. (§4.3, §14 Reliability)
• Export failure (audit log): toast error with a retry action. (§8, §13.4)

Offline states

• Access Manager is a foundational security layer; the technical spec §14 states it must remain operational even during partial platform outages and must prefer denial over unguarded permissiveness when degraded. The UI must reflect this: if connectivity to Access Manager cannot be confirmed, surfaces must show a "limited access" state and prevent actions that require a live RBAC decision. Purely informational views of already-loaded data may remain visible where the session token is still valid. (§14 Reliability)
• Shared in-practice tablets in offline state must not allow new session initiation; they must surface a clear message that authentication requires connectivity. (§4.3)

6. Component inventory

New components introduced by this module:

• User status badge — compact, labelled badge (Active / Suspended / Revoked) shown in user list rows and user detail pane headers. (§3.5, §5.2 above)
• Role scope indicator — persistent element in the authenticated surface header showing the current user's role label and, for ACP identities, an elevated-access indicator. Inferred from the technical spec §9 requirement that the current user's role and active permissions are visible. (§4.4, §4.1)
• Permission toggle row — a labelled toggle within the role-configuration surface that shows enforcement level (module / document category), current state, and is disabled with a tooltip when a security-tier restriction applies. (§4.4, §13.3)
• Destructive action confirmation modal — a modal used for suspend, revoke, and guardian-revocation flows that states the action, its immediate effects, and its irreversibility before the user confirms. (§3.5, §5.3)
• Audit log table — a read-only, filterable, exportable table of AuditEvent records. Columns: event type, actor, target, timestamp, site. No edit affordances. (§8, §13.4)
• Session indicator — visible in the user detail pane, showing active sessions with device, auth method, issued-at, and expires-at, with a "revoke session" action available to permitted actors. (§3.2, §9)
• Locum access card — a summary component in the user detail pane for locum accounts, showing shift-synced access window, expiry time, and an audited "extend access" action. (§6)
• Guardian/proxy access panel — a section within the patient record (where Access Manager surfaces are relevant) showing granted family/guardian access relationships, scope, and a revoke action. (§4.2)
• HR handoff pending-action card — a summary component surfaced in the user list and the Access Manager home screen when HR & People Manager has triggered a joiner, mover, or leaver action awaiting administrator confirmation. Shows the HR-sourced identity data (read-only, labelled by provenance), the required action type, and a direct link into the relevant flow (Flow 8). (§5.1 Flow 8, §10)

Reused from the design system:

• Filter bar (role, status, site, device, event type) — used on the user list and audit log. (§13.4)
• Search input — used on the user list. (§5.3)
• Toast notification — used for success confirmations (e.g. user provisioned, session revoked). (§12)
• In-app banner — used for elevated-risk states (e.g. ACP session active, mid-session permission update applied). (§12)
• Skeleton loader — used on list and table views during data fetch. (§5.3)
• Export action button — used on the audit log. (§13.4)

7. Visual design notes

• Typography: (needs UX writer input — heading scale, body scale, and monospace usage for IDs and audit event data to be defined in the design system pass)
• Colour: Semantic colour usage for status badges must map to the platform's semantic palette: Active → success/green token; Suspended → warning/amber token; Revoked → error/red token. Colour must always be paired with a text label (see §8 accessibility). ACP elevated-access indicator should use a distinct semantic token — not the same as Active — to convey elevated context without implying an error state. (§3.5, §4.1) (exact token names and hex values to be defined in design system)
• Iconography: A lock or shield icon should accompany the role scope indicator in the header to signal that access governance is active. A terminated/locked icon should accompany the Revoked state badge. Icons must never appear without a text label on this module, given its governance-critical nature. (§2.1, §5.2) (icon set to be confirmed in design system pass)
• Motion: Force-logout and revocation events should not be animated in a way that trivialises their finality. Toast confirmations may use a standard entry/exit transition. Mid-session permission updates should produce a subtle, non-alarming banner rather than a disruptive animation. (§4.3, §3.5) (timing values to be defined in 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

Module-specific accessibility requirements:

• Status badges (Active / Suspended / Revoked) must never rely on colour alone; text label is mandatory in every context. (§5.2, §3.5)
• The destructive action confirmation modal must manage focus correctly: focus moves into the modal on open, is trapped within it, and returns to the triggering element on cancel. The primary destructive action must not be the default-focused element when the modal opens. (§5.1 Flow 2)
• Permission toggles must have programmatic labels that describe both the feature being toggled and its current state, so screen reader users understand the effect of toggling. (§4.4)
• The audit log table must be navigable by keyboard with appropriate table semantics (scope attributes on headers) given the volume of rows. (§8)
• Authentication OTP inputs on the patient app must be compatible with mobile OS autofill for one-time codes to reduce manual entry burden. (§4.2)

9. Internationalisation

• Locale-aware date/time/number formatting
• All user-facing strings externalised
• Layouts tolerant of 30% string-length growth (German, French)
• Timestamps in the audit log must render in the user's locale-configured timezone; the stored value remains UTC. (§13.1 AuditEvent)
• Role label names (including custom role labels configured by a practice) are practice-authored strings and must support the full Unicode character set. (§4.4, §13.3)
• RTL support: (needs UX writer input — RTL requirement not specified in the technical spec; to be confirmed by platform internationalisation policy)

10. Cross-module UX touchpoints

All integrations listed below are derived from the technical spec §10.

• Rota Manager — Locum access records originate from shifts defined in Rota Manager. When a Practice Administrator reviews a locum's access card in Access Manager, the associated shift reference should be surfaced (read-only) to provide context. The user does not navigate between the two modules to complete locum provisioning; Rota Manager pushes the shift data and Access Manager presents it inline. (§10, §6)
• Task Manager — Joiner, mover, and leaver workflow steps may generate follow-up tasks visible in Task Manager. From within a completed joiner or leaver flow in Access Manager, a confirmation screen may surface a link or contextual notice that a follow-up task has been created in Task Manager, without requiring the user to navigate away. (§10, §2.2)
• Communication Hub — Access lifecycle events (new user provisioned, leaver confirmed) trigger outbound notifications via Communication Hub. Access Manager does not send notifications directly. The UI should confirm to the administrator that a notification has been dispatched, without exposing Communication Hub's internal configuration. (§10, §12)
• Smart Dashboards — Access Manager governs which dashboard widgets and views are visible per role. From a user's perspective, the dashboard simply reflects their role scope — there is no Access Manager UI visible within Smart Dashboards. Administrators configuring role permissions in Access Manager should see a plain-language description of which dashboard areas a role can access, without needing to navigate to Smart Dashboards to verify. (§10, §4.4)
• Document Hub — Document-category visibility is gated by Access Manager using role, patient-relationship context, and site/group context. The enforcement is silent (unauthorised documents are omitted); Document Hub surfaces are out of scope for this spec, but Access Manager's role-configuration UI must clearly describe document-category permissions in plain language so administrators understand what they are configuring. (§10, §4.4)
• Staff App Mode — Staff App Mode must honour mid-session role scope updates within the platform-defined propagation window. From a UX standpoint, the experience on Staff App Mode should be seamless — the access update should not interrupt the user's current task unless the change revokes access to what they are doing. (§10, §4.3)
• Patient App — Patient authentication is governed by Access Manager. The Patient App's login screen is a delivery surface for Access Manager's passwordless and OTP flows (§4.2). Guardian and proxy access management may surface within the Patient App as a distinct panel. (§10, §4.2)
• Admin Control Plane (ACP) — ACP identities are subject to Access Manager's elevated authentication profile (mandatory MFA, shorter session lifetimes). The ACP surface must visibly communicate the elevated session context — for example, via a persistent elevated-access indicator — and must surface session expiry warnings in advance given the shorter lifetime. (§10, §4.1)
• AI Assistant (Aiden) — Access Manager is the enforcement point for all AI-initiated data requests. From a user's perspective in the audit log, AI-initiated access decisions must be visually distinguishable from human-initiated ones (e.g. an "AI" badge on the actor field). Staff interacting with Aiden do not see Access Manager's enforcement in real time; it operates silently. (§10, §7, §8.1)
• HR & People Manager — HR onboarding and offboarding workflows in HR & People Manager drive joiner, mover, and leaver triggers into Access Manager. When HR & People Manager completes a workflow step that requires an access change, Access Manager surfaces a pre-populated pending action to the Practice Administrator (see §5.1 Flow 8). The administrator always performs the final confirmation; HR & People Manager does not silently execute access changes. The HR workflow reference is recorded in the Access Manager audit log entry for full chain-of-custody traceability. (§10, §5.1, §5.3)

UX consistency rules:

• The role scope indicator (showing the current user's role and elevated-access state) must appear consistently in the header across web portal, tablet, and app surfaces so users always know the access context under which they are operating. (§4.4, §4.1)
• Destructive action confirmation modals must follow a single, consistent pattern across all leaver, suspension, and guardian-revocation flows — same modal structure, same confirmation interaction — to set a reliable mental model for irreversible actions. (§5.3, §4.2)
• Audit log entries that originate from Access Manager's enforcement decisions must use the same actor/target/timestamp column structure whether they are viewed in Access Manager's own log or consumed by Governance Reporting. (§13.5)

11. Governance & auditability

The following treatments are inferred from the technical spec §8, §7, §9, and §13.2.

• AI-initiated actions are visually distinct. In the audit log, access decisions made in response to AI Assistant (Aiden) requests are labelled with a distinct "AI-initiated" indicator on the actor field, differentiating them from human-actor events. This satisfies the technical spec §7 requirement that AI-initiated RBAC decisions are logged as a distinct event class.
• Audit-significant actions show a confirmation step. Suspension, revocation, guardian access removal, locum expiry override, and custom role modification each require an explicit confirmation step before the action executes. The confirmation step must name the action, the affected user, and the immediate consequences. (§3.5, §5.3, §6, §4.4)
• Immutability is surfaced, not hidden. The audit log table must carry a persistent read-only indicator (e.g. a lock icon in the table header or a banner) so administrators understand that records cannot be edited. Attempting to edit a record (e.g. via a keyboard shortcut) must produce a clear read-only message rather than a silent failure. (§8.1)
• The current user's role and active permissions are visible in the header. The role scope indicator shows the current user's role label at all times. For ACP-level identities, an elevated-access indicator is shown for the duration of the elevated session. (§4.1, §4.4)
• Read-only states are visually distinct from editable. User records viewed by a Manager (within their site scope, read-only access per §9) must render with no edit affordances visible — not greyed-out disabled controls, which imply editability. The record must appear as a read-only summary view. (§9)
• ACP session context is persistent and visible. Given the elevated sensitivity of ACP-level actions, the UI must display a persistent session context indicator throughout ACP sessions, and must surface a countdown or expiry warning before the shorter ACP session timeout is reached. (§4.1)
• Audit trail as a first-class UI surface. Consistent with the Admin Control Plane's principle that audit trails must be visible and queryable without leaving the operational environment, Access Manager's audit log must be reachable from within every primary administrative surface — not only from a dedicated Audit section. Staff identity events (login, failed authentication, session termination), permission grants and overrides, and role changes must all be queryable inline: when an administrator views a user record, that record's access history must be directly accessible in the detail pane without navigating away. Similarly, when operating within the ACP, the administrator must be able to query Access Manager audit events — filtered by actor, event type, site, or time range — from within the ACP environment. The audit log view must be indexable and filterable to the same standard as the standalone Audit > Access log surface, and must carry the same read-only, immutable guarantees. (§8, §8.1, §13.4, §10 ACP)

12. Notification & communication patterns

All notification patterns below are inferred from the technical spec §10 (Communication Hub integration) and §8.1 (audit events).

• In-app banner — Used for mid-session permission scope updates that change what the current user can see or do, so the user understands why their view has changed. Also used during ACP sessions to display a persistent elevated-access warning. (§4.3, §4.1)
• Toast — Used for confirmations of completed administrative actions: user provisioned, user suspended, session revoked, custom role saved, audit log export ready. Toasts are brief and non-blocking. (§5.1, §5.2, §5.3)
• Force-logout notification — When a user is force-logged out due to suspension or leaver revocation, the surface on which they were active must display a clear, non-alarming message explaining that their session has ended and prompting them to contact their practice administrator if they believe this is in error. This is distinct from a standard session-expiry message. (§3.5, §4.3)
• Push notification (via Communication Hub — NOT directly) — Access lifecycle events that require staff or patient action (e.g. a new user welcome message, a leaver confirmation to the leavee, or a guardian access notification) are dispatched via Communication Hub. Access Manager does not send push notifications directly. (§10)
• Email / SMS (via Communication Hub — NOT directly) — New user provisioning notifications and leaver confirmations that require an out-of-band communication (e.g. welcome email with authentication setup link, or confirmation to the leaver) are dispatched via Communication Hub. (§10)

13. Open questions

The following UX decisions must be resolved before this spec is promoted from draft to published. Items marked with a † are directly linked to unresolved technical spec open questions (technical spec §15).

1. †Platform-defined propagation window (technical spec OQ 1) — What is the maximum latency for mid-session role scope updates to reach active sessions? The UX treatment for the in-app banner (§12) and the mid-session update flow (§5.1 Flow 5) depends on whether this window is sub-second, seconds, or longer. A perceptible delay may require a loading state on the surface being updated.

2. †ACP session lifetime maximum (technical spec OQ 2) — What is the upper bound for ACP session lifetimes? The design of the session expiry countdown/warning (§11) depends on the magnitude of this value. A 15-minute maximum requires a different UX treatment than a 4-hour maximum.

3. Force-logout message copy — The text shown to a user who is force-logged out due to revocation or suspension needs to be carefully authored to be clear without being alarming or revealing the reason for revocation to the wrong audience. (needs UX writer input)

4. OTP delivery channel selection (patient app) — The technical spec §4.2 states OTP is delivered via Communication Hub but does not specify whether the patient chooses email or SMS at the point of authentication, or whether this is a practice-configured default. The authentication flow design (§5.1 Flow 4) requires this to be resolved.

5. Guardian/proxy consent surface — The technical spec §13.2 Rule 5 states guardian and proxy access requires explicit patient consent, but does not specify whether consent is captured within Access Manager's UI or within the Patient App. The guardian/proxy access panel component (§6) scope depends on this.

6. Teen transition (automatic revocation at 18) — user-facing communication — The technical spec §2.1 mentions teen transition and automatic revocation at 18. The UX for notifying the patient and/or guardian in advance of this transition is not defined. (needs UX writer input — notification timing, copy, and whether this is surfaced in Access Manager's admin UI or solely via Communication Hub)

7. Custom role label character constraints — Are there constraints on custom role label strings (length, character set, reserved words) that would require inline validation in the role-configuration flow (§5.1 Flow 6)?

8. Audit log export format — The technical spec §13.4 states export must be in "machine-readable format" but does not specify CSV, JSON, or another format. The export action design (§6 component inventory) and the export flow (§5.1 Flow 7) require this to be confirmed.

9. Self-service account management scope for patients — The technical spec §9 states users may read their own record. For patients, the extent of self-service account management available within the Patient App (e.g. updating contact details, changing authentication method) needs to be defined so the patient-facing surfaces in §4.3 can be fully specified.

10. HR handoff administrator confirmation window — Flow 8 (§5.1) references a "practice-configured window" after which an unactioned HR-triggered pending action escalates to a banner. The default value and the configuration surface for this window have not been defined. This must be resolved with HR & People Manager and Access Manager technical owners before Flow 8 can be fully specified.