Skip to main content

📘 UI-COMPONENT-TAXONOMY.md (aligned to Interaction Map)

Goal: Build a small set of reusable Bits UI component patterns that cover most of the HTTP surface, while staying calm by default and audit-ready via progressive disclosure.

Capability Baseline (current reality)​

First-class full-page assets (MUST be supported as pages)​

  • question, passage, evaluation, assignment, submission

Drawer-peek-enabled entities (SHOULD be supported as read-only drawers on enabled surfaces)​

  • user, group, taxonomy_term

Pending / feature-flagged peek entities (DO NOT intercept yet)​

  • skill, fact

Rule: If an entity type is not backed by a drawer read model on the current surface, do not intercept normal click. Fall back to canonical full-page navigation.

0. Doctrine (MUST)​

  • URL-as-State and Shallow Routing for drawers.
  • Param preservation (filters, view ids, version pickers must survive drawer open/close).
  • Accessible by default (drawer = dialog + focus trap + Esc close + focus restore).
  • Base-path safety (all internal links respect SvelteKit base).
  • Two worlds: authoring feels editable; Execution is immutable and append-only (UI must surface history).

1) Plumbing Components (app-wide)

  • Always renders a real <a href>, intercepts normal click only for drawer-enabled entity/surface pairs, never intercepts Cmd/Ctrl+Click.

1.2 DrawerService + DrawerCoordinator + ContextDrawer (MUST)​

  • Implements drawer=<type>:<id> + optional drawerTab=..., push/replace policy, fetch in $effect with abort, status states (loading|ready|forbidden|notfound).

1.3 CapabilityGate (MUST)​

  • Capability-first gating (no role-name checks in UI), hide/disable actions consistently.

2) Inventory Workspace Pattern (your reusable “library table”)

Primary components

  • InventoryPageShell
  • FilterBar + StatusChips
  • InventoryTable (server paging, sort, row select)
  • SavedViewsDrawer (“virtual folders”)
  • BulkActionBar
  • ColumnChooser / DensityToggle

Backend features / API that map here

  • Inventory Views (“virtual folders”) as a core capability.
  • Questions views: GET/POST /api/v1/questions/views
  • Evaluations views: GET/POST /api/v1/evaluations/views
  • Users list (also fits inventory, even if user detail uses drawer peek on enabled surfaces): GET /api/v1/users

3) authoring World Pattern (Save Lie allowed)

Rule: Save Lie is allowed for authoring assets where the backend is versioned/replaceable, but the UI must still expose revision history via progressive disclosure.

3.1 “Create Parent then Create Version” authoring flow​

  • Questions explicitly: create parent, version separately (your UI should reflect this without making it scary).

3.2 Structural gating + preview (Evaluations)​

  • Evaluation import “commit” can create versions + section items.
  • (Registry) publish must be blocked if structural authoring errors exist.

Primary components

  • authoringEditorShell (Edit → Save)
  • VersionChip + VersionHistoryDrawer
  • PublishGatePanel (blockers, warnings)
  • PreviewPanel (where applicable)

4) Bulk Actions + Dry-Run Pattern (library-wide)

Primary components

  • BulkActionModal
  • DryRunPreviewPanel (blast radius summary)
  • CommitConfirmation

API

  • Questions bulk actions: POST /api/v1/questions/bulk
  • Evaluations bulk actions exist (same request/response shape).
  • (Registry) bulk actions include dryRun to audit blast radius before commit.

5) Import Wizard Pattern (Preview → Commit)

Primary components

  • ImportWizard
  • ImportPreviewTable (row errors/warnings)
  • ImportCommitResults

API

  • Questions: POST /api/v1/questions/import/preview + /commit
  • Evaluations: POST /api/v1/evaluations/import/preview + /commit

6) Execution World Pattern (Save Lie NOT allowed)

Rule: Execution is immutable, append-only. UI must use verbs like “Amend / Void / Approve / Reject / Verify”, and show history.

6.1 Submission governance actions​

Primary components

  • SubmissionActionsPanel (Approve/Reject)
  • IdempotentActionButton (Idempotency-Key baked in)

API

  • POST /api/v1/submissions/\{id\}/approve
  • POST /api/v1/submissions/\{id\}/reject

6.2 Evidence event lifecycle (record → amend → decide → verify → void)​

Primary components

  • EvidenceManager
  • EvidenceRecordForm
  • EvidenceAmendDrawer
  • EvidenceDecisionDialog (approve/reject)
  • EvidenceIntegrityJobPanel (verify enqueues)

API

  • Submission-level evidence: /api/v1/submissions/\{id\}/evidence/record|amend|approve|reject|verify
  • Item-level evidence: /api/v1/submissions/items/\{itemId\}/evidence/approve|reject|verify|void

7) Glass Box Read-Only Projection Pattern (truth projector)

Primary components

  • GlassBoxViewerShell
  • ForensicHeader (timestamps, state badges, language selector)
  • LedgerTimeline
  • SnapshotRenderer (frozen “what happened”)
  • AmendmentHistoryView (cross-outs/supersedes)

API

  • Submission lens (read-only, includes amendment history + verification context): GET /api/v1/glass-box/submissions/\{id\}
  • Programme lens (“Compliance Passport”): GET /api/v1/glass-box/programmes/\{id\}
  • (Interaction map) Glass Box behaviour must remain calm, shareable (URL-as-state), audit-ready.

8) Defensibility Exceptions Queue Pattern (projection ops)

These queues are explicitly projection/scaffolding, not execution truth.

Primary components

  • ExceptionsQueueTable (filters: state/readiness/owner/suppressed)
  • TriageDrawer (state, ownerUserId, suppressedUntil)
  • RefreshQueueButton

API

  • Engagement queue: GET /api/v1/defensibility/exceptions/engagements
  • Engagement triage: POST /api/v1/defensibility/exceptions/engagements/{engagementId}/triage
  • Submission refresh: POST /api/v1/defensibility/exceptions/submissions/refresh
  • Submission triage: POST /api/v1/defensibility/exceptions/submissions/{submissionId}/triage

9) Reporting “Light Charts + Drilldown Tables” Pattern

Primary components

  • KPIHeader
  • DrilldownTable (always present)
  • Optional: Sparkline, Distribution, Scatter (only where it’s truly additive)

API

  • Evaluation summary metrics: GET /api/v1/evaluation-summary
  • Question health export bundle (ZIP) with rich filters/sort: GET /api/v1/question-health/export
  • (Registry) Question Health Analytics is a first-class capability (facility/omission/time-on-item).

10) Identity & Admin Pattern (inventory + peek drawer detail)

Primary components

  • UsersInventory (Inventory Workspace)
  • UserDrawer (read-only peek drawer entity)
  • GroupsInventory + GroupDrawer

API

  • Users list: GET /api/v1/users
  • (Interaction map baseline) user and group are realistic peek-drawer types on drawer-enabled surfaces.