Digital Forms – UX Specification

Related Technical Authority: Digital Forms – Technical Specification

1. Purpose

This UX specification governs the experience of creating, completing, signing, reviewing, and managing structured digital forms within Primoro. It covers the patient and carer journey through form completion and e-signature, the clinical and front-of-house staff journey through form review and governance, and the administrative journey through template management, bulk operations, and compliance reporting. The primary roles served are: patients, authorised carers, clinical staff, administrative staff, and practice administrators.

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.
• Consent is never ambiguous — the signature step is always a distinct, deliberate act. It must be visually, spatially, and interactively separated from the rest of form completion, so that patients and carers cannot mistake scrolling past a page for giving consent. Inferred from the technical spec's requirement that legally valid e-signatures are captured with delegated signing attribution (§2.1, §3.1).
• Blocking states are honest and actionable — when a mandatory form prevents treatment progression, the UI states exactly what is blocked, who must act, and what the next step is. It never presents a dead end. Inferred from the Surgery Tablet Finish & Send hard stop described in §5.2 and §13.2 rule 1.
• Attribution is always visible — wherever a form has been signed by a carer, guardian, or assisting staff member rather than the patient directly, that attribution is surfaced clearly to all parties with access. Inferred from delegated signing fields (SignedByUserId, SigningRole) in §3.1 and §13.2 rule 6.

3. Design Philosophy

The mental model for Digital Forms is a governed checkpoint, not a filing cabinet. Forms exist in a workflow — they are assigned, completed, and reviewed as part of an appointment or patient journey — and the design must reflect that temporal, sequential quality. Inferred from the state machine (§3.2) and the appointment-driven assignment model (§4.1).

Empty states: A patient who has no outstanding forms should see a positive confirmation of that fact, not a blank screen. A staff view with no outstanding mandatory forms is a good state and should be communicated as such. Inferred from the engagement signal for outstanding mandatory form count per appointment (§5.4) and the Finish & Send hard stop logic (§5.2).

Error states: Errors during form submission, PDF generation, or Document Hub push must never silently fail. If a submission cannot be fully committed — for example, because Document Hub is temporarily unavailable — the patient or carer sees a clear, honest message that their response has been received and is being processed; they are never left uncertain about whether their signature was captured. Inferred from the reliability requirement and graceful degradation rule in §14 and §13.2 rule 7.

AI suggestions: AI-surfaced content (risk indicators, form relevance suggestions, flagged inconsistencies) is always presented as a distinct, labelled layer separate from the form content itself. Staff are never left to guess whether a highlight or suggestion came from the system or a colleague. Accepting or dismissing an AI suggestion is always an explicit action. Inferred from §4.4, §7, and §13.2 rule 4.

Multi-step flows: Form completion for patients is a wizard-style flow with clear progress indication. The signature step is always the final, distinct step — never embedded mid-flow. Inferred from the technical spec's separation of completion and signature events and the requirement that submission timestamp and signature are separately recorded (§3.1).

Undo and redo: Once a form has reached Submitted / Signed status, it cannot be amended or re-opened by the patient; the state machine explicitly prohibits return to Assigned or Viewed (§3.2). The UI must therefore make clear before the signature step that the action is final. Staff with the appropriate role may initiate a re-completion flow, which creates a new form instance rather than editing the signed original.

Read-only vs editable surfaces: Signed forms are always presented in a visually distinct read-only state. The read-only treatment must be unambiguous — it is never possible to mistake a signed form for one that is still open for editing. Inferred from §13.2 rule 2 and the immutability requirements throughout §8.

4. Primary Surfaces

4.1 Web Portal

Who uses it: practice administrators, administrative staff, and clinical staff. Inferred from the staff-facing capabilities described in §5.1 and the role table in §9.

Key tasks performed here:

• Searching, filtering, and reviewing form records by form type, status, expiry date, linked appointment, patient, origin, and audit event. Inferred from §13.4.
• Managing form templates: creating, versioning, and archiving templates via the Admin Control Plane. Inferred from §13.3.
• Configuring expiry rules, signing permissions, delegation rules, pre-visit visibility windows, and consent enablement flags. Inferred from §13.3.
• Initiating and monitoring bulk assignment operations: defining cohorts, submitting bulk jobs, and querying bulk job status post-submission. Inferred from §4.3 and §13.2 rule 8.
• Accessing and exporting the immutable audit log, with date-range, patient, form type, and event-type filtering. Inferred from §8 and §13.4.
• Reviewing AI-suggested form assignments and accepting or dismissing them with an explicit confirmation action. Inferred from §4.4 and §7.
• Overriding or declining a form with a documented reason. Inferred from the override/decline action in §9.
• Manually assigning additional forms to a patient or removing optional forms, with documented justification. Inferred from §4.2.

Layout pattern: list-detail for form record management; wizard for bulk assignment configuration; form layout for template authoring and configuration. Inferred from the nature of the tasks described in §5.1 and §13.3–13.4.

4.2 Tablet App

Who uses it: clinical staff and reception staff during the appointment workflow on the Surgery Tablet. Inferred from §5.2.

Key tasks performed here:

• Viewing outstanding mandatory and recommended forms for the current appointment within the step sequence of the appointment workflow. Inferred from §5.2.
• Presenting forms to patients or carers in-room for completion and signature, including carer-assisted completion flows. Inferred from §5.2 and §14 accessibility note.
• Staff-assisted guided form completion — clinical staff may guide a patient or carer through a structured, step-by-step form flow directly on the tablet. In this pattern, the staff member operates the tablet while the patient provides verbal or physical responses; the flow is identical to unassisted completion but the staff member's assistance is distinct from the staff member signing on the patient's behalf. The UI must make clear at all times who is providing the answers and who will be signing. Inferred from the staff-guided completion pattern described in the Surgery & Decon Day View and Staff App Mode surface specifications.
• Being blocked by the Finish & Send hard stop when one or more mandatory forms remain unsigned, with a clear display of which forms are outstanding and who must act. Inferred from §5.2 and §13.2 rule 1.
• Receiving warnings (non-blocking) for recommended or optional forms that are incomplete at Finish & Send. Inferred from §5.2 and §13.2 rule 10.
• Reviewing AI-surfaced risk indicators and flagged inconsistencies from submitted forms where the AI Guardian add-on is enabled. Inferred from §4.4 and §13.5.

Touch ergonomics: glove-friendly tap targets ≥ 48 px. Form input controls must be reachable in a single-handed, upright-tablet orientation. The signature capture control must be large enough for comfortable stylus or finger signing. Inferred from the clinical in-appointment context described in §5.2 and the WCAG touch target requirement referenced in §14.

Time-bound tablet sessions are enforced: the session interface must surface a clear session-expiry warning with sufficient lead time for staff to save any in-progress state before access is revoked. Inferred from §9.

4.3 Mobile App (Patient)

Who uses it: patients and authorised carers. Inferred from §5.3.

Key tasks performed here:

• Receiving notification that a form has been assigned and navigating directly to the form to complete it. Inferred from the form-assigned notification trigger described in §6.2 and §5.3.
• Completing multi-step structured forms pre-visit, in-visit, and post-visit. Inferred from §5.3.
• Reviewing a summary of answers before the signature step and providing a legally valid e-signature as the final, distinct action. Inferred from §3.1 and the state machine in §3.2.
• Viewing all previously signed forms in a read-only format. Inferred from §5.3 and §9.
• Downloading or securely sharing a signed PDF. Inferred from §5.3 and §9.
• Completing forms as an authorised carer on behalf of a patient, with clear attribution of the carer's signing role (Parent, LegalGuardian, AuthorisedCarer) surfaced throughout and confirmed at signature. Inferred from §3.1 and §5.3.
• Receiving push notification reminders for expiring or expired forms. Inferred from the Communication Hub notification triggers in §6.2.

5. Interaction Model

5.1 Primary Flows

Flow 1 — Patient completes a pre-visit form (mobile app)

Inferred from §5.3, §3.2, and the Communication Hub notification trigger in §6.2.

1. Patient receives a push notification: a form has been assigned to their upcoming appointment.
2. Patient taps notification → lands on the outstanding forms list for that appointment.
3. Patient selects the form → wizard-style multi-step form opens.
4. Patient completes each section; validation feedback is provided inline as each section is completed.
5. Patient reaches the summary step: all answers are presented read-only for review.
6. Patient proceeds to the signature step (distinct screen / distinct action).
7. Patient provides e-signature.
8. Form transitions to Submitted / Signed. A confirmation screen is shown. A signed PDF is generated and pushed to Document Hub in the background.
9. Patient is returned to the outstanding forms list; the completed form now appears as signed.

Flow 2 — In-appointment form completion on the Surgery Tablet (carer-assisted)

Inferred from §5.2, §3.1 delegated signing, and §9.

1. Clinical staff open the appointment in the Surgery Tablet workflow. Outstanding mandatory forms appear as blocking step items.
2. Staff present the tablet to the patient or carer.
3. If the carer is completing the form: the carer's signing role is confirmed on-screen before the form opens (e.g. "Signing as: Parent on behalf of [patient name]"). The delegated signing context banner (see §6 Component Inventory) remains persistently visible throughout the entire form completion flow, so that neither the carer nor a reviewing staff member can be in any doubt about who is completing and who is represented. The signing role and represented patient identity are drawn from Family Profiles; if the authorised carer relationship cannot be confirmed, the form must not be presented for carer signing. (needs UX writer input — exact confirmation prompt copy)
4. Carer completes the multi-step form on the tablet.
5. Carer reaches the summary step and then the distinct signature step.
6. Carer provides e-signature. Delegated signing attribution (SignedByUserId, SigningRole, SignedOnBehalfOfPatientId) is locked immutably at this point.
7. Form transitions to Submitted / Signed. The appointment workflow step is unblocked.
8. If all mandatory forms are now signed, Finish & Send becomes available.
9. If recommended or optional forms remain incomplete, a non-blocking warning is shown before Finish & Send proceeds.

Flow 3 — Staff manually assigns an additional form (web portal)

Inferred from §4.2.

1. Staff navigate to the patient's form record on the web portal.
2. Staff select "Assign form". (needs UX writer input — exact label)
3. Staff select the form template from the available list.
4. Staff provide a documented justification. (needs UX writer input — field label and helper text)
5. Staff confirm the assignment. The form is assigned; the audit log records the actor identity, timestamp, and justification.
6. The patient receives a notification via Communication Hub.

Flow 4 — Finish & Send hard stop (Surgery Tablet)

Inferred from §5.2, §13.2 rules 1 and 10, and §3.2.

1. Staff attempt to close the appointment via Finish & Send.
2. System checks for mandatory forms not in Submitted / Signed state.
3. If one or more mandatory forms are unsigned: Finish & Send is blocked. A blocking state screen is shown listing precisely which forms are outstanding and what action is required. The staff member cannot proceed past this screen until the forms are resolved.
4. If all mandatory forms are signed but recommended or optional forms are incomplete: a non-blocking warning list is shown. Staff may acknowledge and proceed.
5. Once all mandatory forms are signed, Finish & Send completes.

Flow 5 — Admin initiates a bulk form assignment (web portal)

Inferred from §4.3 and §13.2 rule 8.

1. Administrator navigates to bulk assignment in the web portal.
2. Administrator defines or selects a patient cohort using segmentation criteria.
3. Administrator selects the form template(s) to assign.
4. Administrator reviews the cohort summary and confirms the bulk job. (needs UX writer input — confirmation modal copy)
5. The bulk job is submitted asynchronously. The UI immediately returns a job reference and a status indicator; the administrator is not blocked.
6. The administrator can query bulk job status at any point from the job history view.
7. On completion, the audit log records the initiation and completion events.

Flow 6 — Staff reviews AI form suggestion (web portal or tablet)

Inferred from §4.4, §7, and §13.2 rule 4.

1. Primoro AI Assistant surfaces a suggested form assignment or flags an inconsistency in a submitted form. The suggestion is visually labelled as AI-generated (see §11).
2. Staff review the suggestion and the supporting context.
3. Staff take an explicit action: accept or dismiss. Neither outcome is the default; both require a deliberate tap or click.
4. Regardless of the outcome, the action is recorded in the Form AuditLog with actor identity.

Flow 7 — Nurse delegates to Digital Forms for signature capture within authenticated session (Surgery Tablet)

Inferred from the Surgery & Decon Day View surface specification (§4.3) and the authenticated nurse session model in §9.

1. Nurse is operating the Surgery Tablet under an authenticated, time-bound session. The appointment workflow displays form and consent status for the current patient.
2. Nurse reviews the form and consent status panel. Outstanding forms are listed with their RequiredStatus (Mandatory, Recommended, Optional) and current state. The nurse can identify at a glance which items are blocking and which are advisory.
3. Nurse selects a form to initiate signature capture. The Digital Forms wizard launches within the current session context; the nurse's session identity is preserved and visible throughout.
4. If the patient or carer will sign: the nurse hands the tablet to the patient or carer. The delegated signing attribution banner confirms the signer identity and role before the form opens.
5. If a carer is signing on behalf of a minor or dependent patient: the carer's authorised relationship must be confirmed against Family Profiles data before the signature step is presented. If the relationship cannot be confirmed, the signature step is blocked with an actionable error directing staff to resolve the carer relationship in Family Profiles. Inferred from §6.1 and the Family Profiles governance model.
6. Signature is captured. The nurse's session remains active; on return of the tablet, the appointment workflow reflects the updated form status.
7. The nurse's session time-limit warning continues to display throughout. If the session expires mid-flow, the in-progress form state is handled according to the offline/session-expiry policy (open question — see §13, item 1).

Flow 8 — Mandatory form gate in Appointment Manager context (Surgery Tablet)

Inferred from Appointment Manager UX §4.2 (mandatory form gate in the in-chair workflow) and Digital Forms §5.2, §13.2 rule 1.

1. Appointment Manager surfaces the in-chair step sequence on the Surgery Tablet. One or more steps in the sequence are owned by Digital Forms and represent mandatory form completion.
2. The appointment step is shown as incomplete (blocked) until the associated mandatory form reaches Submitted / Signed state. The visual treatment of the appointment step must communicate that it is a form-completion gate, not a generic incomplete task — the form name, RequiredStatus, and current form state are visible within the step.
3. When the clinician attempts to advance the appointment to the next stage, Appointment Manager queries Digital Forms for mandatory form status. If any mandatory form is not in Submitted / Signed state, the appointment stage transition is blocked. The blocking message names the specific outstanding forms and provides a direct action to open the relevant form.
4. Once all mandatory forms for the appointment are signed, the form-gate step is marked complete and appointment progression is unblocked. The transition is reflected immediately in both the Appointment Manager step view and the Digital Forms outstanding forms list.
5. The hand-off between Appointment Manager and Digital Forms is seamless from the staff perspective: tapping the form-gate step opens the Digital Forms wizard without navigating away from the appointment context. On completion, the user is returned to the appointment step view. (needs UX writer input — confirm navigation model: modal overlay vs full-screen takeover vs embedded panel)

5.2 Carer-Delegated Form Completion — Persistent Context Requirements

Inferred from Family Profiles UX §4.3, Digital Forms §3.1 (SigningRole fields), and the "Attribution is always visible" and "Consent is never ambiguous" core principles.

When a form is being completed and signed by an authorised carer on behalf of a patient, the following requirements apply throughout the entire completion flow, across all surfaces (mobile app and Surgery Tablet):

• Persistent identity banner — the represented patient's name and the carer's signing role (e.g. "Parent", "LegalGuardian", "AuthorisedCarer") are displayed in a persistent, non-dismissible banner for the full duration of the form completion session. This banner must be visible on every step of the wizard, including the summary and signature steps. It must not be obscured by scroll, keyboard, or form content. Inferred from Family Profiles' 'consent is a first-class UI event' principle and Digital Forms §13.2 rule 6.
• Authorisation confirmation before form opens — before the first question is presented, the carer is shown a confirmation screen identifying the patient on whose behalf they are acting, their signing role, and the form they are about to complete. The carer must take an explicit action (e.g. "Confirm and continue") to proceed. This screen is not skippable. (needs UX writer input — confirmation screen copy and exact button label)
• Consent eligibility gate — for forms that require parental or guardian consent, the carer's signing role must be verified against the Family Profiles delegated relationship before the signature step is presented. If the carer's signing role does not confer the required consent authority for the form type, the signature step is replaced with a clear, actionable blocking message explaining why the carer cannot sign this form and directing staff or the carer to the appropriate resolution path. Inferred from Family Profiles governance model and §6.1.
• Attribution on signed record — once signed, the signed form record prominently displays the signing carer's identity, their signing role, and the patient on whose behalf the form was signed. This information is shown in the form record header, not in a collapsed metadata section. It is visible to all parties with access to the form record. Inferred from §3.1 and §13.2 rule 6.
• Minor patient context — where the patient is a minor, the UI must not present the patient's full record to the carer beyond what is necessary for the form completion task. The carer sees the patient's name and appointment context; access to broader patient record data is governed by Family Profiles and Access Manager, not by Digital Forms. Inferred from Family Profiles data-minimisation principles and §9.

5.3 State Machines (Mirror of Technical Spec § 3.2)

The following states and transitions are defined in §3.2 of the technical specification. UX treatment is inferred from the governance and auditability requirements in §8 and the blocking rules in §5.2 and §13.2.

Prohibited transitions — the UI must never present a control that would allow a form in Submitted / Signed state to return to Assigned or Viewed. These controls must not appear, not be disabled. Inferred from §3.2 "No dead toggles" and §13.2 rule 9.

5.4 Document Hub Lifecycle States Surfaced in Digital Forms UI

Inferred from the Document Hub module specification and Digital Forms §6.2, §10, and §13.2 rule 7.

When a form is signed, a signed PDF is generated and pushed to Document Hub. Document Hub maintains its own lifecycle states for that document (e.g. processing, available, acknowledged). Digital Forms surfaces a representation of this state to patients and staff without requiring them to navigate to Document Hub directly.

• Processing state — immediately after signing, while Document Hub is generating and indexing the signed PDF, the form record shows a brief "Document being prepared" indicator in place of the download link. The form's own Submitted / Signed state is not affected by this processing; the form is confirmed signed regardless of Document Hub processing progress. The patient confirmation screen shown immediately after signing states that the signed copy is being prepared and will be available shortly. Inferred from §13.2 rule 7 and the graceful degradation requirement in §14.
• Available state — once Document Hub confirms the PDF is available, the download link is activated on the form record in the patient app and the staff web portal. The patient app may surface a brief, non-intrusive notification (in-app banner or toast) confirming that their signed copy is ready. Inferred from §5.3 and §9.
• Document Hub unavailable — if Document Hub is temporarily unavailable at the time of signing, the patient sees the confirmation screen described in §3 (Design Philosophy, Error states): their response has been received and is being processed. The form record shows a pending document state with a message confirming that the signed copy will be available once processing completes. Staff views reflect the same pending state. The form is not re-opened for re-entry under any circumstances. Inferred from §14 reliability and §13.2 rule 7.
• Acknowledgement tracking — where Document Hub tracks patient acknowledgement of a received document (e.g. the patient has opened or confirmed receipt of the signed form), this acknowledgement state is surfaced in the staff web portal form record view as a secondary metadata item. It does not affect the form's own lifecycle state but is visible to staff as a governance signal. (needs UX writer input — confirm acknowledgement label and visual weight with Document Hub UX team)
• Patient download and share — the "Download signed form" action in the patient mobile app retrieves the signed PDF via Document Hub. If the document is not yet available (processing state), the download action is replaced with the "Document being prepared" indicator; the patient is not presented with a broken download link. Inferred from §5.3 and §9.

5.5 Empty / Loading / Error / Offline States

Web portal — form records list

• Empty state: A patient or filter combination with no matching forms shows a contextual message confirming that no forms match the current criteria, with a prompt to adjust filters or assign a new form if the user has permission. Inferred from §13.4 filter capabilities and §4.2.
• Loading state: Skeleton rows while the list fetches. Inferred from the < 1 second performance target in §14 and the async bulk operation requirement.
• Error state: If the list fails to load, a non-blocking error message is shown with a retry action. Partial data is never silently displayed as complete. Inferred from §14 reliability.
• Offline state: The web portal requires connectivity; an offline banner is shown and list/search actions are unavailable. Inferred from the connectivity-dependent nature of the web portal described in §5.1; the offline question for the tablet is an open question (§15.1).

Surgery Tablet — in-appointment form step

• Empty state: If no forms are outstanding for the appointment, the step is shown as complete with a positive confirmation. Inferred from the appointment workflow step logic in §5.2.
• Loading state: Form content must load within the < 1 second target (§14). A skeleton or spinner is shown for any load that exceeds a brief threshold. The surgical context means long loading states are unacceptable; this is a performance constraint as much as a UX one.
• Error state: If a form fails to load, a clear error is shown with a retry action. Staff must not be left with a broken step in the appointment workflow. Inferred from §14 reliability and the critical nature of the Finish & Send gate.
• Offline state: Behaviour is an open question — see §13 (Technical Spec open question 1). The UX treatment for offline mid-form cannot be finalised until the offline handling policy is defined. Placeholder: the tablet must clearly indicate connectivity loss and communicate to staff whether in-progress data is safe.

Patient mobile app — form completion

• Empty state: If the patient has no outstanding forms, they see a positive confirmation. If they have no signed forms, the signed forms list shows a contextual empty state. Inferred from §5.3.
• Loading state: Skeleton screens while form content loads. Progressive rendering where form sections can be shown as they load. Inferred from the patient-facing mobile context in §5.3.
• Error state: If a submission cannot be fully committed (e.g. Document Hub temporarily unavailable), the patient sees a clear message that their response has been received and is being processed; they are not told the submission failed. The form must not re-open for re-entry. Inferred from the graceful degradation rule in §14 and §13.2 rule 7.
• Offline state: Whether offline signing is permitted is an open question — see §13 (Technical Spec open question 5). Until resolved, the UX treatment cannot be finalised. Placeholder: the app must communicate connectivity loss clearly and not allow the patient to submit without confirmation of the sync behaviour.

6. Component Inventory

New components introduced or extended by this module:

• Form wizard — multi-step guided form completion with progress indicator, section-by-section validation, and a distinct final signature step. Appears in patient mobile app and Surgery Tablet. Inferred from §5.2, §5.3, and the state machine in §3.2.
• Signature capture control — a touch- and stylus-optimised e-signature input that forms the final, irreversible step of form completion. Must meet glove-friendly tap target and WCAG touch target requirements. Appears in patient mobile app and Surgery Tablet. Inferred from §2.1 and §14 accessibility note.
• Delegated signing attribution banner — a persistent, contextual banner shown throughout carer-signed form completion, confirming the signing role and the patient on whose behalf the form is being signed. Locked and displayed on the signed form record. Inferred from §3.1 SigningRole fields and §13.2 rule 6.
• Mandatory form blocking screen — a full-step blocking view on the Surgery Tablet that lists outstanding mandatory forms and the actions required to unblock Finish & Send. Not a modal; this is a hard-stop surface. Inferred from §5.2 and §13.2 rule 1.
• AI suggestion card — a visually distinct, labelled card for presenting AI-generated form suggestions or flagged inconsistencies to staff. Contains an accept and dismiss action. Never unlabelled. Inferred from §4.4, §7, and §11.
• Bulk job status indicator — a persistent, queryable status component in the web portal showing the current state of submitted bulk assignment jobs (queued, running, complete, failed). Inferred from §4.3 and §13.2 rule 8.
• Audit log viewer — a filterable, exportable log viewer in the web portal. Supports filtering by date range, patient, form type, and event type. Read-only. Inferred from §8 and §13.4.
• Form status badge — a small, consistently positioned badge indicating the current state of a form (Assigned, Viewed, Submitted/Signed, Reviewed, Expired, Superseded). Used in list views across web portal and mobile app. Inferred from the state machine in §3.2.
• Document Hub document state indicator — a small, inline indicator on a signed form record showing the current Document Hub processing state of the associated signed PDF (processing, available, pending due to unavailability). Activates the download link when the document is available. Inferred from §5.4 and §10 (Document Hub cross-module touchpoint).
• Carer authorisation confirmation screen — a non-skippable interstitial screen shown before a carer-signed form opens, confirming the represented patient, the carer's signing role, and the form to be completed. Requires an explicit "Confirm and continue" action. Inferred from §5.2 (carer-delegated form completion requirements) and Family Profiles governance model.
• Form and consent status panel — a summary panel on the Surgery Tablet listing all forms for the current appointment with their RequiredStatus and current state, providing the nurse with an at-a-glance view of what is outstanding, blocked, or complete before delegating to signature capture. Inferred from Surgery & Decon Day View §4.3 and §5.2 Flow 7.

Reused from the design system:

• Toast notification — for non-blocking confirmations such as successful form assignment or PDF download initiated. Inferred from §12.
• In-app banner — for persistent, contextual alerts such as connectivity loss or bulk job completion. Inferred from §12.
• Filter bar — for the web portal form records list. Inferred from §13.4.
• Skeleton screen — for loading states across list and form views. Inferred from §14 performance requirements.
• Confirmation modal — for irreversible staff actions such as override, decline, and supersede. Inferred from §4.2 and §3.2 state machine.

7. Visual Design Notes

• Signed / read-only forms must have a visually unambiguous read-only treatment — a distinct background, a locked icon or label, and the absence of any input affordances. The treatment must be immediately apparent without requiring the user to attempt an edit. Inferred from §13.2 rule 2 and the immutability requirements throughout §8.
• Mandatory vs recommended vs optional forms must be visually distinguishable in list and step views, so staff and patients can immediately identify which forms are blocking and which are advisory. Inferred from the RequiredStatus enum (Mandatory | Recommended | Optional) in §3.1 and the blocking logic in §5.2.
• AI suggestion cards must be visually distinct from native staff actions and form content — for example, using a distinct border treatment, a labelled AI badge, and a different background. The distinction must not rely on colour alone (accessibility requirement). Inferred from §4.4, §7, and WCAG colour contrast requirements in §8.
• Delegated signing attribution must be visually prominent on signed form records — it is governance-critical information, not secondary metadata. Inferred from §3.1, §13.2 rule 6, and §11.
• Document Hub processing state must be clearly distinguishable from a successful, downloadable signed document — the processing indicator must not look like a broken link or an error state, and the available state must not look like it requires further action. Inferred from §5.4 and the graceful degradation requirement in §14.
• Typography: (needs UX writer input — heading scale, body scale, monospace usage to be defined by design system)
• Colour: (needs UX writer input — semantic colour tokens for success, warning, error, info, and brand to be defined by design system; module must consume, not define)
• Iconography: (needs UX writer input — icon set and sizing to be confirmed; icon-only controls are not permitted without a visible or screen-reader-accessible label)
• Motion: (needs UX writer input — transition usage to be confirmed against platform motion guidelines; prefers-reduced-motion must be honoured per §8)

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:

• The signature capture control must be operable without a stylus — a touch-based signing path must be available. Inferred from the carer-assisted completion context in §5.2 and §14 accessibility note.
• Carer-assisted completion flows must be usable without requiring technical expertise. Instructions must be written in plain language and must not assume familiarity with digital forms. Inferred from §14 accessibility note.
• The mandatory form blocking screen on the Surgery Tablet must be fully operable by keyboard and screen reader. A hard stop cannot be an accessibility dead end. Inferred from §5.2 and WCAG keyboard access requirement.
• AI suggestion cards must not rely on colour alone to convey that the content is AI-generated; a text label or icon-plus-label treatment is required. Inferred from §7 and WCAG colour contrast requirements.
• The read-only state of signed forms must be conveyed programmatically (not just visually), so that screen reader users are informed that the form is locked and cannot be edited. Inferred from §13.2 rule 2.
• The carer authorisation confirmation screen must be fully accessible; plain-language copy, keyboard-reachable confirmation action, and screen reader announcement of the represented patient identity and signing role are required. Inferred from §5.2 (carer-delegated requirements) and §14 accessibility note.
• The Document Hub document state indicator must convey its current state (processing, available, unavailable) programmatically, so that screen reader users receive the same information as sighted users. The download link must be announced as unavailable (not absent) when the document is still processing. Inferred from §5.4 and WCAG keyboard access requirement.

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 explicitly stated in the technical specification. (needs UX writer input — confirm whether RTL is required for any target market in scope for MVP.)
• Form template content (question text, option labels, instructions) must support localisation independently of the application shell strings. Inferred from the template versioning and configuration model in §13.3, and the multi-site, multi-tenant deployment requirement in §14 scalability.
• Date and time stamps in the audit log and on signed form records must be rendered in the user's locale and time zone. Inferred from the timestamptz data types in §13.1 and the audit log export requirement in §8.

10. Cross-Module UX Touchpoints

Where this module's UX intersects with related modules:

• Appointment Manager — forms are surfaced as steps within the appointment workflow. The patient transitions from the appointment view into form completion and returns on completion. On the Surgery Tablet, the Finish & Send gate is owned by Appointment Manager but gated on Digital Forms' mandatory form status query. The visual step sequence must communicate this relationship clearly. The mandatory form gate step (see §5.2, Flow 8) is visually distinct from other appointment steps, identifying the form name, RequiredStatus, and current form state inline, so that clinicians can see at a glance what is needed without entering the Digital Forms wizard. Inferred from §6.1, §6.2, and §10.
• Communication Hub — Digital Forms never sends notifications directly. All notification triggers (form assigned, form expiring, form expired, re-capture required) are events handed to Communication Hub for delivery. From the patient's perspective, push notifications, emails, and SMS messages arrive from the practice communication layer, not from the forms module. The UX implication is that notification copy and delivery preferences are not configured in Digital Forms. Inferred from §6.2, §10, and §2.2.
• Task Manager — when a mandatory form is outstanding or declined, Digital Forms triggers a follow-up task in Task Manager. Staff who work primarily in a task-based workflow will encounter forms as tasks. The handoff point is the task detail linking to the specific form record. Inferred from §6.2 and §10.
• Document Hub — signed PDFs are pushed to Document Hub at generation. From the patient's perspective, "download signed form" in the patient app retrieves the signed PDF via Document Hub. Staff accessing the signed form record will see a link to the Document Hub entry. The forms module displays the SignedPdfReference and a Document Hub processing state indicator (see §5.4 and §6 Component Inventory) but does not host the document. Where Document Hub tracks patient acknowledgement of a received document, this acknowledgement state is surfaced in the staff web portal form record as a secondary governance signal. Inferred from §6.2, §10, and §13.2 rule 7.
• Family Profiles — the carer relationship model and delegated signing rules are owned by Family Profiles. Digital Forms consumes this data to determine who may sign on behalf of a patient and what SigningRole to attribute. From the patient/carer UX perspective, the delegation setup (who is an authorised carer) is managed in Family Profiles, not in Digital Forms. Where a carer's authorised relationship cannot be confirmed against Family Profiles data, Digital Forms blocks the carer signing path and directs staff or the carer to resolve the relationship in Family Profiles. Inferred from §6.1, §3.1, and §5.2.
• Primoro AI Assistant / AI Guardian add-on — when the AI Guardian add-on is enabled, AI suggestions appear within the Digital Forms UI as distinct, labelled suggestion cards. The AI surface is contextual to the form being reviewed; it does not take the user out of the module. Inferred from §4.4, §7, and §13.5.
• Access Manager — all role-based access controls are enforced via Access Manager. The Digital Forms UI must reflect the current user's permissions without exposing controls the user cannot use. Role and permission visibility in the header is governed by the Access Manager integration. Inferred from §9 and §10.
• Aftercare Manager — signed forms relevant to post-visit care are handed off via an outbound event. The UX touchpoint is not interactive for the patient within Digital Forms; the aftercare experience is owned by Aftercare Manager. Inferred from §6.2 and §10.
• Audit & Compliance — the immutable audit log maintained by Digital Forms feeds into the Audit & Compliance module. Administrators accessing compliance dashboards via Governance Reporting will see Digital Forms engagement signals and audit event counts. The export function in the audit log viewer is the primary handoff point. Inferred from §8, §5.4, and §13.5.

UX consistency rules:

• Action buttons on the Surgery Tablet follow the platform-wide tablet layout convention. (needs UX writer input — confirm platform convention for primary action button position on tablet: bottom-right is the assumed default.)
• Form status badges use the same visual vocabulary (colour, shape, label) across the web portal, tablet, and patient app, so that staff and patients develop a consistent mental model of form states. Inferred from the shared state machine in §3.2 and the multi-surface deployment in §5.
• AI suggestion cards use the same visual treatment (badge, border, dismiss/accept pattern) wherever they appear — web portal or tablet — so that the governance signal is consistent regardless of surface. Inferred from §7 and §4.4.

11. Governance & Auditability

The following governance signals must be surfaced in the UI, inferred from §8, §7, §3.1, §9, and §13.2:

• AI suggestions are visually distinct from user actions and form content. AI-generated content (form suggestions, risk indicators, flagged inconsistencies) is presented with a visible AI label or badge and a distinct visual treatment (e.g. outlined card with a labelled AI marker). The distinction must not rely on colour alone. AI suggestions never appear as native form content or native staff actions.
• AI suggestion outcomes are always recorded. After a staff member accepts or dismisses an AI suggestion, the UI confirms the action with a brief, non-intrusive acknowledgement. The underlying audit record is created automatically; the staff member does not need to take a separate logging action.
• Audit-significant actions show a confirmation step. Actions that are irreversible or governance-significant — override, decline, supersede, bulk assignment, audit log export — must pass through a confirmation step (modal or dedicated confirmation screen) before committing. The confirmation step summarises what is about to happen and who will be recorded as the actor.
• The current user's role and active permissions are visible in the header. Staff users can always see which role they are operating under. Where time-bound tablet sessions are active, the remaining session time is visible. Inferred from §9 and the time-bound tablet access rule.
• Read-only states are visually and programmatically distinct from editable states. Signed forms, archived templates, and superseded form instances are presented in a clearly locked read-only treatment. The locked state is conveyed both visually and via programmatic semantics for screen reader users.
• Delegated signing attribution is always visible on signed form records. Where a form was signed by a carer, guardian, or assisting staff member, the signing attribution (signing role, signer identity, patient on whose behalf the form was signed, timestamp) is shown prominently on the signed form record and in the audit log entry. It is never buried in secondary metadata.
• Bulk operations surface their governance trail. The bulk job history view shows the initiating actor, the cohort definition, the timestamp, the job status, and a link to the relevant audit log entries. Administrators can trace every bulk assignment to its authorised originator.
• Form origin is always visible to staff. In list and detail views, the origin of a form assignment (Appointment-driven, Manual, Bulk, AI-Suggested) is displayed, so staff can understand why a form is present in a patient's record. Inferred from the Origin enum in §3.1 and the filter requirement in §13.4.

12. Notification & Communication Patterns

All notification and communication delivery is handled by Communication Hub. Digital Forms emits trigger events only; it never delivers notifications directly. Inferred from §2.2 and §6.2.

• Push notification (via Communication Hub) — used for: form assigned (new form requiring patient or carer action); form expiring (reminder ahead of expiry window); form expired (re-capture required). Inferred from the notification triggers in §6.2.
• Email / SMS (via Communication Hub) — the same trigger events (form assigned, expiring, expired, re-capture required) may be delivered via email or SMS according to the patient's communication preferences as configured in Communication Hub. Digital Forms does not own or display communication preference settings. Inferred from §6.2 and §2.2.
• In-app banner — used within the patient mobile app for: connectivity loss during form completion; submission received and being processed (pending Document Hub confirmation); session expiry warning on the Surgery Tablet. Inferred from §14 reliability and offline handling requirements.
• Toast — used for: successful form assignment confirmation (staff web portal); successful PDF download initiated; bulk job submitted (brief, non-blocking). Inferred from the non-blocking, transient nature of these confirmations and standard platform toast usage.
• Blocking screen (Surgery Tablet only) — the Finish & Send hard stop is not a notification; it is a hard-stop surface that prevents workflow progression. It is not dismissible without resolving the outstanding mandatory forms. Inferred from §5.2 and §13.2 rule 1. This is distinct from all other notification patterns.

13. Open Questions

The following UX decisions must be resolved before this specification is promoted from draft to published.

1. Offline tablet behaviour (UX treatment) — Technical Spec open question 1 (§15) asks whether the Surgery Tablet queues submissions on connectivity loss, hard-blocks, or uses another pattern. Until this is resolved, the empty/loading/error/offline states for the tablet form completion flow cannot be fully specified. The UX treatment depends on the engineering decision.
2. Offline / async signing in the patient app — Technical Spec open question 5 (§15) asks whether patients may sign forms offline and, if so, what the sync and conflict resolution behaviour is. The UX treatment for offline state in the patient mobile app depends on this decision.
3. Signature capture UI pattern — the technical spec specifies legally valid e-signature capture but does not prescribe the input method (drawn signature, typed name, checkbox-plus-declaration, or a combination). The specific signature capture interaction must be confirmed with legal and clinical governance stakeholders before build. (needs UX writer input — confirmation of signature capture pattern and any required legal declaration copy)
4. MFA prompt UX — Technical Spec open question 4 (§15) asks which operations require MFA and whether this is inherited from Access Manager. Until resolved, the UX treatment for MFA prompts within Digital Forms workflows (e.g. audit log export, bulk assignment) cannot be specified.
5. Re-completion flow UX — the technical spec states that authorised staff may request re-completion of an already-signed form with a documented justification. The exact UX for this flow (how the staff member initiates it, what the patient sees, how the superseded and new form instances are visually related) requires design. (needs UX writer input — re-completion flow design and microcopy for justification field)
6. Form expiry warning window — the timing of pre-expiry notifications is configurable by practice administrators (§13.3). The UX for surfacing the expiry warning to patients in the app (how far in advance, how urgently) depends on the configured window. The design must gracefully handle a range of configured values rather than assuming a fixed window.
7. Document Hub acknowledgement label — where Document Hub tracks patient acknowledgement of a signed form document, the label and visual weight of this acknowledgement state in the staff web portal form record requires confirmation with the Document Hub UX team. (needs UX writer input — confirm acknowledgement state label and whether it warrants a status badge or metadata field treatment)
8. Nurse session expiry during carer-signed flow — the interaction between a time-bound nurse tablet session expiring mid-carer-signing flow requires a defined UX treatment. If the session expires while a carer is completing a form, it is unclear whether the carer's in-progress responses are preserved, whether the nurse must re-authenticate before the signature step can be completed, and whether the session expiry warning is visible to the carer or suppressed. This requires resolution with the Access Manager and surgery workflow teams.
9. Appointment Manager navigation model for form gate — when a clinician taps a form-gate step in the Appointment Manager step view, the navigation model (modal overlay, full-screen takeover, or embedded panel) must be confirmed with the Appointment Manager UX team. (needs UX writer input — confirm navigation model and back/return behaviour)
10. (needs UX writer input — all confirmation modal copy, button labels, microcopy for justification fields, and in-app banner text require UX writer authoring before build)
11. (needs UX writer input — the exact visual treatment of each form status badge — label text, colour token, icon — must be confirmed against the design system component library)