docs(roadmap): v3 cross-repo UX roadmap — Waves 8-12, 16 net-new packages
Adds a fresh strategic roadmap (`docs/UI_ROADMAP_2026_V3_CROSS_REPO.md`)
that builds on the showcase repo's v2.5 doc but pivots from
"packages in isolation" to "every product web on the floor".
Contents:
§1 Inventory — 72 in-tree @bytelyst/* packages + v2 wave status
§2 Cross-repo audit — package-consumption matrix across 11 product
webs + 15 duplicated surfaces (Skeleton, *Modal, Sidebar,
OnboardingOverlay, AgentTimeline, MemoryTimeline, recharts
wrappers, sonner toasts, date-fns pickers, settings panels,
filter bars, data tables, privacy pages, etc.)
§3 Future-proof UX themes — OKLCH/P3 palettes, glass+depth,
ambient/calm UI, Material 3 Expressive springs, variable type,
View Transitions API, CSS anchor positioning, popover API,
scroll-driven animations, @scope, field-sizing, WebAuthn,
WebGPU/OffscreenCanvas. Plus AI-native patterns: generative
UI, suggestion chips, inline AI rewrite, confidence chrome,
ambient assistant, voice-first composer, citations everywhere.
§4 Five new waves (8 publish + rollout · 9 charts/rich-text/
data-table · 10 shell/onboarding/billing/settings/legal/
telemetry/timeline/brand · 11 adaptive/assistant/speech/file/
realtime · 12 mobile/i18n/RTL/sustainability/PWA) — totals
~38 person-weeks across 16 net-new packages.
§5 Per-product upgrade matrix — 3 highest-value adoptions per
web (clock, notes, flowmonk, jarvisjr, fastgap, localmemgpt,
voice, trails, dev-intelli, nomgap, peakpulse).
§6 New packages table with gzip budgets (~210 KB total if a
product adopted every one; realistic ~80 KB per product).
§7 Non-goals (still): no recharts rebuild, no bespoke markdown
parser, no new state library, no native iOS/Android UI.
§8 Risks: publish-workflow regression, recharts API drift,
Tiptap StarterKit churn, StreamUI security, View Transitions
cross-doc support, voice/passkey corp-network constraints.
§9 14-day kickoff plan — day-by-day to close TODO #14, publish
the 5 unpublished packages, ship @bytelyst/charts +
rich-text + data-table 0.1.0s, and migrate every product
Skeleton.tsx into @bytelyst/ui/skeleton.
§10 Success metrics — 11/11 products on shared packages,
150+ showcase demos, 250+ Playwright tests, 100% AA + RTL,
4 locales, 3 brand layers, EAA conformance published.
Mirror in copilot/learning_ai_uxui_web/docs/ROADMAP_2026_V3_CROSS_REPO.md
follows in a separate commit on that repo.
This commit is contained in:
saravanakumardb1
parent
acb8f02bca
commit
a94d9b211c
369
docs/UI_ROADMAP_2026_V3_CROSS_REPO.md
Normal file
369
docs/UI_ROADMAP_2026_V3_CROSS_REPO.md
Normal file
@ -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` |
|
||||
| **`<dialog>` + invoker `command`/`commandfor`** | Chrome 134+ | `ui/Modal` to use native `<dialog>` + 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: `<LineChart>`, `<AreaChart>`, `<BarChart>`, `<StackedBar>`, `<Donut>`, `<Gauge>`, `<RadarChart>`. 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: `<RichTextEditor>`, `<RichTextViewer>`, 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** | `<FilterBar>` (chips + clear-all), `<SearchInput>` (with suggestions slot), `<EmptyState>` (illustration slot + CTA), `<TagInput>`, `<Combobox>` (formalise Wave 5a). | 1.5 pw |
|
||||
| 9.5 | **`@bytelyst/ui` v2.x — skeleton + loading** | `<Skeleton>` shimmer with shape variants (`text` / `rect` / `circle` / `card`), `<SkeletonGroup>` (orchestrates fade-out → content), `<LoadingDots>`, `<Spinner>` with token-tinted variants. | 0.5 pw |
|
||||
| 9.6 | `ai-ui@0.5.0` | `<Markdown>` (with citation interop), `<CodeDiff>`, `<ExplainThis>`, `usePromptHistory()`, `useTokenCount()`. Closes Wave 2 deferred items. | 1 pw |
|
||||
| 9.7 | `data-viz@0.2.0` | `<RealtimeChart>` (SSE subscribed), `<Donut>` (re-export from charts), `<Gauge>` (token-tinted), `<TreeMap>`, `<Sankey>` (stretch). Add `confidence` prop to `<KpiCard>`. | 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: `<AppShell><Sidebar/><Topbar/><Main/></AppShell>`. 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`** | `<OnboardingChecklist>`, `<TourStep>`, `<FeatureCallout>`, `<EmptyStateCTA>`, `useTour()`. Persists progress in localStorage. Token-themed. | 1.5 pw |
|
||||
| 10.3 | **`@bytelyst/billing-ui@0.1.0`** | `<PlanCard>`, `<UpgradeModal>`, `<UsageMeter>`, `<InvoiceList>`, `<PaymentMethodList>`. Wired to `platform-service` Stripe module via `@bytelyst/subscription-client` + `@bytelyst/billing-client`. | 1.5 pw |
|
||||
| 10.4 | **`@bytelyst/settings-ui@0.1.0`** | `<SettingsLayout>` (left-rail nav), `<ProfileSection>`, `<SecuritySection>` (passkey + 2FA), `<NotificationPrefs>`, `<DataExportRow>`, `<DangerZone>`. | 1 pw |
|
||||
| 10.5 | **`@bytelyst/legal-ui@0.1.0`** | `<PrivacyPolicyPage>`, `<TermsPage>`, `<CookieBanner>` (token-themed, EAA-compliant), `<DataProcessingNotice>`. 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: `<BrandProvider brand="flowmonk">` 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`** | `<SchemaForm>` (JSON Schema → accessible form, react-hook-form under the hood), `<SchemaTable>`, **`<StreamUI from={stream}>`** — 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`** | `<VoiceInputButton>` (Web Speech API + visualiser), `<DictationOverlay>`, `<TranscriptViewer>`. Integrates with `@bytelyst/speech` and `PromptComposer.voiceInput`. | 1.5 pw |
|
||||
| 11.4 | **`@bytelyst/file-ui@0.1.0`** | `<FileDrop>` (drag-drop + chunked upload via `@bytelyst/blob-client`), `<FilePreview>` (auto image/PDF/text), `<FileBrowser>` (grid + list views), `<ImageCrop>`. | 1 pw |
|
||||
| 11.5 | **`@bytelyst/realtime-ui@0.1.0`** | `<PresenceAvatars>`, `<TypingIndicator>`, `<LiveCursor>`, `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** | `<BottomSheet>` (snap points + scrollable body), `<StickyActionBar>` (safe-area), `<TouchableRipple>`, `<PullToRefresh>`, 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: `<LineChart>`, `<BarChart>`, `<AreaChart>` 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)** | `<Skeleton>` + `<EmptyState>` + `<SearchInput>` 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`)
|
||||
Loading…
Reference in New Issue
Block a user