# 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

- [x] Normalize `web/src/components/TradeProfileManager.tsx`
- [x] Normalize `web/src/components/StrategyWizard.tsx`
- [x] Normalize `web/src/tabs/ReconciliationAuditPanel.tsx`
- [x] Normalize `web/src/components/GlobalConfigManager.tsx`
- [x] 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.