# Launch-Ready UI/UX Roadmap

Last updated: 2026-05-08

## Purpose

This roadmap defines the path to make the trading web product feel modern, coherent, professional, and launch-ready across the entire app. It covers the product frontend in `learning_ai_invt_trdg` and the shared UI/design-system foundation in `learning_ai_common_plat`.

The goal is not another styling pass. The goal is a stable product-quality experience with reusable platform components that can be applied to this product and future ByteLyst products.

## Product Standard

The target experience is a polished operational SaaS console for trading workflows:

- Calm, readable, premium, and practical.
- Dense enough for portfolio/trading operations without feeling cramped.
- Consistent component behavior across all routes.
- Clear primary actions and obvious next steps.
- Strong loading, empty, error, disabled, and success states.
- Responsive across desktop, tablet, and phone without broken menus, overflow, or hidden content.
- Accessible by keyboard and readable under normal contrast settings.

## Current State Summary

The app is functional, but launch readiness is blocked by inconsistent UI systems:

- The shared platform primitives exist, but many product screens still use raw page-specific styling.
- `web/src/index.css` and `web/src/App.css` carry too much global/product-specific behavior.
- Complex screens such as Trade Plans, Portfolio, Backtesting, Settings/Admin, Visual Builder, and Code Editor still contain legacy visual patterns.
- Tables, cards, badges, timeline steps, forms, tabs, alerts, and empty states do not yet fully share one design language.
- Some routes look modern after recent improvements, while deeper states still look like developer tooling.
- Responsive behavior has improved, but the shell still needs a formal contract for desktop/tablet/phone.
- Global overlays such as critical alerts and the assistant widget need collision rules.

## Guiding Principles

1. Centralize primitives in common platform.
2. Compose product screens from approved primitives.
3. Prefer quiet utility over decorative UI.
4. Keep cards for bounded tools/items, not every page section.
5. Use semantic colors only for meaning: success, warning, danger, info.
6. Use monospace only for symbols, prices, IDs, and technical values.
7. Avoid raw HTML controls in product screens unless wrapped by a shared primitive.
8. Every user-facing state needs loading, empty, error, disabled, and success treatment.
9. Every route must pass responsive, accessibility, and overflow checks before launch.

## Phase 0: Stop UI Drift

Objective: prevent new inconsistent UI while remediation is underway.

Scope:

- Expand `pnpm audit:ui` to flag:
  - raw `<button>`, `<input>`, `<select>`, `<textarea>` in production components
  - inline `style` usage outside approved exceptions
  - legacy dark classes such as `bg-black`, `bg-zinc`, `text-gray`, `border-white`
  - arbitrary `rounded-*`, `tracking-*`, and one-off uppercase styling in product components
  - direct `@bytelyst/ui` imports outside the product adapter
- Quarantine legacy global styles in `App.css`.
- Create a migration issue list from audit output.
- Require new UI work to use common/product primitives.

Acceptance criteria:

- Audit runs locally and in CI.
- New raw controls and legacy surface classes fail the audit.
- Known legacy exceptions are documented and temporary.

## Phase 1: Platform Design System Foundation

Objective: make `learning_ai_common_plat` the real source of reusable UI quality.

Common platform components to standardize or add:

- `AppShell`: navigation, topbar, alert region, right panel slot, responsive contract.
- `PageHeader`: title, subtitle, actions, breadcrumbs, compact mode.
- `Section`: consistent section spacing, header, actions, description.
- `Toolbar`: compact action groups.
- `FilterBar`: search, selects, chips, refresh, and responsive wrapping.
- `DataTable`: sticky header, density modes, row actions, loading, empty, error, horizontal scroll.
- `EntityCard`: reusable card pattern for saved setups, watchlist entries, strategy profiles, and presets.
- `FormSection`: sectioned form layout with labels, hints, errors, disabled/read-only states.
- `FieldGrid`: responsive field layout.
- `StatusBadge`: semantic states with consistent icon/color/label behavior.
- `Timeline`: compact and detailed variants.
- `AlertBanner`: inline page alerts and global critical alerts.
- `Toast`: success/error/status feedback.
- `ConfirmDialog`: destructive action confirmation.
- `Skeleton`: route, card, table, and form skeleton variants.
- `EmptyState`: title, body, action, icon, compact/full variants.

Token work:

- Finalize light theme tokens.
- Normalize dark theme tokens after light theme is stable.
- Define component-level radius, shadow, border, spacing, and typography tokens.
- Add token documentation in Storybook.

Acceptance criteria:

- Common UI Storybook demonstrates every primitive with light and dark examples.
- Product adapter maps common primitives to the trading app without duplicating logic.
- At least 80 percent of product UI composition uses shared primitives or product adapters.

## Phase 2: Product Shell And Global UX

Objective: make the app frame stable and professional everywhere.

Scope:

- Replace product-local shell with platform `AppShell` or align it to the same contract.
- Desktop: full left rail or compact left rail depending on width.
- Tablet: compact left rail, no footer nav.
- Phone: bottom nav only.
- Right panel: desktop only, collapsible later if needed.
- Critical alert: inline/sticky shell region, never covering form controls or cards.
- Assistant widget: collision-safe offset and route-aware placement.
- Route fallback: page-shaped skeleton instead of blank loading.
- Global overflow policy: no route can widen the viewport accidentally.
- Theme default: stable light mode; dark mode as a tested secondary mode.

Acceptance criteria:

- No route has horizontal page overflow at 390, 768, 1024, 1440 px.
- Nav never appears as a broken full-page vertical menu.
- Critical alerts and assistant controls do not cover primary actions.

## Phase 3: Core Trading Screen Rebuild

Objective: polish the highest-value product workflows first.

### 3.1 Trade Plans

Current issues:

- Complex form sections still feel dense.
- Saved setup cards were improved but should become a first-class `EntityCard`.
- Metadata and runtime state need better hierarchy.
- Timeline should be a shared component.

Work:

- Convert create/edit flow into a guided plan builder.
- Use `FormSection`, `FieldGrid`, `StatusBadge`, `Timeline`, and `EntityCard`.
- Add saved setup filters: active, waiting, filled, closed, needs attention.
- Add success toast after save/update/delete.
- Add confirm dialog for delete.
- Add compact card view and detail drawer for advanced runtime/event history.

Acceptance criteria:

- A new user can create or review a plan without reading dense operational text.
- Saved setup cards fit comfortably on tablet and desktop.
- Delete/edit/manage actions are clear and not visually dominant.

### 3.2 Portfolio

Current issues:

- `PositionsTab` is large, table-heavy, and still carries legacy dark utility styles.
- Diagnostic/status messages can force overflow.
- Mobile/tablet experience needs a card alternative.

Work:

- Rebuild positions and order activity with common `DataTable`.
- Use compact `AlertBanner` for lifecycle/fallback warnings.
- Create responsive card view below tablet width.
- Replace raw profile filter with `SegmentedControl`.
- Add table skeleton, empty, error, and retry states.
- Add row-level action menus for plan management.

Acceptance criteria:

- No warning or trade ID can break layout.
- Position/order data scans cleanly.
- The page remains usable with many rows and long identifiers.

### 3.3 Research

Current issues:

- Strategies tab looks better, but builder/editor/backtest surfaces use different visual systems.
- Backtest components are still dark/zinc styled.

Work:

- Normalize research tabs with shared `Tabs`.
- Convert strategy cards to `EntityCard`.
- Convert Visual Builder forms to `FormSection` and common controls.
- Convert Code Editor shell to a polished tool panel.
- Rebuild Backtest panels with common cards, tables, metric cards, charts, and alerts.

Acceptance criteria:

- Strategies, Visual Builder, Code Editor, Signals, and Backtesting feel like one product.
- Backtest UI no longer looks like a separate app.

### 3.4 Screener

Current issues:

- Filter layout has improved but needs a final `FilterBar`.
- Table states should use shared `DataTable`.

Work:

- Move filters to `FilterBar`.
- Convert results to `DataTable`.
- Add query count, active filter chips, reset filters.
- Improve API error copy and retry.
- Add row action affordance for opening chart/research.

Acceptance criteria:

- Filters are readable on tablet.
- Result table has consistent empty/loading/error behavior.

### 3.5 Watchlist

Current issues:

- Empty state is improved, but entries should use reusable cards.
- Add/edit flow should feel like a proper modal or side panel.

Work:

- Convert entry cards to `EntityCard`.
- Move add/edit into a modal or drawer.
- Add toasts for create/update/delete/clone.
- Add confirmation for delete.
- Add filter counts.

Acceptance criteria:

- Empty and populated states both look complete.
- Entry management feels safe and predictable.

## Phase 4: Secondary And Admin Surfaces

Objective: remove remaining developer-tool styling from lower-frequency screens.

Scope:

- Settings account page.
- Bot Config.
- Admin Panel.
- Alerts.
- Markets and Marketplace.
- Login, reset password, auth error states.
- Right panel portfolio/news.
- Chat assistant panel and floating button.

Work:

- Convert Settings/Admin/Config to `FormSection`, `DataTable`, `AlertBanner`, and `ConfirmDialog`.
- Add real Alerts filters by severity/type/symbol.
- Convert Markets/Marketplace to common cards and skeletons.
- Improve right panel empty states and links.
- Ensure login/reset flows use common auth UI from platform where possible.

Acceptance criteria:

- No screen looks like raw admin tooling.
- Low-frequency screens are safe, clear, and consistent.

## Phase 5: Interaction And Feedback Quality

Objective: make the app feel trustworthy under real usage.

Add consistently:

- Toasts for create, update, delete, clone, save, refresh.
- Confirmation dialogs for destructive actions.
- Inline validation for all forms.
- Disabled-state explanations.
- Retry affordances for network errors.
- Skeletons that match final layout.
- Empty states with useful next action.
- Success states that confirm what changed.
- Optimistic or pending states where appropriate.

Acceptance criteria:

- A user never wonders whether an action worked.
- Failed network/API states are recoverable.
- Destructive actions are protected.

## Phase 6: Accessibility And Responsive QA

Objective: launch with confidence across device sizes and input modes.

Checks:

- Keyboard-only navigation.
- Visible focus states.
- ARIA labels for icon buttons.
- Form labels and errors.
- Color contrast for text, badges, and disabled states.
- Reduced motion behavior.
- Screen-reader-friendly empty/loading/error states.
- No text clipping in buttons, cards, tabs, or chips.
- No horizontal viewport overflow.

Viewport matrix:

- 390 px phone.
- 768 px tablet.
- 1024 px small desktop/tablet landscape.
- 1440 px desktop.
- 1728 px wide desktop.

Acceptance criteria:

- Every route passes visual QA at all target widths.
- Every primary workflow works with keyboard navigation.

## Phase 7: Visual Regression And CI Gates

Objective: keep the app launch-ready after the cleanup.

Tests and automation:

- Playwright route screenshot suite.
- Axe accessibility scan.
- Horizontal overflow test.
- Component smoke tests for common primitives.
- Storybook snapshots for shared UI.
- CI audit for raw controls, inline styles, and legacy classes.
- Route-level tests for empty/loading/error states.

Acceptance criteria:

- CI blocks UI drift.
- Screenshots make regressions obvious.
- Design system changes can be safely adopted by other products.

## Suggested Implementation Sequence

### PR 1: Foundation And Guardrails

- Expand UI drift audit.
- Introduce missing common primitives.
- Move product shell toward common shell contract.
- Add Storybook coverage for primitives.

### PR 2: Core Screen Rebuild

- Trade Plans.
- Portfolio.
- Watchlist.
- Screener.

### PR 3: Research And Backtesting

- Research tab shell.
- Visual Builder.
- Code Editor.
- Backtest configuration/results.

### PR 4: Settings, Admin, Markets, Alerts

- Settings and Bot Config.
- Admin Panel.
- Markets and Marketplace.
- Alerts.
- Right panel.

### PR 5: Launch QA

- Visual regression.
- Accessibility pass.
- Responsive pass.
- Final polish and copy pass.

## Product Launch Readiness Checklist

- [ ] Shared primitives cover app shell, page header, sections, cards, forms, tables, tabs, badges, timelines, alerts, toasts, modals, skeletons, and empty states.
- [ ] No production route uses raw controls outside approved wrappers.
- [ ] No production route has accidental horizontal overflow.
- [ ] Critical alerts never cover primary content.
- [ ] Assistant widget never covers primary actions.
- [ ] All destructive actions require confirmation.
- [ ] All saves/deletes/updates produce feedback.
- [ ] All pages have loading, empty, error, and success states.
- [ ] All pages pass keyboard navigation checks.
- [ ] All routes are visually checked at phone, tablet, desktop, and wide desktop widths.
- [ ] UI screenshots are captured in CI.
- [ ] Common platform UI can be reused by another product without trading-specific assumptions.

## Immediate Next Recommendation

Start with PR 1 and PR 2 together as the next focused milestone:

1. Harden the shared design system and audit gates.
2. Rebuild Trade Plans and Portfolio using those primitives.

These two screens carry the most product credibility risk. Once they are polished, the rest of the app can converge around the same patterns faster and with less rework.