docs(admin-web): add ByteLyst UX integration roadmap (additive phase 1)
This commit is contained in:
saravanakumardb1
parent
060daa4883
commit
42aaea03e5
115
dashboards/admin-web/docs/roadmaps/UX_INTEGRATION_ADMIN.md
Normal file
115
dashboards/admin-web/docs/roadmaps/UX_INTEGRATION_ADMIN.md
Normal file
@ -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)_ | | |
|
||||
Loading…
Reference in New Issue
Block a user