docs(web): add ux theme normalization handoff
This commit is contained in:
root
parent
69e1b12d63
commit
cc9268cee8
203
docs/UX_THEME_NORMALIZATION_HANDOFF.md
Normal file
203
docs/UX_THEME_NORMALIZATION_HANDOFF.md
Normal file
@ -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 <component> theme surfaces`
|
||||
- `test(web): update <component> theme assertions`
|
||||
- `fix(web): preserve <workflow> 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.
|
||||
Loading…
Reference in New Issue
Block a user