docs(ui): expand production ux remediation gaps

docs/PRODUCTION_GRADE_UX_REMEDIATION_ROADMAP.md

@@ -113,6 +113,37 @@ All production form controls must meet these minimums unless there is a specific
 - 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
@@ -165,6 +196,15 @@ Disallowed product CSS responsibilities:
 - 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
@@ -191,6 +231,8 @@ Disallowed product CSS responsibilities:
   - `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
 
@@ -208,6 +250,7 @@ git diff --check
 - 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.
 
 ---
 
@@ -236,6 +279,8 @@ web/src/components/ui/Primitives.tsx
 - 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
 
@@ -244,6 +289,7 @@ web/src/components/ui/Primitives.tsx
 - 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
 
@@ -279,6 +325,10 @@ web/src/App.css
   - `--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;
@@ -291,6 +341,8 @@ web/src/App.css
   - 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
 
@@ -298,6 +350,8 @@ web/src/App.css
 - 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
 
@@ -361,6 +415,10 @@ Trade Plans should feel like a guided professional workflow:
 - 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
 
@@ -370,6 +428,8 @@ Trade Plans should feel like a guided professional workflow:
 - 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
 
@@ -410,6 +470,9 @@ git diff --check
 - 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
 
@@ -417,6 +480,7 @@ git diff --check
 - 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
 
@@ -453,6 +517,9 @@ git diff --check
 - 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
 
@@ -460,6 +527,7 @@ git diff --check
 - 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
 
@@ -491,6 +559,9 @@ git diff --check
   - 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
 
@@ -505,6 +576,7 @@ git diff --check
 - 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.
 
 ---
 
@@ -527,6 +599,10 @@ git diff --check
 - 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
 
@@ -542,36 +618,72 @@ 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. **Trade Plans / SimpleView**
+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.
 
-2. **App Shell / alert banner / right rail**
+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.
 
-3. **Primitive adapter defaults**
-   - One fix improves many pages.
-
 ### P1 — Next high-impact surfaces
 
-4. **Portfolio / Positions**
+5. **Portfolio / Positions**
-5. **Strategies / MyStrategiesTab**
+6. **Strategies / MyStrategiesTab**
-6. **Backtest**
+7. **Backtest**
-7. **Settings**
+8. **Settings**
-8. **Alerts / Watchlist**
+9. **Alerts / Watchlist**
 
 ### P2 — Polish and consistency
 
-9. **Marketplace**
+10. **Marketplace**
-10. **Membership**
+11. **Membership**
-11. **Admin/config surfaces**
+12. **Admin/config surfaces**
-12. **Secondary empty states and loading panels**
+13. **Secondary empty states and loading panels**
 
 ---
 
@@ -597,6 +709,8 @@ git diff --check
 - 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.
 
 ---
 
@@ -612,6 +726,9 @@ A page is production-grade only when all of these are true:
 - [ ] 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.