# UI/UX Platform Core Migration Roadmap

Live source of truth for migrating `learning_ai_invt_trdg` UI/UX and platform clients onto the shared ByteLyst common platform at `/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat`.

## Current Baseline

- Product repo: `/Users/saravana/BytelystAI/learning_ai/learning_ai_invt_trdg`
- Common platform repo: `/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat`
- Local package toggle: `BYTELYST_PACKAGE_SOURCE=common-plat pnpm install -r`
- Current common-platform usage: `@bytelyst/api-client`, `@bytelyst/design-tokens`, `@bytelyst/errors`, `@bytelyst/kill-switch-client`, `@bytelyst/react-auth`, `@bytelyst/react-native-platform-sdk`, `@bytelyst/telemetry-client`, `@bytelyst/ui`
- UI adapter in code: `web/src/components/ui/Primitives.tsx` imports from `@bytelyst/ui`, re-exports common primitives, and owns product status-to-tone mapping.
- Design token foundation in code: `web/src/index.css` imports `@bytelyst/design-tokens/generated/tokens.css` and defines product `--bl-*` aliases.
- Remaining UI duplicates to migrate: hardcoded color literals and local status/surface/list/table patterns where still product-local.
- Common UI target: `@bytelyst/ui` through the product adapter only; direct `@bytelyst/ui` imports outside the adapter remain disallowed.
- Design token target: `@bytelyst/design-tokens` with product aliases to `--bl-*`; chart/domain colors may remain product-owned when they encode trading semantics.

## Component Ownership

- Common platform core UI (`learning_ai_common_plat/packages/ui`): product-agnostic primitives such as Button, IconButton, Card, Panel, Surface, Badge, StatusBadge, StatusDot, Input, Textarea, Select, Label, Checkbox, RadioGroup, Switch, Tabs, SegmentedControl, DropdownMenu, Tooltip, Modal, ConfirmDialog, DataList, DataTable, Timeline, DiffCard, EmptyState, LoadingSpinner, Sidebar/AppShell base pieces.
- Product UI adapter (`web/src/components/ui/Primitives.tsx`): imports from `@bytelyst/ui`, maps product defaults/status tones, exposes common primitives to product code, and preserves trading-domain composition locally.
- Product-owned UI: trading workflows, strategy/risk/execution domain composition, charts, order lifecycle views, and product-specific copy/state.

## Common-Platform Inventory

| Product Need | Current Product Usage | Common-Platform Package | Migration Decision |
|---|---|---|---|
| Core UI primitives | Local `web/src/components/ui/*`, raw controls, local CSS classes | `@bytelyst/ui` | Add product adapter and migrate local primitives/workflows to common exports. |
| Design tokens | Product CSS variables and hardcoded literals in `web/src/index.css`, `web/src/App.css`, component styles | `@bytelyst/design-tokens` | Add shared token dependency and global `--bl-*` aliases before component migrations. |
| Platform API client | `@bytelyst/api-client` in web dependency graph through local/vendor resolution | `@bytelyst/api-client`, `@bytelyst/platform-client` | Keep current API client, evaluate `platform-client` where product uses platform-service workflows directly. |
| Auth/session | `@bytelyst/react-auth`, backend `@bytelyst/auth` | `@bytelyst/react-auth`, `@bytelyst/auth`, `@bytelyst/auth-client`, `@bytelyst/auth-ui`, `@bytelyst/secure-storage-web` | Keep current auth primitives; evaluate auth UI and secure storage during forms/auth migration. |
| Telemetry | `@bytelyst/telemetry-client` in shared web/mobile and backend telemetry singleton | `@bytelyst/telemetry-client`, `@bytelyst/backend-telemetry`, `@bytelyst/monitoring` | Keep current telemetry client; evaluate backend package consolidation separately from UI migration. |
| Diagnostics | Product-local operational status and error surfaces | `@bytelyst/diagnostics-client`, `@bytelyst/errors` | Add diagnostics client when operational panels migrate; keep `@bytelyst/errors` for shared error contracts. |
| Feature flags | Product-local feature gate utilities and backend config | `@bytelyst/feature-flag-client`, `@bytelyst/backend-flags` | Use common feature flag client for web gates when replacing product-local feature gate plumbing. |
| Kill switch | `@bytelyst/kill-switch-client` in root/web/mobile dependencies | `@bytelyst/kill-switch-client` | Already consumed; migrate UI status surfaces to common primitives, not new service code. |
| Blob and extraction | Product-specific research/import surfaces not yet common-backed | `@bytelyst/blob-client`, `@bytelyst/blob`, `@bytelyst/storage`, `@bytelyst/extraction` | Evaluate when file/blob/extraction workflows are touched; no trading-domain move. |
| Offline and broadcast | Product-local realtime/socket behavior and mobile support | `@bytelyst/offline-queue`, `@bytelyst/broadcast-client`, `@bytelyst/sync`, `@bytelyst/events` | Keep trading WebSocket domain local; use common offline/broadcast only for product-agnostic client concerns. |
| Billing/subscription | Membership tab/product tier policy | `@bytelyst/billing-client`, `@bytelyst/subscription-client`, `@bytelyst/marketplace-client` | Evaluate during membership/marketplace migration; keep trading tier rules local when domain-specific. |
| Feedback and survey | No first-class common client usage found | `@bytelyst/feedback-client`, `@bytelyst/survey-client` | Add only when feedback/survey surfaces are introduced or migrated. |
| Datastore/config | Backend Cosmos repositories and `@bytelyst/config` bootstrap | `@bytelyst/datastore`, `@bytelyst/cosmos`, `@bytelyst/config`, `@bytelyst/backend-config` | Existing `@bytelyst/cosmos`/`config` usage stays; consider `datastore` only for reusable storage helpers. |
| Operational shells/components | Local AppShell, Sidebar, cards, lists, status surfaces | `@bytelyst/ui`, `@bytelyst/dashboard-shell`, `@bytelyst/dashboard-components` | Prefer `@bytelyst/ui` first; evaluate dashboard packages only if they fit product-agnostic shell/list composition. |

## Code Sync Snapshot

Reviewed against current product code on 2026-05-06:

- `web/package.json` includes `@bytelyst/ui` and `@bytelyst/design-tokens`.
- `web/src/components/ui/Primitives.tsx` is present and is the only direct `@bytelyst/ui` import found in `web/src`.
- Product code currently imports adapter primitives in `Login`, `ResetPassword`, `PositionsTab`, `MyStrategiesTab`, `VisualRuleBuilder`, `PortfolioView`, `ScreenerView`, `SimpleView`, `ChatControl`, `SettingsTab`, and `EntriesTab`.
- `web/src/index.css` imports shared generated design tokens and defines `--bl-*` aliases for product surfaces/status/focus/radius.
- Production raw-control audit now reports zero findings outside approved UI primitives.
- Legacy global surface-class audit now reports zero findings; `SymbolCard` status/rule labels route through adapter badges where product-agnostic.
- `scripts/ui-drift-audit.sh` uses a portable Python implementation so missing `rg` cannot produce false-zero counts.

## Common UI Gap Closure Decision

No shared `@bytelyst/ui` code change is required before the product adapter phase. The common UI package already exports the primitives required for the first product migration passes:

- Controls: Button, IconButton, Input, Textarea, Select, Label, Checkbox, RadioGroup, Switch, Tabs, SegmentedControl, DropdownMenu, Tooltip, Modal, ConfirmDialog.
- Surfaces and status: Card, Panel, Surface, Badge, StatusBadge, StatusDot, EmptyState, LoadingSpinner, Separator, StatCard.
- Operational data: DataList, DataTable, Timeline, DiffCard, ListItemButton, Sidebar, AppShell base pieces.

Verification on the common platform passed with the existing checkout:

- `pnpm --filter @bytelyst/ui run build`
- `pnpm --filter @bytelyst/ui exec eslint src --ext .ts,.tsx`
- `git diff --check`

Note: common platform had a pre-existing local modification in `packages/ui/src/components/AppShell.tsx`; this product migration did not modify or commit common-platform files.

## Roadmap

| Status | Phase | Scope / Repo | Implementation Summary | Verification Commands | Commit Hash | Notes / Deferrals |
|---|---|---|---|---|---|---|
| [x] | 1. Baseline audit and package-source rules | product | Added UI drift audit script and package scripts; documented ownership; kept local common-platform resolution available through sibling checkout without editing `.npmrc`. | Passed: `BYTELYST_PACKAGE_SOURCE=common-plat BYTELYST_COMMON_PLAT_ROOT=/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat pnpm install -r --frozen-lockfile`; `pnpm run audit:ui`; `pnpm --filter @bytelyst/trading-web typecheck`; `node -e "require('./.pnpmfile.cjs')"`; `git diff --check`. Expected fail: `pnpm run audit:ui:strict` reports 48 raw controls, 21 legacy classes, 520 color literals, 0 direct `@bytelyst/ui` imports. | `f0cdfe6776b34299abed68bc1741204f16d29723` | Strict audit remains disabled until cleanup phase. Existing pnpm `.npmrc` warning for missing `GITEA_NPM_TOKEN` observed; `.npmrc` was not edited. |
| [x] | 2. Common-platform package inventory | product + common | Mapped product needs to existing common packages for UI, design tokens, platform/auth/session, telemetry, diagnostics, feature flags, kill switch, blob/extraction/offline/broadcast/billing/feedback/survey, datastore/config/errors. | Passed: `rg "@bytelyst/" --glob '!node_modules/**' --glob '!pnpm-lock.yaml' --glob '!vendor/**'`; common package manifest inspection; required common package manifest existence checks; `git diff --check`. | `3ed79933422522dfeec524befcff4f2a4c56dfc7` | No common-platform package gap identified for the next adapter/token phases. Dashboard packages should be evaluated after `@bytelyst/ui` adapter work, not before. |
| [x] | 3. Common-platform UI gap closure | common | Verified common UI already covers the required reusable primitive set; no common-platform code change needed before product adapter work. | Passed in common platform: `pnpm --filter @bytelyst/ui run build`; `pnpm --filter @bytelyst/ui exec eslint src --ext .ts,.tsx`; `git diff --check`. | `09bdf3fbd0d1f8e46631648f90ddeb0f20fd9541` | Deferral recorded: dashboard packages will be evaluated after product adapter work. Common checkout had a pre-existing local `packages/ui/src/components/AppShell.tsx` modification that this migration did not touch. |
| [x] | 4. Product UI adapter foundation | product | Added `web/src/components/ui/Primitives.tsx` wrapping/re-exporting `@bytelyst/ui`; added `@bytelyst/ui` and `@bytelyst/design-tokens` dependencies through local common-platform resolution; added product status-to-tone mapping. | Passed: `BYTELYST_PACKAGE_SOURCE=common-plat BYTELYST_COMMON_PLAT_ROOT=/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat pnpm install -r --frozen-lockfile`; `pnpm --filter @bytelyst/trading-web typecheck`; `pnpm run audit:ui`; `git diff --check`. | `833e85ee0e3c41dfbfd3df76c8b89bd3474f9991` | Audit remains at 48 raw controls, 21 legacy classes, 520 color literals, 0 direct `@bytelyst/ui` imports outside adapter. |
| [x] | 5. Design token alias foundation | product | Imported shared design tokens and added global aliases from product tokens to `--bl-*` in web CSS. | Passed: `pnpm --filter @bytelyst/trading-web typecheck`; `pnpm --filter @bytelyst/trading-web build`; `pnpm run audit:ui`; `git diff --check`. | `ce85504066a1cfbbbca0c6423f397ccb4f291080` | Used `@bytelyst/design-tokens/generated/tokens.css` because Tailwind/Vite did not resolve the package export alias in CSS `@import`. Audit reports 48 raw controls, 23 legacy classes, 520 color literals, 0 direct `@bytelyst/ui` imports outside adapter. |
| [x] | 6. Highest-value workflow migration | product | Migrated Positions workflow profile tabs, order activity filters, lifecycle filters, sort toggles, and pagination controls to adapter Button/Input/Select primitives while preserving visible text and behavior. | Passed: `pnpm --filter @bytelyst/trading-web exec vitest run src/tabs/PositionsTab.dom.test.tsx`; `pnpm --filter @bytelyst/trading-web typecheck`; `pnpm run audit:ui`; `git diff --check`. | `d5a8f36b35f93465a7c80b9192c0d92fe9643060` | Audit raw controls reduced from 48 to 32. Supporting common-platform fix `cd6546ef97a92bf94e0c3893ef9e15bf3bde23d8` made `@bytelyst/ui` root exports Node/Vitest-compatible. Existing common-platform `packages/ui/src/components/AppShell.tsx` local change remains untouched. |
| [x] | 7. Forms, modals, and settings migration | product | Migrated auth reset/sign-in/sign-up controls to adapter Button/Input primitives while preserving labels, placeholders, button names, and provider-error behavior. | Passed: `pnpm --filter @bytelyst/trading-web exec vitest run src/components/Login.dom.test.tsx src/components/ResetPassword.dom.test.tsx`; `pnpm --filter @bytelyst/trading-web typecheck`; `pnpm run audit:ui`; `git diff --check`. | `6511326a3e5de3e6d2cf4f5ec29c30c3ea98cfe7` | Audit raw controls reduced from 32 to 25. Settings/share/create/edit form debt remains for dashboard/workspace and cleanup phases. |
| [x] | 8. Dashboard, search, and workspace migration | product | Migrated My Strategies dashboard card action controls, diagnostic toggle, engine toggle, wizard back control, and empty-state/header CTAs to adapter Button/IconButton primitives. | Passed: `pnpm --filter @bytelyst/trading-web exec vitest run src/tabs/MyStrategiesTab.dom.test.tsx`; `pnpm --filter @bytelyst/trading-web typecheck`; `pnpm run audit:ui`; `git diff --check`. | `1ee57d5aeb548aefd505f53fa7d08d47cc8f4db7` | Audit raw controls reduced from 25 to 17. Dense operational layout and existing card composition preserved. |
| [x] | 9. Advanced product-specific surfaces | product | Migrated Visual Strategy Builder controls to adapter Select/Input/Button/IconButton primitives while keeping dnd-kit composition and strategy rule logic product-owned. | Passed: `pnpm --filter @bytelyst/trading-web exec vitest run src/components/strategy/VisualRuleBuilder.dom.test.tsx`; `pnpm --filter @bytelyst/trading-web typecheck`; `pnpm run audit:ui`; `git diff --check`. | `bb4efc2b0d5f8e2ebbd7487b5731e0e6446ec4fb` | Audit raw controls reduced from 17 to 13. Charts, rule semantics, and strategy execution remain product-owned. |
| [x] | 10. Audit tooling hardening | product | Replaced brittle `rg`-based shell counting with a portable Python audit that excludes approved UI/test surfaces and reports non-zero raw controls reliably. | Passed: `pnpm run audit:ui`; `pnpm --filter @bytelyst/trading-web typecheck`; `git diff --check`. | `9ea72f7` | Audit now reports 0 direct `@bytelyst/ui` imports outside the adapter and no false-zero dependency on local `rg`. |
| [x] | 11. Remaining raw-control migration | product | Migrated remaining production raw controls in portfolio, screener, simple trade plan, chat, settings, and entries surfaces to adapter primitives while preserving trading workflow behavior. | Passed: `pnpm --filter @bytelyst/trading-web exec vitest run src/tabs/SettingsTab.dom.test.tsx src/tabs/EntriesTab.dom.test.tsx`; `pnpm --filter @bytelyst/trading-web typecheck`; `pnpm run audit:ui`; `git diff --check`. | `324e34d`, `7f5f125` | Audit raw interactive controls outside approved primitives reduced to 0. `EntriesTab.tsx` line endings were normalized to satisfy `git diff --check`. |
| [~] | 12. Legacy global cleanup and strict audit | product | Removed unused global `.badge` CSS, removed legacy `SymbolCard` badge selectors, preserved adapter `Badge`/`ProductStatusBadge` usage, and tightened legacy-class audit so product token names such as `--bl-surface-card` are not false positives. | Passed: `pnpm run audit:ui`; `pnpm --filter @bytelyst/trading-web typecheck`; `pnpm --filter @bytelyst/trading-web lint`; `pnpm --filter @bytelyst/trading-web test`; `git diff --check`. | `5f38ada` | Audit now reports 0 legacy global surface classes and 525 hardcoded color literals. Strict audit remains deferred for color classification/allowlisting. |

## Remaining Work

- **Reduce hardcoded colors**: Move reusable surface/status colors to token aliases; keep chart palette and trading semantic colors product-owned when appropriate.
- **Standardize local status/list/table patterns**: Prefer adapter/common primitives for product-agnostic surfaces while keeping trading workflows product-owned.
- **Strict audit decision**: Enable `pnpm run audit:ui:strict` only after accepted legacy CSS/color debt is cleared or explicitly allowlisted.
- **Verify after each slice**: Run targeted DOM tests for touched views, web typecheck, UI audit, and `git diff --check`.

## Running Notes

- Do not hand-edit `.npmrc`.
- Do not move trading-domain behavior into common platform.
- Keep Gitea and vendor support available; use local common platform for implementation and verification.
- Commit and push each implementation step, then update this roadmap with commit hash and verification notes in a separate commit.
