# Launch-Ready UI/UX Roadmap

Last updated: 2026-05-08

## Purpose

This roadmap defines the concrete path to make the trading product launch-ready from a UI, UX, accessibility, and platform-reuse perspective. It covers two repositories that must move together:

- Product repo: `/Users/saravana/BytelystAI/learning_ai/learning_ai_invt_trdg`
- Shared platform repo: `/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat`

The goal is not a styling pass. The goal is a durable product system:

- The trading app should feel like a polished operational SaaS console.
- Shared UI quality should live in common platform, not in product-only CSS.
- Local development and production builds should resolve ByteLyst packages predictably without depending on Gitea package auth.
- Future ByteLyst products should be able to reuse the same primitives without inheriting trading-specific assumptions.

## Current Evidence

This roadmap is based on a review of the current product and common-platform source trees.

Product frontend facts:

- Main app entry: `web/src/App.tsx`, `web/src/main.tsx`
- Shell: `web/src/components/layout/AppShell.tsx`, `Header.tsx`, `Sidebar.tsx`, `RightPanel.tsx`
- Product UI adapter: `web/src/components/ui/Primitives.tsx`
- Global style surface: `web/src/index.css`, `web/src/App.css`
- Major views: `HomeView`, `PortfolioView`, `ResearchView`, `SimpleView`/Trade Plans, `MarketsView`, `ScreenerView`, `WatchlistView`, `AlertsView`, `SettingsView`
- Major tabs/components: `PositionsTab`, `EntriesTab`, `BacktestTab`, `AdminTab`, `ConfigTab`, `MarketplaceTab`, strategy builder/editor components, auth/reset components, chat assistant components
- Current package resolution uses local file references and pnpm hooks for ByteLyst packages.
- `pnpm audit:ui` currently reports zero findings for raw controls, legacy classes, hardcoded colors, and direct common UI imports outside the product adapter.

Common platform facts:

- Shared UI package exists at `packages/ui`
- Shared tokens exist at `packages/design-tokens`
- Shared auth UI exists at `packages/auth-ui`
- Dashboard shell exists at `packages/dashboard-shell`
- Useful common UI primitives already exist: `AppShell`, `Button`, `IconButton`, `Card`, `Panel`, `Surface`, `Field`, `Input`, `Textarea`, `Select`, `Tabs`, `SegmentedControl`, `Badge`, `StatusBadge`, `Timeline`, `DataTable`, `DataList`, `EmptyState`, `Toast`, `Modal`, `ConfirmDialog`, `DropdownMenu`, `Tooltip`, `Skeleton`/loading helpers
- Common platform still contains many `publishConfig.registry` references to the Gitea npm registry and a release script tied to Gitea naming. This conflicts with the desired local-package-first development model.

## Product Standard

The target experience is a calm, modern, professional trading operations console:

- Clean, contemporary SaaS UI with strong hierarchy and restrained visual treatment.
- Dense enough for trading workflows, but never cramped or visually noisy.
- Consistent navigation, page headers, tabs, forms, tables, cards, badges, alerts, dialogs, empty states, and loading states.
- Clear primary actions and obvious next steps.
- Predictable behavior under loading, empty, error, disabled, pending, success, and destructive-action states.
- Responsive layouts across phone, tablet, desktop, and wide desktop.
- Accessible by keyboard and screen readers, with visible focus and readable contrast.
- No global overlays covering primary content or form controls.

## Non-Negotiables

- Shared primitives come from `learning_ai_common_plat`.
- Product-specific styling goes through the product adapter in `web/src/components/ui/Primitives.tsx`.
- Product routes should not import `@bytelyst/ui` directly except through the adapter layer.
- Product routes should not use raw `<button>`, `<input>`, `<select>`, or `<textarea>` outside approved primitives.
- Product routes should not use one-off hardcoded colors.
- ByteLyst package resolution must work locally from sibling repos without a Gitea token.
- Every page must have a documented loading, empty, error, and success or saved state.
- Every destructive action must use confirmation.
- Every create/update/delete action must produce visible feedback.
- Every route must pass responsive overflow checks.

## Design Direction

Use a practical light-first SaaS console direction:

- White or near-white canvas with subtle elevated surfaces.
- Navy/slate text for clarity, blue for primary action, green for success, amber for warning, red for danger.
- Compact spacing scale for operational density, with enough air around forms and cards.
- 8px or smaller card radius unless a shared primitive intentionally defines otherwise.
- Tables for high-density comparison on desktop; cards or data lists for tablet/phone.
- Badges and status chips only for meaningful state, not decoration.
- Icons in buttons where they clarify action, using shared icon-button patterns.
- No decorative gradient-orb backgrounds or marketing-style hero layouts.

## Cipher Reference Standard

Reference: `https://www.usecipher.dev/` and `https://github.com/atom63/cipher-boilerplate`

Cipher is useful as a production-quality reference because it demonstrates a complete design-to-code operating model, not just an attractive page. The parts worth adopting are:

- Token structure that keeps design decisions and code implementation aligned.
- Clear token layers: primitives, aliases, semantics, typography, and effects.
- Modern CSS variable output that can support Tailwind v4 and shadcn/ui-style component APIs.
- A component preview surface that shows real controls, forms, buttons, checkboxes, sliders, loading states, empty states, and dense UI examples.
- Strong visual rhythm: intentional spacing, confident typography, refined borders, clear focus/interaction states, and controlled contrast.
- Production-grade component states: loading, disabled, active, selected, checked, empty, pending, and destructive states all feel designed.
- Design system portability: the system is easy to clone, customize, and reuse because the tokens and components are structured.

What to borrow:

- The token philosophy and layer naming discipline.
- The preview/demo culture: every primitive should be shown in realistic combinations, not only as isolated atoms.
- The shadcn-style API ergonomics where it fits our stack: composable, predictable, accessible primitives backed by CSS variables.
- The polished interaction standard: controls should have obvious hover, focus, active, selected, disabled, loading, and error states.
- The production-ready feel: pages should look intentionally designed even when data is empty, loading, or failing.

What not to copy directly:

- Cipher is a landing/demo site; the trading product is an operational SaaS console.
- Cipher's dark, high-contrast visual expression should not become the default trading product theme.
- Decorative background treatment should not replace our need for clear data density and workflow clarity.
- The trading app should use Cipher as a quality bar, not as a visual skin.

Cipher-inspired acceptance bar:

- A product page should look launch-ready in populated, empty, loading, and error states.
- A component should not be considered done until it has Storybook/preview coverage with realistic content.
- Token changes should be traceable from common-platform source tokens to generated CSS to product usage.
- The trading UI should feel as deliberate as the Cipher preview, but optimized for trading operations rather than marketing.

## Architecture Direction

The platform/product split should be explicit:

- `@bytelyst/design-tokens`: owns token values and generated CSS.
- `@bytelyst/ui`: owns reusable primitives and component-level behavior.
- `@bytelyst/auth-ui`: owns login, reset, MFA, onboarding, and auth feedback surfaces.
- `@bytelyst/dashboard-shell`: either becomes the shared shell package or is merged into `@bytelyst/ui` shell primitives.
- `learning_ai_invt_trdg/web/src/components/ui/Primitives.tsx`: owns trading-specific adapter names, status mappings, and limited product variants.
- Product views/tabs: compose primitives and contain workflow logic only.

Avoid duplicating platform primitives inside product CSS. If two screens need the same pattern, it belongs in common platform or in the product adapter.

## Package Source And Local Dependency Roadmap

Objective: permanently remove day-to-day dependence on Gitea npm tokens for local development and product builds.

Current state:

- Product dependencies already point to local packages with `file:` specifiers.
- Product `.pnpmfile.cjs` rewrites `@bytelyst/*` package sources toward the sibling common-platform repo by default.
- Product `.npmrc` enables workspace preference.
- Common platform still contains many Gitea `publishConfig.registry` values and a Gitea-named release script.

Required work:

- Standardize on one local package root: `/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat` for local developer machines, with `BYTELYST_COMMON_PLAT_ROOT` as an override for nonstandard setups.
- Document the expected sibling repo layout in both repos.
- Remove `GITEA_NPM_TOKEN` from local install requirements.
- Replace Gitea-specific release naming with neutral package-release naming.
- Decide whether `publishConfig.registry` should be removed from common packages or isolated to a publish-only configuration that does not affect installs.
- Add a repo health check that fails when local package paths are missing and gives a clear fix.
- Add a CI mode that verifies local file/package linking without requiring private registry auth.

Acceptance criteria:

- Fresh product install works with only the product repo and sibling common-platform repo.
- `pnpm install` does not require `GITEA_NPM_TOKEN`.
- `pnpm --filter @bytelyst/trading-web build` resolves `@bytelyst/*` from local common-platform packages.
- Common-platform package metadata no longer surprises local product installs with private registry assumptions.

## Phase 0: Freeze UI Drift

Objective: prevent new inconsistent UI while the deeper redesign continues.

Current status:

- `pnpm audit:ui` exists and currently reports zero findings.
- It checks raw interactive controls, legacy product classes, hardcoded color literals, and direct `@bytelyst/ui` imports outside the adapter.

Next improvements:

- Add strict CI usage with `pnpm audit:ui:strict`.
- Expand the audit to catch:
  - inline `style` outside documented exceptions
  - arbitrary Tailwind color classes in product screens
  - arbitrary radius and tracking classes in product screens
  - page-level CSS selectors that duplicate common primitive behavior
  - unapproved direct imports from common packages
  - unsupported z-index values that can break global overlays
- Maintain a small allowlist file with owner, reason, and removal date for temporary exceptions.

Acceptance criteria:

- UI drift audit runs locally and in CI.
- New raw controls and legacy styles fail the audit.
- Exceptions are explicit, temporary, and owned.

## Phase 1: Common Platform Foundation

Objective: make `learning_ai_common_plat` strong enough that product teams do not rebuild primitives locally.

### 1.1 Tokens

Required work:

- Finalize light theme tokens for canvas, surfaces, borders, text, muted text, focus rings, primary action, danger, warning, success, and info.
- Organize token layers in a Cipher-inspired model:
  - primitives for raw color/spacing/type/effect scales
  - aliases for product-neutral named choices
  - semantics for UI meaning such as surface, border, text, danger, warning, success, focus
  - typography for role-based text styles
  - effects for shadows, rings, overlays, and motion
- Normalize radius tokens for controls, cards, dialogs, and pills.
- Normalize spacing tokens for page, section, card, form, table, and toolbar density.
- Normalize typography tokens for page titles, section titles, body copy, labels, captions, numbers, and code/monospace values.
- Add motion tokens for duration/easing so hover, focus, drawer, dialog, toast, and skeleton transitions are consistent.
- Document semantic token usage in `packages/design-tokens/README.md`.
- Generate CSS and platform-specific token outputs through scripts only.

Acceptance criteria:

- No product page needs hardcoded colors for normal UI.
- Token names express purpose, not visual guesses.
- Token generation is documented and repeatable.
- Tokens can be reviewed as a design artifact before product pages consume them.

### 1.2 Core Primitives

Keep and harden:

- `AppShell`
- `Button`
- `IconButton`
- `Card`
- `Panel`
- `Surface`
- `Field`
- `Input`
- `Textarea`
- `Select`
- `Tabs`
- `SegmentedControl`
- `Badge`
- `StatusBadge`
- `Timeline`
- `DataTable`
- `DataList`
- `EmptyState`
- `Toast`
- `Modal`
- `ConfirmDialog`
- `DropdownMenu`
- `Tooltip`

Add or extend:

- `PageHeader`: title, subtitle, actions, breadcrumbs, status, compact mode.
- `Section`: consistent section header/body/action layout.
- `Toolbar`: compact action groups and route-level command bars.
- `FilterBar`: search, selects, chips, reset, refresh, responsive wrapping.
- `FormSection`: grouped fields with description and validation summary.
- `FieldGrid`: responsive form layout.
- `AlertBanner`: inline alerts and global critical alerts.
- `Skeleton`: route, card, table, stat, form, and detail variants.
- `EntityCard`: reusable object card for plans, strategies, watchlist entries, marketplace items, and saved presets.
- `MetricCard`: stat card optimized for trading/portfolio metrics.
- `ActionMenu`: row/card action menu for edit, clone, delete, open, convert, retry.
- `Drawer`: detail and edit side panel for dense workflows.

Acceptance criteria:

- Every primitive has typed props, keyboard-safe behavior, and accessible labels where needed.
- Storybook demonstrates common states: default, hover, focus, disabled, loading, empty, error, destructive, compact.
- Product screens can compose all common trading workflow shapes without custom raw controls.

### 1.3 Platform Storybook And Docs

Required work:

- Add Storybook stories for all common primitives.
- Add a Cipher-style UI preview page inside common platform that shows the primitives working together in realistic product compositions.
- Add operational workflow examples:
  - dense table with actions
  - card list with statuses
  - settings form
  - critical alert
  - confirm delete
  - loading and empty states
  - mobile shell
- Add accessibility addon coverage and keyboard notes.

Acceptance criteria:

- Designers and developers can inspect component states without launching the trading product.
- Storybook becomes the source of truth for shared component behavior.
- Storybook includes enough realistic examples to judge whether the system feels production-grade.
- Common platform can demonstrate a full operational screen composition using only shared primitives.

## Phase 2: Product Adapter And Shell

Objective: make the app frame stable, responsive, and reusable.

### 2.1 Product Adapter

Required work:

- Keep `web/src/components/ui/Primitives.tsx` as the only direct bridge to `@bytelyst/ui`.
- Add trading-specific exports there:
  - `PageHeader`
  - `Section`
  - `Toolbar`
  - `FilterBar`
  - `FormSection`
  - `FieldGrid`
  - `StatusBadge`
  - `Timeline`
  - `EntityCard`
  - `MetricCard`
  - `DataTable`
  - `DataList`
  - `AlertBanner`
  - `ToastProvider`
  - `ConfirmDialog`
  - `Drawer`
  - `ActionMenu`
- Keep trading-only status mapping in the adapter, not scattered across views.

Acceptance criteria:

- Product pages import UI primitives from one adapter.
- Common package changes can be absorbed in one place.

### 2.2 Shell Contract

Required behavior:

- Desktop: persistent left rail, top header, optional right insight panel.
- Tablet: compact left rail or drawer, no broken footer nav.
- Phone: bottom navigation only, with route content taking priority.
- Right panel: hidden or drawer-based below desktop width.
- Critical alert: shell-owned region that never covers forms, cards, or primary actions.
- Assistant widget: route-aware and collision-safe.
- Route loading: page-shaped skeleton, not blank content.
- Not found: useful route recovery.
- Global overflow: no route can widen the viewport.

Known issue to prevent:

- The sidebar must never render as a full-page vertical menu on tablet/mobile.
- Bottom nav must never appear on desktop/tablet widths.

Acceptance criteria:

- Viewports 390, 768, 1024, 1440, and 1728 px render without horizontal overflow.
- Header, sidebar, right panel, critical alert, assistant widget, and route content do not overlap.
- Keyboard focus can move from skip link to nav to main content to right panel predictably.

## Phase 3: Core Product Workflows

Objective: polish the highest-value screens first.

### 3.1 Trade Plans

Files to review/refactor:

- `web/src/views/SimpleView.tsx`
- `web/src/tabs/EntriesTab.tsx`
- `web/src/components/EntryForm.tsx`
- `web/src/views/tradePlansState.ts`
- `web/src/views/tradePlansRoutes.ts`
- related tests

Current risks:

- The workflow is valuable but still visually dense.
- Plan cards, lifecycle steps, status metadata, and next-action copy need stronger hierarchy.
- Saved setup actions can dominate content.
- Mobile/tablet layout must stay clean under long symbols, trade IDs, and lifecycle states.

Required work:

- Rebuild create/edit as a guided plan builder with sections:
  - Symbol and setup type
  - Price source
  - Sizing
  - Trigger
  - Exit rules
  - Risk notes
  - Review and save
- Use `FormSection`, `FieldGrid`, `AlertBanner`, `StatusBadge`, `Timeline`, `EntityCard`, `ConfirmDialog`, and `Toast`.
- Add saved setup filters: active, waiting, filled, closed, needs attention.
- Move advanced runtime details into a collapsible area or drawer.
- Use compact action menus for secondary actions.
- Add delete confirmation and success/error toast feedback.

Acceptance criteria:

- A user can understand the next step on the page in under five seconds.
- Cards do not overflow with long trade IDs.
- Edit/delete/clone/manage actions are clear but not visually overpowering.
- Empty, loading, error, pending, saved, and deleted states are covered.

### 3.2 Portfolio

Files to review/refactor:

- `web/src/views/PortfolioView.tsx`
- `web/src/tabs/PositionsTab.tsx`
- `web/src/tabs/HistoryTab.tsx`
- `web/src/tabs/ReconciliationAuditPanel.tsx`

Current risks:

- Position and order tables are dense and can break under long identifiers.
- Diagnostic messages can feel like developer output.
- Mobile/tablet needs a card/list alternative.

Required work:

- Rebuild positions and order activity around shared `DataTable` and `DataList`.
- Add responsive card view below tablet width.
- Use `SegmentedControl` for profile filters.
- Use `AlertBanner` for lifecycle and reconciliation warnings.
- Use row/card `ActionMenu` for open plan, create exit plan, square off, reconcile.
- Add skeletons, empty state, API error state, and retry behavior.

Acceptance criteria:

- Position/order data is scannable at desktop density.
- No warning, trade ID, sub-tag, or source label breaks layout.
- Mobile users can inspect positions without horizontal table wrestling.

### 3.3 Research And Strategy Builder

Files to review/refactor:

- `web/src/views/ResearchView.tsx`
- `web/src/tabs/MyStrategiesTab.tsx`
- `web/src/components/strategy/VisualRuleBuilder.tsx`
- `web/src/components/strategy/CodeStrategyEditor.tsx`
- `web/src/tabs/SignalsTab.tsx`
- `web/src/tabs/BacktestTab.tsx`
- `web/src/backtest/components/*`

Current risks:

- Strategies, visual builder, code editor, signals, and backtesting do not yet feel like one cohesive product.
- Backtesting and editor surfaces can look like separate developer tools.

Required work:

- Normalize all research tabs with shared `Tabs` and `PageHeader`.
- Convert strategy cards to `EntityCard`.
- Convert visual builder forms to `FormSection`, `FieldGrid`, and common controls.
- Put code editor inside a polished tool panel with toolbar actions, run state, errors, and save feedback.
- Rebuild backtest configuration/results with `Panel`, `MetricCard`, `DataTable`, charts, skeletons, and error banners.

Acceptance criteria:

- Research feels like an integrated strategy workspace.
- Backtest output is credible enough for a customer demo.
- Builder/editor transitions are predictable and preserve user work.

### 3.4 Screener

Files to review/refactor:

- `web/src/views/ScreenerView.tsx`
- market API helpers used by screener

Current risks:

- Filter layout improved but should become a reusable `FilterBar`.
- API failure states need better copy and recovery.

Required work:

- Move filters to `FilterBar`.
- Convert results to shared `DataTable`.
- Add active filter chips, result count, reset filters, refresh, and retry.
- Add row action for opening chart/research/watchlist.
- Add table skeleton and complete empty/error states.

Acceptance criteria:

- Filters remain readable on tablet and phone.
- API failures are clear, calm, and recoverable.
- Results table matches portfolio table behavior.

### 3.5 Watchlist

Files to review/refactor:

- `web/src/views/WatchlistView.tsx`
- `web/src/tabs/EntriesTab.tsx` if shared with manual entries
- manual entry API helpers

Current risks:

- Empty state is improved, but populated management needs the same polish.
- Add/edit should not feel like raw form work.

Required work:

- Convert entries to `EntityCard` or `DataList`.
- Move add/edit into `Modal` or `Drawer`.
- Add filters/counts.
- Add create/update/delete/clone toasts.
- Add delete confirmation.

Acceptance criteria:

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

## Phase 4: Secondary And Admin Workflows

Objective: remove remaining lower-frequency rough edges.

### 4.1 Settings And Bot Config

Files:

- `web/src/views/SettingsView.tsx`
- `web/src/tabs/SettingsTab.tsx`
- `web/src/tabs/ConfigTab.tsx`
- `web/src/components/GlobalConfigManager.tsx`

Required work:

- Use `FormSection`, `FieldGrid`, `AlertBanner`, and validation summary.
- Separate account details, API keys, trading runtime, bot config, and admin access.
- Add save feedback and disabled-state explanations.
- Mask secrets and provide copy/rotate affordances where relevant.

Acceptance criteria:

- Settings feels safe and production-grade, not like a raw config panel.

### 4.2 Admin

Files:

- `web/src/tabs/AdminTab.tsx`

Required work:

- Use shared tables/cards for users, roles, critical issues, jobs, and diagnostics.
- Treat dangerous actions with `ConfirmDialog`.
- Add audit-friendly copy for admin changes.

Acceptance criteria:

- Admin actions are clear, reversible where possible, and protected when destructive.

### 4.3 Alerts

Files:

- `web/src/views/AlertsView.tsx`
- `web/src/components/AlertFeed.tsx`

Required work:

- Add severity/type/symbol filters.
- Use `AlertBanner` for page-level alerts and `DataList` for alert feed items.
- Add read/unread, retry, and empty states.

Acceptance criteria:

- Alerts are actionable and scannable, not just a log stream.

### 4.4 Markets And Marketplace

Files:

- `web/src/views/MarketsView.tsx`
- `web/src/tabs/MarketplaceTab.tsx`
- `web/src/components/MarketOpportunities.tsx`
- `web/src/components/PresetMarketplace.tsx`
- `web/src/components/SymbolCard.tsx`

Required work:

- Normalize market cards, opportunity lists, and marketplace items with `EntityCard`, `MetricCard`, and `DataTable`.
- Add skeletons and API error states.
- Ensure cards do not become oversized marketing blocks.

Acceptance criteria:

- Markets feel operational and useful, not decorative.

### 4.5 Auth And Reset Password

Files:

- `web/src/components/Login.tsx`
- `web/src/components/ResetPassword.tsx`
- `web/src/components/AuthContext.tsx`

Required work:

- Reuse `@bytelyst/auth-ui` where possible.
- Ensure local development can point to production API host when explicitly configured.
- Add clear auth error messages, loading state, reset flow, and disabled state.

Acceptance criteria:

- Login works against configured API environments.
- Auth UI matches the rest of the product.

### 4.6 Chat Assistant And Right Panel

Files:

- `web/src/components/ChatControl.tsx`
- `web/src/components/layout/RightPanel.tsx`

Required work:

- Define collision rules with bottom nav, alerts, and primary page actions.
- Use common card/list/empty-state primitives for right panel portfolio/news.
- Make assistant open/closed state accessible.

Acceptance criteria:

- Assistant and right panel help the product instead of covering it.

## Phase 5: Interaction Quality

Objective: make the product trustworthy during real use.

Required patterns:

- Toast for create/update/delete/clone/save/refresh/import/export.
- Confirm dialog for destructive actions.
- Inline field errors with accessible descriptions.
- Top-of-form validation summary for long forms.
- Pending state for slow actions.
- Disabled state explanation for blocked actions.
- Retry affordance for network/API failures.
- Optimistic update only where rollback is safe.
- Copy that says what happened and what to do next.

Acceptance criteria:

- Users never wonder whether an action worked.
- Failed actions are recoverable.
- Dangerous actions are protected.

## Phase 6: Accessibility And Responsive QA

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

Viewport matrix:

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

Accessibility checks:

- Keyboard-only navigation.
- Visible focus states.
- Skip link.
- ARIA labels for icon buttons.
- Semantic headings in order.
- Form labels, descriptions, and errors.
- Dialog focus trap and return focus.
- Color contrast for text, chips, badges, disabled states, and warnings.
- Reduced motion.
- Screen-reader-friendly loading, empty, and error states.

Responsive checks:

- No horizontal viewport overflow.
- No clipped button text.
- No overlapping alert/header/sidebar/right-panel/assistant elements.
- Tables scroll only inside their own container.
- Cards wrap cleanly.
- Long IDs, symbols, and values truncate or wrap intentionally.

Acceptance criteria:

- Every route passes the viewport matrix.
- Every primary workflow works with keyboard navigation.
- No route creates accidental page-level horizontal scrolling.

## Phase 7: Visual Regression And CI Gates

Objective: keep the product launch-ready after the redesign.

Required automation:

- Playwright route screenshot suite.
- Axe accessibility scan.
- Horizontal overflow test.
- Component smoke tests for common primitives.
- Storybook build for shared UI.
- Storybook snapshots for key primitives.
- `pnpm audit:ui:strict` in CI.
- Route-level tests for empty/loading/error states.
- Package-source health check for local common-platform resolution.

Suggested route screenshot coverage:

- `/`
- `/portfolio`
- `/research`
- `/plans`
- `/markets`
- `/screener`
- `/watchlist`
- `/alerts`
- `/settings`
- `/settings?tab=admin` or equivalent admin route/state
- auth/login/reset states if routed separately

Acceptance criteria:

- CI blocks UI drift and package-source regressions.
- Visual screenshots make layout regressions obvious.
- Common-platform UI changes can be adopted safely by this and future products.

## Suggested PR Sequence

### PR 1: Package Source And Guardrails

Repos:

- `learning_ai_invt_trdg`
- `learning_ai_common_plat`

Scope:

- Finish local-package-first install contract.
- Remove or isolate Gitea registry assumptions from local development.
- Add local package health check.
- Expand UI drift audit and wire strict mode into CI.
- Document sibling repo layout and `BYTELYST_COMMON_PLAT_ROOT`.

Exit criteria:

- Fresh local install works without `GITEA_NPM_TOKEN`.
- UI drift audit blocks new raw controls and unsafe styling.

### PR 2: Platform Primitives And Storybook

Repo:

- `learning_ai_common_plat`

Scope:

- Harden existing primitives.
- Add missing primitives: `PageHeader`, `Section`, `Toolbar`, `FilterBar`, `FormSection`, `FieldGrid`, `AlertBanner`, `Skeleton`, `EntityCard`, `MetricCard`, `ActionMenu`, `Drawer`.
- Add Storybook stories and accessibility coverage.
- Add a Cipher-inspired common-platform preview page that demonstrates realistic operational UI with shared tokens and primitives.

Exit criteria:

- Product has the shared building blocks needed for all target screens.
- The common platform has a visible production-grade quality bar similar to Cipher's preview, adapted for ByteLyst operational products.

### PR 3: Shell And Global UX

Repo:

- `learning_ai_invt_trdg`

Scope:

- Apply the shell contract.
- Fix desktop/tablet/phone navigation.
- Fix critical alert and assistant collision rules.
- Add route skeletons and global overflow policy.

Exit criteria:

- All routes render correctly at 390, 768, 1024, 1440, and 1728 px.

### PR 4: Trade Plans And Portfolio

Repo:

- `learning_ai_invt_trdg`

Scope:

- Rebuild Trade Plans create/edit/saved setup surfaces.
- Rebuild Portfolio positions/order/history surfaces.
- Add confirmations, toasts, skeletons, empty/error states, and responsive card/list views.

Exit criteria:

- The two highest credibility workflows feel demo-ready.

### PR 5: Research, Builder, Editor, Backtesting

Repo:

- `learning_ai_invt_trdg`

Scope:

- Normalize research tab shell.
- Polish strategy list, visual builder, code editor, signals, and backtesting.

Exit criteria:

- Research feels like one integrated workspace.

### PR 6: Screener, Watchlist, Markets, Alerts

Repo:

- `learning_ai_invt_trdg`

Scope:

- Apply `FilterBar`, `DataTable`, `EntityCard`, `DataList`, and complete state handling.
- Normalize secondary but visible workflows.

Exit criteria:

- All day-to-day user screens share one visual and interaction language.

### PR 7: Settings, Admin, Auth, Right Panel, Assistant

Repos:

- `learning_ai_invt_trdg`
- `learning_ai_common_plat` if auth/platform primitives need changes

Scope:

- Polish settings/admin/config/auth.
- Integrate `@bytelyst/auth-ui` where appropriate.
- Finish right panel and assistant accessibility/collision rules.

Exit criteria:

- Low-frequency screens no longer feel like raw internal tools.

### PR 8: Launch QA And Regression Gates

Repos:

- `learning_ai_invt_trdg`
- `learning_ai_common_plat`

Scope:

- Add screenshots, accessibility scans, overflow tests, Storybook snapshots, and route-state tests.
- Final copy, spacing, and contrast pass.

Exit criteria:

- Product is ready for customer/investor/recruiter demo without caveats about UI quality.

## Launch Readiness Checklist

- [ ] Local product install works without Gitea npm auth.
- [ ] Common-platform packages do not surprise local installs with private registry assumptions.
- [ ] Design tokens follow a clear primitive, alias, semantic, typography, and effects structure.
- [x] Common platform has a Cipher-inspired preview surface for realistic component compositions.
- [ ] Shared primitives cover shell, page header, sections, cards, forms, fields, tables, lists, tabs, badges, timelines, alerts, toasts, dialogs, drawers, skeletons, and empty states.
- [x] Product pages import UI through the product adapter.
- [x] No production route uses raw controls outside approved wrappers.
- [ ] No production route uses hardcoded colors for normal UI.
- [ ] No production route has accidental horizontal overflow.
- [ ] Desktop, tablet, and phone navigation each follow the shell contract.
- [ ] Critical alerts never cover primary content.
- [ ] Assistant widget never covers primary actions.
- [ ] Right panel behaves correctly across responsive breakpoints.
- [ ] All destructive actions require confirmation.
- [ ] All saves/deletes/updates produce feedback.
- [ ] All pages have loading, empty, error, and success/saved states.
- [ ] All forms have labels, hints, validation, and disabled-state explanations.
- [ ] All primary workflows pass keyboard navigation. Profile rule toggles now support keyboard access; full route-level keyboard QA remains.
- [ ] All routes pass the viewport matrix.
- [ ] Playwright screenshots and accessibility checks run in CI.
- [ ] Storybook documents shared UI behavior.
- [ ] Common platform UI can be reused by another product without trading-specific assumptions.

## Immediate Recommendation

Start with PR 1, PR 2, and PR 3 as the next milestone.

Rationale:

- Package-source stability prevents repeated local/prod install pain.
- Shared primitives prevent product-only redesign churn.
- Shell correctness fixes the visible global problems first: broken responsive navigation, alert overlap, assistant overlap, and inconsistent route framing.

After that, rebuild Trade Plans and Portfolio first. They carry the highest product credibility risk and will define the patterns that Screener, Watchlist, Research, Settings, and Admin should follow.