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

## Remaining Work

- **Keep strict audit on the clean baseline**: With the current zero-debt audit, future slices should keep `pnpm run audit:ui` and `pnpm run audit:ui:strict` green unless new debt is intentionally introduced and documented.
- **Standardize new product surfaces through the adapter first**: Continue preferring adapter/common primitives for product-agnostic UI while keeping trading workflows and semantic chart palettes product-owned.
- **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.

## Next Agent Handoff

Use this document as the live source of truth for the remaining UI/UX platform-core migration. Before continuing, pull the latest repo state and rebase any local branch on top of the pushed roadmap updates:

```bash
git fetch origin
git pull --rebase origin main
```

Then read this file end-to-end and continue from the clean post-phase-12 baseline:

- **Current phase**: 12 is complete. New work should start from the zero-debt baseline rather than reopening legacy drift.
- **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.
- **Next focus**: keep future UI slices on the strict baseline, prefer adapter/common primitives first, and only introduce new product-local styling when it encodes trading semantics.
- **Verification after each slice**: run `pnpm run audit:ui`, targeted DOM tests for touched files, `pnpm --filter @bytelyst/trading-web typecheck`, and `git diff --check`; add `pnpm --filter @bytelyst/trading-web lint`, targeted Vitest slices, and `pnpm --filter @bytelyst/trading-web build` before major commits or adapter-related changes.
- **Roadmap update requirement**: after every implementation commit, update the roadmap row/checkboxes with the new status, final audit counts, exact verification commands, commit hash, and any deferrals or environment blockers.
- **Commit/push rule**: keep commits small and scoped, push each completed slice, then update this document in a follow-up docs commit so the next agent can resume without reconstructing context.
