From 42aaea03e50421781b4471e0b0f4ad7720d12955 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Fri, 29 May 2026 13:05:00 -0700 Subject: [PATCH] docs(admin-web): add ByteLyst UX integration roadmap (additive phase 1) --- .../docs/roadmaps/UX_INTEGRATION_ADMIN.md | 115 ++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 dashboards/admin-web/docs/roadmaps/UX_INTEGRATION_ADMIN.md diff --git a/dashboards/admin-web/docs/roadmaps/UX_INTEGRATION_ADMIN.md b/dashboards/admin-web/docs/roadmaps/UX_INTEGRATION_ADMIN.md new file mode 100644 index 00000000..531c9af7 --- /dev/null +++ b/dashboards/admin-web/docs/roadmaps/UX_INTEGRATION_ADMIN.md @@ -0,0 +1,115 @@ +# admin-web × ByteLyst UX Integration Roadmap + +> **Purpose:** Additively adopt the latest shared `@bytelyst/*` UX into the platform admin console — +> a token bridge, charts migration (`recharts` → `@bytelyst/charts`), command palette, page chrome, +> motion, and system banners — **without** ripping out the mature local shadcn `src/components/ui/*` +> layer (that wholesale replacement is explicitly out of scope for this phase). +> **Delegation target:** Devin CLI (`devin --prompt-file docs/roadmaps/UX_INTEGRATION_ADMIN.md`). +> +> **Repo:** `learning_ai_common_plat/dashboards/admin-web` (`@bytelyst/admin-web`) +> **Run dir:** this package · **Stack:** Next.js 16 · React 19 · TS 5 · Tailwind 4 · Vitest · Playwright +> **Showcase reference (read-only, do not edit):** `../../../copilot/learning_ai_uxui_web`. + +--- + +## Current-state review (verified 2026-05-29) + +admin-web is large (~45 dashboard surfaces) and has **two** UI layers: a mature local shadcn +`src/components/ui/*` (radix-based: button/dialog/select/tabs/…) **and** a `Primitives.tsx` adapter. +This roadmap is **additive** — it brings in shared capabilities the app lacks; it does **not** +rewrite the shadcn primitive layer. + +| Area | Today | Gap | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | +| Token system | shadcn OKLCH vars (`--background`/`--primary`/`--card`) + `.dark` | `@bytelyst/ui` expects `--bl-*` → **need a bridge** (wave 1) | +| UI-drift guard | `eslint.config.mjs` has **no** `no-restricted-imports` | add ratchet: direct `@bytelyst/ui` only via `Primitives.tsx` | +| Charts | **`recharts` directly in 5 files** (`(dashboard)/page`, `usage`, `users/[id]`, `ops/client-logs`, `docs`, `extraction/entity-chart`) | `@bytelyst/charts` + `@bytelyst/data-viz` | +| Command / nav | none (45 surfaces!) | `@bytelyst/command-palette` (⌘K) — high value | +| Page chrome | mixed | `@bytelyst/dashboard-components` (already a dep) | +| Motion | none | `@bytelyst/motion` (reduced-motion aware) | +| System messages | `broadcasts`/`maintenance`/`notifications` surfaces exist | `@bytelyst/notifications-ui` banners (if a real feed is reachable) | + +**Explicitly OUT of scope this phase:** replacing the local shadcn `src/components/ui/*` components +with `@bytelyst/ui` equivalents. Leave them as-is; only NEW UI and the waves below use shared packages. + +--- + +## Ground rules (non-negotiable) + +1. **Scope lock:** edit only files under `dashboards/admin-web/`. Never edit shared + `packages/@bytelyst/*`, other dashboards, services, the showcase, or any sibling repo. Never + `git push` outside `admin-web/`. +2. **Additive only:** do NOT rewrite the local shadcn `src/components/ui/*` layer. Route only NEW + shared-`@bytelyst/ui` usage through `src/components/ui/Primitives.tsx`. +3. **Deps are `workspace:*`** (common-plat convention) — match that, NOT `"*"`. Keep lockfile + changes minimal (importer link entries only); recover with `pnpm install --frozen-lockfile` if + within-repo links corrupt. Do NOT commit a full monorepo lockfile re-normalization or relink + `packages/ui/node_modules/@radix-ui/*` to a sibling store (this broke Turbopack/e2e on tracker-web). +4. **Tokens:** keep the shadcn OKLCH system; add a `--bl-*` → admin-token **bridge** (wave 1) so + shared components theme correctly in light + dark. Zero new hardcoded color literals. +5. **Tests are sacred** — never weaken/skip/delete; add a test per wave. +6. **Commit cadence:** verify → commit → push **per item** (`feat(admin-web): … (UX-N)`); never + leave >1 wave uncommitted; immediately tick the checkbox with **SHA + test counts**. Not done + until committed **and** pushed. +7. **Deferrals explicit** (`[~]` + reason + table row); **no stray files**; env blockers recorded here. + +### Verify (after EVERY wave + final sweep) + +```bash +pnpm --filter @bytelyst/admin-web typecheck +pnpm --filter @bytelyst/admin-web lint +pnpm --filter @bytelyst/admin-web test +pnpm --filter @bytelyst/admin-web format:check +pnpm --filter @bytelyst/admin-web build +pnpm --filter @bytelyst/admin-web test:e2e # Playwright + @axe-core (no new failures vs wave-1 baseline) +# size:check (bundlesize) where it runs in this env; else record gzipped sizes here +``` + +--- + +## Waves + +- [ ] **UX-1 — Token bridge + UI-drift ratchet (FIRST):** add a `--bl-*` → admin OKLCH bridge in + `globals.css` (light + dark); add ESLint `no-restricted-imports` forbidding direct + `@bytelyst/ui` imports outside `Primitives.tsx`; add a Primitives export-presence test. Capture + the e2e baseline below. +- [ ] **UX-2 — Charts:** migrate the ~6 `recharts` usages to `@bytelyst/charts` (+ `@bytelyst/data-viz` + `KpiCard`/`Sparkline` for stat tiles), lazy-loaded; render tests (no NaN in SVG). Drop `recharts` + if fully unused afterward. +- [ ] **UX-3 — Command palette:** add `@bytelyst/command-palette`; mount `CommandRegistryProvider` + + `CommandPalette` (⌘K, lazy) in `(dashboard)/layout.tsx`; register navigate commands for the major + surfaces (Users, Billing, Flags, Broadcasts, Audit, Experiments, Subscriptions, Licenses, Ops, …) + theme toggle + sign out; Vitest test palette opens on ⌘K. +- [ ] **UX-4 — Page chrome:** use `@bytelyst/dashboard-components` (`PageHeader`/`ErrorPage`/ + `NotFoundPage`/`LoadingSpinner`) on `error.tsx`/`not-found.tsx`/`loading.tsx` + a few high-traffic + surfaces where chrome is bespoke. Keep it additive. +- [ ] **UX-5 — Motion:** add `@bytelyst/motion`; subtle `Reveal`/`Stagger` on the overview dashboard + cards + key tables; respect `prefers-reduced-motion`. (Note tracker-web's lesson: do NOT apply + motion to surfaces an offline axe gate scans synchronously if transient opacity trips contrast.) +- [ ] **UX-6 — System banners (conditional):** if a real broadcasts/maintenance feed is reachable, + add `@bytelyst/notifications-ui` `BannerStack`/`Announcement` in `(dashboard)/layout.tsx`. + `NotificationCenter` only with a real feed; else **defer**. + +## Cross-cutting + +- [ ] **CC.1** Full suite + build green every wave. · [ ] **CC.2** Dark-mode parity (bridge works in `.dark`). +- [ ] **CC.3** No new color literals. · [ ] **CC.4** No new a11y violations; labels on all controls. +- [ ] **CC.5** Bundle: dynamic `import()` for charts/palette; record gzipped sizes / `size:check`. +- [ ] **CC.6** Final tracker + Deferrals table complete. + +## Progress tracker + +``` +Setup : UX-1 ⬜ +Adopt : UX-2 ⬜ UX-3 ⬜ UX-4 ⬜ UX-5 ⬜ UX-6 ⬜(cond) +Cross : CC.1 ⬜ CC.2 ⬜ CC.3 ⬜ CC.4 ⬜ CC.5 ⬜ CC.6 ⬜ +``` + +## E2e baseline (fill on UX-1) + +_(record `pnpm --filter @bytelyst/admin-web test:e2e` passed/failed here; each wave must add no new failures)_ + +## Deferrals (fill in as encountered) + +| Item | Reason (surface/data gate) | Follow-up | +| ------------ | -------------------------- | --------- | +| _(none yet)_ | | |