From 9cfaca740f53aac27a911563f09cdcb607db38c3 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Thu, 7 May 2026 01:54:13 -0700 Subject: [PATCH] docs(ui): expand production ux remediation gaps --- ...PRODUCTION_GRADE_UX_REMEDIATION_ROADMAP.md | 145 ++++++++++++++++-- 1 file changed, 131 insertions(+), 14 deletions(-) diff --git a/docs/PRODUCTION_GRADE_UX_REMEDIATION_ROADMAP.md b/docs/PRODUCTION_GRADE_UX_REMEDIATION_ROADMAP.md index c2f7304..d9db47c 100644 --- a/docs/PRODUCTION_GRADE_UX_REMEDIATION_ROADMAP.md +++ b/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. **Strategies / MyStrategiesTab** -6. **Backtest** -7. **Settings** -8. **Alerts / Watchlist** +5. **Portfolio / Positions** +6. **Strategies / MyStrategiesTab** +7. **Backtest** +8. **Settings** +9. **Alerts / Watchlist** ### P2 — Polish and consistency -9. **Marketplace** -10. **Membership** -11. **Admin/config surfaces** -12. **Secondary empty states and loading panels** +10. **Marketplace** +11. **Membership** +12. **Admin/config surfaces** +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.