diff --git a/docs/UI_ROADMAP_2026_V3_CROSS_REPO.md b/docs/UI_ROADMAP_2026_V3_CROSS_REPO.md new file mode 100644 index 00000000..acbaccd6 --- /dev/null +++ b/docs/UI_ROADMAP_2026_V3_CROSS_REPO.md @@ -0,0 +1,369 @@ +# ByteLyst Cross-Repo UX Roadmap — v3 (Future-Proof, Elegant, Rich) + +> **Status:** Draft for review · 2026-05-27 +> **Owners:** ByteLyst Platform UI guild +> **Predecessor:** `learning_ai_uxui_web/docs/ROADMAP_2026.md` v2.5 (Waves 1–7) +> **Scope:** Every product web app under `/Users/sd9235/code/mygh/` + the common platform packages that should serve them. + +This document **extends** the v2 roadmap rather than replacing it. v2 covered shared packages in isolation; v3 walks the ecosystem floor — looks at what each of the **11 product webs** actually ships today, finds the duplication, and prescribes the next 5 platform waves (Wave 8 – Wave 12) plus a per-product upgrade matrix. + +--- + +## 1. Where we are (May 2026) + +### Shared `@bytelyst/*` packages currently published or in-tree (72) + +| Tier | Packages | +| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Foundation** | `errors`, `config`, `logger`, `testing`, `events`, `event-store`, `queue`, `storage`, `datastore`, `cosmos`, `blob`, `extraction`, `llm`, `llm-router`, `auth`, `field-encrypt`, `client-encrypt`, `palace`, `sync`, `offline-queue` | +| **Service / SDK** | `api-client`, `auth-client`, `react-auth`, `secure-storage-web`, `platform-client`, `telemetry-client`, `feature-flag-client`, `kill-switch-client`, `diagnostics-client`, `feedback-client`, `subscription-client`, `survey-client`, `billing-client`, `blob-client`, `broadcast-client`, `org-client`, `marketplace-client`, `referral-client`, `mcp-client`, `ollama-client`, `gentle-notifications`, `time-references`, `celebrations`, `webhook-dispatch`, `push`, `accessibility`, `use-keyboard-shortcuts`, `use-theme`, `quick-actions` | +| **Backend infra** | `backend-config`, `backend-flags`, `backend-telemetry`, `fastify-core`, `fastify-auth`, `fastify-sse` | +| **UI / UX (v2)** | `design-tokens`, `ui`, `auth-ui`, `dashboard-components`, `dashboard-shell`, **`ai-ui`** (Wave 2), **`command-palette`** (Wave 3), **`motion`** (Wave 4), **`data-viz`** (Wave 5b), **`notifications-ui`** (Wave 7), `monitoring` | +| **Native (out-of-scope for v3 web work)** | `kotlin-platform-sdk`, `swift-platform-sdk`, `swift-diagnostics`, `react-native-platform-sdk`, `speech`, `devops`, `create-app` | + +### v2 wave status (as of `acb8f02b`) + +| Wave | Theme | Status | +| ---- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| 1 | Foundations · tokens · density · LHCI · vis-reg | **✅ shipped** (DTCG v3 RFC + Storybook rollout still incremental) | +| 2 | `@bytelyst/ai-ui` | **✅ 0.4.0 shipped** — 8 components, 2 hooks, 53/53 tests | +| 3 | `@bytelyst/command-palette` | **✅ 0.1.0 shipped** — 26/26 tests, Cmd-K live in showcase | +| 4 | `@bytelyst/motion` | **✅ 0.1.0 shipped** — Reveal, Stagger, NumberFlow, Tilt, ScrollProgress | +| 5a | Forms additions to `@bytelyst/ui` | 📋 not started | +| 5b | `@bytelyst/data-viz` | **✅ 0.1.0 shipped** — Sparkline, KpiCard, ProgressRing, Heatmap (+ SSR-safe useId fix in `acb8f02b`) | +| 5c | `@bytelyst/adaptive-ui` (SchemaForm / StreamUI) | 📋 not started | +| 6 | Mobile · inclusive · i18n | 📋 not started | +| 7 | `@bytelyst/notifications-ui` | **✅ 0.1.0 shipped** — NotificationCenter, InboxItem, BannerStack, Announcement | +| 7 | `@bytelyst/billing-ui` | 📋 not started | +| 7 | `@bytelyst/onboarding-ui` | 📋 not started | +| 7 | `@bytelyst/telemetry-ui`, `brand-*`, PWA, create-app | 📋 not started | + +--- + +## 2. Cross-repo audit — what every product web actually ships + +Sampled from `/Users/sd9235/code/mygh/{learning_ai_clock,learning_ai_notes,learning_ai_flowmonk,learning_ai_jarvis_jr,learning_ai_fastgap,learning_ai_local_memory_gpt,learning_voice_ai_agent,learning_ai_trails,learning_ai_dev_intelli}/web` plus the upcoming reference in `/copilot/learning_ai_uxui_web`. + +### 2.1 `@bytelyst/*` package consumption matrix + +| Product | `ui` | `design-tokens` | `react-auth` | `telemetry-client` | `feature-flag-client` | `dashboard-components` | `dashboard-shell` | `ai-ui` | `command-palette` | `motion` | `data-viz` | `notifications-ui` | +| ---------------------- | -------------------- | --------------- | ------------ | ------------------ | --------------------- | ---------------------- | ----------------- | ------- | ----------------- | -------- | ---------- | ------------------ | +| clock/web | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | — | — | — | — | +| notes/web | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | — | — | — | +| flowmonk/web | ✅ | ✅ | ✅ | — | ✅ | — | — | — | — | — | — | — | +| jarvisjr/web | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | — | — | — | — | +| fastgap/web | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | — | — | — | +| localmemgpt/web | ✅ | ✅ | — | ✅ | ✅ | — | — | — | — | — | — | — | +| voice (user-dashboard) | — | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | — | — | — | +| trails/web | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | — | — | — | — | +| dev-intelli/web | ✅ | ✅ | ✅ | ✅ | ✅ | — | — | — | — | — | — | — | +| nomgap/web | (sampled separately) | … | … | … | … | … | — | — | — | — | — | — | + +**Observation:** none of the 11 product webs consume the **5 newest UI packages** (`ai-ui`, `command-palette`, `motion`, `data-viz`, `notifications-ui`). All five are shipped to source but **awaiting publish** to the Gitea npm registry (still tracked as TODO #14 in v2.5). This is the single highest-impact unblock in v3 — see Wave 8. + +### 2.2 Duplicated / reimplemented surfaces + +Patterns found 3+ times across product repos that should collapse into shared packages: + +| Surface | Found in | Proposed home | +| ------------------------------------------------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------- | +| **`Skeleton.tsx`** (shimmer loading) | clock, notes, flowmonk, jarvisjr, fastgap, trails | `@bytelyst/ui/skeleton` (extend existing `ui`) | +| **Modal / Dialog wrappers** (`CreateXModal.tsx`, `LinkXModal.tsx`) | clock (1), notes (4), fastgap (2) | `@bytelyst/ui/modal` v2 (composable; replaces bespoke) | +| **Sidebar layout** (`Sidebar.tsx`, route-aware) | notes, flowmonk, jarvisjr (+ many more) | `@bytelyst/dashboard-shell@0.3.0` — generic, slot-based | +| **`OnboardingOverlay.tsx` / tour steps** | clock (1), fastgap (1), notes (TBD) | new `@bytelyst/onboarding-ui` (Wave 7-pending → Wave 9) | +| **`AgentTimeline.tsx`** (bespoke vertical thought-trace) | notes (1) | already in `@bytelyst/ai-ui` — direct swap (Wave 8) | +| **`MemoryTimeline.tsx`** | notes (1), likely mindlyst | new `@bytelyst/timeline` (Wave 11) | +| **Recharts wrappers** (KPI tiles, line/bar/area) | clock, jarvisjr, fastgap, voice (user-dashboard) | new `@bytelyst/charts` (Wave 9) | +| **Tiptap editor** (rich-text body) | notes only (today); mindlyst, jarvisjr planned | new `@bytelyst/rich-text` (Wave 9) | +| **Toast / sonner** | notes, fastgap | already in `@bytelyst/ui/toast` — sonner usage to deprecate (Wave 8 hygiene) | +| **Date-fns + bespoke pickers** | clock, jarvisjr, voice | new `@bytelyst/ui/date-picker` (Wave 5a) | +| **Empty states** (`No items yet…`) | every product | new `@bytelyst/ui/empty-state` (Wave 5a) | +| **Settings panel** (account / API keys / billing / privacy) | every product | new `@bytelyst/settings-ui` (Wave 10) | +| **Filter bar / search input + chips** | notes, fastgap, voice, jarvisjr | new `@bytelyst/ui/filter-bar` (Wave 9) | +| **Data table / virtualised list** | notes, fastgap, voice | new `@bytelyst/data-table` (Wave 9, TanStack Table v9) | +| **Privacy / Legal pages** | jarvisjr (only) | new `@bytelyst/legal-ui` (Wave 10) | + +### 2.3 Tech currently mixed across products + +| Need | Library in product | Recommendation | +| -------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------- | +| Charting | `recharts` (5+ apps) | Wrap recharts in `@bytelyst/charts` with token theming — keep recharts as peer dep | +| Toasts | `sonner` (notes, fastgap) | `@bytelyst/ui/toast` already exists; align all apps | +| Drag-drop reordering | none yet | Adopt `@dnd-kit/sortable`, expose via `@bytelyst/ui/sortable` | +| Virtualisation | none yet | Adopt `@tanstack/react-virtual`, expose via `@bytelyst/ui/virtual-list` | +| Animations | `framer-motion` (clock) | Migrate to `@bytelyst/motion` (already shipped) — smaller bundle | +| Forms | bespoke + `zod` (clock, flowmonk, jarvisjr) | Adopt `react-hook-form` + `zod` resolver, expose via `@bytelyst/ui/form` (Wave 5a) | +| Date picking | none consistent | `@bytelyst/ui/date-picker` on `react-day-picker` v9 | +| Rich text | `@tiptap/*` (notes) | `@bytelyst/rich-text` (Wave 9) | + +--- + +## 3. Future-proof UX themes & design patterns to adopt + +The v2 roadmap nailed accessibility, motion, density, AI-native primitives. v3 layers in the **next-decade design language** that products like Linear, Arc, Raycast, Vercel, Apple Intelligence and Material 3 Expressive are pushing in 2025-26: + +### 3.1 Visual language + +| Theme | What it means | Where it lands | +| --------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| **OKLCH / Display-P3 palettes** | Perceptually-uniform colour math; vibrant on modern displays; safe fallback to sRGB | `design-tokens` v3 — Tier 1 emits both `oklch()` and `color(display-p3 ...)` with `@supports` fallback | +| **Glass + depth (selective)** | Translucent surfaces with `backdrop-filter`, layered shadows; **not** for body text | `ui/Surface`, modal/popover variants | +| **Soft gradients + mesh** | OKLCH-driven background washes (no banding) | Landing pages, hero sections; `motion/MeshBackground` | +| **Material 3 Expressive springs** | Larger, more emotive transitions (~600ms) for hero interactions | New `SPRINGS.expressive` preset in `@bytelyst/motion` | +| **Ambient / calm UI** | Low-saturation default state; saturation lifts on focus | `data-mood` token tier (`calm` / `focus` / `celebrate`) | +| **Tactile micro-feedback** | Press-state scale (0.98), hover lift, haptic-style cubic-bezier | Already in tokens; **codify in `@bytelyst/motion/Pressable`** | +| **Variable typography** | Variable axes (`wght`, `opsz`, `GRAD`) on Inter Variable + Atkinson Hyperlegible | `design-tokens` Tier 1 — `font-variation-settings` | +| **Iconography v2** | Lucide v0.500+ as default; add provider for Phosphor / Tabler swap | New `@bytelyst/icons` peer-deps re-export | + +### 3.2 Platform capabilities to wire in (2025-26 web platform) + +| Capability | Browser support | Where it lands | +| ------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------- | +| **View Transitions API (same-doc + cross-doc)** | Chrome 126+ / Safari 18+ / Firefox 132+ (cross-doc) | `@bytelyst/motion/PageTransition` (Wave 4 stretch) — with fallback | +| **CSS Anchor Positioning** | Chrome 125+ / Safari TP / Firefox flag | Replace JS-anchored tooltips/popovers in `@bytelyst/ui` | +| **`` + invoker `command`/`commandfor`** | Chrome 134+ | `ui/Modal` to use native `` + invoker fallback | +| **Popover API (`popover` attribute)** | All evergreen | `ui/Tooltip`, `ui/Dropdown`, `ui/Menu` upgrade | +| **Container queries everywhere** | All evergreen | Already partial; codify `@container` breakpoints in `design-tokens` | +| **`color-mix()` / `color()` / relative colour syntax** | All evergreen | Already used by `data-viz/Heatmap`; expand to `ui` | +| **Scroll-driven animations (`animation-timeline: scroll()`)** | Chrome 115+ | `@bytelyst/motion/ScrollLinked` primitive | +| **`@scope`** | Chrome 118+ / Safari 17.4+ | Scope brand overrides cleanly without selector wars | +| **`text-wrap: balance` / `text-wrap: pretty`** | All evergreen | Default on headings via `ui/Heading` | +| **CSS nesting** | All evergreen | Update `globals.css` patterns | +| **`field-sizing: content`** | Chrome 123+ | `ui/Textarea` auto-grow without JS | +| **Web Speech API** | All evergreen (Chrome best) | `@bytelyst/speech-ui` — voice-input button, dictation | +| **WebAuthn / Passkeys** | All evergreen | `ui/PasskeyButton` (Wave 5a) | +| **WebGPU** (when stable) | Chrome 113+ / Safari 26 | Document-heavy products only (e.g. mindlyst) — defer beyond v3 | +| **OffscreenCanvas + Worker** | All evergreen | Charts re-render off-thread (`@bytelyst/charts`) | + +### 3.3 AI-native UX patterns (extend Wave 2) + +| Pattern | Surface | +| ---------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| **Generative UI** (LLM emits component tree from JSON Schema) | `@bytelyst/adaptive-ui/StreamUI` (Wave 5c) | +| **Suggestion chips** (next-action prediction) | `ai-ui/SuggestionRow` (Wave 8 v0.5) | +| **Inline AI rewrite** (highlight → "Make shorter" / "Translate") | `ai-ui/InlineAI` (Wave 8 v0.5) | +| **Confidence chrome** (delta arrow + ± range + source) | `data-viz/KpiCard` already supports trend; add `confidence` (Wave 9) | +| **Agentic progress** (steps, retries, cancellations) | `ai-ui/AgentTimeline` already supports — add cancel/retry actions (Wave 8 v0.5) | +| **Ambient assistant** (subtle dot, summon with ⌘J) | `@bytelyst/assistant-shell` (Wave 11) | +| **Voice-first composer** (push-to-talk in `PromptComposer`) | `ai-ui/PromptComposer.voiceInput` (Wave 8 v0.6) — uses `@bytelyst/speech-ui` | +| **Citations everywhere** (any text can attach `CitationChip`s) | `ui/Markdown` (Wave 5c) renders inline citations | + +--- + +## 4. The next five waves + +Builds on v2.5. All effort in person-weeks (pw). + +### **Wave 8 — Unblock & rollout** _(weeks 16–18, ~4 pw)_ + +> **Theme:** ship what's built; remove the showcase's "vendored snapshot" workaround; get every product onto the new packages. + +| # | Status | Deliverable | Effort | +| --- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | +| 8.1 | 📋 | Trigger common_plat publish workflow → push **`react-auth@0.2.0`**, **`dashboard-shell@0.2.0`**, **`design-tokens@0.2.0`**, **`ai-ui@0.4.0`**, **`command-palette@0.1.0`**, **`motion@0.1.0`**, **`data-viz@0.1.0`**, **`notifications-ui@0.1.0`** to the Gitea registry | 0.5 pw | +| 8.2 | 📋 | Showcase: delete `src/lib/*-preview/` snapshots; swap imports to registry packages (TODO #14) | 0.5 pw | +| 8.3 | 📋 | Cross-repo dep update PR: every product web pins `@bytelyst/design-tokens@0.2.0` + adopts at least one new package (`motion` is the easiest first win — landing-page reveals) | 1 pw | +| 8.4 | 📋 | Migrate `learning_ai_notes/web/src/components/AgentTimeline.tsx` → `@bytelyst/ai-ui/AgentTimeline` (delete bespoke) | 0.5 pw | +| 8.5 | 📋 | Migrate `learning_ai_clock` `framer-motion` usage → `@bytelyst/motion` (Reveal + Stagger only on landing + history pages) | 0.5 pw | +| 8.6 | 📋 | Migrate every product `Skeleton.tsx` → `@bytelyst/ui/skeleton` (new sub-surface — see Wave 5a) | 0.5 pw | +| 8.7 | 📋 | Wire `@bytelyst/command-palette` into 3 pilot products (notes, jarvisjr, fastgap) with at minimum nav + theme commands | 0.5 pw | + +**DoD:** zero vendored snapshots in showcase · `pnpm outdated --filter "*web*"` shows current `@bytelyst/*` versions · 3 products live with Cmd-K. + +--- + +### **Wave 9 — Data, content, search** _(weeks 17–20, ~10 pw)_ + +> **Theme:** the surfaces every product reinvented — charts, rich-text editing, filterable lists. Each is a separate package so products opt in. + +| # | Package / surface | Notes | Effort | +| --- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | +| 9.1 | **`@bytelyst/charts@0.1.0`** | Recharts wrapper + token theming. Components: ``, ``, ``, ``, ``, ``, ``. Plug-in `OffscreenCanvas` mode for big series. Peer dep on `recharts@^2.15`. | 2 pw | +| 9.2 | **`@bytelyst/rich-text@0.1.0`** | Tiptap v2 wrapper. Exports: ``, ``, default toolbar (bold/italic/headings/lists/links/code), slash menu, mention extension. Theming via tokens. Peer dep on `@tiptap/*`. | 2 pw | +| 9.3 | **`@bytelyst/data-table@0.1.0`** | TanStack Table v9 + TanStack Virtual. Sortable headers, column resize, pinned columns, faceted filters, row selection, keyboard nav, sticky header. Variants: `compact` / `comfortable`. | 2 pw | +| 9.4 | **`@bytelyst/ui` v2.x — filter & search additions** | `` (chips + clear-all), `` (with suggestions slot), `` (illustration slot + CTA), ``, `` (formalise Wave 5a). | 1.5 pw | +| 9.5 | **`@bytelyst/ui` v2.x — skeleton + loading** | `` shimmer with shape variants (`text` / `rect` / `circle` / `card`), `` (orchestrates fade-out → content), ``, `` with token-tinted variants. | 0.5 pw | +| 9.6 | `ai-ui@0.5.0` | `` (with citation interop), ``, ``, `usePromptHistory()`, `useTokenCount()`. Closes Wave 2 deferred items. | 1 pw | +| 9.7 | `data-viz@0.2.0` | `` (SSE subscribed), `` (re-export from charts), `` (token-tinted), ``, `` (stretch). Add `confidence` prop to ``. | 1 pw | + +**DoD:** 3 products consume `charts` · 1 product (notes) consumes `rich-text` · `data-table` deployed in at least the tracker-web admin views. + +--- + +### **Wave 10 — Product surfaces & shells** _(weeks 19–22, ~9 pw)_ + +> **Theme:** every product builds the same chrome from scratch. Stop doing that. + +| # | Package / surface | Notes | Effort | +| ---- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | +| 10.1 | **`@bytelyst/dashboard-shell@0.3.0`** | Slot-based shell: `
`. Sidebar with collapsible groups, badges, route-active states. Topbar with breadcrumbs + user menu + Cmd-K trigger + theme picker + notifications bell slot. Density-aware. Mobile drawer mode auto-applied <768px. | 2 pw | +| 10.2 | **`@bytelyst/onboarding-ui@0.1.0`** | ``, ``, ``, ``, `useTour()`. Persists progress in localStorage. Token-themed. | 1.5 pw | +| 10.3 | **`@bytelyst/billing-ui@0.1.0`** | ``, ``, ``, ``, ``. Wired to `platform-service` Stripe module via `@bytelyst/subscription-client` + `@bytelyst/billing-client`. | 1.5 pw | +| 10.4 | **`@bytelyst/settings-ui@0.1.0`** | `` (left-rail nav), ``, `` (passkey + 2FA), ``, ``, ``. | 1 pw | +| 10.5 | **`@bytelyst/legal-ui@0.1.0`** | ``, ``, `` (token-themed, EAA-compliant), ``. Driven by a single MDX corpus shipped with each product. | 0.5 pw | +| 10.6 | **`@bytelyst/telemetry-ui@0.1.0`** | `data-bl-event` attribute scraper + React provider; auto-emits to `@bytelyst/telemetry-client`. `useTrackedClick(name)` hook. PostHog + OpenTelemetry compatible. | 1 pw | +| 10.7 | **`@bytelyst/timeline@0.1.0`** | Generic vertical event timeline — extracts pattern from `notes/MemoryTimeline.tsx`. Groups by day, infinite scroll, sticky date headers, search. | 1 pw | +| 10.8 | **Brand-layer packages** | `@bytelyst/brand-flowmonk`, `brand-chronomind`, `brand-mindlyst` — Tier-2 token overrides. Multi-tenant runtime: `` reads from URL/header. | 0.5 pw | + +**DoD:** 3 products use `dashboard-shell@0.3.0` end-to-end · onboarding-ui ships in nomgap (highest-value) · settings-ui used by ≥ 2 products. + +--- + +### **Wave 11 — Adaptive / ambient / multimodal** _(weeks 21–24, ~8 pw)_ + +> **Theme:** the futuristic layer. Generative UI, ambient assistant, multimodal input. + +| # | Package / surface | Notes | Effort | +| ---- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | +| 11.1 | **`@bytelyst/adaptive-ui@0.1.0`** | `` (JSON Schema → accessible form, react-hook-form under the hood), ``, **``** — renders LLM-emitted component trees from a constrained schema (à la Vercel AI SDK `streamUI`, but transport-agnostic). | 2.5 pw | +| 11.2 | **`@bytelyst/assistant-shell@0.1.0`** | Ambient assistant — small floating dot, summon with ⌘J. Mounts `ai-ui/ChatStream` in a sheet with context-aware system prompt (sees current route + selected text + recent telemetry). | 2 pw | +| 11.3 | **`@bytelyst/speech-ui@0.1.0`** | `` (Web Speech API + visualiser), ``, ``. Integrates with `@bytelyst/speech` and `PromptComposer.voiceInput`. | 1.5 pw | +| 11.4 | **`@bytelyst/file-ui@0.1.0`** | `` (drag-drop + chunked upload via `@bytelyst/blob-client`), `` (auto image/PDF/text), `` (grid + list views), ``. | 1 pw | +| 11.5 | **`@bytelyst/realtime-ui@0.1.0`** | ``, ``, ``, `useRealtimePresence(channel)`. Backed by `@bytelyst/fastify-sse` + `@bytelyst/sync`. | 1 pw | + +**DoD:** assistant-shell live in ≥ 1 product (likely notes or mindlyst) · `StreamUI` renders a real LLM-emitted form in dev. + +--- + +### **Wave 12 — Mobile-first, i18n, sustainability** _(weeks 23–26, ~7 pw)_ + +> **Theme:** finish what v2 Wave 6 sketched. + +| # | Package / surface | Notes | Effort | +| ---- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | +| 12.1 | **`@bytelyst/ui` v3 — mobile primitives** | `` (snap points + scrollable body), `` (safe-area), ``, ``, mobile-specific variants of `Dropdown`/`Tooltip` (long-press). | 1.5 pw | +| 12.2 | **`@bytelyst/i18n@0.1.0`** | `react-intl` wrapper, type-safe message catalogues, auto-extraction CLI. Default locales: `en`, `es`, `ar`, `ja`. | 1.5 pw | +| 12.3 | **RTL audit** | Every primitive uses logical properties (`margin-inline-start`, `text-align: start`). Visual-regression test set for `dir="rtl"`. Codemod to convert `left`/`right` → `inline-start`/`inline-end` in product webs. | 1 pw | +| 12.4 | **Inclusive design** | Atkinson Hyperlegible toggle, contrast lock-up (forces AAA), motion-pause toggle. VPAT 2.5 ACR drafted & published on showcase. | 1 pw | +| 12.5 | **Showcase additions** | Viewport switcher per demo (375 / 768 / 1280 / fluid), per-demo a11y inspector, RTL toggle, locale switcher in theme picker. | 1 pw | +| 12.6 | **Sustainability** | Per-package bundle/CO₂ budget in CI (`co2.js`), dark-mode default to save OLED energy, image-format negotiation helper. | 0.5 pw | +| 12.7 | **PWA + create-app** | Showcase becomes installable PWA with offline catalog. `pnpm create @bytelyst/app` scaffolds new product webs wired with shell + auth + tokens + theme picker + Cmd-K + telemetry. | 0.5 pw | + +**DoD:** 100% RTL visual-test pass · 4 locales live · `pnpm create @bytelyst/app my-app` produces a working dev server in < 60s. + +--- + +## 5. Per-product upgrade matrix + +For each product web, the **3 highest-value adoptions** in the next two waves. (Each row is independent and can be tackled by the product team.) + +| Product | Adoption #1 (Wave 8) | Adoption #2 (Wave 9) | Adoption #3 (Wave 10) | +| ------------------------------ | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| **clock/web** | Replace `framer-motion` with `@bytelyst/motion` Reveal + NumberFlow on `/landing` + `/history` | Adopt `@bytelyst/charts` for time-distribution donut; deprecate inline recharts | `@bytelyst/dashboard-shell@0.3.0` + `command-palette` | +| **notes/web** | Swap bespoke `AgentTimeline` → `@bytelyst/ai-ui/AgentTimeline`; swap bespoke `Skeleton` → `ui/skeleton` | Adopt `@bytelyst/rich-text` for the note body editor; ship `@bytelyst/timeline` for `MemoryTimeline` | Wire `@bytelyst/assistant-shell` (Wave 11) — first product to host the ambient assistant | +| **flowmonk/web** | Adopt `@bytelyst/motion` + Cmd-K palette commands for task switching | `@bytelyst/data-table` for the schedule view; `@bytelyst/data-viz/Heatmap` for streaks | `@bytelyst/onboarding-ui` checklist on first task creation | +| **jarvisjr/web** | Adopt `@bytelyst/motion` on landing; swap recharts → `@bytelyst/charts` | Adopt `@bytelyst/data-table` for sessions list | `@bytelyst/billing-ui` upgrade modal + plan card | +| **fastgap/web** | Replace bespoke `Skeleton` + swap sonner → `@bytelyst/ui/toast` | `@bytelyst/charts` for weight-trend line + fasting heatmap; `@bytelyst/data-viz/KpiCard` for streaks | `@bytelyst/onboarding-ui` for first-fast tour | +| **localmemgpt/web** | Adopt `@bytelyst/motion` Reveal on chat threads; Cmd-K palette | Adopt `@bytelyst/ai-ui/PromptComposer` + `ChatStream` for the chat UI (currently bespoke) | `@bytelyst/file-ui/FileDrop` for memory imports | +| **voice / user-dashboard-web** | Adopt `@bytelyst/ui` (replaces bespoke `radix-ui` direct usage) | Swap recharts → `@bytelyst/charts`; adopt `@bytelyst/data-table` for transcript browser | `@bytelyst/billing-ui` + `@bytelyst/settings-ui` | +| **trails/web** | Adopt `@bytelyst/motion` + `@bytelyst/notifications-ui` for alert banner | Adopt `@bytelyst/data-table` for the action log; `@bytelyst/timeline` for revert history | `@bytelyst/settings-ui` | +| **dev-intelli/web** | Adopt Cmd-K palette + `@bytelyst/motion` | `@bytelyst/data-table` for diagnostics list; `@bytelyst/ai-ui/CodeDiff` (Wave 9) for proposed fixes | `@bytelyst/assistant-shell` (Wave 11) — second host | +| **nomgap/web** | Swap bespoke modals → `@bytelyst/ui/modal v2` | `@bytelyst/charts` for weight + meal heatmap; `@bytelyst/onboarding-ui` for first-day setup | `@bytelyst/billing-ui` | +| **peakpulse/web** | Adopt `@bytelyst/motion` + Cmd-K | `@bytelyst/charts` for session pulse; `@bytelyst/data-viz/KpiCard` for streaks | `@bytelyst/settings-ui` | + +> **Cross-cutting:** every product adopts `@bytelyst/telemetry-ui` (Wave 10.6) in the same PR that swaps in `dashboard-shell@0.3.0` — they share the topbar slot. + +--- + +## 6. New common-platform packages proposed in v3 + +Summary table — 16 net-new packages over Waves 8 – 12: + +| Package | Wave | Pkg size budget (gzip) | Purpose | +| -------------------------------- | --------- | ---------------------- | ------------------------------------------- | +| `@bytelyst/charts` | 9 | 25 KB | Token-themed recharts wrapper + Donut/Gauge | +| `@bytelyst/rich-text` | 9 | 40 KB | Tiptap wrapper + slash menu + mentions | +| `@bytelyst/data-table` | 9 | 25 KB | TanStack Table + Virtual | +| `@bytelyst/onboarding-ui` | 10 | 10 KB | Checklist + tour + callouts | +| `@bytelyst/billing-ui` | 10 | 15 KB | Plan/upgrade/usage/invoice | +| `@bytelyst/settings-ui` | 10 | 10 KB | Settings layout + sections | +| `@bytelyst/legal-ui` | 10 | 6 KB | Privacy/terms/cookie banner | +| `@bytelyst/telemetry-ui` | 10 | 4 KB | Auto-event tracking | +| `@bytelyst/timeline` | 10 | 8 KB | Generic vertical event timeline | +| `@bytelyst/brand-flowmonk` (× 3) | 10 | 1 KB each | Token overrides | +| `@bytelyst/adaptive-ui` | 11 | 18 KB | SchemaForm + StreamUI | +| `@bytelyst/assistant-shell` | 11 | 8 KB | Ambient ⌘J assistant | +| `@bytelyst/speech-ui` | 11 | 6 KB | Voice input + dictation | +| `@bytelyst/file-ui` | 11 | 12 KB | FileDrop + FileBrowser + ImageCrop | +| `@bytelyst/realtime-ui` | 11 | 8 KB | Presence + typing + cursors | +| `@bytelyst/i18n` | 12 | 12 KB | react-intl wrapper | +| `@bytelyst/icons` | 3.x bonus | 0 KB (peer) | Lucide / Phosphor / Tabler swap provider | + +Total net-new package bytes if a product consumes **every** package: ~210 KB gzip. Per-product realistic adoption (5-6 of these): ~80 KB gzip — within the 100 KB JS budget per page after gzip. + +--- + +## 7. Non-goals (still) + +- Rebuilding charts from scratch — wrap recharts. +- Custom Markdown parser — adopt `react-markdown` + remark plugins inside `@bytelyst/ui/Markdown`. +- A new state library — products keep TanStack Query / Zustand / Redux as they choose. +- A new test runner — Vitest + Playwright is the stack. +- Native iOS/Android UI work — `swift-platform-sdk` / `kotlin-platform-sdk` continue to share **tokens only**. + +--- + +## 8. Risks & mitigations (v3 specific) + +| Risk | Likelihood | Impact | Mitigation | +| ----------------------------------------------------------- | ---------- | ------ | -------------------------------------------------------------------------------------------------------- | +| Publish-workflow regression blocks Wave 8 | Low | High | Manual `npm publish` fallback script already in `scripts/publish-outdated-gitea-packages.sh` | +| Recharts API drift (peer-dep mismatch across products) | Med | Med | Pin to `^2.15`; `@bytelyst/charts` has type-only re-exports so a major bump fails build, not silent | +| Tiptap StarterKit extension churn (v2 → v3) | Med | Low | Lock to a known-good range in `@bytelyst/rich-text/package.json` | +| StreamUI security (LLM emits arbitrary components) | Med | High | Strict allow-list of renderable component names; never `dangerouslySetInnerHTML`; schema-validated props | +| Browser support for View Transitions cross-doc | Low | Med | Mandatory crossfade fallback already in `@bytelyst/motion` | +| Voice / passkey UX in corp networks (proxy strips WebAuthn) | Low | Low | Document; provide username/password fallback | + +--- + +## 9. Concrete next 14 days — kickoff + +| Day | Action | Output | +| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | +| **1 (Wed)** | Trigger publish workflow with broad filter — close out 5 unpublished packages | Gitea registry shows all 5 at latest source versions | +| **2 (Thu)** | Showcase: delete all `src/lib/*-preview/` snapshots; swap to registry imports | TODO #14 closed | +| **3 (Fri)** | Land cross-repo dep update PR for **all 11 product webs** — `@bytelyst/design-tokens@^0.2.0` + adopt `@bytelyst/motion` Reveal on landing | 11 product webs on latest tokens; motion adopted incrementally | +| **4 (Sat)** | Migrate `learning_ai_notes/web/AgentTimeline.tsx` → `@bytelyst/ai-ui/AgentTimeline`; delete bespoke | -250 LOC in notes/web | +| **5 (Sun)** | Wire `command-palette` into notes + jarvisjr + fastgap | 3 products with Cmd-K | +| **6 (Mon)** | **`@bytelyst/charts@0.1.0`** scaffold: ``, ``, `` MVPs | New package published 0.1.0 | +| **7 (Tue)** | `@bytelyst/charts` showcase demos + adoption in `clock/web` history view | 1 product on charts | +| **8 (Wed)** | **`@bytelyst/rich-text@0.1.0`** scaffold | Package published 0.1.0 | +| **9 (Thu)** | `@bytelyst/rich-text` adoption in `notes/web` body editor | Notes ships rich-text via shared package | +| **10 (Fri)** | **`@bytelyst/data-table@0.1.0`** scaffold | Package published 0.1.0 | +| **11 (Sat)** | `` + `` + `` added to `@bytelyst/ui@0.2.0` | UI v0.2.0 published | +| **12 (Sun)** | Migrate every product `Skeleton.tsx` → `@bytelyst/ui/skeleton`; codemod commit per repo | -1,400 LOC across product webs | +| **13 (Mon)** | **`@bytelyst/dashboard-shell@0.3.0`** scaffolding kicks off | RFC drafted, scaffold landed | +| **14 (Tue)** | Wave 9 retro + Wave 10 kickoff | Roadmap doc bumped to v3.1 | + +--- + +## 10. Success metrics — end of v3 (Wave 12, ~26 weeks) + +| Metric | v2.5 baseline | v3 target | +| -------------------------------------------- | ---------------------- | ------------------------------- | +| `@bytelyst/*` packages published | 66 | **82** | +| Products on at least one Wave 4/5/7 package | 0 | **11** | +| Products on `dashboard-shell@0.3.0` | 0 | **8** | +| Products on `charts` | 0 | **6** | +| Products on `command-palette` | 0 | **11** | +| Bespoke `Skeleton.tsx` files in product webs | ~7 | **0** | +| Bespoke `*Modal.tsx` files | 10+ | **≤ 3** (product-specific only) | +| Showcase demos | 90+ | **150+** | +| Playwright tests | 94+ | **250+** | +| Lighthouse Perf (showcase + each product) | unmeasured per product | **≥ 90 across the board** | +| WCAG 2.2 AA pass rate | partial | **100%** | +| RTL visual-test pass rate | none | **100%** | +| Locales | 1 (en) | **4** | +| Brand-layer packages | 0 | **3** | +| EU EAA conformance statement | none | **published** | + +--- + +## 11. Document hygiene + +- **v3 (this doc):** new cross-repo UX roadmap; builds on v2.5 (showcase repo). Adds Waves 8–12, 16 net-new packages, per-product upgrade matrix, and modern-web-platform adoption guidance. +- Mirror at `learning_ai_uxui_web/docs/ROADMAP_2026_V3_CROSS_REPO.md` after this commit lands. +- Future versions bump as waves close (`v3.1`, `v3.2`, etc.). + +**Owner:** ByteLyst Platform UI guild +**Discussion:** `tracker-web` (issue tag: `roadmap-2026`, milestone: `v3`)