Skip to main content

UX-ACCESSIBILITY-STANDARDS-AND-GUARDRAILS.md

This document defines the accessibility baseline and enforcement guardrails for Evalium frontend work.

Purpose:

  • make accessibility a build-time quality gate, not a late QA step
  • keep authoring and delivery interfaces usable for keyboard, touch, and assistive technology users
  • prevent regressions through automated checks and release gates

Capability Baseline (Validated 2026-02-25)​

Use this standard with explicit backend maturity awareness:

  • apply as hard requirements to backend-live surfaces (authoring, assignments/monitoring, runtime delivery, review/readiness, reporting/remediation)
  • for target-state surfaces (skills profiles, compliance case timeline), enforce the same accessibility contracts when the first-class UI ships

0. Accessibility Doctrine (MUST)​

  1. Accessibility is part of product correctness, not enhancement work.
  2. A feature is incomplete if it is not keyboard operable, screen-reader understandable, and touch usable.
  3. No custom widget ships without matching an established WAI-ARIA APG interaction pattern.
  4. No critical action relies on color, hover, or pointer precision alone.

1. Target Standard (MUST)​

1.1 Baseline​

  • Conformance target is WCAG 2.2 AA for all frontend interfaces.
  • Internal quality floor remains keyboard completion for all critical flows.

1.2 Critical Flow Definition​

Critical flows include at minimum:

  • authoring create/edit/publish
  • assignment creation and monitor triage
  • runtime candidate delivery (start, answer, submit)
  • submission review/approval and defensibility triage

1.3 Pattern Contract​

When using custom components (drawers, data grids, popovers, builders):

  • map behavior to a documented APG pattern
  • implement required keyboard interactions and focus management
  • avoid invalid ARIA states (for example modal semantics on non-modal popovers)

1.4 ATAG Contract for authoring/Admin (MUST)​

Evalium treats authoring/admin interfaces as authoring tools and applies ATAG responsibilities in addition to WCAG.

ATAG objective A (accessible authoring UI):

  • authoring/admin workflows (question/evaluation editors, validation sidekick, publish/impact dialogs) must be fully operable with keyboard and assistive technology
  • configuration-heavy interfaces must not require pointer precision or drag-only gestures

ATAG objective B (support accessible authored output):

  • authoring flows must not strip accessibility-relevant metadata when saving/publishing/importing
  • where content types support media, authoring must provide fields for alternatives (for example alt text/transcript) and surface missing-value warnings
  • validation surfaces should include accessibility quality checks for authored content and block/flag publish according to severity policy

Scope note:

  • some objective B checks are progressive and must be feature-gated where content models are still evolving
  • no shipped authoring flow may regress objective A requirements

2. Shared Component Requirements (MUST)​

2.1 Keyboard and Focus​

  • all interactive elements are reachable via Tab order
  • visible focus indicator is always present
  • focus trap is used only for true modal contexts
  • escape and close behavior returns focus to invoking control

2.2 Labels and Semantics​

  • all controls have programmatic labels
  • status and validation text is announced and linked to relevant controls
  • tables and dense data surfaces expose meaningful headers/relationships

2.3 Pointer and Touch​

  • target size is appropriate for touch interaction in field use
  • no hover-only disclosure for essential actions
  • drag/drop interactions must have keyboard and button alternatives

2.4 Motion and Contrast​

  • reduced-motion preference is respected
  • text and interactive states meet contrast requirements
  • status is not conveyed by color alone

3. Surface-Specific Rules​

3.1 authoring (Desktop-Dense + Accessible)​

  • complex builders remain keyboard-completable
  • validation sidekick must be keyboard navigable with actionable links
  • publish-impact dialogs must clearly announce risk levels and next actions

3.2 Delivery (Field-First)​

  • runtime UI is touch-friendly and readable in variable environments
  • save/sync/submitted states are explicit and announced
  • reconnect/offline/expiry messages are plain language and actionable

3.3 Operations and Review​

  • queue tables support keyboard row navigation and row actions
  • triage actions and reasons are accessible without pointer-only controls
  • readiness/exception chips include equivalent text labels for AT users

4. Automated Guardrails (MUST)​

4.1 Static Gate (CI Required)​

  • fail build on Svelte accessibility warnings
  • fail build on accessibility lint violations
  • fail build on forbidden hardcoded UI strings (for localisable labels and helper text)

4.2 Component Gate (CI Required)​

  • run automated accessibility checks against shared primitives:
    • EntityLink
    • ContextDrawer
    • DataTable
    • FilterPopover / selection popovers
    • Status chips and validation widgets

4.3 Flow Gate (CI Required)​

  • run end-to-end accessibility checks on critical journeys:
    • authoring publish workflow
    • assignment issue + monitor triage
    • runtime submit workflow
    • review/approval decision flow

4.4 Manual Release Gate (Required)​

  • keyboard-only smoke across critical flows
  • screen reader smoke (at least one desktop SR and one mobile SR path)
  • zoom/dynamic text smoke for core pages

Note:

  • automated checks are necessary but not sufficient
  • manual checks remain release blockers for critical workflows

4.5 ATAG-Specific Gate (Required for authoring/Admin Surfaces)​

  • authoring UI paths pass the same automated accessibility gates as other critical flows
  • authoring acceptance tests verify accessible creation/edit/publish without pointer-only interaction
  • output-support checks validate that accessibility-relevant fields are preserved across save/import/publish operations
  • accessibility warnings in authoring validation are deterministic (clear codes/messages), localisable, and test-covered

5. Definition of Done Additions (MUST)​

A frontend feature is done only when:

  1. WCAG 2.2 AA expectations are met for the implemented surface
  2. automated accessibility gates pass in CI
  3. keyboard completion works for all feature-critical tasks
  4. screen reader announcements are clear and non-ambiguous
  5. no severe accessibility regressions are introduced in shared components
  6. for authoring/admin features, ATAG objective A requirements are met
  7. for authoring/admin features, ATAG objective B requirements are met or explicitly feature-gated with tracked follow-up

6. Source Docs​

This file complements, not replaces:

  • /docs/ux/UX-GOVERNANCE.md
  • /docs/ux/UX-FRONTEND-CONVENTIONS.md
  • /docs/ux/UX-SHARED-COMPONENTS-CONTRACT.md
  • /docs/ux/UX-CHECKLIST.md
  • /docs/ux/UX-RUNTIME-CANDIDATE-DELIVERY.md
  • /docs/ux/UX-AUTHORING.md