# UI Phase 1 — Audit and Design System Foundation

Date: 2026-08-19

## Scope lock

| Item | Locked scope |
| --- | --- |
| Files expected to change | Global tokens/styles, shared UI primitives, direct tests, this audit |
| Modules affected | Theme/tokens, buttons, form feedback, shared screen states |
| Behavior expected to change | Consistent scales, accessible validation descriptions, reusable loading/not-found states |
| Behavior that must remain unchanged | Routing, API contracts, business logic, backend, page workflows, app-shell layout |

## Baseline inventory

| Measure | Baseline |
| --- | ---: |
| TSX files | 90 |
| CSS files | 24 |
| Files using native buttons | 37 |
| Files using shared `Button` | 31 |
| Files using native form controls | 36 |
| Files using `FormField` | 8 |
| Files using `ScreenState` | 27 |
| CSS files containing raw colors | 12 |

The project already had a sound semantic light/dark palette, Dana/Inter font stacks, visible focus rings, 44px touch targets, reduced-motion handling, modal focus management, and shared primitives. Phase 1 strengthens that existing foundation instead of replacing it.

## Product surface audit

| Surface | Main findings | Priority | Routed phase |
| --- | --- | --- | --- |
| Login and recovery | Strong two-column hierarchy; raw brand colors and form composition need token adoption checks | Medium | UI Phase 8 polish |
| Dashboard | Useful semantic panels exist; action hierarchy and card density need a dedicated pass | High | UI Phase 3 |
| Courses and workspace | Shared states are used; filter, action, and content-density patterns vary | High | UI Phase 6 |
| Builder | Functional and state-rich; owns several local colors/radii and needs canvas-first UX work | High | UI Phase 4 |
| Library and assets | Good loading/empty coverage; picker overlay and preview surfaces use local styling | Medium | UI Phase 6 |
| Templates and question bank | Dense native controls and local tab/action patterns reduce consistency | High | UI Phase 6 |
| Users, teams, assignments | Similar management workflows use partially different table/filter/action patterns | High | UI Phase 6 |
| Monitoring, reports, skills | Data hierarchy is serviceable; chart/filter and empty/error presentation need alignment | Medium | UI Phase 6 |
| Reviews, certificates, subscription, settings | Shared cards/states exist; destructive actions and long-form settings need pattern review | Medium | UI Phase 6 |
| AI Studio | Core flow exists, but progress, source selection, advanced settings, and review need a single wizard hierarchy | High | UI Phase 5 |
| Learner home/player/assessments | Deliberately distinct learner styling; glass-like surfaces, mobile density, and reading flow need targeted validation | High | UI Phase 7 |

## Findings by category

| Category | Status | Finding |
| --- | --- | --- |
| Consistency | Needs improvement | Shared primitives coexist with many page-local native controls; bulk replacement is deferred to page phases. |
| Hierarchy | Mixed | Global page/section typography existed but was not represented as a reusable token scale. |
| Density | Mixed | Spacing was mostly tokenized, but the scale skipped 20, 40, and 48 pixels. |
| Typography | Good foundation | Dana and Inter are preserved; page, section, card, body, secondary, and caption sizes are now explicit. |
| Forms | Improved | Labels, required markers, focus, disabled, and error styles existed; helper text was lost whenever an error was present. |
| Interactive states | Improved | Focus and disabled states existed; shared buttons now expose compatible size variants and an async loading contract. |
| Loading/empty/error | Good foundation | Skeleton and ScreenState were already reused broadly; loading, success, and not-found semantics are now available. |
| RTL/LTR | Good foundation | Logical CSS properties and language font tokens are established. Page-level exceptions remain phase-specific. |
| Dark mode | Good foundation | Semantic dark tokens exist; elevated, interactive, and subtle-text layers were added explicitly. |
| Accessibility | Improved | Visible focus, reduced motion, modal focus trap, and touch targets exist; form helper/error associations are now complete. |

## Foundation contract

- Surfaces: canvas, surface, elevated, interactive, soft, accent, overlay.
- Semantic color: primary, success, warning/attention, danger, info.
- Spacing: 4, 8, 12, 16, 20, 24, 32, 40, 48.
- Radius: 8, 12, 16, 20; the previous 18px value remains available as a compatibility alias.
- Typography: page, section, card, body, secondary, caption with four documented weights.
- Motion: 150–200ms with standard and exit easing; reduced motion remains enforced globally.
- Layering: base, sticky, drawer, popover, tooltip, modal, toast.
- Buttons: primary, secondary, outline, ghost, danger, icon-compatible styling; small, medium, and large sizing; loading semantics.
- Forms: persistent helper text, adjacent validation message, required marker, `aria-describedby`, and `aria-errormessage`.
- States: skeleton plus empty, loading, error, offline, permission, not-found, and success screen states.

## Deferred technical debt

| Item | Severity | Reason deferred |
| --- | --- | --- |
| Replace or normalize page-local native controls | Medium | Requires page-level visual and behavioral regression checks in Phases 3–7. |
| Remove remaining raw colors and arbitrary radii | Medium | Some values are media/certificate/user-configurable colors; each needs contextual review. |
| Standardize table, tabs, select, checkbox, switch, tooltip, drawer, pagination, search, and filter APIs | High | No complete shared implementations exist; creating them without their consuming page phase risks unused abstractions. |
| Validate every learner glass/blur surface in dark mode | Medium | Belongs to learner and final polish phases. |
| Route-level lazy loading | Medium | Performance change is outside the visual foundation scope and needs measurement first. |

## Before / after UX summary

Before, the product had a capable but implicit foundation: common colors and controls existed, while typography, spacing, surfaces, layering, async buttons, and validation relationships were only partially codified. After Phase 1, those contracts are explicit and test-covered, existing component APIs remain compatible, and later page phases have a stable base without a broad visual rewrite.