docs(ui): add production ux remediation roadmap

2026-05-07 01:51:58 -07:00 · 2026-05-07 01:51:58 -07:00 · b30f470873
commit b30f470873
parent b4f68725ef
1 changed files with 644 additions and 0 deletions
--- a/docs/PRODUCTION_GRADE_UX_REMEDIATION_ROADMAP.md
+++ b/docs/PRODUCTION_GRADE_UX_REMEDIATION_ROADMAP.md
@ -0,0 +1,644 @@
+# Production-Grade UX Remediation Roadmap
+
+**Repo**: `learning_ai_invt_trdg`  
+**App**: ByteLyst Trading Web  
+**Status**: Post platform-core migration UX remediation  
+**Priority**: Critical  
+**Primary concern**: The app is audit-clean and uses common UI primitives, but several production surfaces still look visually broken, over-compressed, and unpolished.
+
+---
+
+## 1. Executive Summary
+
+The UI/UX platform-core migration successfully moved the trading web app onto shared ByteLyst UI primitives, design tokens, and strict drift auditing. However, the migration solved architectural drift more than visual quality. The screenshot of the Trade Plans surface shows a severe production-readiness gap:
+
+- controls are too short and cramped;
+- text is squeezed into thin strips;
+- field hierarchy is unclear;
+- dark surfaces feel flat and overly dense;
+- important actions are visually weak;
+- side panels and content areas are poorly balanced;
+- the page does not feel rich, premium, or professional.
+
+This roadmap defines a full remediation plan to turn the app into a production-grade, high-trust, premium trading interface while preserving the completed common-platform architecture.
+
+---
+
+## 2. Current State
+
+### 2.1 What is already good
+
+- `@bytelyst/ui` is consumed through `web/src/components/ui/Primitives.tsx`.
+- Direct `@bytelyst/ui` imports outside the adapter are blocked by audit.
+- Raw production controls outside approved primitives are at zero.
+- Legacy global surface classes are at zero.
+- Hardcoded color literals in product code are at zero.
+- Token definitions are centralized in `web/src/index.css` and intentionally excluded from product-debt audit.
+- Business logic remains product-owned; common platform owns generic primitives.
+
+### 2.2 What is still bad
+
+The app still carries legacy visual-density assumptions:
+
+- tiny form controls;
+- excessive uppercase labels;
+- compressed line heights;
+- weak page/card hierarchy;
+- low contrast secondary text;
+- border-heavy dark panels;
+- repeated inline layout styles;
+- page-specific CSS fighting common primitive defaults;
+- insufficient spacing between sections, fields, and helper copy.
+
+### 2.3 Main diagnosis
+
+The current UI is **architecturally migrated but visually under-designed**. The next phase must be a design-system quality pass, not another token/audit pass.
+
+---
+
+## 3. North Star UX
+
+The app should feel like a premium professional trading cockpit:
+
+- **Confident**: clear hierarchy, strong primary actions, readable operational state.
+- **Calm**: no visual noise, no compressed controls, no frantic neon overload.
+- **Dense but readable**: trading apps need information density, but not at the cost of scanability.
+- **Trustworthy**: risk, live trading, automated exits, and account state must be visually unmistakable.
+- **Responsive**: desktop-first, but usable at tablet widths and smaller laptop screens.
+- **Accessible**: keyboard focus, contrast, touch/click target size, semantic labels.
+- **Common-platform aligned**: use adapter primitives first; product CSS should compose layout, not restyle primitives into broken shapes.
+
+---
+
+## 4. Non-Negotiable Design Standards
+
+### 4.1 Control sizing
+
+All production form controls must meet these minimums unless there is a specific compact-table exception:
+
+- **Default input/select/button height**: `40px` to `44px`.
+- **Compact control height**: no less than `32px`.
+- **Primary CTA height**: `44px` to `48px`.
+- **Icon button target**: at least `36px x 36px`.
+- **Inline table action target**: at least `32px x 32px`.
+
+### 4.2 Typography
+
+- Page title: `28px-36px`, strong but not oversized.
+- Section title: `16px-20px`, clear hierarchy.
+- Field label: `12px-13px`, readable, not over-letterspaced.
+- Body/helper text: `13px-14px`, line-height `1.45-1.65`.
+- Avoid all-caps except badges, ticker symbols, and compact status labels.
+
+### 4.3 Spacing
+
+- Page padding: `24px-32px` desktop.
+- Card padding: `20px-28px`.
+- Form field gap: `14px-18px`.
+- Section gap: `24px-36px`.
+- Dense trading lists can use `8px-12px`, but never collapse text into borders.
+
+### 4.4 Color and contrast
+
+- Keep token audit at zero debt.
+- Do not introduce raw hex/rgba in product files.
+- Use success/danger/warning/info tokens only where they carry meaning.
+- Secondary text must remain readable on dark backgrounds.
+- Alert banners must be prominent without looking like a debug strip.
+
+### 4.5 Motion and interaction
+
+- Hover/focus states must be visible and consistent.
+- Avoid sudden layout jumps.
+- Use subtle elevation and border changes for cards and controls.
+- Respect reduced-motion preferences.
+
+---
+
+## 5. Target Architecture
+
+### 5.1 Common UI remains the source for primitives
+
+Continue using:
+
+- `Button`
+- `IconButton`
+- `Input`
+- `Select`
+- `Textarea`
+- `Badge`
+- `ProductStatusBadge`
+
+from:
+
+```text
+web/src/components/ui/Primitives.tsx
+```
+
+### 5.2 Product adapter should own product defaults
+
+The adapter should define trading-product defaults that prevent broken UX:
+
+- sensible default heights;
+- rich field variants;
+- button size aliases;
+- status tone mapping;
+- compact mode only when explicitly requested;
+- no page-specific hacks inside individual screens.
+
+### 5.3 Product CSS should own layout, not primitive internals
+
+Allowed product CSS responsibilities:
+
+- grid layout;
+- page shells;
+- card composition;
+- responsive behavior;
+- trading-specific chart/list composition;
+- domain-specific badges when common primitives do not fit.
+
+Disallowed product CSS responsibilities:
+
+- shrinking primitive inputs/buttons below usable sizes;
+- overriding primitive text color randomly;
+- using all-caps micro-labels everywhere;
+- introducing one-off dark surface systems;
+- using raw color literals.
+
+---
+
+## 6. Phase Roadmap
+
+## Phase 0: Baseline Capture and Safety Net
+
+**Goal**: Freeze the current broken state as a known baseline and prevent blind visual edits.
+
+### Tasks
+
+- Capture screenshots for key routes at desktop widths:
+  - Home
+  - Trade Plans / SimpleView
+  - Portfolio
+  - Strategies
+  - Backtest
+  - Settings
+  - Alerts
+  - Marketplace
+- Capture dark-mode and, if supported, light-mode screenshots.
+- Record viewport sizes:
+  - `1440x900`
+  - `1280x800`
+  - `1024x768`
+- Add or update DOM tests only for structural behavior, not pixel-perfect visuals.
+- Confirm audit baseline remains clean.
+
+### Verification
+
+```bash
+pnpm run audit:ui
+pnpm run audit:ui:strict
+pnpm --filter @bytelyst/trading-web typecheck
+pnpm --filter @bytelyst/trading-web lint
+pnpm --filter @bytelyst/trading-web build
+git diff --check
+```
+
+### Exit criteria
+
+- Current screenshots are stored or referenced in the issue/PR notes.
+- No uncommitted baseline changes.
+- Strict audit remains green.
+
+---
+
+## Phase 1: Primitive Adapter Quality Pass
+
+**Goal**: Fix the common cause of tiny, cramped controls by improving product adapter defaults.
+
+### Target file
+
+```text
+web/src/components/ui/Primitives.tsx
+```
+
+### Tasks
+
+- Review `Button`, `Input`, `Select`, and `Textarea` default sizing.
+- Ensure default fields render at production height without requiring every page to pass classes.
+- Make compact controls opt-in only.
+- Add richer variants if needed:
+  - `surface`
+  - `muted`
+  - `ghost`
+  - `danger`
+  - `success`
+- Ensure `Button size="sm"` is not visually collapsed.
+- Ensure `Select` arrow alignment is correct and not detached from the field.
+- Ensure focus rings are visible and premium.
+- Avoid changing common platform unless the missing capability is truly product-agnostic.
+
+### UX acceptance criteria
+
+- Default controls are readable and clickable.
+- No button text appears squeezed.
+- Select arrows sit inside the control and align vertically.
+- Focus states are visible in dark mode.
+- Existing adapter import contract remains stable.
+
+### Verification
+
+```bash
+pnpm --filter @bytelyst/trading-web exec vitest run src/components/ComponentsSmoke.test.ts
+pnpm --filter @bytelyst/trading-web typecheck
+pnpm --filter @bytelyst/trading-web lint
+pnpm run audit:ui
+git diff --check
+```
+
+---
+
+## Phase 2: Global Form and Surface Rhythm
+
+**Goal**: Create a consistent visual rhythm that all pages can inherit.
+
+### Target files
+
+```text
+web/src/index.css
+web/src/App.css
+```
+
+### Tasks
+
+- Add product-level spacing aliases if missing:
+  - `--bl-space-page-x`
+  - `--bl-space-page-y`
+  - `--bl-space-card`
+  - `--bl-space-section`
+  - `--bl-control-height`
+  - `--bl-control-height-sm`
+  - `--bl-radius-card`
+  - `--bl-radius-control`
+- Add shared utility classes for:
+  - page shell;
+  - page header;
+  - section card;
+  - form grid;
+  - field stack;
+  - helper text;
+  - action row;
+  - status strip;
+  - empty state.
+- Remove or override legacy CSS that compresses form controls.
+- Standardize cards with subtle elevation, borders, and background separation.
+
+### UX acceptance criteria
+
+- Form rows breathe.
+- Section boundaries are obvious.
+- Helper text is readable and no longer visually glued to controls.
+- Card surfaces look premium rather than like raw bordered boxes.
+
+### Verification
+
+```bash
+pnpm run audit:ui
+pnpm run audit:ui:strict
+pnpm --filter @bytelyst/trading-web typecheck
+pnpm --filter @bytelyst/trading-web lint
+git diff --check
+```
+
+---
+
+## Phase 3: Trade Plans / SimpleView Rescue
+
+**Goal**: Fix the worst visible surface first.
+
+### Target file
+
+```text
+web/src/views/SimpleView.tsx
+```
+
+### Problems to fix
+
+- The Trade Plans form is visually collapsed.
+- Primary/secondary actions look like thin text strips.
+- Field labels are too tiny and over-letterspaced.
+- Helper text is cramped and dim.
+- Sections do not read as a guided workflow.
+- The reset button looks like a debug control.
+- Select chevrons are detached from the field.
+
+### Desired experience
+
+Trade Plans should feel like a guided professional workflow:
+
+1. Choose setup type.
+2. Choose symbol or holding.
+3. Confirm market price.
+4. Choose sizing method.
+5. Set trigger/risk/exit details.
+6. Review and create plan.
+
+### Tasks
+
+- Split the form into clear cards or sections:
+  - `Setup Type`
+  - `Instrument`
+  - `Market Price`
+  - `Sizing`
+  - `Trigger`
+  - `Risk Controls`
+  - `Review`
+- Replace thin segmented action strips with real button groups.
+- Add a clear primary CTA: `Create Plan`.
+- Use a secondary CTA for `Manage Holding`.
+- Move `Reset` into a secondary/ghost action row, not the top-right debug-strip style.
+- Use two-column layout where appropriate, single-column where content needs explanation.
+- Add readable helper copy under each field.
+- Use badges/status indicators for price source, symbol validation, and plan type.
+- Add empty/loading/error states for market price and holdings.
+- Verify keyboard navigation through the full form.
+
+### UX acceptance criteria
+
+- No controls are visually collapsed.
+- The page can be understood in 5 seconds.
+- Primary action is obvious.
+- Field grouping matches the trading workflow.
+- Disabled/loading states are visually clear.
+- The page feels like a modern fintech product, not a debug console.
+
+### Verification
+
+```bash
+pnpm --filter @bytelyst/trading-web exec vitest run src/views/SimpleView.test.ts
+pnpm --filter @bytelyst/trading-web typecheck
+pnpm --filter @bytelyst/trading-web lint
+pnpm run audit:ui
+pnpm run audit:ui:strict
+git diff --check
+```
+
+---
+
+## Phase 4: App Shell and Alert System Polish
+
+**Goal**: Make the surrounding frame feel professional and trustworthy.
+
+### Target areas
+
+- Header
+- Sidebar
+- Right panel
+- System alert banner
+- Live status indicators
+- Search bar
+- Notification controls
+
+### Tasks
+
+- Redesign the top critical-alert banner so it looks like a production incident banner, not a terminal warning strip.
+- Add clear severity hierarchy:
+  - critical;
+  - warning;
+  - info;
+  - success.
+- Improve sidebar active states and label readability.
+- Ensure right panel cards have consistent spacing and useful empty states.
+- Align search bar height, padding, and placeholder contrast with other controls.
+- Improve portfolio/news empty states so the right rail does not feel abandoned.
+
+### UX acceptance criteria
+
+- Critical alerts are noticeable but not visually ugly.
+- Sidebar feels polished and stable.
+- Right rail does not look like unused space.
+- Search and live indicators feel integrated into the shell.
+
+### Verification
+
+```bash
+pnpm --filter @bytelyst/trading-web exec vitest run src/components/layout/Header.dom.test.tsx src/components/layout/AppShell.dom.test.tsx src/App.dom.test.tsx
+pnpm --filter @bytelyst/trading-web typecheck
+pnpm run audit:ui
+git diff --check
+```
+
+---
+
+## Phase 5: Core Trading Workflows Polish
+
+**Goal**: Apply the new rhythm to the highest-value trading workflows.
+
+### Target surfaces
+
+- Portfolio / Positions
+- History
+- Entries
+- Watchlist
+- Alerts
+- Markets / Screener
+- Strategy builder
+- Backtest
+
+### Tasks
+
+- Standardize table/list row heights.
+- Use status badges consistently.
+- Improve empty states.
+- Normalize filter bars and toolbar actions.
+- Make destructive actions visually clear.
+- Improve card hierarchy for strategy and backtest panels.
+- Preserve chart-specific domain coloring where semantically meaningful.
+
+### UX acceptance criteria
+
+- All core routes feel like the same product.
+- Tables/lists are dense but readable.
+- Filters and actions are easy to discover.
+- Empty states explain what to do next.
+
+### Verification
+
+```bash
+pnpm --filter @bytelyst/trading-web exec vitest run src/tabs/PositionsTab.dom.test.tsx src/tabs/EntriesTab.dom.test.tsx src/views/ScreenerView.dom.test.tsx src/components/ComponentsSmoke.test.ts
+pnpm --filter @bytelyst/trading-web typecheck
+pnpm --filter @bytelyst/trading-web lint
+pnpm run audit:ui
+git diff --check
+```
+
+---
+
+## Phase 6: Rich Visual Polish Layer
+
+**Goal**: Add the premium feel after usability is fixed.
+
+### Tasks
+
+- Add subtle card gradients using existing tokens.
+- Add consistent elevation and hover states.
+- Add polished status chips and metric cards.
+- Add skeleton/loading states for major panels.
+- Add premium empty states with icons and next actions.
+- Add trading-specific visual accents:
+  - live mode glow;
+  - risk warning strip;
+  - managed-exit badge;
+  - paper/live account distinction;
+  - price-source status chip.
+- Improve responsive behavior for laptop and tablet widths.
+
+### Guardrails
+
+- Do not add visual effects before fixing layout/spacing.
+- Do not use raw color literals.
+- Do not sacrifice readability for ornamentation.
+- Avoid animation that distracts from trading workflows.
+
+### UX acceptance criteria
+
+- UI feels rich and modern.
+- Operational status is clear without being noisy.
+- Panels feel intentionally designed.
+- Hover/focus states feel smooth and consistent.
+
+---
+
+## Phase 7: Accessibility and Production QA
+
+**Goal**: Ensure the improved UX is safe for production use.
+
+### Tasks
+
+- Keyboard test all primary workflows.
+- Verify focus order on forms and shell navigation.
+- Verify visible focus rings in dark mode.
+- Check color contrast for:
+  - helper text;
+  - disabled states;
+  - alert banners;
+  - status chips;
+  - positive/negative values.
+- Test responsive widths.
+- Test empty/loading/error states.
+- Test with long symbol names, long descriptions, and missing data.
+- Run build and targeted tests.
+
+### Verification
+
+```bash
+pnpm run audit:ui
+pnpm run audit:ui:strict
+pnpm --filter @bytelyst/trading-web typecheck
+pnpm --filter @bytelyst/trading-web lint
+pnpm --filter @bytelyst/trading-web build
+pnpm --filter @bytelyst/trading-web exec vitest run
+git diff --check
+```
+
+---
+
+## 7. Route-by-Route Priority
+
+### P0 — Fix immediately
+
+1. **Trade Plans / SimpleView**
+   - Worst visible regression.
+   - High business value.
+   - Must become a guided workflow.
+
+2. **App Shell / alert banner / right rail**
+   - Present on nearly every route.
+   - Determines first impression.
+
+3. **Primitive adapter defaults**
+   - One fix improves many pages.
+
+### P1 — Next high-impact surfaces
+
+4. **Portfolio / Positions**
+5. **Strategies / MyStrategiesTab**
+6. **Backtest**
+7. **Settings**
+8. **Alerts / Watchlist**
+
+### P2 — Polish and consistency
+
+9. **Marketplace**
+10. **Membership**
+11. **Admin/config surfaces**
+12. **Secondary empty states and loading panels**
+
+---
+
+## 8. Implementation Strategy
+
+### Recommended commit sequence
+
+1. `feat(ui): add production ux remediation roadmap`
+2. `refactor(ui): normalize primitive adapter sizing`
+3. `refactor(ui): add form rhythm utilities`
+4. `refactor(ui): redesign trade plans workflow shell`
+5. `refactor(ui): polish trade plans form controls`
+6. `refactor(ui): normalize app shell alert and side panels`
+7. `refactor(ui): standardize trading workflow surfaces`
+8. `test(ui): add ux regression coverage for trade plans`
+9. `docs(ui): record production ux remediation progress`
+
+### Work rules
+
+- Keep commits small and scoped.
+- Push after each completed slice.
+- Update this roadmap after each major slice.
+- Do not combine UX redesign with business logic rewrites.
+- Preserve existing tests and add focused coverage when changing structure.
+- Keep audit strict green unless an intentional exception is documented.
+
+---
+
+## 9. Acceptance Checklist for Production Grade
+
+A page is production-grade only when all of these are true:
+
+- [ ] Page has a clear title, description, and primary action.
+- [ ] Controls meet minimum usable height.
+- [ ] Field labels and helper text are readable.
+- [ ] Primary/secondary/destructive actions are visually distinct.
+- [ ] Empty/loading/error states are designed.
+- [ ] Cards/sections have consistent spacing and hierarchy.
+- [ ] Keyboard focus is visible and logical.
+- [ ] Responsive layout does not collapse at common laptop widths.
+- [ ] No raw controls outside approved primitives.
+- [ ] No direct common UI imports outside adapter.
+- [ ] No hardcoded product color literals.
+- [ ] `typecheck`, `lint`, `build`, audit, and focused tests pass.
+
+---
+
+## 10. Immediate Next Action
+
+Start with the lowest-risk, highest-leverage sequence:
+
+1. Update adapter defaults for `Input`, `Select`, `Textarea`, and `Button` sizing.
+2. Add form rhythm utility classes in global CSS.
+3. Redesign the `Trade Plans` / `SimpleView` setup form into a guided card workflow.
+4. Verify `SimpleView.test.ts`, typecheck, lint, build, strict audit, and screenshot review.
+5. Commit and push.
+
+---
+
+## 11. Final Definition of Done
+
+The remediation is complete when:
+
+- Trade Plans no longer looks broken or compressed.
+- All primary trading workflows share a consistent premium visual language.
+- The app shell feels production-grade.
+- Common UI primitives remain routed through the product adapter.
+- Strict UI audit remains clean.
+- Full web verification passes.
+- The app is visually reviewed at multiple viewport sizes.