From e63db2627eac65f4aa751b1d52a325e7ab67bb07 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 21 Jun 2026 01:23:48 +0000 Subject: [PATCH] docs: add UI overhaul completion record to docs/history Past-tense paper trail for the apps/ui design-system overhaul (PRs #165-#174): typography unified on the --text-* scale, a single ui/ primitive layer with the duplicate MeasurementPrimitives set deleted, accessibility lifted to WCAG AA, and a style-discipline CI guard. Records the two planned phases deliberately dropped as diff-churn (chip declutter, token scales) and the deferred monolith restyle/split. Adds the matching Contents entry to docs/history/README.md. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_016to3B8Hf9eAGxAbzpQNvku --- docs/history/README.md | 1 + docs/history/ui-overhaul-2026-06-21.md | 84 ++++++++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 docs/history/ui-overhaul-2026-06-21.md diff --git a/docs/history/README.md b/docs/history/README.md index 76165ff1..f8843729 100644 --- a/docs/history/README.md +++ b/docs/history/README.md @@ -22,4 +22,5 @@ Everything in this directory is past-tense. Treat it as a paper trail, not a sou - `public-hosting-foundation-2026-04-01.md` — completion record for the hosted runtime foundation (`runtime_profile.py`, `worker.py`, `artifact_storage.py`, `auth_context.py`, plus frontend runtime overrides). The implementation it describes is current code; the "Remaining work before real public hosting" punch list inside is aspirational — re-open items in `BACKLOG.md` if needed. - `field_utilization_report.md` — point-in-time (2026-03-26) snapshot of which Phase 1 fields appear in Phase 2 recommendations. Field names and removal recommendations are stale; see `apps/backend/JSON_SCHEMA.md` for the authoritative field list. - `generate_phase2_truthfulness_doc.js` — one-shot Node script that generated a Phase 2 truthfulness analysis document. Past-tense; not part of the product path. +- `ui-overhaul-2026-06-21.md` — completion record for the `apps/ui` design-system overhaul (PRs #165–#174): typography unified on `--text-*`, a single `ui/` primitive layer (duplicate `MeasurementPrimitives` deleted), accessibility to WCAG AA, and a style-discipline CI guard. Records the two planned phases deliberately dropped as churn, and the deferred monolith restyle/split. - `archive/` — older archived plans and result stubs. diff --git a/docs/history/ui-overhaul-2026-06-21.md b/docs/history/ui-overhaul-2026-06-21.md new file mode 100644 index 00000000..38834e16 --- /dev/null +++ b/docs/history/ui-overhaul-2026-06-21.md @@ -0,0 +1,84 @@ +# UI Overhaul — Completion Record (2026-06-21) + +Past-tense paper trail for the front-end (`apps/ui`) design-system overhaul. The +work described here is current code on `main`. This document records what shipped, +what was deliberately **not** done and why, and the one piece left deferred. + +## Goal + +Move the UI from an organically-grown collection of one-off styled boxes onto a +single, enforceable design-system vocabulary — without changing any Phase 1 +measurement, Phase 2 recommendation, or chain-of-custody behaviour. The overhaul +was scoped to presentation only; `PURPOSE.md` invariants were never in play. + +## What shipped + +Nine UI-overhaul PRs (`#165`–`#174`), plus `#164` which deflaked a stop-monitoring +smoke test to unblock the work. Every PR landed with `tsc` clean, the full Vitest +unit suite green, a passing production build, and Chromatic — squash-merged under +the repo's green-is-go rule. + +### Uniformity + +- **Phase 0 (`#165`)** — added a style-discipline CI guard that blocks raw hex + colours and off-scale type sizes from re-entering `src/components/ui/`, and + tokenized the primitive layer's type sizes onto the `--text-*` scale. This guard + is what keeps the rest of the overhaul from eroding over time. +- **Phase 1 (`#166`)** — unified all typography onto the `--text-*` scale tokens; + removed ad-hoc `text-[..px]` and mismatched Tailwind size utilities. +- **Phase 2a–d (`#167`–`#170`)** — migrated every feature component onto a single + `src/components/ui/` primitive layer (`Button`, `Panel`, `DeviceRack`, + `SectionHeader`, `Pill`, `DataTable`, `LedIndicator`, metric/lane primitives, + …) and **deleted the duplicate `MeasurementPrimitives` set**. The codebase now + has one primitive vocabulary, not two. + +### Integrity + +- **Phase 4a (`#174`)** — replaced remaining hand-rolled markup with primitives + (DiagnosticLog status dot → `LedIndicator`; consistency table → `DataTable`) and + removed a duplicate "Signal Monitor" heading. The chain-of-custody consistency + report (`Phase2ConsistencyReport`) was held behaviourally identical throughout, + guarded by its existing pinning suite. + +### Accessibility + +- **Phase 3a (`#172`)** — keyboard-operable file upload, visible focus rings on + interactive elements, and accessible labels on the canvas-based visualizers. +- **Phase 3b (`#173`)** — lifted muted text colours to meet WCAG AA contrast on the + dark surfaces. + +## What was deliberately not done + +Two phases from the original plan were dropped after inspection revealed the +foundation was already more mature than the plan assumed. Implementing them would +have produced diff-churn rather than improvement, violating the repo's working +principle that *every changed line trace directly to the request*. + +- **Chip/badge declutter** — the chip system is already disciplined: status and + semantic chips are correctly colour-coded, and a real four-band confidence + ladder (`solid`/`workable`/`rough`/`unreliable`) is shared across + `ConfidenceBandBadge`, `RecommendationVerificationBadge`, and citations. The only + genuine gap is *label-tier hierarchy* among static section labels, which lives + inside the `AnalysisResults` monolith and is best addressed there (see Deferred). + +- **Radius / elevation / motion token scales** — elevation is already a token + system (`--shadow-device-face/rack/active/success/error`); motion is only ~8 + `duration-*` call-sites over a consistent 150 ms default with + `prefers-reduced-motion` already handled; the `rounded` vs `rounded-sm` split is + plausibly intentional hierarchy. No clean, non-speculative win remained. + +## Deferred + +The `AnalysisResults` (~2,800 lines) and `App` (~2,600 lines) monoliths were left +untouched by design. Two distinct pieces of work remain available if prioritized: + +1. **In-place restyle (user-visible)** — give the monolith's flat cards + device-rack character (`DeviceRack`/`SectionHeader`/`Panel`) and apply the + label-tier + accent discipline. Best done as small per-section PRs that respect + the pinned smoke tests (`tests/smoke/`) and the `analysisResultsUi` unit + coverage. +2. **Code split (maintainability-only)** — extract cohesive sub-components from the + two monoliths as pure moves, verifying tests green per slice. No user-visible + payoff; the highest-risk item in the original plan. + +Neither is required for the overhaul's stated goal, which is complete.