docs(tracker-web): expand UX integration roadmap (UX-9..UX-13 + cross-cutting)

Re-audited tracker-web against the full showcase catalog (~60 entries) and added delegate-ready waves beyond the core UX-1..8: - UX-9 complete the Primitives adapter + export-presence test (closes the Primitives.tsx 0%-coverage gap without a jsdom dep) - UX-10 page chrome via @bytelyst/dashboard-components (ErrorPage, PageHeader) - UX-11 @bytelyst/auth-ui on the login + MFA surface (presentation only) - UX-12 detail/board richness (Tabs/Tooltip/Drawer/Timeline; rich-text stretch) - UX-13 @bytelyst/notifications-ui (stretch, data-gated) - CC.6 UI-drift ESLint ratchet, CC.7 bundle budget, CC.8 coverage ratchet Also refreshed the entry point (UX-1 done -> start at UX-2) and the gap matrix.
2026-05-28 20:22:56 -07:00 · 2026-05-28 20:22:56 -07:00 · 3515fbddc5
commit 3515fbddc5
parent b9bc2163f4
1 changed files with 92 additions and 6 deletions
--- a/dashboards/tracker-web/docs/roadmaps/UX_INTEGRATION_BYTELYST.md
+++ b/dashboards/tracker-web/docs/roadmaps/UX_INTEGRATION_BYTELYST.md
@ -34,7 +34,20 @@
 - `@bytelyst/charts`: `LineChart` `BarChart` `AreaChart` `Donut` `Gauge`
 - `@bytelyst/data-viz`: `Sparkline` `BarSparkline` `KpiCard` `ProgressRing` `Heatmap`
 - `@bytelyst/command-palette`: `CommandPalette` `CommandRegistryProvider` `useCommandPalette`
- `@bytelyst/motion`: `Reveal` `Stagger` `NumberFlow` … (see showcase `/showcase/motion/all`)
+- `@bytelyst/motion`: `Reveal` `Stagger` `NumberFlow` `TiltCard` `ScrollProgress` … (see `/showcase/motion/all`)
+- `@bytelyst/ui` (not yet in the adapter): `Tooltip` `Tabs` `SegmentedControl` `DropdownMenu`
+  `Switch` `Checkbox` `RadioGroup` `Select` `Textarea` `Panel` `Surface` `Card` `Separator`
+  `DataList` `Timeline` `Drawer` `ActionMenu` `IconButton` `AlertBanner`
+- `@bytelyst/dashboard-components`: `PageHeader` `ErrorPage` `NotFoundPage` `EmptyState`
+  `LoadingSpinner` `LoadingSkeleton`
+- `@bytelyst/auth-ui`: `LoginForm` `MfaChallenge` `SocialButtons` `PasswordStrengthBar` …
+- `@bytelyst/notifications-ui`: `NotificationCenter` `InboxItem` `BannerStack` `Announcement`
+- `@bytelyst/rich-text`: `RichTextEditor` (Tiptap v3, slash + mentions) · `RichTextViewer`
+
+> **Expansion (2026-05-28):** waves **UX-9 … UX-13** below were added after re-auditing
+> tracker-web against the full showcase catalog (`src/catalog/routes.ts`, ~60 entries).
+> They are sequenced **after** the core UX-2 … UX-8 migration and several are explicitly
+> **stretch / data-gated** — do not start them until the wave they depend on is green.

 > Aligns with master `docs/ROADMAP.md` Phase 2.1 (UI primitives migration) — this roadmap is the
 > concrete, delegate-ready execution plan and extends it with charts/palette/toast/motion.
@ -156,6 +169,66 @@ pnpm build      # final gate
      toggle), keeping `ProductSwitcher`, user email, sign-out, and adding the ⌘K trigger + theme
      toggle. **Verify:** `pnpm typecheck && pnpm lint && pnpm build`; keyboard nav + skip-link work.

+## UX-9 — Complete the Primitives adapter (+ close the coverage gap)
+
+> The adapter (`src/components/ui/Primitives.tsx`) currently re-exports ~12 components and
+> sits at **0% test coverage** (flagged in `docs/TEST_VALIDATION_LOG.md`). Broaden it and
+> lock it with a cheap export-presence test — no `@testing-library/react`/jsdom needed.
+
+- [ ] **9.1** Extend `Primitives.tsx` to also re-export the shared controls the app will need
+      in later waves: `Select` `Textarea` `Checkbox` `Switch` `RadioGroup` `Tooltip` `Tabs`
+      `SegmentedControl` `DropdownMenu` `Drawer` `ActionMenu` `IconButton` `AlertBanner`
+      `Card` `Panel` `Separator` `DataList` `Timeline`. Keep app code importing only from the
+      adapter (preserves the UI-drift ratchet).
+- [ ] **9.2** Add `src/__tests__/primitives-adapter.exports.test.ts` asserting every adapter
+      export is `defined` (a pure import test — raises `Primitives.tsx` off 0% without a DOM dep).
+      **Verify:** `pnpm typecheck && pnpm lint && pnpm test && pnpm build`.
+
+## UX-10 — Page chrome via `@bytelyst/dashboard-components`
+
+- [ ] **10.1** `src/app/error.tsx`: render `ErrorPage` from `@bytelyst/dashboard-components`
+      (keep the existing `trackEvent` telemetry side-effect + `reset` wiring). `not-found.tsx`
+      already uses `NotFoundPage` — leave it.
+- [ ] **10.2** Add `PageHeader` (title + breadcrumbs) to the top of `/dashboard`, `/dashboard/items`,
+      `/dashboard/board`, and the item detail page for a consistent header band.
+- [ ] **10.3** Replace ad-hoc loading text with `LoadingSpinner`/`LoadingSkeleton` where a full
+      `SkeletonGroup` (UX-2) is overkill.
+      **Verify:** `pnpm typecheck && pnpm lint && pnpm build`.
+
+## UX-11 — Adopt `@bytelyst/auth-ui` on the login surface
+
+> `src/app/login/page.tsx` is a hand-rolled `<form>` with a second MFA step. The existing
+> `/api/auth/*` proxy routes and `auth-context` stay as-is — only the **presentation** changes.
+
+- [ ] **11.1** Add `@bytelyst/auth-ui` as a `workspace:*` dep; `pnpm install` from the root.
+- [ ] **11.2** Replace the password form with `LoginForm` and the OTP step with `MfaChallenge`,
+      wiring their submit handlers to the current login/MFA fetch calls. Add `SocialButtons`
+      only for providers the backend actually supports (gate on `/api/auth/oauth/[provider]`).
+- [ ] **11.3** Keep all existing auth tests green; add a render test asserting the login form
+      shows email/password fields + submit.
+      **Verify:** `pnpm typecheck && pnpm lint && pnpm test && pnpm build`.
+
+## UX-12 — Detail & board richness (Tabs · Tooltip · Drawer · Timeline · rich-text)
+
+- [ ] **12.1** `/dashboard` board↔list: use `SegmentedControl` (or `Tabs`) for the view toggle
+      instead of bespoke buttons; `Tooltip` on truncated titles / status dots.
+- [ ] **12.2** Item detail: move row/item actions into an `ActionMenu`, and render the item's
+      activity/comment history with `Timeline`.
+- [ ] **12.3** _(stretch — needs HTML-capable description/comment storage)_ Swap the plain
+      description/comment `<textarea>` for `RichTextEditor`, and render saved content with
+      `RichTextViewer`. **Only do this if** the backend stores/returns rich HTML safely;
+      otherwise leave `- [ ]` with a note. **Verify per task:** `pnpm typecheck && pnpm lint && pnpm build`.
+
+## UX-13 — Notifications surface via `@bytelyst/notifications-ui` (stretch / data-gated)
+
+> **Gate:** only build this if tracker has (or will get) a notifications data source. If there
+> is no feed, ship just the `BannerStack` for client-side system messages and leave the rest `- [ ]`.
+
+- [ ] **13.1** Add `@bytelyst/notifications-ui`; mount a `NotificationCenter` bell in the header
+      (or AppShell from UX-8) fed by the notifications API, with `InboxItem` rows.
+- [ ] **13.2** Use `BannerStack` for top-of-page system/maintenance messages and `Announcement`
+      for a dismissible "what's new" pill. **Verify:** `pnpm typecheck && pnpm lint && pnpm build`.
+
 ## Cross-cutting (run continuously)

 - [ ] **CC.1** Full suite green after every wave: `pnpm typecheck && pnpm lint && pnpm test && pnpm build`.
@ -165,14 +238,27 @@ pnpm build      # final gate
      and `/login`; otherwise Vitest render assertions for roles/labels.
 - [ ] **CC.5** Update master `docs/ROADMAP.md` Phase 2.1 checkboxes **only if** the operator asks —
      default: leave it, this doc is the source of truth for the integration.
+- [ ] **CC.6** **UI-drift ratchet:** once UX-9 lands, add an ESLint `no-restricted-imports` rule
+      forbidding direct `@bytelyst/ui` imports outside `src/components/ui/Primitives.tsx`, so all
+      future UI goes through the adapter. Fix any existing violations in the same commit.
+- [ ] **CC.7** **Bundle budget:** after chart/motion/rich-text waves, re-check the `bundlesize`
+      budgets in `package.json`. If a route grows, prefer dynamic `import()` for heavy surfaces
+      (charts, rich-text editor) over raising a budget. Note the gzipped sizes in the log.
+- [ ] **CC.8** **Coverage ratchet:** keep the enforced Vitest thresholds (80%) green; each wave
+      that adds a component should add the render/export test that keeps `Primitives.tsx` and new
+      surfaces above threshold (no silently-dead gates — see `docs/TEST_VALIDATION_LOG.md`).

 ## Progress

 ```
-UX-1 ✅  UX-2 ⬜  UX-3 ⬜  UX-4 ⬜  UX-5 ⬜  UX-6 ⬜  UX-7 ⬜  UX-8 ⬜
+Core   : UX-1 ✅  UX-2 ⬜  UX-3 ⬜  UX-4 ⬜  UX-5 ⬜  UX-6 ⬜  UX-7 ⬜  UX-8 ⬜
+Expand : UX-9 ⬜  UX-10 ⬜  UX-11 ⬜  UX-12 ⬜  UX-13 ⬜   (stretch: 12.3, 13.*)
 ```

-**Start with UX-1** (token bridge + adapter) — without the `--bl-*` bridge, every shared component
-renders unstyled. Read `src/app/globals.css`, the showcase `globals.css` fallback layer, and
-`src/app/dashboard/items/page.tsx` (the working `data-table` adoption) before editing. Then execute
-one task at a time with verify + commit after each.
+**UX-1 is done** (token bridge + Primitives adapter, commit `dc01dd02`) — the `--bl-*` bridge is
+live, so shared components already inherit tracker's theme. **Start with UX-2.** Before editing,
+read `src/app/globals.css` (the `--bl-*` bridge), `src/components/ui/Primitives.tsx` (the adapter
+all app code imports from), and `src/app/dashboard/items/page.tsx` (the working `data-table`
+adoption — the reference pattern). Execute **one task at a time**, verify + commit after each, and
+do the **Core** waves (UX-2 … UX-8) before the **Expand** waves (UX-9 … UX-13). Treat 12.3 and all
+of UX-13 as data-gated stretch — leave them `- [ ]` with a note if the backend can't support them.