bytelyst/learning_ai_invt_trdg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
217b46e123
learning_ai_invt_trdg/docs/UX_THEME_NORMALIZATION_HANDOFF.md

5.8 KiB
Raw Blame History

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

  • Add ThemeProvider with persisted theme preference
  • Add tokenized light/dark theme variables in web/src/index.css
  • Add shared utility classes for sections, pills, chips, and hero surfaces
  • Add local Shadcn-style primitives:
    • Button
    • Card
    • Input
    • Select
    • PageHeader
  • Wrap the app with the theme provider in web/src/main.tsx

App shell normalization

  • Header
  • Sidebar
  • Right panel
  • Loading states
  • 404 / not-found state

Main page normalization

  • Home
  • Research
  • Markets
  • Screener
  • Portfolio
  • Settings
  • Watchlist
  • Alerts
  • Simple

Secondary surface normalization

  • Backtest
  • Marketplace wrapper
  • Membership
  • Research fallback panels

Advanced custom surface normalization

  • PresetMarketplace
  • ChatControl
  • CodeStrategyEditor
  • VisualRuleBuilder

Validation already performed

  • Focused DOM regression tests updated for token-based styling
  • Focused DOM regression suite passed:
    • ChatControl
    • Header
    • ResearchView
    • ScreenerView
    • SettingsView
    • ComponentsSmoke
  • pnpm build passed
  • 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:

cd /opt/bytelyst/trading/learning_ai_invt_trdg/web
pnpm exec vitest run
pnpm build

For a focused component pass:

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:

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.