From 26ca71ac63ec87ae83d0b0f7a90d802694159089 Mon Sep 17 00:00:00 2001
From: Saravana Achu Mac <saravanakumardb1@gmail.com>
Date: Fri, 8 May 2026 21:07:37 -0700
Subject: [PATCH] docs: expand launch-ready UX implementation roadmap

---
 docs/LAUNCH_READY_UI_UX_ROADMAP.md | 978 +++++++++++++++++++++--------
 1 file changed, 733 insertions(+), 245 deletions(-)

diff --git a/docs/LAUNCH_READY_UI_UX_ROADMAP.md b/docs/LAUNCH_READY_UI_UX_ROADMAP.md
index 651226e..d7f87be 100644
--- a/docs/LAUNCH_READY_UI_UX_ROADMAP.md
+++ b/docs/LAUNCH_READY_UI_UX_ROADMAP.md
@@ -4,395 +4,883 @@ 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`.
+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:
 
-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 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 polished operational SaaS console for trading workflows:
+The target experience is a calm, modern, professional trading operations console:
 
-- Calm, readable, premium, and practical.
-- Dense enough for portfolio/trading operations without feeling cramped.
-- Consistent component behavior across all routes.
+- 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.
-- 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.
+- 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.
 
-## Current State Summary
+## Non-Negotiables
 
-The app is functional, but launch readiness is blocked by inconsistent UI systems:
+- 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.
 
-- 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.
+## Design Direction
 
-## Guiding Principles
+Use a practical light-first SaaS console direction:
 
-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.
+- 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.
 
-## Phase 0: Stop UI Drift
+## Cipher Reference Standard
 
-Objective: prevent new inconsistent UI while remediation is underway.
+Reference: `https://www.usecipher.dev/` and `https://github.com/atom63/cipher-boilerplate`
 
-Scope:
+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:
 
-- 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.
+- 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:
 
-- Audit runs locally and in CI.
-- New raw controls and legacy surface classes fail the audit.
-- Known legacy exceptions are documented and temporary.
+- 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 1: Platform Design System Foundation
+## Phase 0: Freeze UI Drift
 
-Objective: make `learning_ai_common_plat` the real source of reusable UI quality.
+Objective: prevent new inconsistent UI while the deeper redesign continues.
 
-Common platform components to standardize or add:
+Current status:
 
-- `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.
+- `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.
 
-Token work:
+Next improvements:
 
-- 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.
+- 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:
 
-- 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.
+- UI drift audit runs locally and in CI.
+- New raw controls and legacy styles fail the audit.
+- Exceptions are explicit, temporary, and owned.
 
-## Phase 2: Product Shell And Global UX
+## Phase 1: Common Platform Foundation
 
-Objective: make the app frame stable and professional everywhere.
+Objective: make `learning_ai_common_plat` strong enough that product teams do not rebuild primitives locally.
 
-Scope:
+### 1.1 Tokens
 
-- 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.
+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 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.
+- 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.
 
-## Phase 3: Core Trading Screen Rebuild
+### 1.2 Core Primitives
 
-Objective: polish the highest-value product workflows first.
+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
 
-Current issues:
+Files to review/refactor:
 
-- 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.
+- `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
 
-Work:
+Current risks:
 
-- Convert create/edit flow into a guided plan builder.
-- Use `FormSection`, `FieldGrid`, `StatusBadge`, `Timeline`, and `EntityCard`.
+- 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.
-- Add success toast after save/update/delete.
-- Add confirm dialog for delete.
-- Add compact card view and detail drawer for advanced runtime/event history.
+- 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 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.
+- 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
 
-Current issues:
+Files to review/refactor:
 
-- `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.
+- `web/src/views/PortfolioView.tsx`
+- `web/src/tabs/PositionsTab.tsx`
+- `web/src/tabs/HistoryTab.tsx`
+- `web/src/tabs/ReconciliationAuditPanel.tsx`
 
-Work:
+Current risks:
 
-- 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.
+- 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:
 
-- No warning or trade ID can break layout.
-- Position/order data scans cleanly.
-- The page remains usable with many rows and long identifiers.
+- 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
+### 3.3 Research And Strategy Builder
 
-Current issues:
+Files to review/refactor:
 
-- Strategies tab looks better, but builder/editor/backtest surfaces use different visual systems.
-- Backtest components are still dark/zinc styled.
+- `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/*`
 
-Work:
+Current risks:
 
-- Normalize research tabs with shared `Tabs`.
+- 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` and common controls.
-- Convert Code Editor shell to a polished tool panel.
-- Rebuild Backtest panels with common cards, tables, metric cards, charts, and alerts.
+- 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:
 
-- Strategies, Visual Builder, Code Editor, Signals, and Backtesting feel like one product.
-- Backtest UI no longer looks like a separate app.
+- 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
 
-Current issues:
+Files to review/refactor:
 
-- Filter layout has improved but needs a final `FilterBar`.
-- Table states should use shared `DataTable`.
+- `web/src/views/ScreenerView.tsx`
+- market API helpers used by screener
 
-Work:
+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 `DataTable`.
-- Add query count, active filter chips, reset filters.
-- Improve API error copy and retry.
-- Add row action affordance for opening chart/research.
+- 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 are readable on tablet.
-- Result table has consistent empty/loading/error behavior.
+- Filters remain readable on tablet and phone.
+- API failures are clear, calm, and recoverable.
+- Results table matches portfolio table behavior.
 
 ### 3.5 Watchlist
 
-Current issues:
+Files to review/refactor:
 
-- Empty state is improved, but entries should use reusable cards.
-- Add/edit flow should feel like a proper modal or side panel.
+- `web/src/views/WatchlistView.tsx`
+- `web/src/tabs/EntriesTab.tsx` if shared with manual entries
+- manual entry API helpers
 
-Work:
+Current risks:
 
-- 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.
+- 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 complete.
+- Empty and populated states both look finished.
 - Entry management feels safe and predictable.
 
-## Phase 4: Secondary And Admin Surfaces
+## Phase 4: Secondary And Admin Workflows
 
-Objective: remove remaining developer-tool styling from lower-frequency screens.
+Objective: remove remaining lower-frequency rough edges.
 
-Scope:
+### 4.1 Settings And Bot Config
 
-- 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.
+Files:
 
-Work:
+- `web/src/views/SettingsView.tsx`
+- `web/src/tabs/SettingsTab.tsx`
+- `web/src/tabs/ConfigTab.tsx`
+- `web/src/components/GlobalConfigManager.tsx`
 
-- 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.
+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:
 
-- No screen looks like raw admin tooling.
-- Low-frequency screens are safe, clear, and consistent.
+- Settings feels safe and production-grade, not like a raw config panel.
 
-## Phase 5: Interaction And Feedback Quality
+### 4.2 Admin
 
-Objective: make the app feel trustworthy under real usage.
+Files:
 
-Add consistently:
+- `web/src/tabs/AdminTab.tsx`
 
-- 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.
+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:
 
-- A user never wonders whether an action worked.
-- Failed network/API states are recoverable.
-- Destructive actions are protected.
+- 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: 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.
+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.
+- 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 visual QA at all target widths.
+- 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 app launch-ready after the cleanup.
+Objective: keep the product launch-ready after the redesign.
 
-Tests and automation:
+Required 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.
+- 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.
-- Screenshots make regressions obvious.
-- Design system changes can be safely adopted by other products.
+- 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 Implementation Sequence
+## Suggested PR Sequence
 
-### PR 1: Foundation And Guardrails
+### PR 1: Package Source And Guardrails
 
-- Expand UI drift audit.
-- Introduce missing common primitives.
-- Move product shell toward common shell contract.
-- Add Storybook coverage for primitives.
+Repos:
 
-### PR 2: Core Screen Rebuild
+- `learning_ai_invt_trdg`
+- `learning_ai_common_plat`
 
-- Trade Plans.
-- Portfolio.
-- Watchlist.
-- Screener.
+Scope:
 
-### PR 3: Research And Backtesting
+- 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`.
 
-- Research tab shell.
-- Visual Builder.
-- Code Editor.
-- Backtest configuration/results.
+Exit criteria:
 
-### PR 4: Settings, Admin, Markets, Alerts
+- Fresh local install works without `GITEA_NPM_TOKEN`.
+- UI drift audit blocks new raw controls and unsafe styling.
 
-- Settings and Bot Config.
-- Admin Panel.
-- Markets and Marketplace.
-- Alerts.
-- Right panel.
+### PR 2: Platform Primitives And Storybook
 
-### PR 5: Launch QA
+Repo:
 
-- Visual regression.
-- Accessibility pass.
-- Responsive pass.
-- Final polish and copy pass.
+- `learning_ai_common_plat`
 
-## Product Launch Readiness Checklist
+Scope:
 
-- [ ] Shared primitives cover app shell, page header, sections, cards, forms, tables, tabs, badges, timelines, alerts, toasts, modals, skeletons, and empty states.
+- 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.
+- [ ] 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.
+- [ ] Product pages import UI through the product adapter.
 - [ ] 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 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.
+- [ ] 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.
+- [ ] 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 Next Recommendation
+## Immediate Recommendation
 
-Start with PR 1 and PR 2 together as the next focused milestone:
+Start with PR 1, PR 2, and PR 3 as the next milestone.
 
-1. Harden the shared design system and audit gates.
-2. Rebuild Trade Plans and Portfolio using those primitives.
+Rationale:
 
-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.
+- 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.