Skip to main content

📗 UX-AUTHORING.md

This document specifies the UX patterns for the authoring category. This is where users blueprint their Knowledge, Observation, and Evidence (KOE) content.

The primary challenge in authoring is masking the immutability and versioning mechanics so authors can focus on content quality, while still making “blast radius” and downstream impacts explicit and defensible.

0. authoring Doctrine (MUST)​

0.1 SMB Interface, Enterprise Engine​

The UI must not expose backend mechanics (version trees, recalculation jobs, ledger tables). Authors interact with simple actions:

  • Save
  • Publish
  • Update where used
  • Preview
  • Archive

0.2 No Silent Blast Radius​

If a change could affect multiple assets, the UI must show an Impact Summary and require an explicit choice before propagating changes.

0.3 Context is King​

Every entity reference is a link:

  • Question → Question Detail
  • Evaluation → Evaluation Hub
  • Programme → Programme Hub
  • Tag / Skill → Taxonomy drawer
  • “Used by” → Usage Context drawer/list

0.4 Progressive Disclosure​

Default flows must be “beginner mode”. Advanced functionality appears only when:

  • the user explicitly opens Advanced, and/or
  • the user has the capability to use it.

0.5 Device Task-Tiering (MUST)​

authoring is task-tiered by complexity, not blocked by device type.

  • Tier A (mobile-safe): quick edits (text/metadata/tags/status), archive/restore, usage lookup.
  • Tier B (responsive): guided publish confirmation and moderate structure edits.
  • Tier C (desktop-optimized): complex evaluation structure and weighted bucket configuration.

If a Tier C path is started on constrained devices, UI must provide explicit handoff:

  • Continue on desktop
  • Send me a link
  • Save and exit

No silent feature disappearance and no dead-end copy.

0.6 authoring Accessibility Responsibility (ATAG) (MUST)​

authoring/admin UX must satisfy both:

  • WCAG 2.2 AA (interface accessibility)
  • ATAG responsibilities (authoring tool behavior)

Practical requirements:

  • authoring UI is keyboard/screen-reader complete for create/edit/publish flows
  • authored accessibility-relevant data is preserved across save/import/publish
  • validation sidekick includes accessibility checks when content type supports them
  • publish flow must not silently allow severe accessibility regressions in authored artifacts

0.7 authoring Interface Guardrails (MUST)​

  • Question and evaluation status language must use canonical labels with no mixed synonyms.
  • High-impact operations (publish, propagate, archive in-use) must present explicit impact and consequence copy before commit.
  • Validation and warning messages must be deterministic and localisable; no raw backend message rendering in primary UX.
  • Keyboard and touch paths must support Tier A/Tier B authoring tasks on iPad/mobile.
  • Tier C authoring flows may be desktop-optimized but must always provide explicit handoff (Continue on desktop, Send me a link, Save and exit).
  • Save/import/publish paths must preserve authored accessibility metadata and provenance context.

1. Content Lifecycle (UI Semantics)​

authoring surfaces a simple lifecycle that remains consistent across Questions and Evaluations.

1.1 Lifecycle States (MUST)​

  • Draft: editable in place
  • Published: immutable version; selectable for use in future assignments
  • Archived: not selectable for new usage (historical references remain valid)

1.2 Usage Badges (Separate from Lifecycle) (MUST)​

Usage is shown as separate badges/chips (because “Published” ≠ “high stakes”):

  • In use: referenced by one or more Evaluations/Programmes
  • Active runs: referenced by Evaluations/Programmes with active Assignments/Sessions (high stakes)

This separation prevents “Live” from becoming a confusing catch-all term.

2. The Question Library (Discovery)​

The Library is the entry point for content discovery. It must solve “folder anxiety” using Virtual Folders (saved filters) rather than physical folders.

2.1 Library Layout​

The sidebar displays “Virtual Folders” implemented as saved filters:

  • Saved Filters (Personal): “My Safety Bank”
  • Shared Collections (Org Unit): “Compliance Standard Set”

Both are tag-based; the difference is ownership/visibility.

SMB defaults

  • Show a small set of default collections (e.g., Safety, Compliance, Onboarding).
  • Allow pinning 3–5 favourites at the top.

List View​

The list shows:

  • Question title
  • K/O/E type icon
  • Status chip (Draft / Published / Archived)
  • Usage badge (In use / Active runs)
  • Health badge (from Item Health reporting when available)

Health badge data-sufficiency rule (MUST) If sample size is below threshold, the badge must display:

  • Insufficient data …rather than implying “Good/Bad”.

Tooltips must include:

  • the sample size (N)
  • the scope reference (e.g., “based on last N attempts for Eval vX”)

Peek Pane (Right Drawer)​

Clicking a question title opens a peek drawer with:

  • Preview: rendered candidate view
  • Version chip: “vX · Draft/Published”
  • Freshness: “Updated 2d ago”
  • Usage Context (grouped):
    • Used in Draft Evaluations
    • Used in Published Evaluations
    • Used by Active runs (high stakes)
  • Quick actions (capability gated):
    • Edit
    • Publish (if Draft)
    • Archive / Restore (if applicable)
    • Open full page

3. Question Detail + Individual Publishing (Option B)​

Questions must be publishable individually because they can be reused across many Evaluations and Programmes.

3.1 Question Hub (Full Page)​

The Question Hub is a primary asset page with:

  • Header: title, status chip, usage badges, primary CTA
  • Tabs:
    • Overview
    • Content (editor)
    • Usage
    • Activity (audit/ledger-like history)

4. Publish Workflow: “Publish + Guided Propagation” (MUST)​

Publishing is a calm action; propagation is a deliberate choice with impact visibility.

4.1 Step 1 — Publish​

Primary CTA: Publish

  • Publishing finalises the current draft into a new immutable published version.
  • UI confirms:
    • “Published.”
    • Shows new version chip: “vX · Published”

4.2 Step 2 — Impact Summary (MUST)​

Immediately after publish, show an Impact Summary panel/modal.

Traffic Light Classification (MUST)​

The Impact Summary must group affected assets with a clear risk cue:

  • Green (Safe): Draft Evaluations

    • “Safe to update” (updates draft references immediately)

  • Amber (Caution): Published Evaluations

    • “Requires new evaluation version” (affects future runs only)

  • Red (High Risk): Active runs

    • “High risk — do not change running sessions”
    • Triggers safer defaults (see below)

The summary includes:

  • counts per group (Green/Amber/Red)
  • a short list (top 5) per group + “View all”
  • an Explain link: “What does updating change?”

4.3 Step 3 — Propagation Choices (MUST)​

Offer explicit, safe options:

  1. Update Draft Evaluations now (Green)

    • Updates draft evaluation references to the new question version.
    • (If the evaluation itself must version, it happens silently.)

  2. Create updated versions for Published Evaluations (Amber)

    • Creates new evaluation versions for the affected published evaluations.
    • Copy: “Affects future assignments only.”

  3. Don’t update anything (Safe default)

    • Publish the question only; no downstream changes.

Default selection rule (MUST)​

  • If any Red (Active runs) exist:
    • Default selection: Don’t update anything
    • Highlight: “Active runs detected — propagation disabled by default.”

4.4 Step 4 — Result Confirmation (MUST)​

After completion, show a confirmation summary:

  • “Updated 2 draft evaluations”
  • “Created 1 new evaluation version for future runs”
  • “0 active runs affected”
  • Links to each affected evaluation

5. The Evaluation Hub (Structure)​

The Evaluation Hub is the “Primary Asset” page for an assessment and uses the standard Entity Hub template.

5.1 Builder Canvas (Structure Tab)​

Authors manage the hierarchy: Sections → Items → Question Versions

  • Linear sections are flagged with a lock icon (no back-navigation).
  • Free sections allow back-navigation.

Fixed Items​

  • Display the referenced question version chip inline (e.g., “Question v3”).
  • If a newer published question version exists, show:
    • “Update available” badge
    • Inline action: Upgrade to latest published
    • Clicking opens a mini Impact Summary:
      • Green/Amber/Red awareness if the evaluation is published/in use

Dynamic Buckets​

Buckets display:

  • Tag rule summary (e.g., “Draw 5 from Topic: Safety”)
  • Availability count inline (e.g., “Available: 18”)
  • Inline warning/error badge when insufficient (“Needs 5, found 3”)
Deterministic Preview Sampling (MUST)​

A bucket includes preview-only sampling:

  • Button label: Refresh Sample (Preview)
  • Must not imply it changes the live draw.
  • Shows a visible, copyable seed:
    • “Preview seed: ######”
  • The seed must be stable for that preview until refreshed, so authors can reference it in review.

Optional advanced control (collapsed):

  • “Use fixed preview seed”
    • Allows reproducible previewing during authoring/support.

6. Validation Sidekick (MUST)​

A persistent sidebar/drawer in the builder that flags structural and scoring issues in real time.

6.1 Categories​

  • Errors (block Publish)
  • Warnings (do not block; require acknowledgement on Publish)

6.2 Structural & Policy Examples​

  • Errors:
    • “Section 2 is empty”
    • “Bucket ‘Safety’ has only 3 questions available (needed 5)”
  • Warnings:
    • “Pass mark (80%) is higher than total possible score”

6.3 Score Integrity Checks (MUST)​

The Sidekick must warn when authoring changes reduce defensibility or competence coverage.

Examples:

  • “Warning: Removing this item reduces evidence coverage for Skill: [Safe Lifting].”
  • “Warning: This section no longer contains any items tagged to [Framework: Compliance].”

Each score integrity warning must include:

  • the affected skill/tag/framework link (drawer)
  • “View impacted skills” (opens a focused list)
  • (Optional later) a coverage delta hint (“Coverage 3/5 → 2/5”)

6.4 Actionability (MUST)​

Each Sidekick item includes:

  • Go to link (focuses the relevant section/bucket/setting)
  • Where possible: a single-click fix (e.g., “Add section item”, “Lower draw count”)

6.5 Publish Rules (MUST)​

  • Publish is blocked if any Errors exist.
  • If Warnings exist, Publish requires:
    • “Proceed with warnings” acknowledgement.

7. The “Save Lie” in authoring (MUST)​

Authors should never be asked to “create a new version”.

7.1 Save Behaviour (Quiet)​

  • If editing a Draft: Save updates in place.
  • If the author begins editing a Published asset:
    • The UI must fork visually into a draft-working state.

7.2 Visual Fork (Working Draft) (MUST)​

When editing a Published asset, the UI must clearly indicate the author is no longer viewing the immutable version.

Pattern

  • Header shows:
    • “Viewing: Published vX”
    • “Editing: Working Draft” badge (e.g., “Working Draft (unpublished)”)
  • Primary CTA becomes: Publish
  • Save remains quiet:
    • “Saved.” / “Saved to Working Draft.”

Rationale This prevents authors from thinking they are modifying “the live thing”, without exposing the underlying version tree.

7.3 Propagation Happens at Publish (Loud)​

Ripple/propagation decisions occur at Publish time via the Impact Summary, not on every Save.

8. Randomisation & Seed Logic (Clarified)​

Evalium uses deterministic seed logic to make bucket selection reproducible and defensible, while still feeling “random” to candidates.

8.1 Default Delivery Mode: Per-Session Seed (MUST)​

  • At session launch, a seed is generated for that session.
  • Bucket draws are deterministic under that seed.
  • Result: candidates receive a “random form” just-in-time, but it is reproducible if needed.

8.2 High-Stakes Mode (Advanced): Fixed Seeds / Forms (SHOULD)​

The platform supports passing a fixed seed into the session so a cohort receives the same randomised form.

UX principle

  • This is an advanced feature and must not pollute default authoring.

Where it belongs

  • Operations → Assignments (Advanced policy), not in the default authoring flow.

How it is presented

  • “Randomisation mode” selector (Advanced):
    • Per-session random (default)
    • Fixed form (A/B/C…) for high-stakes cohorts

Authors may see a read-only indicator on an Evaluation:

  • “Supports fixed forms” (info only)

9. Author-Based Access (Sharing)​

Access is managed via a Share modal on the Question/Evaluation hub.

9.1 SMB Defaults (MUST)​

  • “Shared with [Org Unit] Authors” by default.

9.2 Enterprise Overrides (Progressive Disclosure) (SHOULD)​

  • “Advanced sharing” expands to allow adding specific Users/Groups:
    • Can View
    • Can Edit

9.3 Silo Enforcement (MUST)​

Collaborator search only returns users/groups within the author’s RLS-authorised scope.

authoring TaskUI PatternLink Contract (Drawer/Hub)
Manage QuestionsLibrary + PeekUsage Context: shows every Evaluation version currently anchored to this item
Publish QuestionImpact Summary (Traffic Light)Where Used: lists blast radius across Draft / Published / Active runs
Build EvaluationCanvas + SidekickItem Peek: quick look at question content without leaving the builder
Skill MappingTaxonomy HubMapping Set: shows which Evaluations provide evidence for this skill (and coverage signals)

11. Backend Alignment Addendum​

authoring backend capabilities have expanded faster than the initial UX plan.

The canonical delta and proposed UX handling now lives in:

  • docs/ux/UX-AUTHORING-BACKEND-ALIGNMENT.md

This addendum should be treated as part of authoring UX scope, not optional notes.