From 850b9d35a2239ac01e63239fc0c3e5d41056090a Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Wed, 27 May 2026 15:18:07 -0700 Subject: [PATCH] =?UTF-8?q?docs(roadmap):=20v3.1=20review=20pass=20?= =?UTF-8?q?=E2=80=94=20futurism=20amendment=20+=20Wave=2013=20+=20correcti?= =?UTF-8?q?ons?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Comprehensive review of the v3.0 cross-repo UX roadmap. The diff grows the doc from 370 to 591 lines (+60%); core structure preserved. ────────────────────────────────────────────────────────────────── Bug fixes & corrections (no regressions) ────────────────────────────────────────────────────────────────── - Product-web inventory: 11 → 15+ (was missing mindlyst-native/web, talk2obsidian/web, productivity-web, sidecar-dashboard-web, mac-tooling/dashboard, devops-tools/dashboard/web, agent-monitoring-fx, local-llms/dashboard, efforise/client, admin-web, tracker-web). New total: **20 web apps**. - Net-new package count: 16 → 26 (the brand-* row was 3 packages, not 1; plus Wave 13 adds 8 more) - §4 heading: "five waves" → "six waves" (Wave 13 added) - §10 metrics targets refreshed to reflect 20-app scope - §11 hygiene bumped to v3.1 with full changelog ────────────────────────────────────────────────────────────────── Major content amendments — "futurism layer" ────────────────────────────────────────────────────────────────── NEW §3.4 On-device & privacy-first AI (8 surfaces) • WebLLM / transformers.js for client-side LLM inference • Privacy-mode toggle + GPC header honouring • Explainable refusal, cost transparency, confidence transparency • Provenance trails, telemetry opt-out, "Why did the AI say this?" debug overlay NEW §3.5 Real-time CRDT collaboration (6 patterns) • Yjs canonical + Automerge adapter • Liveblocks-grade presence (PresenceAvatars, TypingIndicator, LiveCursor) • Co-edit indicators, conflict-free sync, selective sharing, comment threads anchored to selections NEW §3.6 Spatial / visionOS-inspired surfaces (8 primitives) • SurfaceFloat (multi-stop shadow + backdrop-blur) • Parallax (scroll-driven), Spotlight (cursor-follow), Magnetic buttons, TiltGallery, glass-with-depth modals, MeshBackground (OKLCH ambient gradients) NEW §3.7 Performance & sustainability budgets • LCP ≤ 2.5s p75 · INP ≤ 200ms p75 · CLS ≤ 0.1 p75 • First-page JS ≤ 100 KB gzip · CO₂ ≤ 0.5g/view • content-visibility, RSC for static surfaces, Suspense islands, route prefetch, AVIF/WebP negotiation NEW §3.8 Anti-patterns we will NEVER ship (10 entries) • Dark patterns, auto-playing media, prefers-reduced-motion ignored,
, hard-coded colours, layout-shifting skeletons, polling instead of streaming, notification spam, modal stack > 2, generic 'Something went wrong'. NEW Wave 13 — Futurism layer (~9 pw, 7 packages): 13.1 @bytelyst/on-device-ai (WebLLM + transformers.js) 13.2 @bytelyst/collab (Yjs CRDT + Automerge adapter) 13.3 ai-ui@0.5 trust surfaces (CostMeter, ConfidenceTag, RefusalCard, ProvenanceDrawer, DebugOverlay, PrivacyBadge) 13.4 motion@0.2 spatial (Parallax, Spotlight, Magnetic, MeshBackground, TiltGallery) 13.5 @bytelyst/generative-theme ("describe your brand" → tokens) 13.6 @bytelyst/customizable-workspace 13.7 @bytelyst/media-ui (ImageGenStream, AudioWaveform, PdfPreview, VideoPlayer) NEW §6.1 RSC vs client guidance — per-package table for React Server Component safety (design-tokens, ui-stateless, legal-ui, settings-ui rail are RSC-safe; everything else is client-only or hybrid) NEW §6.2 Web Components interop — Lit-wrapped , etc. for non-React consumers (efforise/Vite, talk2obsidian/Obsidian plugin, local-llms dashboard) NEW §6.3 Adjacent token packages — email-tokens (MJML), audio-tokens (notification sounds), motion-tokens (Lottie/Rive interpolation curves) NEW §9.1 Demo-first showcase list — 8 customer-magnet prototypes to lead with: MeshBackground+Spotlight landing, on-device-AI chat, CostMeter+ConfidenceTag dashboard, CRDT multi-user notes, ThemeStudio, customizable workspace, ImageGenStream+ AudioWaveform, Shift-click DebugOverlay. ────────────────────────────────────────────────────────────────── Risks + metrics expanded ────────────────────────────────────────────────────────────────── - 6 new risk-matrix rows (WebGPU fragmentation, CRDT memory bloat, generative-theme palette accessibility, media-ui bundle weight, workspace layout collisions, WebLLM model-download UX) - §10 success metrics: added Core Web Vital p75 targets per product, INP/LCP/CLS gates, privacy-mode + CRDT + on-device AI + CostMeter adoption KPIs, dark-pattern audit, Web Components export, create-app scaffolding ────────────────────────────────────────────────────────────────── Coverage now complete ────────────────────────────────────────────────────────────────── Per-product matrix expanded from 11 to 20 web apps and gains a "Wave 13 futurism hook" column. Pilots: • notes/web + tracker-web → CRDT multi-user editing • localmemgpt/web + local-llms dashboard → on-device AI • mindlyst/web → ImageGenStream + CRDT memory canvas • flowmonk + peakpulse + mac-tooling → customizable workspace • jarvisjr + trails + sidecar + devops-tools + agent-monitoring → CostMeter + ConfidenceTag + ProvenanceDrawer • clock/web → MeshBackground + Spotlight landing hero Mirror in copilot/learning_ai_uxui_web follows in a paired commit. --- docs/UI_ROADMAP_2026_V3_CROSS_REPO.md | 362 +++++++++++++++++++++----- 1 file changed, 292 insertions(+), 70 deletions(-) diff --git a/docs/UI_ROADMAP_2026_V3_CROSS_REPO.md b/docs/UI_ROADMAP_2026_V3_CROSS_REPO.md index acbaccd6..5d42f670 100644 --- a/docs/UI_ROADMAP_2026_V3_CROSS_REPO.md +++ b/docs/UI_ROADMAP_2026_V3_CROSS_REPO.md @@ -1,17 +1,20 @@ # ByteLyst Cross-Repo UX Roadmap — v3 (Future-Proof, Elegant, Rich) -> **Status:** Draft for review · 2026-05-27 +> **Version:** v3.1 — 2026-05-27 (review + futurism amendment) +> **Status:** Draft for review > **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. +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 **15+ product webs** actually ships today, finds the duplication, and prescribes the next **6 platform waves (Wave 8 – Wave 13)** plus a per-product upgrade matrix, with explicit futurism amendments in v3.1 (§3.4 – §3.8, §6.1 – §6.3, Wave 13). + +> **What changed in v3.1 vs v3.0:** corrected product-web inventory (15+ not 11), corrected new-package count (18 in original waves + 8 added below = **26 net-new**), added five subsections on the frontier UX themes that attract today's most discerning customers (on-device AI, real-time CRDT collab, cost & confidence transparency, spatial UI, anti-patterns), introduced Wave 13 (futurism layer), expanded the per-product matrix to all 15+ webs, and added a dedicated **RSC vs client / Web Components interop** section. --- ## 1. Where we are (May 2026) -### Shared `@bytelyst/*` packages currently published or in-tree (72) +### Shared `@bytelyst/*` packages currently published or in-tree (~73) | Tier | Packages | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -42,7 +45,33 @@ This document **extends** the v2 roadmap rather than replacing it. v2 covered sh ## 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`. +Sampled from every Next.js / Vite web in the workspace — v3.1 audit is **comprehensive** (was sample-based in v3.0): + +``` +/copilot/learning_ai_uxui_web — reference showcase (Next.js 16) +/learning_ai_clock/web — ChronoMind +/learning_ai_notes/web — NoteLett +/learning_ai_flowmonk/web — FlowMonk +/learning_ai_jarvis_jr/web — JarvisJr +/learning_ai_fastgap/web — NomGap (FastGap) +/learning_ai_trails/web — ActionTrail +/learning_ai_local_memory_gpt/web — LocalMemGPT +/learning_ai_dev_intelli/web — DevIntelli +/learning_voice_ai_agent/user-dashboard-web — LysnrAI user portal +/learning_multimodal_memory_agents/mindlyst-native/web — MindLyst web shell +/learning_ai_talk2obsidian/web — Talk2Obsidian +/learning_ai_productivity_web — Productivity hub +/learning_sidecar_setup/sidecar_dashboard_web — Sidecar dashboard +/learning_ai_mac_tooling/dashboard — Mac Tooling dashboard +/learning_ai_devops_tools/dashboard/web — DevOps tools dashboard +/learning_agent_monitoring_fx/apps/web — Agent Monitoring FX +/learning_ai_local_llms/dashboard — Local LLMs dashboard +/learning_ai_efforise (Vite) — EffoRise client +/learning_ai_common_plat/dashboards/admin-web — Platform admin +/learning_ai_common_plat/dashboards/tracker-web — Issue tracker + roadmap +``` + +**Total: 20 web apps** (12 product webs, 2 platform dashboards, 6 internal/utility dashboards). v3.1 widens scope from the 11 highlighted in v3.0. ### 2.1 `@bytelyst/*` package consumption matrix @@ -148,11 +177,95 @@ The v2 roadmap nailed accessibility, motion, density, AI-native primitives. v3 l | **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 | +### 3.4 On-device & privacy-first AI — the trust differentiator + +The single biggest 2026 customer-acquisition wedge: **"your data never leaves your device unless you ask it to."** Surfaces: + +| Pattern | What it is | Where it lands | +| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| **WebLLM / transformers.js** in browser | Run 1B–8B-parameter models client-side via WebGPU; falls back to cloud if hardware can't | New `@bytelyst/on-device-ai` package (Wave 11) with `useOnDeviceModel()` hook + capability detection | +| **"Privacy mode" toggle** | App-wide switch that routes every AI call to local model when capable; disables telemetry beacons | `@bytelyst/ai-ui/PrivacyBadge` chrome + `usePrivacyMode()` (Wave 11) | +| **Explainable refusal** | When AI refuses, show _why_ (policy excerpt + appeal link), never a generic "I can't help" | `ai-ui/RefusalCard` (Wave 9 v0.5) | +| **Cost transparency** | Inline per-turn cost ($ + tokens + provider), running session total | `ai-ui/CostMeter` (Wave 9 v0.5) — opt-in via `showCost` prop on `ChatStream` | +| **Confidence transparency** | "Model is 73% confident; 2 of 3 sources agree" — surfaced on every AI response | `ai-ui/ConfidenceTag` (Wave 9 v0.5) | +| **Provenance trails** | Every AI artefact carries a verifiable hash chain back to the prompt + model + tools used | `ai-ui/ProvenanceDrawer` (Wave 11) — backed by `@bytelyst/event-store` | +| **Telemetry opt-out UX** | Single switch in `@bytelyst/settings-ui` honours **Global Privacy Control** (`Sec-GPC` header) | Wave 10 | +| **"Why did the AI say this?"** debug overlay | Shift-click any AI response → opens inspector with system prompt, retrieved context, tool calls, raw stream | `ai-ui/DebugOverlay` (Wave 11) — dev/staging only by default | + +### 3.5 Real-time collaboration — the Linear/Figma-tier patterns + +Today's premium products are multiplayer. Wave 11 ships the primitives. + +| Pattern | Tech | Surface | +| ----------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| **CRDT document collab** | **Yjs** as the canonical CRDT; **Automerge** swap supported via adapter | `@bytelyst/collab` (new in Wave 11) — `useSharedDoc()`, `` | +| **Liveblocks-grade presence** | SSE/WebSocket transport via `@bytelyst/fastify-sse` | `@bytelyst/realtime-ui` — ``, ``, `` (already in Wave 11) | +| **Co-edit indicators** | Show "Sara is editing line 14" with avatar | `rich-text/CollabSelection` extension (Wave 11) | +| **Conflict-free sync** | Offline edits replay on reconnect; never lose work | `@bytelyst/sync` + Yjs binding | +| **Selective sharing** | Share-by-link UI with permission tier (view / comment / edit) | `@bytelyst/settings-ui/SharePanel` (Wave 10) | +| **Comment threads** | Anchored to a selection range; resolves + reopens | `@bytelyst/collab/CommentThread` (Wave 11) | + +### 3.6 Spatial / immersive — visionOS-inspired surfaces + +Inspired by Apple Vision Pro, Arc Browser, Linear's depth layering. Subtle but unmistakably "next-gen". + +| Pattern | Implementation | +| -------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | +| **Floating cards with depth** | Multi-stop shadows + 1px translucent border + `backdrop-filter: blur()`; never used for body text | `ui/SurfaceFloat` variant (Wave 9) | +| **Parallax on scroll** | `motion/Parallax` driven by scroll-driven animations — zero-JS where supported | New primitive in `@bytelyst/motion@0.2.0` (Wave 9 hygiene) | +| **3D model embed** | `` web component, lazy-loaded behind `@bytelyst/file-ui` | Wave 11 | +| **Cursor-aware spotlight** | Radial gradient that follows pointer, hugely effective on landing pages | `motion/Spotlight` (Wave 9) | +| **Magnetic buttons** | Pointer-attracted CTAs, Arc-browser-style | `motion/Magnetic` (Wave 9) — already in v2 sketch | +| **Tilt cards** | Already shipped in `motion@0.1.0` — add `` for product grids | Wave 9 | +| **Glass-with-depth modal** | Backdrop blur + tinted vignette + spring entrance | `ui/Modal v2` (Wave 9) | +| **Ambient gradient backgrounds** | OKLCH mesh that subtly shifts based on time-of-day or active route | `motion/MeshBackground` (Wave 9) | + +### 3.7 Performance & sustainability — the Core Web Vital budgets + +Every customer ultimately judges UX by speed. We publish per-route budgets and CI gates them. + +| Metric | Target | How we measure | +| --------------------------------------- | ------------- | --------------------------------------------- | +| **LCP** (Largest Contentful Paint) | ≤ 2.5s p75 | Lighthouse + RUM via `@bytelyst/telemetry-ui` | +| **INP** (Interaction to Next Paint) | ≤ 200ms p75 | `web-vitals@4` in `@bytelyst/telemetry-ui` | +| **CLS** (Cumulative Layout Shift) | ≤ 0.1 p75 | Lighthouse | +| **First-page JS** | ≤ 100 KB gzip | `size-limit` per-route budget | +| **Image weight per page** | ≤ 500 KB | Lighthouse | +| **CO₂ per page-view** | ≤ 0.5 g | `co2.js` in CI (Wave 12.6) | +| **Time-to-Interactive on Moto G Power** | ≤ 4.5s | Lighthouse mobile profile in LHCI | + +**Patterns we adopt to hit them:** + +- `content-visibility: auto` on long lists & off-screen panels (10× INP improvement) +- React 19 **Server Components** for static surfaces (legal-ui, settings-ui rails, marketing pages) +- **Streaming SSR with progressive hydration** for AI surfaces +- **Suspense islands** — never block a page on a slow chart +- **Route prefetch** on hover/pointer-near (Next.js native + `@bytelyst/dashboard-shell` Sidebar opt-in) +- **Image components** with AVIF + WebP negotiation, blurhash placeholders +- **Cache-aware Cmd-K** — palette uses IndexedDB for the catalog so it opens instantly offline + +### 3.8 Anti-patterns — what ByteLyst products will **never** ship + +A short register, codified in `docs/design-system/ANTIPATTERNS.md` (created by Wave 9), and CI-checkable where possible. + +| Forbidden pattern | Why | Detection | +| --------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------ | +| **Dark patterns** (cookie banner with hidden "Reject all", pre-checked opt-in, fake urgency timers) | EU EAA + ethics | Manual review + cookie-banner lint in `@bytelyst/legal-ui` | +| **Auto-playing audio/video** without explicit user gesture | Accessibility + bandwidth | ESLint rule on `