From cc9268cee89078dd92d799be7f57748ede9f21e9 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 6 May 2026 04:28:10 +0000 Subject: [PATCH] docs(web): add ux theme normalization handoff --- docs/UX_THEME_NORMALIZATION_HANDOFF.md | 203 +++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 docs/UX_THEME_NORMALIZATION_HANDOFF.md diff --git a/docs/UX_THEME_NORMALIZATION_HANDOFF.md b/docs/UX_THEME_NORMALIZATION_HANDOFF.md new file mode 100644 index 0000000..9faa659 --- /dev/null +++ b/docs/UX_THEME_NORMALIZATION_HANDOFF.md @@ -0,0 +1,203 @@ +# UX Theme Normalization Handoff + +**Last updated**: 2026-05-06 +**Scope**: Web UX consistency, shared light/dark theming, Shadcn-style local primitives +**Repo**: `learning_ai_invt_trdg` + +--- + +## TL;DR + +The trading web app now has a shared light/dark theme system, tokenized colors, +Shadcn-style local UI primitives, and normalized page chrome across the main +surfaces. Two follow-up passes extended this to the biggest remaining custom UX +surfaces. The app is live with the latest bundle and the remaining work is now +mostly legacy component cleanup rather than foundation work. + +Latest shipped UX/theme commits: + +- `266b367` `feat(web): add shared light dark theme system` +- `76d326c` `refactor(web): normalize secondary ux surfaces` +- `69e1b12` `refactor(web): normalize advanced theme surfaces` + +Current public bundle: + +- `index-SQotmrnT.js` +- `index-F_eQCdHQ.css` + +--- + +## What is already done + +### Shared foundation + +- [x] Add `ThemeProvider` with persisted theme preference +- [x] Add tokenized light/dark theme variables in `web/src/index.css` +- [x] Add shared utility classes for sections, pills, chips, and hero surfaces +- [x] Add local Shadcn-style primitives: + - [x] `Button` + - [x] `Card` + - [x] `Input` + - [x] `Select` + - [x] `PageHeader` +- [x] Wrap the app with the theme provider in `web/src/main.tsx` + +### App shell normalization + +- [x] Header +- [x] Sidebar +- [x] Right panel +- [x] Loading states +- [x] 404 / not-found state + +### Main page normalization + +- [x] Home +- [x] Research +- [x] Markets +- [x] Screener +- [x] Portfolio +- [x] Settings +- [x] Watchlist +- [x] Alerts +- [x] Simple + +### Secondary surface normalization + +- [x] Backtest +- [x] Marketplace wrapper +- [x] Membership +- [x] Research fallback panels + +### Advanced custom surface normalization + +- [x] `PresetMarketplace` +- [x] `ChatControl` +- [x] `CodeStrategyEditor` +- [x] `VisualRuleBuilder` + +### Validation already performed + +- [x] Focused DOM regression tests updated for token-based styling +- [x] Focused DOM regression suite passed: + - [x] `ChatControl` + - [x] `Header` + - [x] `ResearchView` + - [x] `ScreenerView` + - [x] `SettingsView` + - [x] `ComponentsSmoke` +- [x] `pnpm build` passed +- [x] Web redeployed and live asset hash verified + +--- + +## Remaining roadmap + +## Phase 4: Remaining legacy component cleanup + +- [ ] Normalize `web/src/components/TradeProfileManager.tsx` +- [ ] Normalize `web/src/components/StrategyWizard.tsx` +- [ ] Normalize `web/src/tabs/ReconciliationAuditPanel.tsx` +- [ ] Normalize `web/src/components/GlobalConfigManager.tsx` +- [ ] Normalize `web/src/components/EntryForm.tsx` +- [ ] Normalize remaining old admin/config surfaces +- [ ] Remove remaining dark-only bespoke surface systems +- [ ] Replace remaining one-off controls with shared primitives where practical + +## Phase 5: Styling consolidation + +- [ ] Audit remaining hardcoded colors: + - Suggested command: + - `rg -n "background: '#|color: '#|bg-\\[|text-\\[|border-\\[|linear-gradient|radial-gradient" web/src/components web/src/tabs web/src/views` +- [ ] Replace duplicated inline styling with shared CSS utilities where helpful +- [ ] Standardize section titles, descriptions, and spacing across remaining tabs +- [ ] Standardize empty states and status chips across remaining legacy views +- [ ] Reduce implementation drift between old inline-style components and the new tokenized system + +## Phase 6: QA and no-regression pass + +- [ ] Run the full web test suite +- [ ] Add targeted DOM tests for any newly normalized legacy components +- [ ] Smoke test major routes in both light and dark mode +- [ ] Verify keyboard focus visibility in both themes +- [ ] Verify Monaco/editor areas remain readable in both themes +- [ ] Verify responsive layouts after each converted component +- [ ] Confirm no auth/session regressions related to `ThemeProvider` + +## Phase 7: Optional system polish + +- [ ] Add more local primitives if needed: + - [ ] `Textarea` + - [ ] `Badge` + - [ ] `Tabs` + - [ ] `Dialog` +- [ ] Normalize bespoke modal/drawer patterns +- [ ] Consider better code-splitting for Monaco-heavy surfaces +- [ ] Document theme token usage for future contributors + +--- + +## Recommended execution order + +1. `TradeProfileManager` +2. `StrategyWizard` +3. `ReconciliationAuditPanel` +4. `GlobalConfigManager` +5. `EntryForm` +6. Remaining admin/config leftovers +7. Full regression pass +8. Optional polish and documentation + +--- + +## Guardrails for the next agent + +- Do not change business logic unless a UI normalization step forces a bug fix. +- Prefer shared theme tokens over hardcoded hex values. +- Prefer shared primitives over one-off control styling. +- Match the normalized page language already established in the app. +- Run focused tests after each major component conversion. +- Run `pnpm build` before commit. +- Verify the public asset hash after deploy instead of assuming rollout success. +- Keep commits scoped and grep-able. + +Recommended commit style: + +- `refactor(web): normalize theme surfaces` +- `test(web): update theme assertions` +- `fix(web): preserve while normalizing theme` + +--- + +## Suggested verification commands + +From repo root: + +```bash +cd /opt/bytelyst/trading/learning_ai_invt_trdg/web +pnpm exec vitest run +pnpm build +``` + +For a focused component pass: + +```bash +pnpm exec vitest run src/components/layout/Header.dom.test.tsx src/views/ScreenerView.dom.test.tsx src/views/SettingsView.dom.test.tsx src/components/ComponentsSmoke.test.ts +``` + +After deploy: + +```bash +curl -s https://invttrdg.bytelyst.com | sed -n '1,120p' +curl -sI https://invttrdg.bytelyst.com +``` + +--- + +## Handoff summary + +The theme foundation is complete and live. The remaining work is now a +systematic cleanup of older bespoke components, with the main risk being UI +drift rather than architectural uncertainty. The next agent should continue by +normalizing the remaining legacy components in the recommended order, validating +each pass with focused DOM tests and a production build.