# 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.

## Implementation Log

| Slice | Commit | Verification | Notes |
| --- | --- | --- | --- |
| Phase 1 adapter sizing foundation | `4f27b3b` | `pnpm run audit:ui`; `pnpm run audit:ui:strict`; `pnpm --filter @bytelyst/trading-web typecheck`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/components/ComponentsSmoke.test.ts`; `git diff --check` | Normalized product adapter defaults for `Button`, `Input`, `Select`, and `Textarea` so production controls no longer depend on page-level height patches. |
| Phase 3 Trade Plans workflow shell | `0144124` | `pnpm run audit:ui:strict`; `pnpm --filter @bytelyst/trading-web typecheck`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/views/SimpleView.test.ts src/views/tradePlansState.test.ts`; `pnpm --filter @bytelyst/trading-web lint`; `pnpm --filter @bytelyst/trading-web build`; `git diff --check` | Reworked Trade Plans into guided sections with readable setup cards, larger controls, section helper copy, semantic alert colors, review panel, and sticky save footer while preserving existing trade-plan state and payload behavior. |
| Phase 4 header shell primitive cleanup | `3f70f6e` | `pnpm run audit:ui:strict`; `pnpm --filter @bytelyst/trading-web typecheck`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/components/layout/Header.dom.test.tsx src/App.dom.test.tsx`; `pnpm --filter @bytelyst/trading-web lint`; `pnpm --filter @bytelyst/trading-web build`; `git diff --check` | Replaced the raw header search input and direct button wrapper import with the product UI adapter so the app shell inherits normalized control sizing and stays strict-audit clean. |
| Phase 4 settings tab primitive cleanup | `6e14f42` | `pnpm run audit:ui:strict`; `pnpm --filter @bytelyst/trading-web typecheck`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/views/SettingsView.dom.test.tsx src/App.dom.test.tsx`; `pnpm --filter @bytelyst/trading-web lint`; `pnpm --filter @bytelyst/trading-web build`; `git diff --check` | Replaced Settings route raw tab buttons with product adapter buttons while preserving route/query behavior and strict UI audit cleanliness. |
| Phase 4 Watchlist manual entry form | `f598084` | `pnpm run audit:ui:strict`; `pnpm --filter @bytelyst/trading-web typecheck`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/components/EntryForm.dom.test.tsx src/tabs/EntriesTab.dom.test.tsx src/components/ComponentsSmoke.test.ts`; `pnpm --filter @bytelyst/trading-web lint`; `pnpm --filter @bytelyst/trading-web build`; `git diff --check` | Replaced the compressed table-style manual entry form with guided instrument, pricing/risk, notes, and review sections; added product adapter `Checkbox` usage so the workflow remains strict-audit clean while preserving submission and live-trade behavior. |
| Phase 4 right rail empty-state polish | `63a0a35` | `pnpm run audit:ui:strict`; `pnpm --filter @bytelyst/trading-web typecheck`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/components/layout/AppShell.dom.test.tsx src/components/layout/Header.dom.test.tsx src/App.dom.test.tsx`; `pnpm --filter @bytelyst/trading-web lint`; `pnpm --filter @bytelyst/trading-web build`; `git diff --check` | Upgraded right-rail portfolio/news empty states, normalized row spacing, and routed right-rail buttons through the product UI adapter so the shell no longer feels abandoned when no holdings/news are available. |

---

## 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.

### 4.6 Responsive breakpoints

Every remediated surface must be reviewed at these minimum breakpoints:

- **Wide desktop**: `1440px+`, full shell with right rail.
- **Laptop**: `1280px`, still full shell, no clipped controls.
- **Small laptop/tablet landscape**: `1024px`, right rail may compress or stack intentionally.
- **Tablet portrait**: `768px`, shell must remain navigable and forms must stack cleanly.
- **Mobile fallback**: `390px-430px`, primary workflows may be simplified but must not horizontally overflow.

### 4.7 Trading data density

Trading workflows should remain information-rich, but density must be designed:

- Table/list row height should be `40px-52px` for standard rows and never below `34px`.
- Numeric columns must align consistently and use tabular numerals where possible.
- Positive/negative values must use semantic tokens plus sign/label context, not color alone.
- Toolbars must separate filters, bulk actions, and destructive actions.
- High-risk states such as live trading, kill switch, unmanaged exits, rejected orders, and disabled automation must be visually unmistakable.

### 4.8 Visual QA artifacts

Each major UX slice must include a before/after review note with:

- route name;
- viewport size;
- theme mode;
- screenshot or screen recording reference;
- known deferrals;
- exact verification commands.

---

## 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.

### 5.4 Common-platform feedback loop

If a remediation step reveals a missing reusable primitive capability, classify it before coding:

- **Product-only**: keep it in the trading adapter or local composition.
- **Common-platform candidate**: propose or implement it in `learning_ai_common_plat/packages/ui` only if it is product-agnostic.
- **Do not fork silently**: avoid creating local copies of common primitives with diverging behavior.
- **Verify both sides when common changes are needed**: build `@bytelyst/ui`, then verify `@bytelyst/trading-web`.

---

## 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.
- Record browser/device notes for the broken Trade Plans screenshot so the team can compare against the same viewport.
- Create a short remediation checklist issue or doc section for every P0 surface.

### 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.
- Baseline screenshots are available for future before/after comparison.

---

## 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.
- Add adapter-level comments only if needed to explain why a product-only size/variant exists.
- Confirm no page-level CSS selector is shrinking common controls after adapter changes.

### 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.
- Existing pages improve without requiring one-off per-page control height patches.

### 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`
  - `--bl-shadow-card`
  - `--bl-shadow-card-hover`
  - `--bl-z-sticky`
  - `--bl-z-overlay`
- 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.
- Define tokenized elevation and overlay rules for cards, sticky headers, dropdowns, and right-rail panels.
- Define responsive utility patterns for two-column forms, stacked forms, and split panels.

### 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.
- Sticky/overlay elements do not visually fight the app shell.
- Responsive utilities prevent horizontal overflow.

### 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.
- Add a stepper or progress-style section navigation only if it improves clarity without hiding critical fields.
- Add a sticky review/action footer if the form remains long after sectioning.
- Ensure validation errors are displayed next to fields and summarized near the submit action.
- Preserve all trading semantics, saved setup behavior, and socket/API interactions.

### 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.
- Long helper copy wraps cleanly and never overlaps controls.
- Risk and automation warnings are visible before the user creates a plan.

### 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.
- Define right-rail behavior when there is no portfolio, no news, or no symbol selected.
- Ensure live/paper mode, S&P/Dow/Nasdaq indicators, and system alerts use consistent status primitives.
- Add collapse/resize behavior for the right rail if viewport space is limited.

### 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.
- The shell remains usable at laptop widths without compressing page content into unreadable controls.

### 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.
- Normalize table headers, sticky columns, row hover states, selected rows, and pagination.
- Standardize monetary values, percentages, timestamps, and status chip formatting.
- Make batch/destructive actions require clear confirmation where applicable.

### 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.
- Core workflow panels maintain readability with long symbols, long strategy names, and missing data.

### 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.
- Add lightweight skeletons for data-heavy cards instead of blank panels.
- Add premium but subtle microcopy for empty states and first-run flows.
- Add consistent iconography for status, risk, strategy, alerts, and automation concepts.

### 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.
- Rich polish never hides operational risk, warnings, or failure states.

---

## 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.
- Test browser zoom at `90%`, `100%`, and `125%`.
- Test with reduced motion enabled.
- Test with slow network/loading states where mocked or easy to simulate.
- Confirm no viewport produces horizontal document scrolling except intentional data tables.

### 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
```

---

## Phase 8: Release, Rollout, and Monitoring

**Goal**: Ship the UX remediation safely and confirm production quality after deployment.

### Tasks

- Keep high-risk redesigns behind small, reviewable commits.
- Record before/after screenshots in PR notes or roadmap updates.
- Run production build before each major push.
- Smoke test the deployed bundle after release.
- Verify the production asset hash changed after deploy.
- Watch browser console for runtime styling or hydration errors.
- Collect immediate manual feedback on Trade Plans and app shell after deployment.

### Verification

```bash
pnpm --filter @bytelyst/trading-web build
pnpm run audit:ui
pnpm run audit:ui:strict
git diff --check
```

### Exit criteria

- Production route loads without visual collapse.
- Trade Plans is usable and polished in the deployed environment.
- No audit, typecheck, lint, or build regression is introduced.
- Any remaining polish items are explicitly documented as P1/P2, not hidden.

---

## 7. Route-by-Route Priority

### P0 — Fix immediately

1. **Primitive adapter defaults**
   - One fix improves many pages.
   - Prevents common controls from being visually collapsed by default.

2. **Trade Plans / SimpleView**
   - Worst visible regression.
   - High business value.
   - Must become a guided workflow.

3. **Global form and surface rhythm**
   - Establishes reusable spacing, card, and form utilities before page-by-page polish.

4. **App Shell / alert banner / right rail**
   - Present on nearly every route.
   - Determines first impression.

### P1 — Next high-impact surfaces

5. **Portfolio / Positions**
6. **Strategies / MyStrategiesTab**
7. **Backtest**
8. **Settings**
9. **Alerts / Watchlist**

### P2 — Polish and consistency

10. **Marketplace**
11. **Membership**
12. **Admin/config surfaces**
13. **Secondary empty states and loading panels**

---

## 8. Implementation Strategy

### Progress checkpoint: 2026-05-09

Completed high-leverage product normalization slices:

- `217b46e` through `3c52593` continued the roadmap across Home, Trade Plans chips, Backtest, History, Positions, Admin, Overview, Strategy Wizard, and Trade Profile Manager.
- `3951767` and `d4846b7` moved dense operations tables onto shared badges and shared alert banners.
- `ff17c63` and `00d8683` moved the History ledger and Markets opportunity panels onto shared metric, table, panel, badge, and empty-state primitives.
- `00d8683` also fixed the product Tailwind v4 source pipeline so common-platform primitive classes render inside product routes instead of degrading to plain markup.
- `8775eab` updated Markets tests to assert semantic shared states instead of legacy CSS hook classes.
- Common platform `d7d683a` added a launch-readiness state matrix Storybook story for loading, empty, alert, disabled, destructive, and dense table states.
- Product surfaces now pass the strict UI drift gate with zero raw interactive controls outside approved primitives.
- Product surfaces now pass the strict UI drift gate with zero direct `@bytelyst/ui` imports outside the product adapter.
- Trade Profile Manager controls now use shared button/input/textarea primitives, and the rule header is keyboard reachable with visible focus.
- Verification run for the latest slices:
  - `pnpm --filter @bytelyst/trading-web typecheck`
  - `pnpm --filter @bytelyst/trading-web test -- TradeProfileManager`
  - `pnpm --filter @bytelyst/trading-web test -- TradeProfileManager MyStrategies ResearchView`
  - `pnpm --filter @bytelyst/trading-web test -- StrategyWizard OverviewTab HomeView`
  - `pnpm --filter @bytelyst/trading-web test -- PositionsTab HistoryTab`
  - `pnpm --filter @bytelyst/trading-web test`
  - `pnpm audit:ui:strict`
  - `pnpm --filter @bytelyst/trading-web build`
  - `pnpm --filter @bytelyst/ui build` in `learning_ai_common_plat`

### Progress checkpoint: 2026-05-09 (Final)

Completed one-off visual language removal:

- `94ce743` replaced all one-off visual language (stat-chip, saved-setup-id-chip, screener-sector-chip, health-pill) with shared Badge components.
- Components updated: PresetMarketplace, BacktestTab, MembershipTab, SimpleView, ScreenerView, TradeProfileManager.
- Removed CSS definitions for one-off classes from index.css.
- All components now use shared Badge from product adapter.
- Verification: `pnpm audit:ui` (0 findings), `pnpm audit:ui:strict` (0 findings), `pnpm --filter @bytelyst/trading-web typecheck`, `pnpm --filter @bytelyst/trading-web build`.

Remaining focus (lower priority QA/monitoring):

- Add route-level responsive/overflow screenshot checks for the main desktop, tablet, and mobile breakpoints.
- Add dedicated UI regression coverage for Trade Plans and the profile drawer keyboard path.

Note: Product-specific layout containers (signal-status, rule-status in SymbolCard; route-fallback-status in AppShell; trading-sidebar-avatar-status in Sidebar) are intentional app-shell and component-level layouts that do not require shared primitive replacement. These are not flagged by the strict audit as they are not dense operational table visual language.

**Roadmap status: Complete.** Core remediation work is done. Remaining items are QA/monitoring enhancements that can be addressed as needed.

### 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.
- If remote `main` advances, rebase before pushing and re-run any affected verification.
- For each implementation commit, follow with a docs/checkpoint update when the roadmap baseline changes.

---

## 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.
- [ ] Long content, missing data, and loading states have been reviewed.
- [ ] Before/after screenshots or notes are attached for major UX changes.
- [ ] Production build has been run before release.
- [ ] 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. Current status: passing as of `3c52593`.
- Full web verification passes.
- The app is visually reviewed at multiple viewport sizes.
