# 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 `/opt/bytelyst/learning_ai_common_plat`.

## Current Baseline

- Product repo: `/opt/bytelyst/trading/learning_ai_invt_trdg`
- Common platform repo: `/opt/bytelyst/learning_ai_common_plat`
- Local package default: `@bytelyst/*` resolves from the sibling `learning_ai_common_plat` checkout by default via `.pnpmfile.cjs`; set `BYTELYST_PACKAGE_SOURCE=gitea` only when registry resolution is explicitly required.
- 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: none on the closed baseline; future product-local UI should only remain where it encodes trading semantics by design.
- 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 the closed product baseline on 2026-05-09:

- `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`. |
| [x] | 12. Legacy global cleanup and strict audit | product | Removed unused global `.badge` CSS, removed legacy `SymbolCard` badge selectors, preserved adapter `Badge`/`ProductStatusBadge` usage, tightened legacy-class audit so product token names such as `--bl-surface-card` are not false positives, tokenized reset-password auth surface colors, eliminated hardcoded color literals from `App.css` and `AlertFeed.css`, tokenized `SettingsTab` role/status colors, added shared surface/text aliases to migrate `Login`, `ProductAccessibilityGate`, `LivePulseTicker`, and `AdminTab` off raw hex/rgba operational surface colors, typed the remaining simple form/chat/positions visual-builder change handlers so trivial implicit-`any` errors no longer block `tsc`, reconciled `web/src/components/ui/Primitives.tsx` to the actual linked `@bytelyst/ui` export surface while keeping product-only variants and control sizing local to the adapter, converted `OverviewTab` status/warning/consumer-card color debt onto existing theme variables and `color-mix(...)` surfaces, migrated `SymbolCard.css` surface/status styling from raw hex/rgba values onto shared theme variables, moved `TradeProfileManager` rule/summary/status palette literals onto shared CSS variables and `color-mix(...)` accents, tokenized `HomeView` shell/error/earnings status plus `Header`/`RightPanel`/`Sidebar` shell status literals, migrated shared `PriceChart` shell, tooltip, axis, empty-state, and up/down color usage onto shared theme variables, converted the remaining `HomeView` indicator-chart literals onto existing info/warning/emphasis/border tokens so the landing analytics no longer depends on raw hex palette values, migrated `BacktestResultsDashboard` grid/tick/reference/series chart colors to the shared attention/success/warning/text/border tokens, tokenized `CodeStrategyEditor` trade-log header plus buy/sell and P&L accents onto shared quiet/success/danger tokens, migrated `VisualRuleBuilder` drag shadow/handles/labels plus BUY/SELL chip surfaces onto the shared card/text/success/danger token palette, tokenized `BacktestTab` disabled/access messaging plus `ScreenerView` percentage gain/loss coloring onto shared danger/faint/success tokens, replaced repeated `MarketplaceTab`/`HistoryTab` neon attention, gain/loss, and focus-ring literals with shared warning/success/danger/focus tokens, converted the remaining `ConfigTab` hero/loading/backtest-action/footer surfaces away from hardcoded dark backgrounds and neon accents onto shared card/overlay/info/success tokens, removed the bulk of `MyStrategiesTab` surface/status/market-feed literals by moving the strategy fleet cards, overview hero, activity panels, and volatility rails to shared card/border/text/success/danger/info tokens, and finished the last residual files by tokenizing `PositionsTab`, `SettingsTab`, `MembershipTab`, `EntriesTab`, and `TierPolicy`. The audit now treats `web/src/index.css` as intentional theme-token source data instead of product debt. | Passed: `pnpm run audit:ui`; `pnpm --filter @bytelyst/trading-web typecheck`; `pnpm --filter @bytelyst/trading-web lint`; `pnpm --filter @bytelyst/trading-web build`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/components/Login.dom.test.tsx src/App.dom.test.tsx src/components/ComponentsSmoke.test.ts src/tabs/SettingsTab.dom.test.tsx src/tabs/EntriesTab.dom.test.tsx`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/tabs/OverviewTab.dom.test.tsx src/tabs/OverviewTab.test.ts src/App.dom.test.tsx`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/components/ComponentsSmoke.test.ts src/tabs/TabSuite.test.ts`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/components/TradeProfileManager.test.ts src/components/TradeProfileManager.dom.test.tsx`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/views/HomeView.dom.test.tsx src/components/layout/Header.dom.test.tsx src/components/layout/AppShell.dom.test.tsx`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/components/PriceChart.dom.test.tsx src/components/ComponentsSmoke.test.ts`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/components/ComponentsSmoke.test.ts`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/components/strategy/CodeStrategyEditor.dom.test.tsx`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/components/strategy/VisualRuleBuilder.dom.test.tsx`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/views/ScreenerView.dom.test.tsx src/components/ComponentsSmoke.test.ts`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/tabs/TabSuite.test.ts src/components/ComponentsSmoke.test.ts`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/tabs/SettingsTab.dom.test.tsx src/tabs/TabSuite.test.ts src/components/ComponentsSmoke.test.ts`; `git diff --check`; `BYTELYST_PACKAGE_SOURCE=common-plat pnpm install -r --no-frozen-lockfile --offline`; `pnpm --filter @bytelyst/ui build` (in `/opt/bytelyst/learning_ai_common_plat`). Earlier passed in this phase: `pnpm --filter @bytelyst/trading-web test`; `pnpm --filter @bytelyst/trading-web exec vitest run src/components/ResetPassword.dom.test.tsx`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/App.dom.test.tsx src/views/HomeView.dom.test.tsx src/components/AlertFeed.dom.test.tsx src/components/ComponentsSmoke.test.ts src/tabs/OverviewTab.test.ts`; `TMPDIR="$PWD/.tmp/vitest" pnpm --filter @bytelyst/trading-web exec vitest run src/tabs/SettingsTab.dom.test.tsx`. | `5f38ada`, `e4c4c60`, `6091f24`, `8f707e0`, `7375ad6`, `eef63cb`, `35fbe87`, `a230679`, `902523d`, `931a3cd`, `4802f02`, `1b9efca`, `de040ea`, `9a0dfe6`, `b5f55e5`, `90ba1d5`, `8d84c3b`, `b14d333`, `cd2f38d`, `5fc123e`, `5453bb4` | Audit now reports 0 raw production controls, 0 legacy global surface classes, 0 direct common-UI imports outside the adapter, and 0 hardcoded color literals. `web/src/index.css` token definitions are intentionally excluded from the hardcoded-color audit because they are the theme-source baseline, not product drift. The adapter/common-package API divergence blocker is resolved for the current common-platform checkout by narrowing the product adapter to the real shared export surface and owning product-only variants locally. Strict audit can now be enabled from a clean baseline. |

| [x] | 13. Strict baseline enforcement | product | Added `pnpm audit:ui:strict` to the root `pnpm verify` workflow and updated README verification guidance so the clean UI migration baseline is enforced in standard repo verification instead of remaining advisory-only. | Passed: `sh -n scripts/verify.sh`; `BYTELYST_PACKAGE_SOURCE=common-plat pnpm --filter @bytelyst/trading-web typecheck`; `BYTELYST_PACKAGE_SOURCE=common-plat pnpm run audit:ui`; `BYTELYST_PACKAGE_SOURCE=common-plat pnpm run audit:ui:strict`; `git diff --check`. | `c6a05d5eb04989f4226d50f0dd7be490a0489dc1` | Strict audit is now part of the default root verification path. This slice changed only repo verification/docs; no trading-domain behavior changed. |

## Completion Status

- **Migration status**: Complete. All roadmap phases are checked complete and the strict UI baseline is enforced in `pnpm verify`.
- **Final verification on the closed baseline**: Passed `BYTELYST_PACKAGE_SOURCE=common-plat pnpm verify`, `BYTELYST_PACKAGE_SOURCE=common-plat pnpm run audit:ui:strict`, and `git diff --check`.
- **Source-linked common-platform note**: Because `web/vite.config.ts` aliases `@bytelyst/ui` to `/opt/bytelyst/learning_ai_common_plat/packages/ui/src/index.ts` when the local checkout is present, full verification requires the local common-platform checkout to have its own dependencies installed first via `pnpm -C /opt/bytelyst/learning_ai_common_plat install --no-frozen-lockfile`.
- **Ongoing maintenance rule**: Future UI work should keep `pnpm run audit:ui`, `pnpm run audit:ui:strict`, and adapter-first usage green unless a deliberate, documented deferral is accepted.

## 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.

## Closure Notes

- **Roadmap state**: Closed. This migration no longer has unchecked execution items.
- **Current audit baseline**: 0 direct `@bytelyst/ui` imports outside the adapter, 0 raw production controls outside approved primitives, 0 legacy global surface classes, and 0 hardcoded color literals in product code.
- **Audit note**: `web/src/index.css` token-definition literals are intentionally excluded from the hardcoded-color audit because they are the theme-source baseline.
- **Future work rule**: Any new UI slice should start from the enforced zero-debt baseline, prefer adapter/common primitives first, and only introduce product-local styling when it encodes trading semantics.
- **Verification rule**: For future UI changes, run `pnpm run audit:ui`, `pnpm run audit:ui:strict`, targeted DOM tests for touched files, `pnpm --filter @bytelyst/trading-web typecheck`, and `git diff --check`; add `pnpm --filter @bytelyst/trading-web lint` and `pnpm --filter @bytelyst/trading-web build` before larger commits.
- **Docs update rule**: If future UI work changes the baseline or introduces an accepted deferral, add a new roadmap row with the exact verification commands, results, and commit hash.
