Document Hub – UX Specification

Related Technical Authority: Document Hub – Technical Specification

1. Purpose

This UX specification governs every user-facing interaction with Document Hub — the single, secure source of truth for all practice documents in Primoro. It defines how staff, managers, and patients experience document ingestion, lifecycle management, secure sharing, acknowledgement, and audit visibility across the web portal, tablet app, mobile staff app, and patient mobile app. The primary roles it serves are practice staff (uploaders, reviewers, annotators), practice managers (oversight, acknowledgement tracking, compliance), and patients (secure document receipt and third-party sharing).

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.
• Security is legible — the current lifecycle state, active shares, and access permissions of every document are always one step away; users should never have to guess whether a document is live, shared, or revoked. Inferred from the technical spec's single-source-of-truth principle and the requirement for complete, immutable auditability across all document events (§2.1, §8).
• Patient data is never exposed carelessly — staff annotations are never visible to patients; raw files are never transmitted; every share carries an explicit expiry. Inferred from the technical spec's patient annotation isolation requirement (§5.3) and the secure-by-reference integration pattern (§11).
• Irreversibility is signalled clearly — deletion, purge, and version-lock events are distinct from reversible actions and always require explicit confirmation. Inferred from the state machine rules (§3.2) and the requirement for confirmation before purge transitions.

3. Design Philosophy

Document Hub presents itself as a governed filing system, not a collaboration tool or file drive. Inferred from the technical spec's explicit non-goal of acting as a generic file share (§11) and the single-master-copy principle (§2.1).

Mental model: Every document has one authoritative home. Staff navigate to it, act on it in place, and leave it there. Nothing is emailed as an attachment, nothing is copied to an external system, and nothing disappears silently.

Empty states: An empty document list for a given patient or category is an honest, calm state — not an error. The UI should surface a clear prompt to upload or await incoming documents rather than implying something has gone wrong. Inferred from the ingestion flow across multiple sources (§4) and the unassigned queue pattern (§4.4).

Error states: Access-denied states (triggered by real-time permission revocation) must explain clearly that access has changed and direct the user to their manager or Access Manager — never silently blank the screen. Inferred from the immediate session-termination requirement on permission revocation (§9).

AI suggestions: In the current MVP scope there are no AI surfaces (§7). If the AI Guardian extension is enabled in a future version, category suggestions during ingestion will be presented as unconfirmed proposals — visually distinct from confirmed values — and the user must explicitly confirm before commit. Inferred from AI boundary rules (§7).

Multi-step flows: Flows with irreversible consequences (deletion, purge, bulk-share) use a stepped confirmation pattern. Single-step reversible actions (annotation, share creation with expiry) use in-context panels rather than full-page wizards. Inferred from the state machine irreversibility rules (§3.2) and the MFA gate requirement for delete/purge/bulk-share (§9).

Undo/redo: Undo is not available for lifecycle-state transitions (Approved → Superseded, deletion, purge) because state changes are immutable and audit-logged. Reversible operations such as ShareLink revocation are surfaced as explicit actions, not undo. Inferred from the immutability rules in §3.2 and §13.2.

Read-only vs editable surfaces: Superseded, Archived, Deleted, and Purged documents are always presented in a read-only state with a clear visual badge indicating their lifecycle state. Draft and Approved documents surface available actions according to the user's role. Inferred from the lifecycle state machine (§3.2) and RBAC action table (§9).

4. Primary Surfaces

4.1 Web Portal

Who uses it: Practice managers, clinical staff, administrative staff, and front-of-house staff — each seeing only the document categories and actions permitted by their role. Inferred from the RBAC action table (§9) and the enriched description of web portal access (§5.1).

Key tasks performed here:

• Uploading documents and categorising them by type and patient context. Inferred from §4.1.
• Reviewing and approving patient-submitted documents before they reach Approved state. Inferred from §4.2.
• Reviewing and acting on the unassigned document queue (scanner and email artefacts that could not be automatically associated with a patient). Inferred from §4.4.
• Viewing, downloading, and annotating documents in the embedded secure viewer. Inferred from §5.1.
• Creating, monitoring, and revoking internal and external ShareLinks. Inferred from §3.3 and §5.1.
• Tracking acknowledgement status per document, user, role, and site — with manager-level filtering for outstanding gaps. Inferred from §5.4 and §13.4.
• Viewing the audit trail for individual documents (views, downloads, annotations, share events, revocations). Inferred from §8.
• Configuring practice-level settings via the Admin Control Plane: document categories, retention policies, acknowledgement requirements, ShareLink default expiry, OCR behaviour. Inferred from §13.3.
• Performing lifecycle-state transitions: approving drafts, archiving, and initiating soft-deletion. Inferred from §3.2 and the RBAC action table (§9).

Layout pattern: list-detail for the main document library (filterable list on the left or top; embedded viewer and action panel on the right or below); dashboard-style summary view for managers reviewing acknowledgement and share activity. Inferred from the filtering and views specification (§13.4) and the engagement signals described in §5.4.

4.2 Tablet App

Who uses it: Clinical staff and receptionists in the practice, using the staff app mode of the tablet. Inferred from the enriched tablet surface description (§5.2).

Key tasks performed here:

• Viewing documents relevant to the current patient or appointment context. Inferred from §5.2.
• Capturing in-app patient acknowledgements at the point of care. Inferred from the acknowledgement tracking requirement in §5.2.
• Staff-facing document review for documents delivered to the practice context. Inferred from §5.2.

Touch ergonomics: all interactive controls must meet a minimum touch target of 44×44 px. Glove-friendly target sizing should be considered for decontamination contexts. The acknowledgement capture flow in particular should be operable one-handed or with a stylus, as it is used at chairside. Inferred from the in-practice, chairside acknowledgement use case (§5.2) and the WCAG 2.1 AA accessibility requirement (§14).

4.3 Mobile Staff App

Who uses it: Clinical staff and administrative staff accessing Document Hub from the Primoro mobile staff app — typically away from a fixed workstation (e.g. between appointments, on a home-visit call, or reviewing documents ahead of a patient's arrival). Inferred from Staff App Mode §4.3 and the Document Hub technical specification's reference to staff app mode integration.

Key tasks performed here:

• Accessing and viewing practice policies and internal documents relevant to the staff member's role and permitted categories. Inferred from Staff App Mode §4.3.
• Uploading documents from the device (e.g. photographing a paper form or selecting a file from device storage) and assigning category and patient context. Inferred from Staff App Mode §4.3.
• Acknowledging receipt of documents where acknowledgement is required of staff — for example, confirming that a new policy document has been read. Inferred from Staff App Mode §4.3 and the acknowledgement tracking requirement (§5.4).
• Viewing the acknowledgement status of documents assigned to the staff member. Inferred from §5.4.

Scope constraints: The mobile staff app presents a focused subset of Document Hub's capability. Document lifecycle-state transitions (approval, archiving, deletion), ShareLink management, the unassigned queue, and admin configuration are not available from this surface — those operations require the web portal or tablet app. Read-only access to documents within the staff member's permitted categories is the primary use case. Inferred from Staff App Mode's task-focused scope and the RBAC action table (§9).

Touch ergonomics follow the same 44×44 px minimum target requirement as the tablet app. Inferred from the WCAG 2.1 AA accessibility requirement (§14).

4.4 Mobile App (Patient)

Who uses it: Patients accessing documents delivered to them by the practice. Inferred from §5.3.

Key tasks performed here:

• Viewing documents shared with them by the practice (treatment plans, aftercare instructions, consent forms, agreements). Inferred from §5.3 and §4.3.
• Acknowledging receipt of documents where acknowledgement is required. Inferred from the acknowledgement tracking requirement across §5.4 and §3.3.
• Generating secure, time-limited links to share documents with nominated third parties (e.g. a specialist or insurer). Inferred from §5.3.
• Controlling verification requirements on third-party share links they have created. Inferred from §5.3.
• Revoking their own third-party share links at any time. Inferred from §5.3.

Patients never see staff annotations. This must be enforced at the rendering layer — not merely hidden by convention. Inferred from the explicit annotation isolation rule (§5.3 and §9).

5. Interaction Model

5.1 Primary Flows

Flow 1 — Staff upload and document approval

Inferred from §4.1 (staff uploads), §4.2 (patient submissions routed for review), and the Draft → Approved state transition (§3.2).

1. Staff navigates to document library and initiates upload
2. Staff selects file(s) and assigns category and patient context
   (if AI category suggestion is active in a future version: suggestion
   presented as unconfirmed; staff must confirm before commit)
3. System encrypts, indexes, and begins async OCR
4. Document enters Draft state; staff sees OCR-in-progress indicator
   (see Open Question 2 re: search behaviour during OCR)
5. Authorised staff reviews document in embedded viewer
6. Staff promotes to Approved — confirmation step shown
7. Document is now live; access granted to permitted roles
8. [If relevant category requires acknowledgement: acknowledgement
   requests are queued for the designated recipients]

Flow 2 — Patient-submitted document review

Inferred from §4.2 and the RBAC rule that patient submissions require staff review before reaching Approved state.

1. Patient submits document via mobile app
2. Document enters Draft state; flagged as Source = Patient
3. Staff is notified (via Communication Hub) of pending review
4. Staff opens document in embedded viewer on web portal or tablet
5. Staff approves or rejects
   - Approved → document enters Approved state; patient is notified
     via Communication Hub
   - Rejected → [rejection reason captured] → patient notified
     *(needs UX writer input — confirmation and rejection messaging patterns)*

Flow 3 — Unassigned document queue management

Inferred from §4.4 (scanner and email artefacts held in queue when patient association cannot be determined automatically) and the outbound trigger to Task Manager (§6.2).

1. Scanner or email artefact arrives; automatic patient association fails
2. Document enters unassigned queue; Task Manager receives a task trigger
3. Assigned staff member opens queue item from task or queue view
4. Staff reviews document in viewer and assigns patient and category
5. Document is now associated and proceeds to standard Draft → Approved flow
   (see Open Question 3 re: queue ownership and escalation)

Flow 4 — Secure share creation and revocation (staff-initiated)

Inferred from §3.3 (ShareLink object), §5.1 (external share activity logged), and the mandatory expiry rule (§13.2 rule 7).

1. Staff opens document and selects share action
2. Staff selects recipient type (internal / patient / third-party)
3. Staff sets expiry (default from practice policy; may override within bounds)
4. ShareLink is created; link delivered via Communication Hub
   (Document Hub issues secure reference only — no raw file transmitted)
5. Staff can view active links and access events from the document detail panel
6. Staff may revoke a link at any time — confirmation step shown
7. On revocation: link is invalidated immediately; audit event written

Flow 5 — Patient-initiated third-party share

Inferred from §5.3 (patient controls third-party sharing) and §3.3 (ShareLink with Patient as CreatedByType).

1. Patient selects document in mobile app and chooses to share externally
2. Patient sets recipient context and verification requirements
3. Patient sets or accepts default expiry
4. Secure link is generated; patient can copy or share via their device
5. Patient can view active links and revoke at any time from the document view

Flow 6 — Document deletion (soft-delete → pending purge)

Inferred from the Deleted (Pending Purge) and Purged states (§3.2), the synchronous revocation requirement (§13.2 rule 8), and the MFA gate for delete/purge (§9).

1. Authorised staff selects delete action on an Approved or Archived document
2. MFA gate enforced if required by Access Manager policy
3. Confirmation step: user must explicitly confirm; irreversibility is
   stated clearly *(needs UX writer input — confirmation modal copy)*
4. On confirmation:
   - Document moves to Deleted (Pending Purge) state
   - All ShareLinks are synchronously revoked
   - All active viewing sessions for that document are terminated
   - Audit event written
5. Document remains visible in library with Deleted badge (read-only)
   for the retention period; no content is accessible
6. After retention period elapses: purge is system-initiated; audit event
   confirming erasure is written and retained permanently

Flow 7 — Session termination on permission revocation

Inferred from the real-time session termination requirement on Access Manager revocation (§9 and §13.2 rule 9).

1. Access Manager revokes or modifies a user's role or category-level access
2. Document Hub terminates all active viewing sessions for affected documents
3. Viewer closes or blocks further interaction; access-denied message displayed
   *(needs UX writer input — access-denied message copy)*
4. User is directed to contact their manager or practice administrator

5.2 State Machines (Mirror of Technical Spec § 3.2)

The following UX treatments mirror the Document state machine defined in §3.2 of the technical specification.

Signed Digital Forms PDFs — special treatment:

Documents sourced from Digital Forms with a signed-form status must display a permanent lock indicator showing that the document is version-locked to its signing event and that no edits, supersession, or re-upload can alter the original. This lock indicator must be visible in the document detail panel and in the embedded viewer. Inferred from the immutability requirement in §3.2 and §4.3.

5.3 Empty / Loading / Error / Offline States

Document library (web portal and tablet)

• Empty state: When no documents exist for the current filter context (patient, category, date range), display a calm, informational empty state that explains no documents match the current filter and surfaces the upload action if the user has upload permission. For a brand-new practice with no documents at all, display a contextual prompt to begin uploading or configuring ingestion sources. Inferred from §4 (multiple ingestion sources) and the action-first principle.
• Loading state: Use a skeleton list — placeholder rows matching the expected document list shape — rather than a spinner, to reduce perceived latency. The embedded viewer streams documents progressively; a streaming progress indicator is shown while the file loads. Inferred from the performance requirement that the viewer must stream responsively (§14).
• Error state: If the document list fails to load, display an error message with a retry action. If the embedded viewer fails, display an error message that names the specific document and offers a retry; do not leave the user looking at a blank panel. Inferred from the no-dead-toggles principle and the reliability requirement (§14).
• Offline state: Document Hub requires live permission checks on every request (§9) and documents are never stored as local copies (§13.2 rule 1). Therefore offline access to document content is not supported. The offline state should display a clear, calm message explaining that documents require a connection and that no content is available offline — not an error, but an honest constraint. Inferred from the zero-trust, no-caching permission requirement (§9) and the no-raw-copy principle (§2.1).

Unassigned document queue

• Empty state: A calm confirmation that the queue is clear — no pending artefacts awaiting assignment. Inferred from §4.4.
• Loading state: Skeleton list.
• Error state: If the queue cannot be loaded, display an error with a retry action and a note to contact the platform administrator if the problem persists. Inferred from reliability principle.
• Offline state: Queue is unavailable offline; same messaging pattern as document library offline state. Inferred from §9.

Embedded viewer

• Empty state: Not applicable — the viewer only appears when a document is selected. Inferred from the list-detail layout pattern.
• Loading state: Progressive streaming indicator. Inferred from §14 performance requirement.
• Error state: Named document error with retry. Inferred from reliability principle.
• Offline state: Viewer unavailable; connection-required message. Inferred from §9.

OCR in progress:

When a document has been ingested but OCR indexing is not yet complete, the document record is visible and accessible for viewing, but search-within-document and full-text search results for that document are unavailable. An OCR-in-progress indicator is shown on the document record and within the viewer. Inferred from the async OCR requirement (§13.2 rule 10) and Open Question 2 from the technical spec (§15).

Access-denied (session terminated):

When an active viewing session is terminated by a permission-revocation event, the viewer is immediately blocked and replaced with an access-denied message. The message must not expose the reason for revocation but must direct the user to their manager or administrator. No retry is offered because the denial is authoritative. Inferred from §9 and §13.2 rule 9.

6. Component Inventory

New components introduced or extended by this module:

• Embedded document viewer — secure, streaming viewer for all document types; supports in-viewer search highlighting for OCR-indexed documents; renders annotations as overlays without altering the underlying file; presents version-lock indicator for signed Digital Forms PDFs. Appears on web portal (full-pane), tablet (full-screen or split), and mobile staff app (full-screen). Inferred from §5.1, §13.2 rules 3 and 5, and §13.4.
• Document lifecycle badge — compact state indicator (Draft / Approved / Superseded / Archived / Deleted / Purged) shown on every document record in list and detail views. Inferred from §3.2 state machine and the governance-always-visible principle.
• ShareLink management panel — in-context panel for creating, viewing, and revoking ShareLinks; shows recipient type, expiry, access events, and revocation status. Appears in document detail on web portal and (read-only summary) on tablet. Inferred from §3.3, §5.1, and §5.4.
• Acknowledgement tracker — per-document view showing acknowledgement status by user, role, and site; manager-level filter for outstanding gaps. Appears in document detail on web portal. Inferred from §5.4 and §13.4.
• Unassigned document queue view — filterable list of scanner and email artefacts awaiting manual patient and category assignment; surfaced on web portal. Inferred from §4.4.
• Version history panel — progressive-disclosure panel showing all DocumentVersions for a document, with timestamps, creator, and file hash; read-only for all users. Inferred from §3.3 (DocumentVersion object) and the immutability requirement (§13.2 rule 4).
• OCR-in-progress indicator — inline status indicator on document records and within the viewer while async OCR processing is underway. Inferred from §13.2 rule 10 and Open Question 2.
• Version-lock indicator — permanent badge/icon on signed Digital Forms PDFs indicating the document is immutable. Inferred from §3.2 and §4.3.
• Deletion / purge confirmation modal — stepped, high-friction confirmation component for irreversible state transitions; includes explicit irreversibility statement and MFA passthrough where required. Inferred from §3.2, §9, and §13.2 rules 7–8. (needs UX writer input — exact modal copy and button labels)
• Access-denied overlay — full-panel overlay displayed when an active viewing session is terminated by permission revocation. Inferred from §9 and §13.2 rule 9. (needs UX writer input — message copy)

Reused from the design system:

• Toast notification — for transient confirmations (ShareLink created, acknowledgement recorded, document uploaded).
• In-app banner — for persistent attention states (unassigned queue items pending, outstanding acknowledgement gaps).
• Filterable list — standard list with category, date range, source, and lifecycle-state filters.
• Form / upload input — file selection and metadata entry for staff upload flow.
• Skeleton loader — for list and panel loading states.
• Confirmation modal — base component extended by the deletion/purge confirmation modal above.

7. Visual Design Notes

• Typography: heading scale, body scale, and monospace usage to follow platform design system. Monospace is appropriate for file hashes displayed in the version history panel.
• Colour: semantic colour usage only — success (Approved state), warning (Deleted/Pending Purge, outstanding acknowledgements), error (access denied, purged), info (Draft, OCR in progress, ShareLink active). No decorative colour usage. Brand colour application follows platform design system.
• Iconography: platform icon set; sized consistently; never icon-only without a visible label or accessible tooltip for document action controls.
• Motion: transitions used only where they aid spatial orientation (e.g. panel slide-in for document detail, viewer loading progression). State badge changes are never animated in a way that draws unnecessary attention. All motion must respect prefers-reduced-motion.
• The version-lock indicator and the lifecycle badge must be visually distinct from each other and from action controls, so that governance state is never mistaken for an interactive element. Inferred from the no-dead-toggles principle and the governance-always-visible principle.

8. Accessibility & Inclusivity

The module MUST meet WCAG 2.2 AA. Specifically:

• Text contrast ≥4.5:1 (normal) / ≥3:1 (large).
• All interactive controls reachable via keyboard.
• Focus states visible.
• Form fields have programmatic labels.
• ARIA used only where native semantics are insufficient.
• Touch targets ≥44×44 px on mobile/tablet.
• Motion can be reduced via prefers-reduced-motion.
• Screen reader tested on NVDA (Windows/web), VoiceOver (macOS/iOS), and TalkBack (Android patient mobile app).
• The embedded viewer must be keyboard-navigable and screen-reader accessible for document content; page-by-page navigation controls must have descriptive labels. Inferred from the WCAG 2.1 AA requirement stated in the technical spec §14 and the centrality of the viewer to all surfaces.
• The lifecycle badge and version-lock indicator must have programmatic text equivalents (not colour-only) so that state is communicated to screen reader users. Inferred from WCAG 1.4.1 (use of colour) and the governance-always-visible principle.
• The acknowledgement capture flow on tablet must be operable with assistive touch, as it is used at chairside with patients who may have accessibility needs. Inferred from the in-practice acknowledgement capture use case (§5.2).
• Access-denied and session-terminated overlays must be announced to screen readers immediately on appearance. Inferred from the real-time session termination requirement (§9).

9. Internationalisation

• Locale-aware date/time/number formatting throughout — particularly important for ShareLink expiry timestamps, document creation dates, retention period displays, and audit event timestamps.
• All user-facing strings externalised to a translation layer.
• Layouts tolerant of 30% string-length growth (relevant for German and French localisations of document category names, lifecycle state labels, and confirmation modal copy).
• RTL support: not required for MVP, but layout must not structurally preclude future RTL addition.
• Document category names and retention policy labels are configured by practice administrators and may be entered in any language; the UI must not assume ASCII or a fixed character set for these fields. Inferred from the configurable category and metadata schema (§13.3).

10. Cross-Module UX Touchpoints

Where this module's UX intersects with related modules:

• Access Manager — the user never directly interacts with Access Manager's UI from within Document Hub, but Access Manager's decisions are felt at every turn: role-based action availability, MFA gates before delete/purge/bulk-share, and the access-denied overlay on session termination. The UX handoff is invisible to the user but must feel seamless — an MFA challenge should appear as part of the Document Hub flow, not as a jarring redirect. Inferred from §6.1, §9, and §13.2 rules 2 and 9.

Access Manager enforces the principle that unauthorised records are omitted from lists entirely — they are not shown as locked, greyed-out, or access-denied placeholders (Access Manager §2, §13.2 Rule 7). Document Hub MUST implement this consistently: document lists and search results on the web portal, tablet app, mobile staff app, and patient mobile app must only contain records the current user is permitted to access. A user whose permissions have been narrowed should see a shorter list, not a list with inaccessible items. This means that the access-denied overlay (§5.3, §6) is reserved exclusively for the real-time session-termination scenario (where a document the user was actively viewing has its permission revoked mid-session); it is never used as a general "you can't open this" affordance on list items.

• Digital Forms — signed-form PDFs arrive in Document Hub automatically at signing time. From the staff perspective, these documents appear in the library with a version-lock indicator and the source labelled as Module. No manual upload step is needed. From the patient perspective, the signed consent form becomes visible in their mobile app document list. Inferred from §4.3, §6.1, and the immutability requirement.
• Aftercare Manager — care documents generated by Aftercare Manager appear in Document Hub automatically, similarly labelled Source = Module. Staff see them in the library; patients receive them in the mobile app if they have been shared. Inferred from §4.3 and §6.1.
• Communication Hub — Document Hub never shows a messaging UI directly. When a document event requires a notification (e.g. patient-submitted document pending review, document shared with patient), Document Hub emits an event to Communication Hub. The resulting notification (push, email, SMS) is the patient's or staff member's entry point back into Document Hub. The UX continuity rule is: a notification link must resolve directly to the relevant document in the correct app, not to a generic inbox. Inferred from §6.2, §5.3, and the secure-by-reference pattern (§11).
• Task Manager — unassigned queue items and document-linked actions surface as tasks in Task Manager. From a staff member's perspective, a Task Manager task card for an unassigned document should deep-link directly to the queue item in Document Hub. The UX consistency rule is: the task card is the entry point; Document Hub is the place of action. Inferred from §6.2 and §4.4.
• Staff App Mode — the mobile staff app surface (§4.3) is the delivery channel for staff document access, upload, and acknowledgement outside of fixed workstations. Document Hub's list-visibility and permission-enforcement rules apply identically on this surface: only documents within the staff member's permitted categories appear; no inaccessible records are shown. Deep links from Communication Hub notifications and Task Manager task cards must resolve to the correct document within the mobile staff app context when the staff member is authenticated on that surface. Inferred from Staff App Mode §4.3 and the cross-surface RBAC consistency requirement (§9).
• Lab Manager — for LabArtefact documents (e.g. digital impression files from iTero), the Lab Manager UI presents the artefact in the context of a Lab Case without ever storing a raw copy. From a staff perspective, navigating from a Lab Case in Lab Manager to the associated impression file opens the Document Hub embedded viewer in context. Inferred from §4.4, §6.1, §6.2, and §13.2 rule 11.
• PMS (e.g. Dentally) — the PMS surfaces a Primoro document link alongside clinical records. Clicking that link opens the Document Hub embedded viewer (requiring Primoro authentication). The staff member never leaves Primoro's governed environment to view a document. Inferred from §6.2 and the PMS boundary rules (§6.3).
• Smart Dashboards — acknowledgement completion rates and engagement signals computed from Document Hub data are surfaced in Smart Dashboards, not within Document Hub itself. Document Hub's manager-level views show operational data (what needs action now); Smart Dashboards shows trend and performance data. Inferred from §5.4 and the explicit non-responsibility for analytics dashboards (§2.2).
• Security & Privacy module — all audit events are written to the Security & Privacy module's AuditEvent store. Staff with compliance roles can inspect the audit trail via an audit log view within Document Hub (per-document) and via the Security & Privacy module for cross-document or cross-actor queries. Inferred from §3.3, §6.2, and §8.

UX consistency rules:

• Action controls (approve, share, annotate, delete) always appear in the document detail panel, not within the list. The list is for navigation and status scanning only. Inferred from the list-detail layout pattern and the action-first principle.
• Document lists and search results MUST only surface records the current user is permitted to access. Unauthorised records are omitted entirely — never shown as locked, dimmed, or inaccessible placeholders. This rule applies uniformly across web portal, tablet app, mobile staff app, and patient mobile app. Inferred from Access Manager §2 and §13.2 Rule 7.
• Lifecycle state badges use the same visual language on web, tablet, mobile staff app, and patient mobile app — with labels, not colour alone. Inferred from the cross-surface state machine requirement and the accessibility principle.
• ShareLink expiry is always shown in the user's local time zone, formatted to the platform locale standard. Inferred from the internationalisation requirement and the patient-control-over-sharing principle.
• Navigation from a Task Manager task, a Communication Hub notification, or a PMS link must always resolve to the specific document — not to the Document Hub home screen. Deep linking is a consistency requirement, not an enhancement. Inferred from the cross-module notification and task trigger patterns (§6.2).

11. Governance & Auditability

• AI suggestions (document category suggestions during ingestion) are visually distinct from confirmed values — presented as a suggested value in an unconfirmed state that requires explicit staff action before commit. This applies only when the AI Guardian extension is enabled in a future version; in current MVP scope there are no AI suggestions. Inferred from §7 and the AI boundary rules.
• Audit-significant actions — deletion, purge, ShareLink creation with third-party recipients, bulk-share, and version promotion — always show a confirmation step that names the action and its consequences before the user can proceed. Inferred from §3.2, §8, and §9.
• The current user's role and their access level for the current document category are visible in the document detail panel, so staff always understand why certain actions are or are not available to them. Inferred from the RBAC action table (§9) and the governance-always-visible principle.
• Read-only states (Superseded, Archived, Deleted, Purged, version-locked signed forms) are visually distinct from editable states — using the lifecycle badge, the version-lock indicator, and the absence of edit/annotate controls. Inferred from §3.2 and §13.2.
• The per-document audit log (views, downloads, annotations, shares, revocations, state changes) is accessible to authorised staff from the document detail panel under a progressive-disclosure expand — visible on demand, not cluttering the default view. Inferred from §8, §5.1, and the progressive-disclosure principle.
• Active external ShareLinks are surfaced with their recipient type, creation time, expiry time, and access event count, so staff can see at a glance whether a link has been used and when it expires. Inferred from §5.4 and §13.4.
• When a document reaches Deleted (Pending Purge) state, the practice administrator can see the scheduled purge date derived from the configured retention policy. This date must be shown alongside the deleted badge so that the administrator understands the document's remaining lifecycle. Inferred from §3.2 and §13.3 (retention policies).

12. Notification & Communication Patterns

All notifications are delivered via Communication Hub. Document Hub emits event triggers and secure references; it does not send notifications directly. Inferred from §2.2 and §6.2.

• In-app banner (web portal and tablet): Shown for persistent states requiring staff attention — specifically, unassigned documents in the queue awaiting patient assignment, and outstanding acknowledgement gaps flagged for managers. Banners persist until the underlying condition is resolved. Inferred from §4.4, §5.4, and the calm-by-default principle (banners reserved for genuinely actionable states).
• Toast (web portal, tablet, mobile staff app, and patient mobile app): Shown for transient confirmations — document successfully uploaded, ShareLink created, ShareLink revoked, acknowledgement recorded, document approved. Toasts are brief, non-blocking, and do not require user dismissal. Inferred from the list of audit events in §8 and the calm-by-default principle.
• Push notification (patient mobile app, delivered via Communication Hub): Used to notify patients that a document has been shared with them or that an acknowledgement is required. Push notifications are never generated by Document Hub directly — Document Hub emits a trigger and secure reference to Communication Hub, which manages delivery preferences and channel. Inferred from §5.3, §6.2, and §12 (Communication Hub orchestrates messaging).
• Email and SMS (delivered via Communication Hub): Used for document delivery events when the patient's notification preferences include email or SMS. As with push, Document Hub provides the secure time-limited reference; Communication Hub handles the channel and message content. Raw document content is never transmitted by email. Inferred from §4.2 ("never transmit patient-submitted documents as email attachments"), §6.2, and §11 (non-goal: sending documents as attachments).
• Staff email/push (delivered via Communication Hub): Used to alert relevant staff when a patient-submitted document is pending review or when a document-linked task has been created. Inferred from §4.2 and the Task Manager outbound trigger (§6.2).

13. Open Questions

The following UX decisions must be resolved before this spec is promoted from draft to published. Items 1–6 are carried forward from Open Questions in the technical specification (§15); items 7–10 are UX-specific additions.

1. Retention policy defaults and their display — The technical spec does not specify default retention durations per category. Until defaults are defined, the UI cannot show meaningful retention period indicators on Archived or Deleted documents. UX needs the agreed minimum defaults to design the retention display in the document detail panel and the scheduled-purge-date indicator. Carried from technical spec Open Question 1.
2. OCR-in-progress UX — The technical spec requires OCR to be asynchronous but does not define search behaviour for partially-indexed documents. UX needs a decision on: (a) whether partially-indexed documents appear in search results with a caveat, or are excluded until OCR completes; and (b) how the OCR-in-progress indicator is dismissed. Carried from technical spec Open Question 2.
3. Unassigned queue ownership and entry point — It is not yet decided which role owns the unassigned queue, whether queue items surface as Task Manager tasks (deep-linking to Document Hub) or as a Document Hub-native view, or what happens if items remain unassigned beyond a threshold. This decision directly affects the information architecture of the queue view and the task/notification patterns. Carried from technical spec Open Question 3.
4. MFA gate — which operations require it — The list of Document Hub operations that will trigger an MFA challenge from Access Manager has not been finalised. UX needs this list to design the stepped confirmation flows for those operations and to ensure the MFA challenge appears as a seamless in-flow step rather than an unexpected redirect. Carried from technical spec Open Question 6.
5. (needs UX writer input) Confirmation modal copy — All deletion, purge, and irreversible-transition confirmation modals require final microcopy including the irreversibility statement, button labels, and any supporting explanation of consequences.
6. (needs UX writer input) Access-denied and session-terminated message copy — The message shown when an active viewing session is terminated by permission revocation must be clear, calm, and actionable without exposing privileged information about why access was revoked.
7. (needs UX writer input) Document rejection messaging — When a staff member rejects a patient-submitted document, the rejection reason and patient-facing communication need copy decisions.
8. Patient acknowledgement flow design — The technical spec confirms that acknowledgement capture occurs on tablet at chairside, but does not define the interaction pattern (e.g. digital signature, checkbox, biometric). UX must define and validate this flow before tablet build begins. Inferred from §5.2 and the acceptance criterion for acknowledgement tracking (§13.6).
9. Embedded viewer capabilities per document category — The technical spec identifies Imaging as a future extension that will replace the embedded viewer for applicable categories. UX needs to decide whether the MVP viewer should degrade gracefully for imaging artefacts (e.g. show a placeholder with a future-capability message) or whether imaging artefacts are simply not viewable until the Imaging extension is live. Inferred from §11 (non-goal: clinical viewers for advanced imaging) and §13.5 (Imaging extension).
10. Manager audit log export UI — The technical spec requires the audit log to be exportable for authorised compliance roles (§8), but does not define the export surface — whether this is a Document Hub-native export, a Governance Reporting feature, or both. UX needs this boundary clarified before designing the compliance-role view of the audit log. Inferred from §8 and §13.5 (Governance Reporting future extension).
11. Mobile staff app scope boundaries — The capability boundary for the mobile staff app surface (§4.3) has not been fully validated against Staff App Mode's final task inventory. UX needs confirmation from the Staff App Mode team of which Document Hub actions (beyond view, upload, and acknowledgement) are in scope for that surface before the mobile staff app flows are detailed. Inferred from Staff App Mode §4.3 and the RBAC action table (§9).