Skip to main content

UX-FRONTEND-READINESS-CHECKLIST.md

This document is a practical readiness gate for moving from backend-first progress into production-grade frontend delivery.

Purpose:

  • convert UX intent into executable frontend readiness criteria
  • define pass/fail checks before broad frontend build-out
  • reduce rework by forcing shared foundations before feature-by-feature UI work

Capability Baseline (Validated 2026-02-25)​

Backend APIs are already strong across authoring, assignments, delivery, review, and reporting lenses.

Frontend readiness work therefore focuses on:

  • contract-safe client integration
  • shared UI primitives
  • accessibility and resilience guardrails
  • release quality gates

0. Readiness Rule (MUST)​

Do not scale feature UI development until all P0 gates pass.

Definition:

  • PASS: objective evidence exists and gate criteria are satisfied.
  • FAIL: criteria missing, partial, or non-deterministic.

1. P0 Gates (Blocking)​

1.1 Frontend Contract Layer (MUST)​

Scope:

  • shared API wrapper for auth/session, CSRF, idempotency key behavior, and error translation
  • canonical status mapping utility (backend enums -> UI labels)
  • localization resolver integration (org -> tenant -> product fallback)

Pass criteria:

  • one shared client contract module is used by all mutating and authenticated flows
  • raw backend error strings are not primary UX output
  • idempotency conflicts/in-progress states map to deterministic UI states
  • status label mapping is centralized and reused in chips, filters, and exports

Fail criteria:

  • per-page ad-hoc fetch/mutation logic
  • duplicated enum mapping logic
  • user-facing raw backend messages

Evidence:

  • shared contract module path
  • integration/unit tests for error/status/idempotency mapping

1.2 Shared Navigation and Page Primitives (MUST)​

Scope:

  • EntityLink
  • Drawer coordinator + context drawer shell
  • standard hub shell and table primitive
  • canonical status chip

Pass criteria:

  • link contract is enforced (read-only drawer peek on drawer-enabled surfaces, full page for edit/deeper workflows)
  • URL-driven drawer behavior supports back/forward
  • status chips use canonical language
  • table/list interactions support keyboard and touch baselines

Fail criteria:

  • dead-text references
  • drawer behavior implemented differently across features
  • divergent status wording

Evidence:

  • shared component implementations
  • usage in at least one admin surface and one candidate/runtime-adjacent surface

1.3 Delivery Runtime Resilience Foundation (MUST)​

Scope:

  • autosave/reconcile behavior
  • retry-safe submit flow
  • reconnect-safe session handling

Pass criteria:

  • no duplicate submit on retry/tap race
  • unsent answers are preserved across recoverable failure
  • runtime state transitions are explicit and deterministic

Fail criteria:

  • answer loss on transient failure
  • ambiguous submit outcome
  • missing retry guidance

Evidence:

  • runtime flow tests
  • explicit state model implementation

1.4 Accessibility Guardrails in CI (MUST)​

Scope:

  • compile/lint accessibility gates
  • component-level automated checks
  • critical flow end-to-end checks

Pass criteria:

  • CI fails on accessibility regressions
  • critical flows include automated a11y checks (authoring publish, assignment monitor, runtime submit, review decisions)
  • release checklist includes keyboard + screen-reader smoke

Fail criteria:

  • accessibility checked manually only
  • no CI blocking behavior for a11y regressions

Evidence:

  • CI jobs and config files
  • test reports for critical flows

1.5 Candidate-Facing Delivery Accessibility (MUST)​

Scope:

  • runtime completion path (start -> answer -> submit)

Pass criteria:

  • completion path works on phone, iPad, keyboard-only, and screen-reader-assisted usage
  • timer/expiry/lockdown messages are plain-language and accessible
  • critical actions are never hover-dependent

Fail criteria:

  • device-dependent reduced completion path
  • color-only risk signaling
  • inaccessible submit confirmation/recovery flow

Evidence:

  • runtime accessibility test results
  • device matrix run logs

2.1 Design Token and Responsive System​

Pass:

  • tokenized spacing/typography/contrast/breakpoints used in shared components
  • touch target and density rules enforced for mobile/iPad surfaces

2.2 Frontend Observability​

Pass:

  • frontend telemetry captures critical UX failures and retry patterns
  • correlation IDs are surfaced for support/debug flows

2.3 Release Device Matrix​

Pass:

  • repeatable smoke across supported phone/tablet/desktop classes
  • documented no-ship conditions for critical regressions

2.4 Language Override Safety (Org > Tenant > Product)​

Pass:

  • translation resolution precedence is deterministic and tested (org, then tenant, then product default)
  • override edits are capability-gated and auditable
  • missing override keys cleanly fall back without broken UI text

3. P2 Gates (Scale and Optimization)​

3.1 Performance Budgets​

Pass:

  • key routes meet agreed interaction/paint budgets
  • data-dense views use progressive loading/virtualization where required

3.2 Advanced Offline Activation​

Pass:

  • offline sync contracts are implemented behind explicit feature gating
  • recovery and rejection states are deterministic and user-actionable

3.3 Progressive Complexity Modes​

Pass:

  • quick-mode flows exist for mobile/task-light operations
  • advanced-mode flows remain available for complex authoring/operations tasks
  • mode availability and handoff messaging are explicit and non-ambiguous

3.4 Explainability Action Panels​

Pass:

  • readiness/KOE reason codes are translated into operator-facing action guidance
  • each action panel links to concrete remediation surfaces
  • action guidance never overrides ledger truth; it is clearly a projection layer

4. Gate Review Template​

Use this template in PR/release reviews:

  1. Gate name:
  2. Current status: PASS or FAIL
  3. Evidence links (tests/screens/CI runs):
  4. Known risk if failing:
  5. Next action and owner:
  • /docs/ux/UX-FRONTEND-CONVENTIONS.md
  • /docs/ux/UX-SHARED-COMPONENTS-CONTRACT.md
  • /docs/ux/UX-ACCESSIBILITY-STANDARDS-AND-GUARDRAILS.md
  • /docs/ux/UX-MOBILE-AND-TASK-TIER-POLICY.md
  • /docs/ux/UX-CHECKLIST.md
  • /docs/ux/UX-RUNTIME-CANDIDATE-DELIVERY.md