Knowledge, Training & Learning – UX Specification

Related Technical Authority: Knowledge, Training & Learning – Technical Specification

1. Purpose

This UX specification governs the user experience of the Knowledge, Training & Learning module — the platform's authoritative system for organisational knowledge and structured learning delivery. It defines how managers, administrators, and staff discover, consume, create, and track learning content across the web portal and staff app surfaces. The primary roles it serves are practice managers and administrators (who define and govern learning), and clinical and front-of-house staff (who consume and complete it).

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
• Knowledge does not act — the module stores and delivers; it never reminds, escalates, or enforces. Any action surface that crosses into execution must visually hand off to Task Manager. Inferred from technical spec §10 "Knowledge MUST NOT send reminders, escalate, enforce deadlines."
• Pathway before course — the learner's primary context is their assigned learning pathway, not an undifferentiated catalogue. Individual courses and lessons are reached from within a pathway where possible. Inferred from technical spec §4.3 and §6 describing role-based pathway assignment.
• Compliance is owned elsewhere — the UI must never imply that completing a course inside this module constitutes formal compliance sign-off; that judgement belongs to HR & People Manager and Task Manager. Inferred from technical spec §11 and §15.

3. Design Philosophy

The module's mental model is a learning library with a personal queue. Staff arrive knowing what they must do next (their assigned pathway tasks surfaced by Task Manager) and can also browse the wider knowledge base. Inferred from technical spec §§4–6, 10. The design therefore privileges the "my learning" view over the catalogue by default, and exposes the full catalogue one level deeper.

Empty states are instructive: a staff member with no assigned pathway yet should see a prompt explaining that their manager or HR will assign learning, not a blank screen. Inferred from the auto-assignment model in technical spec §6.2. (needs UX writer input — empty-state heading and body copy for a user awaiting pathway assignment)

Error states distinguish between content-delivery errors (a SCORM package failing to load, an external link being unreachable) and data errors (a course record failing to save). Content-delivery errors offer a fallback action (manual certificate upload); data errors offer retry and a support path. Inferred from technical spec §7 CPD integration modes including manual certificate upload as a fallback.*

AI suggestions (course recommendations, knowledge-base answers) are always visually secondary to assigned work and clearly badged as AI-generated. Inferred from technical spec §12 which limits AI to "answer questions, suggest training" and forbids it from validating compliance.*

Multi-step flows (course creation, pathway definition, certificate upload) use a wizard pattern with a persistent step indicator so that managers can leave and return without losing progress. Inferred from technical spec §9 governance requirements: version control, ownership, approval workflows.*

Read-only and editable surfaces are visually distinct. Staff viewing a published SOP or lesson see a read-only treatment; managers editing course content see an editor chrome.

4. Primary Surfaces

4.1 Web Portal

Who uses it: Managers and Administrators (course creation, pathway management, compliance reporting); HR staff (compliance requirement definition, handoff to Task Manager); Clinicians and front-of-house staff (knowledge lookup, learning completion). Inferred from technical spec Table 1 and §9.2 permissions table.

Key tasks performed here:

• Browse and search the knowledge base (SOPs, policies, operational guides, role responsibilities). Inferred from technical spec §4.1.
• View and progress through an assigned learning pathway. Inferred from technical spec §4.3 and §6.
• Create, edit, version, and submit internal courses for approval. Inferred from technical spec §9.
• Define and manage learning pathways (role assignment, sequencing, required vs optional modules). Inferred from technical spec §6.1 and §4.3.
• Link external CPD courses and upload completion certificates. Inferred from technical spec §7 and §17.
• View Primoro-distributed platform and compliance courses and manage their adoption. Inferred from technical spec §8.
• Review completion and CPD evidence records across the team. Inferred from technical spec §13 and §17.5.

Layout pattern: list-detail for knowledge browsing and course catalogue; wizard for course creation and pathway setup; dashboard for the manager's compliance and completion overview. Inferred from the breadth of tasks and the governance requirements in §9 and §13.

4.2 Tablet App

Who uses it: Clinical staff (dental nurses, clinicians) and front-of-house staff accessing learning content and knowledge articles between clinical tasks. Inferred from technical spec §4 Staff App Mode integration and the role-based delivery model.*

Key tasks performed here:

• View assigned pathway and open the next required lesson. Inferred from technical spec §4.3 pathway model.
• Complete lesson types: video, text, checklist, quiz. Inferred from technical spec §5.2.
• Look up an SOP or operational guide for a quick reference during a task. Inferred from technical spec §4.1.
• Mark a lesson complete and, where applicable, upload a certificate. Inferred from technical spec §13 and §7.2.

Touch ergonomics: glove-friendly tap targets ≥48 px; lesson navigation controls (next, back, mark complete) positioned in the lower two-thirds of the screen for one-handed reach; quiz answer targets full-width. Inferred from the clinical setting implied by the dental-practice context and the Staff App Mode integration.

4.3 Mobile App (Staff)

Who uses it: Staff accessing learning content or knowledge articles away from a desk or clinical bay — for example, reviewing a module before a shift or uploading a CPD certificate from a phone photo. Inferred from technical spec §7.2 manual certificate upload mode and §4 Staff App Mode integration.*

Key tasks performed here:

• View assigned learning pathway progress. Inferred from technical spec §4.3.
• Complete text-based and checklist lessons. Inferred from technical spec §5.2 lesson types.
• Upload a CPD certificate via the device camera. Inferred from technical spec §7.2 "manual certificate upload" mode.
• Read knowledge base articles. Inferred from technical spec §4.1.

5. Interaction Model

5.1 Primary Flows

Flow A — Staff completes an assigned lesson

Inferred from technical spec §§4.3, 5, 6.2, 10.2 and Table 6.

1. Staff opens Staff App / web portal
2. "My Learning" view shows active pathway with next required lesson highlighted
3. Staff taps / clicks lesson → lesson player opens (video / text / checklist / quiz)
4. Staff completes lesson content
5. If quiz: submits answers → pass/fail shown inline
6. "Mark complete" confirmed → CourseProgress record updated
7. Task Manager task corresponding to this lesson is marked complete (background)
8. Staff returned to pathway view; next lesson unlocked if dependencies met

(needs UX writer input — label for "Mark complete" action and confirmation microcopy)

Flow B — Staff uploads an external CPD certificate

Inferred from technical spec §7.2 "manual certificate upload" and §17.5 compliance behaviour.

1. Staff navigates to "My CPD" section
2. Selects "Add external record"
3. Wizard step 1: select or type provider name (against known list: Agilio iLearn, Dental CPD Network, etc.)
4. Wizard step 2: enter course name and CPD hours
5. Wizard step 3: upload certificate file or photograph
6. Wizard step 4: confirm and submit
7. ExternalTrainingRecord created; mapped to compliance requirement if match found
8. Toast confirms submission; HR / manager notified via Communication Hub

(needs UX writer input — step labels, upload prompt copy, confirmation toast copy)

Flow C — Manager creates an internal course

Inferred from technical spec §§9, 5.1, 9.3.

1. Manager navigates to "Course library" → "Create course"
2. Wizard: title, description, visibility (Role / Organisation), source = Internal
3. Add modules → add lessons (type: video / text / checklist / quiz per lesson)
4. Set version label
5. Submit for approval (if approval workflow configured)
6. Approver reviews → approves or returns with comments
7. Course published and available for pathway assignment

(needs UX writer input — approval request notification copy, rejection feedback field label)

Flow D — Manager defines a learning pathway

Inferred from technical spec §§4.3, 6.1, 6.2.

1. Manager navigates to "Learning pathways" → "Create pathway"
2. Selects target role (e.g. Dental Nurse, Receptionist)
3. Adds courses in sequence; marks each as required or optional
4. Sets dependency rules (course B unlocks only after course A complete)
5. Saves pathway
6. Pathway auto-assigned to staff with matching role (new starters or role changes trigger this)
7. Task Manager receives instruction to create corresponding tasks for assignees

(needs UX writer input — dependency rule explanation tooltip copy)

Flow E — Staff or manager searches the knowledge base

Inferred from technical spec §4.1 and §12 AI assistance.

1. User enters search query in knowledge base search bar
2. Results show: articles (SOPs, policies, guides), courses, and (if AI active) an AI-suggested answer
3. AI answer shown with AI badge and "Suggested by AI — verify with source" qualifier
4. User opens article (read-only view)
5. "Related training" link visible if a course maps to this article

(needs UX writer input — AI badge label and qualifier microcopy)

Flow F — HR defines mandatory training requirements and reviews compliance status

Inferred from HR & People Manager spec §4.4, and technical spec §11 and Table 1, which together define the two-way integration between HR & People Manager and this module.

This flow has two complementary directions that together constitute the HR–KTL compliance loop. The KTL module is the delivery and evidence layer; HR & People Manager is the requirements and compliance-status layer. Neither module should duplicate the other's responsibility in its UI.

Direction 1 — HR publishes mandatory training requirements into KTL:

1. HR Manager opens HR & People Manager and navigates to a role definition
   or staff group record
2. HR Manager defines or updates mandatory training requirements for that
   role (course titles, CPD hours thresholds, recurrence periods)
3. HR & People Manager publishes the requirements; KTL receives them and
   maps them to existing courses or pathways where a match is found
4. In KTL, a manager viewing a learning pathway for the affected role sees
   a "Mandatory — HR requirement" badge against each matched course
5. Where no existing course matches a newly published HR requirement,
   KTL surfaces an unmet-requirement indicator in the Course library;
   the manager is prompted to create or adopt a course that satisfies it
6. Staff assigned to the role see no change to the pathway surface — the
   HR-requirement badge is a manager/admin-facing annotation only

Direction 2 — KTL surfaces completion and non-compliance signals back to HR:

1. A staff member completes a course or uploads a CPD certificate in KTL
2. KTL updates the relevant CourseProgress or ExternalTrainingRecord
3. The completion event is raised; HR & People Manager reads the signal
   and updates the staff member's compliance status for the matched
   mandatory requirement
4. An HR Manager reviewing the staff compliance view in HR & People Manager
   sees the updated status without needing to open KTL
5. Where a mandatory requirement remains incomplete past its deadline,
   Task Manager owns escalation — KTL and HR & People Manager each reflect
   the outstanding status but neither module sends its own reminder
6. Deep links from the HR compliance record open the correct pathway or
   course directly in KTL, so the HR Manager can investigate without
   navigating manually

The handoff between the two modules must feel seamless to the user: a deep link from an HR compliance record opens the correct pathway or course in KTL without requiring re-authentication or manual navigation. Conversely, an HR badge on a KTL pathway card links directly to the relevant HR requirement record. The compliance status displayed in HR & People Manager is the canonical value; KTL's completion records are the evidence that drives it.

(needs UX writer input — label for the "Mandatory — HR requirement" badge and the unmet-requirement indicator copy in the Course library)

5.2 State Machines

The following states are inferred from the CourseProgress data model (technical spec §14), the pathway sequencing rules (§4.3), and the external CPD record model (§14). Inferred from technical spec §§4.3, 5, 13, 14.

Lesson / module completion state

External CPD record state

Course approval state (internal courses)

Inferred from technical spec §9.3 approval workflows.

Irreversible transitions (publishing a course, submitting a certificate) show a confirmation modal before proceeding.

5.3 Empty / Loading / Error / Offline States

"My Learning" pathway view

• Empty: No pathway assigned yet — shown when HR/manager has not yet assigned a pathway. Inferred from §6.2 auto-assignment model. (needs UX writer input — empty state illustration concept and copy)
• Loading: Skeleton rows matching the expected pathway card layout
• Error: Inline error with retry action; (needs UX writer input — error message copy)
• Offline: Previously loaded pathway structure and text-based lessons available; video lessons and SCORM content unavailable offline — shown with an offline indicator. Inferred from the Staff App Mode integration and the variety of lesson types in §5.2. (needs UX writer input — offline banner copy)

Lesson player

• Empty: N/A (lesson always has content before it is published)
• Loading: Spinner centred in player area; content type label visible while loading
• Error (SCORM / video load failure): Inline error with "Try again" and "Upload certificate manually" fallback for external content. Inferred from §7.2 fallback mode. (needs UX writer input)
• Offline: Text and checklist lessons accessible; video / SCORM lessons display an offline notice

Course catalogue

• Empty: No courses exist yet — shown for a brand-new practice. Inferred from §9 user-generated courses and §8 Primoro distribution being adoption-controlled. (needs UX writer input)
• Loading: Skeleton card grid
• Error: Full-page error with retry
• Offline: Cached catalogue titles visible; content detail unavailable

6. Component Inventory

New components introduced or extended by this module:

• Pathway progress card — displays a role-based learning pathway, ordered list of modules with completion state, and the next action. Appears on "My Learning" dashboard and staff profile. Inferred from §4.3 pathway model.
• Lesson player — full-screen or panel component supporting video, text, checklist, and quiz lesson types with a progress bar and "mark complete" control. Inferred from §5.2.
• Quiz component — renders single or multiple-choice questions, captures answers, shows pass/fail inline. Inferred from §5.2 lesson types.
• CPD record tile — compact card showing provider, course name, CPD hours, evidence status badge, and mapped requirement. Appears in "My CPD" and team compliance views. Inferred from §14 ExternalTrainingRecord and §17.5.
• Course approval banner — contextual banner inside a draft course view indicating approval status and, where returned, reviewer comments. Inferred from §9.3.
• AI answer card — inline card in knowledge search results presenting an AI-suggested answer with an AI badge and source citation. Inferred from §12.
• Certificate upload widget — multi-step upload supporting file selection and device camera capture; shows file preview before submission. Inferred from §7.2 manual certificate upload.
• HR requirement badge — annotation displayed on a pathway course card (manager/admin view only) indicating that the course satisfies a mandatory training requirement published by HR & People Manager. Links to the corresponding HR requirement record. Inferred from HR & People Manager spec §4.4 and technical spec §11.

Reused from the design system:

• Data table (completion and compliance reporting views)
• Wizard / stepper (course creation, pathway setup, CPD certificate upload)
• Modal (confirmation of irreversible actions)
• Toast notification (completion confirmation, submission acknowledgement)
• Search bar with results list
• Badge / status chip (state treatments throughout)
• Skeleton loader

7. Visual Design Notes

• Typography: defer to the platform design system heading and body scale. Monospace usage limited to code-adjacent content (e.g. SCORM identifiers if ever surfaced to an admin).
• Colour: semantic colour usage only — success (completion, approved), warning/amber (pending review, locked prerequisite), error (rejected, failed load), info (AI suggestion, Primoro-distributed badge). No decorative colour introduced by this module.
• Iconography: lesson type icons (video, document, checklist, quiz) must always be accompanied by a visible text label — never icon-only. Inferred from the four lesson types in §5.2 and the need to distinguish them at a glance.
• Motion: transitions used only for lesson player open/close and progress bar fill. Nothing in compliance or governance flows is animated in a way that could distract from a confirmation step. Respects prefers-reduced-motion.

8. Accessibility & Inclusivity

The module MUST meet WCAG 2.2 AA. Specifically:

• Text contrast ≥4.5:1 (normal) / ≥3:1 (large)
• All interactive controls reachable via keyboard
• Focus states visible
• Form fields have programmatic labels
• ARIA used only where native semantics are insufficient
• Touch targets ≥44×44 px on mobile/tablet
• Motion can be reduced via prefers-reduced-motion
• Screen reader tested on NVDA (Windows), VoiceOver (iOS/macOS), TalkBack (Android)
• The lesson player must expose video captions and transcripts where video content is present. Inferred from §5.2 video lesson type and the clinical-staff audience which may include users with hearing impairments.
• Quiz components must be fully keyboard-navigable with clear focus order across answer options. Inferred from §5.2 quiz lesson type.
• Certificate upload must support keyboard-triggered file selection as an alternative to drag-and-drop. Inferred from §7.2 certificate ingestion mode.

9. Internationalisation

• Locale-aware date/time/number formatting (CPD hours, completion dates, pathway deadlines)
• All user-facing strings externalised to translation keys
• Layouts tolerant of 30% string-length growth (German, French)
• RTL support: not required at launch based on the target market implied by UK dental CPD provider list (§17.3), but layouts must not hard-code directional assumptions. Inferred from §17.3 provider list being UK/Ireland-focused.*

10. Cross-Module UX Touchpoints

Where this module's UX intersects with related modules:

• HR & People Manager — Learning pathways and compliance requirements are defined in HR & People Manager and delivered here. The user transitions from an HR compliance record into the relevant course or pathway in this module. On completion, evidence flows back to HR. The handoff should feel seamless: a deep link from the HR record opens the correct pathway or course directly. Mandatory training requirements published by HR are surfaced in this module as manager-facing annotations on pathway courses (see Flow F); completion and non-compliance signals flow back to HR & People Manager without requiring manual data entry in either system. Inferred from technical spec §11 and Table 1, and HR & People Manager spec §4.4.
• Task Manager — Task Manager is the execution layer for all learning. When a user has an outstanding learning task, it appears in Task Manager's task list; tapping it deep-links into the lesson player here. Completion in this module marks the Task Manager task as done. Users must never see two separate "complete" actions — the act of finishing a lesson is the completion event. Inferred from technical spec §§10, 15 and Table 6.
• AI Assistant — The AI Assistant surfaces within the knowledge search experience as an inline answer card. The transition is in-page: the user does not navigate away to the AI Assistant module. The AI Assistant's suggestions are visually subordinate to verified knowledge-base content. Inferred from technical spec §12.
• Communication Hub — All outbound notifications triggered by this module (CPD certificate submitted, course approved, pathway assigned) are dispatched via Communication Hub, never directly. The module itself has no notification-sending UI; it only triggers events. Inferred from technical spec §15 "Knowledge MUST NOT send reminders" and the Communication Hub integration listed in module metadata.
• Staff App — The Staff App is the primary mobile/tablet surface for learning consumption. The Staff App shell hosts the lesson player and pathway view in Staff App Mode. Inferred from technical spec metadata listing Staff App Mode as an integration.

UX consistency rules:

• The "mark complete" action and any compliance-adjacent confirmation must use the platform's standard confirmation modal — not a custom pattern — so the interaction is familiar regardless of which module initiates it. Inferred from the cross-module completion flow in Table 6.
• Action buttons appear bottom-right on tablet, top-right on web.
• AI badge style and qualifier text must match exactly what the AI Assistant module uses platform-wide. Inferred from §12 and the AI Assistant integration.

11. Governance & Auditability

• AI suggestions in knowledge search are rendered with a persistent AI badge and a qualifier indicating they are not verified policy. The user must take an explicit action (open source article) to proceed to authoritative content. Inferred from technical spec §12 "AI MUST NOT interpret policy."
• Course approval is an audit-significant action: submitting for approval, approving, and returning a course each produce a visible log entry on the course record showing who acted and when. Inferred from technical spec §9.3 "approval workflows" and §16 "compliance auditable."
• Completion records and CPD evidence are read-only once confirmed — staff and managers can view them but cannot delete or overwrite them without an explicit admin action, which itself is logged. Inferred from technical spec §13 "tracks completion, stores evidence" and §16.
• The source of each course (Internal / External / Primoro) is permanently visible on the course and lesson record so users always know the provenance of the content they are consuming. Inferred from the CourseObject Source field in technical spec §5.1.
• Read-only states are visually distinct from editable states.
• The current user's role and active permissions are visible in the platform header.

12. Notification & Communication Patterns

All notifications from this module are dispatched via Communication Hub. The module does not send messages directly. Inferred from technical spec §15 and §10.2 rules.

• In-app banner — shown when a new learning pathway has been assigned to the current user (persists until the user acknowledges or opens their pathway). Also shown when a Primoro platform course is newly available and the practice has adopted it. Inferred from §6.2 auto-assignment and §8.2.
• Toast — shown on lesson completion ("Lesson marked as complete"), certificate upload confirmation, and course approval/return events for managers. Inferred from §13, §7.2, §9.3.
• Push notification (via Communication Hub) — sent to staff when a new pathway is assigned or a learning deadline is approaching (the deadline is owned and triggered by Task Manager; Knowledge module raises the event). Inferred from §10.2 and Table 6 where Task Manager owns deadlines and escalation.
• Email (via Communication Hub) — sent to managers when a course submitted for approval is awaiting their review. Sent to staff when a CPD certificate record is rejected and requires re-upload. Inferred from §9.3 approval workflows and §7 CPD evidence flow.

13. Open Questions

• (needs UX writer input) What is the precise visual treatment that distinguishes a Primoro-distributed course from an internal or external course in the catalogue? The technical spec identifies three source types (Internal / External / Primoro) but does not prescribe a visual hierarchy.
• How does a staff member re-access a lesson they have already completed — is the lesson player re-openable in a read-only mode, or is completed content locked? The technical spec confirms completion tracking but does not define post-completion access. Inferred gap from §5 and §13.
• What happens to a learner's in-progress lesson state if Task Manager marks the parent task overdue while the lesson is open? The escalation path belongs to Task Manager but the lesson player UI may need to surface a warning. Inferred from the boundary between §10 (Task Manager enforces) and the lesson player UX.
• (needs UX writer input) Is there a maximum CPD-hours value the upload form should validate against, or is that a compliance rule owned entirely by HR?
• Should managers be able to preview a lesson as a learner (without it recording a completion event against their profile)? The technical spec does not define a preview mode; this needs a product decision before the course-creation wizard is designed. Inferred gap from §9 user-generated courses.
• (needs UX writer input) What is the intended empty-state experience for a brand-new practice that has no internal courses and has not yet adopted any Primoro content? The catalogue could be entirely empty on day one.
• The future CPD marketplace (technical spec §17.8) will require a browse/purchase or browse/request surface that does not exist in the current scope. UX should note this as a seam — the current catalogue design must not make assumptions that break when marketplace content is introduced.
• (needs UX writer input) What label and visual treatment should the "Mandatory — HR requirement" badge use on pathway course cards, and how prominently should the unmet-requirement indicator appear in the Course library when a newly published HR requirement has no matching course? Product and HR module owners should align on this before the manager-facing pathway view is designed (see Flow F).