Skip to main content

UX-GOVERNANCE.md

Evalium UX Doctrine

Purpose​

Evalium is designed for SMBs today and enterprise scale tomorrow. The backend is intentionally sophisticated (versioning, ledgers, projections, jobs), but the UI must remain simple, trustworthy, and fast.

This document defines the non-negotiable UX rules and the reusable UI patterns that keep the experience consistent across all components.

Capability Baseline (Validated 2026-02-25)​

Use this doctrine with explicit awareness of current backend maturity:

  • Live now: authoring for questions/passages/evaluations, assignments/schedules/overrides/monitoring, submission readiness + defensibility exception queues, reporting/remediation, taxonomy on questions/evaluations, compliance jobs + ledger.
  • Feature-flag/pending: skills inference/profile hubs, evidence-fact profile surfaces, first-class compliance case/timeline orchestration, explicit proctor command endpoints, dedicated grading queue read model.

Rule:

  • UX doctrine is stable, but surfaces not backed by first-class backend contracts must be marked target-state and gated.

0. Core Principles (Non-Negotiables)​

0.1 SMB Interface, Enterprise Engine​

Never expose backend mechanics (version chains, silos, recalculation jobs, projection workers).
Users should experience intuitive actions like Save, Refresh, Correct, Export, Revoke.

0.2 Context is King​

Everything the user sees that represents an entity is a functional link to its context when the entity is backend-backed and the user is permitted.

0.3 The Ledger Principle​

High-stakes truths (Scores, Skills, Compliance, Certifications) are append-only and never overwritten.
The UI must show provenance: who/what/when/why, and how the current value was derived.

0.4 Localization Integrity​

User-facing language is part of product correctness.

Rules:

  • all UI copy must originate from Inlang Paraglide-JS keys (no hardcoded UI literals).
  • runtime copy override precedence is fixed: org override -> tenant override -> product default.
  • override publishing must preserve variable tokens and remain auditable.

1. Governance Levels (MUST / SHOULD / MAY)​

MUST (Hard Rules)​

  • Entity references are links (see Link Contract).
  • High-stakes changes require a reason and create a ledger record.
  • Any corrected/derived value must expose its Evidence Basis.
  • Authorization boundaries are respected (org unit / scope isolation); UI must not leak cross-scope data.
  • Accessibility: WCAG 2.2 AA; keyboard-only navigation is a hard requirement for the Evaluation Builder.
  • authoring/admin surfaces additionally follow ATAG responsibilities (accessible authoring UI + support for accessible authored output).

SHOULD (Defaults)​

  • Drawer-first navigation for “support context” entities; full page for “primary assets”.
  • Progressive disclosure: default to simple controls; advanced controls gated by capability and intent.
  • Consistent “Entity Hub” template for all primary assets.
  • Consistent “Scope Chips” and “Freshness Indicators” for any derived view.

MAY (Optional Enhancements)​

  • Global search / jump (Ctrl+K) for entity navigation.
  • Universal “Create” button that adapts to current workspace.
  • Inline quick-edit in drawers for low-risk metadata (name/description/tags), where allowed.

2. Navigation & Information Architecture​

2.1 The Primary Sidebar (The Spine)​

The application is divided into five task-oriented categories to maintain a clean SMB experience while supporting enterprise operations:

  1. authoring
  • Blueprints for K (Knowledge), O (Observation), E (Evidence)
  • Question library, passages, evaluation builder
  • Skills/framework hubs are target-state (taxonomy foundations are live; skills projection UX is parked)
  1. Programmes
  • Multi-step certification paths
  • Enrolments, requirements, completion logic
  • Certificates (issue + verify surfaces)
  1. Operations (The Pulse)
  • Assignments & Schedules (issue work to individuals/cohorts)
  • Grading Queue (target-state unified queue on top of live review/findings primitives)
  • Command Centre (live session monitoring, proctor telemetry)
  1. Insights
  • Reporting (dashboards, version-scoped summaries)
  • Competence Profiles (target-state; activate when skills inference/provenance is live)
  • Remediation (high-stakes correction batches)
  1. Governance (The Safety Net)
  • Compliance Centre (jobs/ledger live now; case/timeline orchestration is target-state)
  • Users & access
  • Roles / capabilities
  • Audit views

3. UX Primitives (Reusable Building Blocks)​

To keep UX consistent across components, all screens should be composed from these primitives.

3.1 Entity Hub Page (Full Page)​

Used for primary assets with full management workflows.

Structure

  • Header: Title, Status chip, key metadata, Primary CTA
  • Tabs (standardised):
    • Overview
    • Activity (Audit / Ledger)
    • Results (if applicable)
    • Settings

Rules

  • Primary CTA is always visible and action-oriented (e.g., “Publish”, “Assign”, “Start Review”, “Export”).
  • “Danger Zone” actions are grouped and visually separated (archive, revoke, irreversible changes).

3.2 Context Drawer (Side Panel)​

Used to provide supporting context without forcing navigation away.

Drawer MUST include

  • Clear title
  • Key facts (minimal, scannable)
  • 1–3 contextual actions
  • “Open full page” escape hatch (when applicable)

3.3 Wizard (Guided Creation / High-Impact Actions)​

Used when the user needs to make a sequence of decisions.

Rules

  • Default to the simplest path (“Beginner Mode”).
  • Advanced options are tucked behind an “Advanced” section and capability gated.

3.4 Insight Block (Dashboard Card)​

Reusable reporting surface.

Block MUST include

  • Title + description (what this represents)
  • Scope chips (version/timeframe/cohort)
  • Freshness indicator (last updated)
  • Drilldown CTA

3.5 Ledger Row (Immutable Record)​

Reusable pattern for append-only truth changes.

Ledger Row MUST include

  • Timestamp
  • Actor/system
  • Action type
  • Reason (user provided or system generated)
  • Link to details (batch/job/submission)

Every entity reference is actionable. The default destination depends on the target type:

  • Support Context Entities → Drawer-first
    • Users, Groups, Taxonomy terms, Org Units, Holds, artifact/receipt details
    • Feature-flagged until backend profile hubs are active: skills, evidence facts
  • Primary Assets → Full-page
    • Questions, Passages, Evaluations, Programmes, Assignments, Submissions/Attempt viewer, Reports, Remediation batches
    • Compliance case entity is target-state; until then route to compliance jobs/ledger hubs

Rule: “Smallest sufficient context”

  • Default to the smallest view that answers the likely question.
  • Always provide “Open full page” when the user needs full management capabilities.

4.2 Evidence Basis Rule (MUST)​

Whenever a derived value is shown (skill level, competence rating, corrected score):

  • Clicking it opens a drawer showing the specific evidence items (Submissions and facts) that contributed to the value.
  • The evidence drawer must include scope chips (mapping set/version/timeframe).

For derived values that are not yet backend-explainable (for example parked skills projections), the UI must not fake precision; show capability-gated unavailable messaging.

4.3 Breadcrumbs (MUST for full-page assets)​

Full-page navigation must show persistent breadcrumbs:

  • Example: Insights > Competence Profiles > [User Name]

4.4 SMB Org Unit Simplification (MUST)​

If a tenant has only one Org Unit:

  • Org Unit controls, chips, and navigation are globally hidden.
  • The org boundary still applies (invisible, not removed).

5. Core Interface Standards​

5.1 High-Stakes Grading (Ledger UX)​

Principle: subjective grades (essays, observations, evidence reviews) are immutable once finalised.

Grading Queue UI

  • Split-screen:
    • Candidate response (left)
    • Rubric / marking guide (right)
  • Review actions:
    • Save draft (non-final)
    • Finalise grade (high-stakes: requires reason/confirmation copy)

Correction Label (MUST) If a grade/score is modified via Remediation:

  • Display a “Corrected” badge next to the value.
  • Provide a direct link to the remediation batch, including reason/audit trail.
  • Where meaningful: show Original → Current.

5.2 The “Save” Lie (Automatic Versioning)​

Principle: authors press Save, not “Create New Version”.

User-visible behaviour

  • “Saved” means persisted and safe.
  • “Effective” messaging clarifies when it applies.

Effective State Messaging (MUST)

  • If the underlying content is Live:
    • “Saved. This update will apply to future sessions.”
  • If not Live:
    • “Saved.”

No UI should expose internal version identifiers by default.

5.3 Progressive Disclosure (Skills & Mapping)​

Principle: complexity appears only when capability and intent are present.

  • Authors see simple Skill Tags and outcomes, not mapping mechanics.
  • Skills admins see:
    • Mapping set editor
    • Versioned mappings
    • Impact preview surfaces (when implemented)
  • All advanced mapping controls live behind an “Advanced” area.

Until skills inference is active, mapping controls remain backend/admin surfaces and user-facing skill outcome language stays disabled.

5.4 Scope Chips & Freshness (MUST for derived views)​

Any view that is a projection, rollup, or version-scoped truth must display:

  • Version scope (e.g., Evaluation v3, Mapping Set v7)
  • Time window (e.g., last 30 days)
  • Cohort / group scope (when relevant)
  • Freshness indicator (e.g., “Updated 2m ago”)

6. Component Pattern Map (Default UX Patterns)​

authoring​

  • Questions: Library + Editor (drawer quick-view; full editor page)
  • Evaluations: Builder Canvas (tabs for structure/settings/preview)
  • Buckets: Rule Builder + Preview (simple mode first)

Programmes​

  • Programme Hub: Overview + Requirements + Enrolments + Activity
  • Enrolment Detail: Checklist progress + evidence basis links
  • Certificates: Outcome panel + verify surface

Operations​

  • Assignments: Issue Wizard + Policy Drawer (advanced options collapsed)
  • Grading Queue: Split-screen + ledger finalisation rules
  • Command Centre: Live table + drill-in drawer (live vs history separation)

Insights​

  • Reporting: Blocks-based dashboards + drilldowns
  • Competence Profiles: Profile view + skill rows (evidence basis drawer)
  • Remediation: Guided “Danger Zone” workflow + ledger linkage

Governance​

  • Compliance Centre: Job queue + receipts + ledger
  • Users & Roles: Simple defaults, advanced editor behind capability
  • Audit: Filterable ledger views, export later

7. Technical UX Requirements​

7.1 Responsiveness​

  • Admin UI supports laptop + desktop.
  • Candidate Delivery is mobile-first / responsive.
  • Use task-tier policy for all domains: quick tasks mobile-safe, complex tasks desktop-optimized with explicit handoff.

7.2 Accessibility (MUST)​

  • WCAG 2.2 AA across the app.
  • Keyboard-only navigation is a hard requirement for the Evaluation Builder.
  • Focus management must be correct for drawers, modals, and wizards.
  • Automated accessibility guardrails are required in CI and release gates.

7.3 Performance​

  • Derived dashboards and skill rollups must use UI-ready read models.
  • Target: under 200ms for core Insight block loads (excluding network latency).

7.4 Compliance Awareness (MUST)​

  • Competence Profiles are included in DSAR exports only when skills projection surfaces are active and backed by defensible provenance.
  • “Forget User” must scrub/anonymise derived profile projections consistently.

7.5 Silo Isolation (MUST)​

  • Users only see Grading Queue items, Profiles, and Governance data within their authorised org_unit_id scope.
  • Cross-scope links must never render.

8. Review & Enforcement​

8.1 UX Consistency Checklist (Use for PR review)​

  • Does every entity name behave as a link?
  • Does the destination follow Drawer-first vs Full-page rules?
  • Are scope chips + freshness shown for derived data?
  • Do high-stakes changes require a reason + create a ledger record?
  • Are corrected values labelled + linked to the correcting event?
  • Is progressive disclosure applied (simple by default)?
  • Are accessibility and keyboard flows verified (especially builder/drawers)?
  • Are P0 frontend readiness gates satisfied for new surface activation (UX-FRONTEND-READINESS-CHECKLIST.md)?

8.2 Versioning & Projection Changes​

When backend capabilities expand (e.g., impact previews, approvals, projection rebuilds), the UI must:

  • Fit into existing primitives (Block, Ledger Row, Wizard),
  • Avoid introducing a new navigation paradigm,
  • Preserve SMB simplicity by keeping advanced mechanics behind intent-driven affordances.

Related policy docs:

  • /docs/ux/UX-ACCESSIBILITY-STANDARDS-AND-GUARDRAILS.md
  • /docs/ux/UX-MOBILE-AND-TASK-TIER-POLICY.md