New_Micro_Learning/docs/ui-audit-phase1.md

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.