# ByteLyst Ecosystem — Design System & UI/UX Audit

> **Date:** 2026-03-27 (Principal Review: 2026-03-27)
> **Author:** Principal Product & Design Engineering Review
> **Scope:** All 16 workspace repos — 11 product web apps, 5 iOS apps, 5 Android apps, 3 React Native/Expo apps, 3 platform dashboards, 1 UX lab
> **Canonical Source:** `packages/design-tokens/tokens/bytelyst.tokens.json` (v1.1.0)
> **Methodology:** Automated full-workspace scan + manual code review against industry design system maturity standards (Material 3, Radix/shadcn, Shopify Polaris, Atlassian Design System, Apple HIG, Google Material You)

---

## Executive Summary

**Overall Design System Completeness: 41%**
**Design System Maturity Level: 2 of 5 (Fragmented)**

The ByteLyst ecosystem has built a **comprehensive canonical token foundation** (211 tokens, 4-platform generation pipeline, 7 product-specific palettes) — this puts the _foundation layer_ at roughly best-in-class for an ecosystem of this size. However, the **adoption, component, and experience layers are critically underdeveloped**. The gap between what the token system _defines_ and what product code _actually uses_ is the single largest design debt in the ecosystem.

### Maturity Scorecard

| Dimension                       | Score   | Industry Benchmark                                                                  | Gap                                                         |
| ------------------------------- | ------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| **Token Foundation**            | **75%** | Tokens defined, generator works, 4 platforms                                        | Generator only outputs MindLyst; 4 products have no palette |
| **Token Adoption (Web)**        | **35%** | 0/11 apps import `@bytelyst/design-tokens`; all hand-write CSS                      | Every web app should import generated tokens                |
| **Token Adoption (Mobile)**     | **30%** | iOS themes exist but diverge; Android consistent via SDK; RN has 337+ hardcoded hex | RN needs shared theme package                               |
| **Component Library**           | **15%** | Zero shared components; 11 apps build from scratch; 0 shadcn/ui                     | Industry standard: shared primitives library                |
| **Accessibility (WCAG 2.1 AA)** | **8%**  | Near-zero ARIA; 0 focus-visible in 5/7 apps; 0 screen reader testing                | Legal risk; must be P0                                      |
| **Responsive Design**           | **5%**  | Zero `@media` queries in product apps; tokens define 4 breakpoints unused           | Fixed layouts only                                          |
| **Dark/Light Theme**            | **30%** | Only 2/11 web apps have toggles                                                     | All apps define dark tokens but don't offer switching       |
| **Animation/Motion**            | **35%** | ChronoMind excellent (75 refs); 4 apps have zero animation                          | Motion tokens exist unused                                  |
| **UX Patterns (Feedback)**      | **32%** | 3/11 toasts, 3/11 modals, 2/11 confirmation dialogs, 1/11 error boundaries          | Critical gap in user feedback                               |
| **Interaction Quality**         | **25%** | 0 hover states in 4/7 apps; 0 focus-visible in 5/7; minimal loading states          | Feels unpolished                                            |
| **Information Architecture**    | **65%** | Sidebar nav consistent; semantic HTML varies (7-88 refs per app)                    | Good foundation, needs standardization                      |
| **E2E / Visual Testing**        | **40%** | 45 Playwright specs across 7 apps; zero visual regression                           | No screenshot/snapshot testing                              |
| **Design Documentation**        | **20%** | 1 component spec (MindLyst only); UX lab exists but disconnected                    | No Storybook, no living docs                                |

---

## 1. Design System Maturity Model

Industry-standard design system maturity is measured across 5 levels. ByteLyst is at **Level 2** with pockets of Level 3.

### 1.1 The Five Maturity Levels

| Level | Name           | Description                                                                                               | ByteLyst Status    |
| ----- | -------------- | --------------------------------------------------------------------------------------------------------- | ------------------ |
| **1** | **Ad-hoc**     | No tokens, no shared patterns, each app is fully bespoke                                                  | Passed             |
| **2** | **Fragmented** | Tokens exist, some apps adopt them, but no shared components; patterns diverge                            | **Current state**  |
| **3** | **Consistent** | Shared component library exists; tokens adopted in >80% of surfaces; documented patterns                  | Target (6 months)  |
| **4** | **Systematic** | Component catalog (Storybook), automated a11y/visual regression, design-code parity, contribution model   | Target (12 months) |
| **5** | **Optimized**  | Design tokens drive runtime theming, A/B tested layouts, real-time adoption metrics, federated governance | Aspirational       |

### 1.2 What Level 2 → 3 Requires (The Critical Leap)

This is the highest-ROI investment in the entire ecosystem. Moving from Level 2 to Level 3 means:

1. **Every web app imports tokens from `@bytelyst/design-tokens`** — zero hand-written CSS custom properties
2. **A shared `@bytelyst/ui` package exists** with at minimum: Button, Input, Select, Toast, Modal, Badge, Card, EmptyState, Sidebar, StatCard
3. **Every surface has focus-visible, ARIA labels, semantic HTML** — WCAG 2.1 AA baseline
4. **Every app has `not-found.tsx`, `error.tsx`, `loading.tsx`** — Next.js error boundary coverage
5. **Documented component patterns** — even a simple README per component counts

### 1.3 Current Level Evidence

| Signal                        | Expected at Level 2 | Measured                                                        |
| ----------------------------- | ------------------- | --------------------------------------------------------------- |
| Canonical token file          | Yes                 | `bytelyst.tokens.json` — 211 tokens                             |
| >50% of apps reference tokens | Yes                 | 7/11 web apps have correct CSS prefix                           |
| Some apps share code          | Minimal             | 0 shared React components; 11 duplicate Sidebars                |
| Inconsistent patterns         | Typical             | Toast in 3 apps, Modal in 3 apps, all different implementations |
| Documentation sparse          | Typical             | 1 component spec (MindLyst); UX lab exists but disconnected     |

---

## 2. Industry Best Practices Checklist

Benchmarked against Material 3, Radix/shadcn, Shopify Polaris, Atlassian Design System, Apple HIG.

### 2.1 Token Layer (Foundation)

| Best Practice                                      | Status      | Evidence                                                                   |
| -------------------------------------------------- | ----------- | -------------------------------------------------------------------------- |
| Single source of truth JSON                        | **PASS**    | `bytelyst.tokens.json` v1.1.0                                              |
| Multi-platform generation (CSS, TS, Kotlin, Swift) | **PASS**    | `generate.ts` outputs 4 formats                                            |
| Semantic color tokens (not just palette)           | **PASS**    | dark/light semantic sets with 16 tokens each                               |
| 8pt spacing grid                                   | **PASS**    | 12-step scale (0–64px)                                                     |
| Elevation/shadow scale                             | **PASS**    | 4 levels (none, sm, md, lg)                                                |
| Motion/easing tokens                               | **PASS**    | 4 durations + 3 easing curves                                              |
| Per-product color palettes                         | **PARTIAL** | 7/11 products defined; ActionTrail, NoteLett, LocalMemGPT, LLM Lab missing |
| All apps consume generated tokens                  | **FAIL**    | 0/11 web apps import from package; all hand-write                          |
| Light theme fully defined                          | **PASS**    | Both dark and light semantic sets exist                                    |
| Focus ring token                                   | **PASS**    | `focusRing` defined in both themes                                         |
| Overlay/scrim token                                | **PASS**    | `overlayScrim` defined                                                     |

### 2.2 Component Layer (Primitives)

| Best Practice                                                        | Status      | Evidence                                                           |
| -------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------ |
| Shared Button with variants (primary, secondary, ghost, destructive) | **FAIL**    | Each app uses raw `<button>` with inline styles                    |
| Shared Input with validation states                                  | **FAIL**    | No shared input; 1/11 apps uses Zod client-side                    |
| Shared Modal/Dialog with trap focus                                  | **FAIL**    | 3 apps have modals, all different, none trap focus                 |
| Shared Toast with severity levels                                    | **FAIL**    | 3 apps have toasts, all different implementations                  |
| Shared Badge/StatusBadge                                             | **FAIL**    | ActionTrail has `RiskBadge.tsx` + `StatusBadge.tsx` but not shared |
| Shared Card component                                                | **FAIL**    | Each app defines its own card styles                               |
| Shared EmptyState illustration                                       | **FAIL**    | ~2 empty state refs across 7 apps                                  |
| Shared LoadingSpinner/Skeleton                                       | **FAIL**    | 4 apps have loading refs, all inline                               |
| Consistent icon library                                              | **PARTIAL** | 5/7 apps have Lucide in `package.json`; 2 have no icon library     |
| Component composition patterns (Compound Components, Render Props)   | **FAIL**    | No evidence of advanced composition                                |

### 2.3 Experience Layer (Patterns)

| Best Practice                                   | Status      | Evidence                                                                           |
| ----------------------------------------------- | ----------- | ---------------------------------------------------------------------------------- |
| Consistent error boundary (app-level)           | **FAIL**    | 1/11 apps has `not-found.tsx` or `error.tsx`                                       |
| Empty state design for every list view          | **FAIL**    | ~5 total empty state refs across all 7 web apps                                    |
| Confirmation dialog before destructive actions  | **FAIL**    | Only 2/7 apps have `window.confirm` (NomGap 3, LocalMemGPT 2)                      |
| Optimistic updates with rollback                | **PARTIAL** | ActionTrail has optimistic approve/reject; others don't                            |
| Toast feedback on every mutation                | **FAIL**    | Most apps silently succeed/fail                                                    |
| Loading state for every async operation         | **PARTIAL** | 4/7 apps have `isLoading`/`isPending` patterns                                     |
| Hover/active states on all interactive elements | **FAIL**    | 4/7 apps have zero hover refs                                                      |
| Focus-visible on all focusable elements         | **FAIL**    | Only ChronoMind (17 refs); 5 apps have 0-1                                         |
| Keyboard navigation for all flows               | **PARTIAL** | 4/7 apps have keyboard shortcut files                                              |
| Onboarding / first-run experience               | **PARTIAL** | NomGap (5 files), ActionTrail (5), ChronoMind (1), PeakPulse iOS (1), MindLyst (2) |
| Responsive layout for tablet/mobile             | **FAIL**    | Zero `@media` queries in product web apps                                          |
| Consistent micro-copy and success messages      | **PARTIAL** | NoteLett has 38 refs; most apps have 1-9                                           |
| Scroll virtualization for long lists            | **FAIL**    | No `react-window` or `react-virtuoso` in any app                                   |

### 2.4 Quality Layer (Testing & Governance)

| Best Practice                     | Status      | Evidence                                                    |
| --------------------------------- | ----------- | ----------------------------------------------------------- |
| Playwright E2E for critical flows | **PASS**    | 45 spec files across 7 product web apps                     |
| Visual regression screenshots     | **FAIL**    | No Chromatic, Percy, or Playwright screenshot comparison    |
| Automated a11y testing (axe-core) | **FAIL**    | No `@axe-core/playwright` or similar in any repo            |
| Component catalog (Storybook)     | **FAIL**    | 29 `.mdx` files found in common-plat but no Storybook setup |
| Design review PR template         | **FAIL**    | No PR template requiring screenshots                        |
| Token drift detection (CI check)  | **FAIL**    | No CI job validates tokens match generated output           |
| Bundle size tracking              | **PARTIAL** | admin-web + user-dashboard have `.bundlesizerc.json`        |

### 2.5 Native Platform Best Practices

| Best Practice                       | iOS Status                                         | Android Status                        |
| ----------------------------------- | -------------------------------------------------- | ------------------------------------- |
| Theme file using generated tokens   | MindLyst only (gen); 3 hand-written                | All use MindLystTokens.kt or Theme.kt |
| Haptic feedback on key interactions | ChronoMind (9), PeakPulse (12)                     | Not measured                          |
| Live Activities / Dynamic Island    | ChronoMind (8 files), PeakPulse (10), JarvisJr (5) | N/A                                   |
| Widgets (WidgetKit / Glance)        | All 3 iOS apps + NomGap + AuthApp                  | ChronoMind, AuthApp                   |
| VoiceOver / TalkBack labels         | PeakPulse (15), ChronoMind (8), JarvisJr (5)       | Not measured                          |
| Dynamic Type / scalable text        | Minimal evidence                                   | Material 3 handles this               |
| App Intents / Shortcuts             | ChronoMind, PeakPulse                              | Not present                           |

---

## 3. Design Token Foundation

### 3.1 Canonical Source: `bytelyst.tokens.json`

| Category                                                                        | Token Count | Status   |
| ------------------------------------------------------------------------------- | ----------- | -------- |
| **Color Palette** (neutral 11 + brand 10)                                       | 21          | Complete |
| **Semantic Colors** (dark 16 + light 16)                                        | 32          | Complete |
| **Product Palettes** (7 products)                                               | 66          | Complete |
| **Typography** (families 3, weights 4, sizes 7, lineHeights 3, letterSpacing 3) | 20          | Complete |
| **Spacing** (8pt grid, 12 steps)                                                | 12          | Complete |
| **Radius** (6 levels)                                                           | 6           | Complete |
| **Elevation** (4 levels)                                                        | 4           | Complete |
| **Motion** (4 durations + 3 easings)                                            | 7           | Complete |
| **Breakpoints** (4 levels)                                                      | 4           | Complete |
| **Layout** (5 values)                                                           | 5           | Complete |
| **z-Index** (9 levels)                                                          | 9           | Complete |
| **Icon Sizes** (6 levels)                                                       | 6           | Complete |
| **Grid** (columns, gutter, breakpoints)                                         | 8           | Complete |
| **Opacity** (11 levels)                                                         | 11          | Complete |
| **TOTAL**                                                                       | **~211**    |          |

**Product-specific palettes defined:**

- MindLyst (brain gradients: 5), JarvisJr (9), PeakPulse (10), ChronoMind (10), NomGap (10), LysnrAI (7), FlowMonk (20)
- **Missing:** ActionTrail, NoteLett, LocalMemGPT, Local LLM Lab — no product-specific palette in canonical JSON

### 3.2 Generation Pipeline

| Output     | File                                       | Target                   |
| ---------- | ------------------------------------------ | ------------------------ |
| CSS        | `generated/tokens.css` (79 lines)          | Web — `--ml-*` namespace |
| TypeScript | `generated/tokens.ts` (317 lines)          | Web — full JSON export   |
| Kotlin     | `generated/MindLystTokens.kt` (138 lines)  | KMP shared module        |
| Swift      | `generated/MindLystTheme.swift` (89 lines) | iOS SwiftUI              |

**Critical Issue:** The generator outputs **only `--ml-*` (MindLyst) CSS namespace**. It does NOT generate `--cm-*`, `--jj-*`, `--ng-*`, `--at-*`, `--fm-*`, `--nl-*`, `--lmg-*`, `--llm-*` per-product CSS files. Every other product hand-writes its own CSS custom properties.

---

## 4. Per-App Design System Audit

### 4.1 Web Applications (11 total)

| App                   | Repo                              | CSS Lines | Prefix            | Tailwind | Components     | Pages  | Hardcoded Hex | Token Source                 |
| --------------------- | --------------------------------- | --------- | ----------------- | -------- | -------------- | ------ | ------------- | ---------------------------- |
| **ChronoMind**        | learning_ai_clock                 | 109       | `--cm-`           | Yes      | 16             | 10     | **0**         | Hand-written                 |
| **JarvisJr**          | learning_ai_jarvis_jr             | 58        | `--jj-`           | Yes      | 1              | 8      | 7             | Hand-written                 |
| **NomGap**            | learning_ai_fastgap               | 198       | `--ng-` + `--ml-` | Yes      | 13             | 12     | **117**       | Hand-written (leaks `--ml-`) |
| **ActionTrail**       | learning_ai_trails                | 88        | `--at-`           | **No**   | 4              | 10     | 0             | Hand-written                 |
| **FlowMonk**          | learning_ai_flowmonk              | 102       | `--fm-`           | **No**   | 1              | 8      | 29            | Hand-written                 |
| **NoteLett**          | learning_ai_notes                 | 157       | `--nl-` + `--ml-` | Yes      | 16             | 7      | 4             | Hand-written (leaks `--ml-`) |
| **LocalMemGPT**       | learning_ai_local_memory_gpt      | 155       | `--lmg-`          | Yes      | 7              | 1      | 0             | Hand-written                 |
| **MindLyst**          | learning_multimodal_memory_agents | **2,485** | `--ml-`           | **No**   | ~33 API routes | 9      | N/A           | Most comprehensive           |
| **Admin Dashboard**   | learning_ai_common_plat           | 126       | Tailwind          | Yes      | 29             | **62** | 8             | Tailwind defaults            |
| **User Dashboard**    | learning_voice_ai_agent           | 126       | Tailwind          | Yes      | 32             | 22     | 0             | Tailwind defaults            |
| **Tracker Dashboard** | learning_ai_common_plat           | 99        | Tailwind          | Yes      | 2              | 8      | 10            | Tailwind defaults            |
| **Local LLM Lab**     | learning_ai_local_llms            | 182       | `--llm-`          | Yes      | 5              | 6      | 31            | Hand-written                 |

### 4.2 Key Web Findings

1. **No app imports `@bytelyst/design-tokens`** — every single web app hand-writes its CSS custom properties
2. **NomGap web has 117 hardcoded hex colors** in components — worst offender
3. **FlowMonk + ActionTrail have no Tailwind** — plain CSS only
4. **Zero apps use shadcn/ui** — despite AGENTS.md recommending it
5. **JarvisJr web has only 1 component** (Sidebar.tsx) — extremely minimal UI
6. **MindLyst web has the richest CSS** (2,485 lines) but uses vanilla CSS, not Tailwind

### 4.3 iOS Applications (5 apps)

| App               | Swift Files | Screens/Views | Components | Theme File                                     | Hardcoded Colors | a11y Refs |
| ----------------- | ----------- | ------------- | ---------- | ---------------------------------------------- | ---------------- | --------- |
| **PeakPulse**     | 98          | 25            | 17         | `PeakPulseTheme.swift`                         | **0**            | 15        |
| **ChronoMind**    | 89          | 30            | 7          | `ChronoMindTheme.swift`                        | 46               | 8         |
| **JarvisJr**      | 64          | 12            | 7          | `JarvisJrTheme.swift` + `JarvisJrColors.swift` | 20               | 5         |
| **MindLyst**      | 32          | 4             | 2          | `MindLystTheme.swift` (generated)              | N/A              | N/A       |
| **ByteLyst Auth** | 17          | 6             | 0          | None (uses SDK)                                | N/A              | N/A       |

**Best iOS app: PeakPulse** — zero hardcoded colors, most a11y references, richest component library (17 components), proper theme file.

### 4.4 Android Applications (5 apps)

| App               | Screens | Theme File              | Uses kotlin-platform-sdk |
| ----------------- | ------- | ----------------------- | ------------------------ |
| **ChronoMind**    | 5       | `Theme.kt` (Material 3) | Yes                      |
| **JarvisJr**      | 6       | `Theme.kt` (Material 3) | Yes                      |
| **LysnrAI**       | 9       | `Theme.kt` (Material 3) | Yes                      |
| **MindLyst**      | 4       | `MindLystTheme.kt`      | Yes                      |
| **ByteLyst Auth** | 11      | `Theme.kt` (Material 3) | Yes                      |

All Android apps use Material 3 theming and the shared `kotlin-platform-sdk`. Android is the **most consistent** platform for design system adoption.

### 4.5 React Native / Expo (2 apps)

| App                 | Components | Screens | Theme Files                                          | Hardcoded Hex (non-theme) |
| ------------------- | ---------- | ------- | ---------------------------------------------------- | ------------------------- |
| **NomGap** (Expo)   | 13         | 24      | 6 (colors, typography, spacing, ThemeContext, index) | **337**                   |
| **NoteLett** (Expo) | ~10        | ~8      | 0 (no theme dir)                                     | N/A                       |
| **FlowMonk** (Expo) | ~5         | ~7      | 0 (no theme dir)                                     | N/A                       |

**NomGap mobile is the worst offender** in the entire ecosystem — 337 hardcoded hex colors outside the theme directory. The theme files exist but are not being consumed by most screen/component code.

---

## 5. Deep UX Pattern Audit

### 5.1 Navigation Patterns

| Pattern                     | Web Apps                        | Status                                       |
| --------------------------- | ------------------------------- | -------------------------------------------- |
| **Sidebar navigation**      | All 11                          | Consistent — every web app has `Sidebar.tsx` |
| **Tab navigation (mobile)** | NomGap, NoteLett, FlowMonk      | Consistent — Expo Router tabs                |
| **Tab navigation (iOS)**    | ChronoMind, PeakPulse, JarvisJr | 5-tab SwiftUI TabView                        |
| **Bottom nav (Android)**    | ChronoMind, LysnrAI, JarvisJr   | Material 3 BottomNavigationBar               |

**Score: 80%** — Navigation is the most consistent UX pattern across the ecosystem.

### 5.2 Feedback & Notifications

| Pattern                 | Apps With                                  | Apps Without                                 | Score |
| ----------------------- | ------------------------------------------ | -------------------------------------------- | ----- |
| **Toast notifications** | ChronoMind, NomGap, ActionTrail            | JarvisJr, FlowMonk, NoteLett, LocalMemGPT    | 43%   |
| **Modal dialogs**       | ChronoMind (3), NomGap (2), NoteLett (4)   | JarvisJr, ActionTrail, FlowMonk, LocalMemGPT | 43%   |
| **Loading states**      | NomGap, ActionTrail, FlowMonk, LocalMemGPT | ChronoMind, JarvisJr, NoteLett               | 57%   |
| **Error boundaries**    | MindLyst web                               | All others                                   | 9%    |
| **Empty states**        | Minimal across all                         | —                                            | ~20%  |

### 5.3 Data Visualization

| Pattern                  | Apps With                                                        | Score |
| ------------------------ | ---------------------------------------------------------------- | ----- |
| **Recharts charts**      | ChronoMind, NomGap, ActionTrail, Admin Dashboard, User Dashboard | 36%   |
| **Canvas visualization** | NomGap web (BodyCanvas), NomGap mobile (Skia)                    | Niche |
| **Stats/metric cards**   | ChronoMind, NomGap, ActionTrail, FlowMonk                        | ~36%  |

### 5.4 Form & Input Patterns

| Pattern                        | Apps With            | Score |
| ------------------------------ | -------------------- | ----- |
| **Zod client-side validation** | ChronoMind (11 refs) | 9%    |
| **react-hook-form**            | None                 | 0%    |
| **Form error messages**        | Minimal              | ~10%  |
| **Input masking**              | None                 | 0%    |

**Score: 5%** — Forms are the weakest UX area. No shared form components, no validation library adoption beyond ChronoMind.

### 5.5 Accessibility

| Dimension                     | Score   | Evidence                                                  |
| ----------------------------- | ------- | --------------------------------------------------------- |
| **ARIA labels (web)**         | 5%      | Only ChronoMind (10), NoteLett (6), JarvisJr (3) have any |
| **VoiceOver (iOS)**           | 10%     | PeakPulse (15), ChronoMind (8), JarvisJr (5)              |
| **Dynamic Type (iOS)**        | ~5%     | Minimal                                                   |
| **Keyboard navigation (web)** | 15%     | 4/7 apps have keyboard shortcut files                     |
| **Color contrast**            | Unknown | No automated contrast checking                            |
| **Screen reader testing**     | 0%      | No evidence                                               |

### 5.6 Responsive Design

**Score: 5%** — Essentially zero `@media` queries or responsive breakpoints in any product web app, despite the token file defining 4 breakpoints. All apps are fixed-width sidebar+content layouts.

### 5.7 Dark/Light Theme

| App              | Dark      | Light   | Toggle               | Score |
| ---------------- | --------- | ------- | -------------------- | ----- |
| **LocalMemGPT**  | Yes       | Yes     | Yes (`use-theme.ts`) | Full  |
| **ChronoMind**   | Yes       | Partial | Yes (`use-theme.ts`) | 80%   |
| **NomGap web**   | Yes       | No      | No                   | 30%   |
| **MindLyst web** | Yes       | Yes     | `data-theme`         | 70%   |
| All others       | Dark only | No      | No                   | 20%   |

### 5.8 Animation & Motion

| App             | Refs | Quality                                              |
| --------------- | ---- | ---------------------------------------------------- |
| **ChronoMind**  | 75   | Excellent — CountdownRing, AlarmOverlay, transitions |
| **NomGap**      | 22   | Good — body visualization, stage transitions         |
| **LocalMemGPT** | 16   | Decent — chat message animations                     |
| **ActionTrail** | 6    | Minimal                                              |
| Others          | 0-2  | None/trivial                                         |

---

### 5.9 Interaction Quality (NEW — Principal Review Finding)

| Dimension                | Best                  | Worst                                         | Ecosystem Avg |
| ------------------------ | --------------------- | --------------------------------------------- | ------------- |
| **Hover states**         | LocalMemGPT (14 refs) | JarvisJr, ActionTrail, FlowMonk, NoteLett (0) | 2.9/app       |
| **Focus-visible**        | ChronoMind (17 refs)  | 5 apps with 0-1                               | 2.7/app       |
| **Semantic HTML**        | ChronoMind (88 refs)  | NomGap (7 refs)                               | 33/app        |
| **Button consistency**   | ChronoMind (92 refs)  | JarvisJr (3 refs)                             | 33/app        |
| **Confirmation dialogs** | NomGap (3 refs)       | 5 apps with 0                                 | 0.7/app       |
| **Success micro-copy**   | NoteLett (38 refs)    | FlowMonk (1 ref)                              | 9/app         |
| **Loading feedback**     | NomGap (24 refs)      | JarvisJr (0)                                  | 9.6/app       |

**Principal Assessment:** The interaction layer is the ecosystem's weakest UX dimension. Users clicking buttons get no hover feedback in 4/7 web apps. Destructive actions (delete) proceed without confirmation in 5/7 apps. Mutations succeed or fail silently in most apps. This creates a perception of an unfinished, unreliable product regardless of how strong the backend is.

### 5.10 Error Recovery & Edge Cases (NEW — Principal Review Finding)

| Pattern                          | Apps With                         | Apps Without |
| -------------------------------- | --------------------------------- | ------------ |
| **Next.js `not-found.tsx`**      | ChronoMind (2 special pages)      | 6/7 apps     |
| **Next.js `error.tsx` boundary** | ChronoMind (included in 2 above)  | 6/7 apps     |
| **Next.js `loading.tsx`**        | None                              | All 7 apps   |
| **Error boundary (React)**       | MindLyst web only                 | 10/11 apps   |
| **Offline indicator**            | None (web)                        | All web apps |
| **Retry on failure**             | ActionTrail (optimistic rollback) | 10/11 apps   |
| **Session expired handling**     | None consistently                 | All apps     |

**Principal Assessment:** If a user navigates to a non-existent route in 6/7 product web apps, they get the default Next.js 404 — no branded error page, no navigation back. If an API call fails, most apps show nothing. This is a critical gap for production readiness.

---

## 6. Shared Infrastructure Gaps

### 6.1 What EXISTS

| Asset                  | Location                                               | Status                                 |
| ---------------------- | ------------------------------------------------------ | -------------------------------------- |
| Canonical token JSON   | `packages/design-tokens/tokens/bytelyst.tokens.json`   | Complete (211 tokens)                  |
| Token generator        | `packages/design-tokens/scripts/generate.ts`           | Works (4 outputs)                      |
| Generated CSS          | `packages/design-tokens/generated/tokens.css`          | MindLyst only (`--ml-`)                |
| Generated TypeScript   | `packages/design-tokens/generated/tokens.ts`           | Full JSON export                       |
| Generated Kotlin       | `packages/design-tokens/generated/MindLystTokens.kt`   | MindLyst only                          |
| Generated Swift        | `packages/design-tokens/generated/MindLystTheme.swift` | MindLyst only                          |
| MindLyst design-system | `design-system/` in MindLyst repo                      | 5 files (CSS, tokens, component specs) |
| kotlin-platform-sdk    | `packages/kotlin-platform-sdk/`                        | 13 components, all 5 Android apps      |
| swift-platform-sdk     | `packages/swift-platform-sdk/`                         | 13 components, all 5 iOS apps          |

### 6.2 What is MISSING

| Gap                                                     | Impact                                                 | Priority |
| ------------------------------------------------------- | ------------------------------------------------------ | -------- |
| **Per-product CSS generation**                          | Every web app hand-writes tokens                       | P0       |
| **Shared React component library** (`@bytelyst/ui`)     | Zero reusable UI; 11 apps build from scratch           | P0       |
| **shadcn/ui adoption**                                  | Recommended in AGENTS.md but zero apps use it          | P0       |
| **Per-product Swift theme generation**                  | Only MindLyst gets generated Swift; others hand-write  | P1       |
| **Per-product Kotlin token generation**                 | Only MindLyst gets generated Kotlin; others hand-write | P1       |
| **Shared Sidebar component**                            | Every app has its own `Sidebar.tsx` (~11 copies)       | P1       |
| **Shared Toast/notification component**                 | 3/11 apps have toasts, all different                   | P1       |
| **Shared Modal/Dialog component**                       | 3/11 apps have modals, all different                   | P1       |
| **Form validation library**                             | 1/11 apps uses Zod client-side                         | P2       |
| **Responsive breakpoint utilities**                     | Token file defines 4 breakpoints; zero apps use them   | P2       |
| **Accessibility audit tooling**                         | No automated a11y testing                              | P2       |
| **Visual regression testing**                           | No Chromatic/Percy/Playwright screenshot tests         | P2       |
| **Design system documentation site** (Storybook/Cosmos) | No component catalog                                   | P3       |
| **React Native shared theme package**                   | NomGap has 337 hardcoded hex values                    | P1       |

---

## 7. Per-Product Completeness Scorecard

| Product             | Web | iOS     | Android | Mobile (RN) | Token Adoption | UX Richness | Overall |
| ------------------- | --- | ------- | ------- | ----------- | -------------- | ----------- | ------- |
| **ChronoMind**      | 65% | 60%     | 50%     | —           | 55%            | **70%**     | **60%** |
| **NomGap**          | 40% | —       | —       | 25%         | 20%            | 55%         | **35%** |
| **PeakPulse**       | —   | **75%** | —       | —           | **70%**        | 60%         | **68%** |
| **MindLyst**        | 55% | 35%     | 40%     | —           | 60%            | 50%         | **48%** |
| **LocalMemGPT**     | 55% | —       | —       | —           | 55%            | 50%         | **53%** |
| **NoteLett**        | 50% | —       | —       | 30%         | 40%            | 45%         | **41%** |
| **JarvisJr**        | 20% | 45%     | 45%     | —           | 35%            | 30%         | **35%** |
| **ActionTrail**     | 40% | —       | —       | —           | 45%            | 40%         | **42%** |
| **FlowMonk**        | 30% | —       | —       | 25%         | 30%            | 30%         | **29%** |
| **LysnrAI**         | 45% | 50%     | 50%     | —           | 40%            | 45%         | **46%** |
| **Local LLM Lab**   | 40% | —       | —       | —           | 35%            | 35%         | **37%** |
| **Admin Dashboard** | 60% | —       | —       | —           | 50%            | 55%         | **55%** |
| **User Dashboard**  | 55% | —       | —       | —           | 50%            | 50%         | **52%** |
| **ByteLyst Auth**   | —   | 30%     | 40%     | —           | 30%            | 25%         | **31%** |

### Scoring Methodology

- **Web**: Components, pages, Tailwind, token usage, loading states, modals, toasts, a11y, keyboard shortcuts
- **iOS**: Swift files, screens, components, theme file, hardcoded colors, accessibility, platform SDK
- **Android**: Screens, theme, kotlin-platform-sdk, Material 3 compliance
- **Mobile (RN)**: Components, screens, theme files, hardcoded colors
- **Token Adoption**: Correct prefix, imports from generated tokens, no hardcoded hex
- **UX Richness**: Charts, animations, dark/light, responsive, forms, feedback, empty states

---

## 8. Rankings: Best to Worst UX/Design

### Tier 1 — Good Foundation (55-70%)

1. **PeakPulse iOS (68%)** — Best native app. Zero hardcoded colors, proper theme, 17 components, 15 a11y refs, gamification UI (badges, streaks, XP), map integration, charts.
2. **ChronoMind (60%)** — Best web app. 16 components, 75 animation refs, countdown rings, alarm overlays, Pomodoro UI, PWA support, dark/light theme, Zod validation.
3. **Admin Dashboard (55%)** — Most pages (62), 29 components, Recharts, Tailwind, shadcn-like patterns.

### Tier 2 — Moderate (40-55%)

4. **LocalMemGPT (53%)** — Clean single-page app, dark/light toggle, 7 components, markdown rendering, code syntax highlighting.
5. **User Dashboard (52%)** — 32 components, 22 pages, Tailwind, clean Recharts integration.
6. **MindLyst (48%)** — Richest CSS (2,485 lines), KMP shared tokens, but web uses vanilla CSS with no Tailwind.
7. **LysnrAI (46%)** — Comprehensive iOS platform wrappers, 3 theme files, but web dashboard is the user-dashboard (shared).
8. **ActionTrail (42%)** — Clean token system (`--at-*`), SSE real-time, 4 components, but no Tailwind.
9. **NoteLett (41%)** — 16 components, 4 modals, keyboard shortcuts, but CSS leaks `--ml-*` prefix.

### Tier 3 — Minimal (25-40%)

10. **Local LLM Lab (37%)** — 5 components, 31 hardcoded hex, `--llm-*` tokens exist but not fully adopted.
11. **NomGap (35%)** — Rich mobile visualization (Skia canvas), but **337 hardcoded hex** in mobile and **117 in web**. Theme files exist but unused.
12. **JarvisJr (35%)** — Web has only 1 component (Sidebar). iOS is richer (64 swift files, 12 screens) but 20 hardcoded hex.
13. **FlowMonk (29%)** — 1 web component, no Tailwind, 29 hardcoded hex, minimal mobile.
14. **ByteLyst Auth (31%)** — Thin auth companion, no theme file on iOS, relies on SDK.

---

## 9. Target Architecture Blueprint

This is the rock-solid design system architecture that ByteLyst should converge toward. It follows the **layered design system** model used by Shopify Polaris, GitHub Primer, and Atlassian Design System.

### 9.1 Architecture Layers

```
┌─────────────────────────────────────────────────────────────────┐
│  Layer 5: PRODUCT SURFACES                                      │
│  ChronoMind · NomGap · JarvisJr · ActionTrail · FlowMonk · ...  │
│  (consume layers 1-4; add product-specific components only)      │
├─────────────────────────────────────────────────────────────────┤
│  Layer 4: EXPERIENCE PATTERNS (guidelines, not code)             │
│  Navigation · Forms · Error Recovery · Onboarding · Feedback     │
│  Empty States · Loading · Destructive Actions · Accessibility    │
├─────────────────────────────────────────────────────────────────┤
│  Layer 3: @bytelyst/ui — SHARED COMPONENT LIBRARY               │
│  Button · Input · Select · Toast · Modal · Badge · Card ·       │
│  EmptyState · Sidebar · StatCard · Skeleton · ConfirmDialog      │
│  (built on Radix primitives + Tailwind + design tokens)          │
├─────────────────────────────────────────────────────────────────┤
│  Layer 2: @bytelyst/design-tokens — MULTI-PLATFORM TOKENS       │
│  CSS (per-product) · TypeScript · Kotlin · Swift · RN            │
│  (auto-generated from bytelyst.tokens.json)                      │
├─────────────────────────────────────────────────────────────────┤
│  Layer 1: bytelyst.tokens.json — CANONICAL SOURCE OF TRUTH       │
│  Colors · Typography · Spacing · Radius · Elevation · Motion     │
│  Breakpoints · z-Index · Icons · Grid · Opacity · Per-product    │
└─────────────────────────────────────────────────────────────────┘
```

### 9.2 Package Architecture (Target State)

| Package                        | Purpose                                                                         | Consumers                         | Status                                    |
| ------------------------------ | ------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------- |
| `@bytelyst/design-tokens`      | JSON → CSS/TS/Kotlin/Swift/RN generation                                        | All surfaces                      | **EXISTS** (needs per-product CSS)        |
| `@bytelyst/ui`                 | Shared React component library (Radix + Tailwind)                               | All 11 web apps                   | **MISSING**                               |
| `@bytelyst/react-native-theme` | Shared RN theme provider + tokens                                               | NomGap, NoteLett, FlowMonk mobile | **MISSING**                               |
| `@bytelyst/icons`              | Curated Lucide icon re-exports + custom product icons                           | All web + RN                      | **MISSING**                               |
| `@bytelyst/hooks`              | Shared React hooks (useTheme, useKeyboardShortcuts, useMediaQuery, useDebounce) | All web apps                      | **MISSING** (4 apps have inline versions) |

### 9.3 Component Library Design (`@bytelyst/ui`)

Based on the **shadcn/ui + Radix primitives** model (copy-paste friendly, fully customizable):

| Component         | Variants                                                                       | Priority | Based On           |
| ----------------- | ------------------------------------------------------------------------------ | -------- | ------------------ |
| **Button**        | primary, secondary, ghost, destructive, outline; sizes sm/md/lg; loading state | P0       | Radix Slot         |
| **Input**         | text, email, password, search; error/success states; left/right icons          | P0       | Native             |
| **Select**        | single, multi; searchable; with groups                                         | P1       | Radix Select       |
| **Toast**         | success, error, warning, info; auto-dismiss; action button; stack              | P0       | Radix Toast        |
| **Modal/Dialog**  | sizes sm/md/lg/full; focus trap; close on escape; overlay                      | P0       | Radix Dialog       |
| **ConfirmDialog** | destructive confirmation; with input; loading state                            | P0       | Radix AlertDialog  |
| **Badge**         | status (success/warning/error/info); size sm/md; dot variant                   | P0       | Native             |
| **Card**          | default, elevated, outlined; header/body/footer slots                          | P1       | Native             |
| **EmptyState**    | icon, title, description, action button                                        | P0       | Native             |
| **Skeleton**      | text, circle, rect; pulse animation                                            | P1       | Native             |
| **Sidebar**       | collapsible; section groups; badge counts; active state                        | P0       | Native             |
| **StatCard**      | value, label, trend indicator, sparkline slot                                  | P1       | Native             |
| **DataTable**     | sortable, filterable, paginated; row actions; empty state                      | P2       | @tanstack/table    |
| **Tabs**          | default, underline, pill variants                                              | P1       | Radix Tabs         |
| **Tooltip**       | auto-position; delay; rich content                                             | P1       | Radix Tooltip      |
| **Popover**       | auto-position; focus management                                                | P2       | Radix Popover      |
| **DropdownMenu**  | items, separators, sub-menus, keyboard nav                                     | P1       | Radix DropdownMenu |

### 9.4 Every Web App Must Have (Non-Negotiable Checklist)

This is the **minimum UX quality bar** for any ByteLyst web surface shipping to users:

| Requirement              | File/Pattern                                 | Why                                       |
| ------------------------ | -------------------------------------------- | ----------------------------------------- |
| `not-found.tsx`          | `src/app/not-found.tsx`                      | Branded 404 with navigation back          |
| `error.tsx`              | `src/app/error.tsx`                          | Graceful error recovery with retry        |
| `loading.tsx`            | `src/app/loading.tsx` (or per-route)         | Skeleton/spinner during route transitions |
| Global ErrorBoundary     | `providers.tsx` wrapping children            | Catch unhandled React errors              |
| Toast provider           | `<ToastProvider>` in root layout             | Feedback for every mutation               |
| Focus-visible styles     | `globals.css` + `:focus-visible` ring        | Keyboard users can see focus              |
| ARIA labels on icons     | `aria-label` on icon-only buttons            | Screen readers announce actions           |
| Semantic HTML            | `<main>`, `<nav>`, `<h1>`–`<h3>` hierarchy   | SEO + screen readers                      |
| Confirmation on delete   | `<ConfirmDialog>` before destructive actions | Prevent accidental data loss              |
| Loading state on buttons | `disabled` + spinner while `isPending`       | Prevent double-submit                     |
| Empty state for lists    | `<EmptyState>` when data array is empty      | Users know what to do next                |
| Responsive sidebar       | Collapsible on mobile viewport               | Usable on tablets                         |
| `prefers-color-scheme`   | CSS media query or toggle hook               | Respect OS theme preference               |

---

## 10. Detailed Remediation Plan

### Phase 1: Foundation Fix (Weeks 1-2) — Unblock Everything

**Goal:** Make the design system actually consumable. Currently it's defined but not used.

| #   | Task                                                                 | Files to Change                                                       | Impact                                   |
| --- | -------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------- |
| 1.1 | Extend `generate.ts` to output per-product CSS                       | `packages/design-tokens/scripts/generate.ts`                          | Enables all 11 web apps to import tokens |
| 1.2 | Add product palettes for ActionTrail, NoteLett, LocalMemGPT, LLM Lab | `tokens/bytelyst.tokens.json`                                         | Complete coverage                        |
| 1.3 | Generate per-product Swift themes                                    | `generate.ts` → `ChronoMindTheme.swift`, `PeakPulseTheme.swift`, etc. | iOS apps consume generated tokens        |
| 1.4 | Generate per-product Kotlin tokens                                   | `generate.ts` → `ChronoMindTokens.kt`, etc.                           | Android apps consume generated tokens    |
| 1.5 | Generate React Native theme export                                   | `generate.ts` → `tokens.native.ts` with `StyleSheet`-ready values     | RN apps consume tokens                   |
| 1.6 | Fix NomGap `--ml-*` CSS leak                                         | `learning_ai_fastgap/web/src/app/globals.css`                         | Correct namespace                        |
| 1.7 | Fix NoteLett `--ml-*` CSS leak                                       | `learning_ai_notes/web/src/app/globals.css`                           | Correct namespace                        |

### Phase 2: Component Library (Weeks 3-5) — The Highest-ROI Work

**Goal:** Build `@bytelyst/ui` so product teams stop reinventing.

| #   | Task                                           | Approach                                                     |
| --- | ---------------------------------------------- | ------------------------------------------------------------ |
| 2.1 | Create `packages/ui/` with Radix + Tailwind    | `pnpm create` in workspace; peer deps on react, tailwindcss  |
| 2.2 | Build 6 P0 components                          | Button, Toast, Modal, ConfirmDialog, Badge, EmptyState       |
| 2.3 | Build Sidebar as shared component              | Extract from ChronoMind (best implementation, 16 components) |
| 2.4 | Publish to Gitea npm registry                  | Same pattern as other @bytelyst/\* packages                  |
| 2.5 | Pilot adoption in ChronoMind + Admin Dashboard | Replace bespoke components with @bytelyst/ui imports         |
| 2.6 | Add each component README with usage examples  | In-package documentation                                     |

### Phase 3: UX Quality Bar (Weeks 5-7) — Make It Feel Finished

**Goal:** Every web app meets the non-negotiable checklist from §9.4.

| #   | Task                                                          | Apps Affected                                       |
| --- | ------------------------------------------------------------- | --------------------------------------------------- |
| 3.1 | Add `not-found.tsx` + `error.tsx` + `loading.tsx` to all apps | 6/7 product webs missing these                      |
| 3.2 | Add `<ToastProvider>` to all app root layouts                 | 4/7 apps have no toast system                       |
| 3.3 | Add focus-visible CSS to all `globals.css`                    | 5/7 apps have 0-1 focus refs                        |
| 3.4 | Add confirmation dialogs before all delete actions            | 5/7 apps have no confirmation                       |
| 3.5 | Add loading states to all mutation buttons                    | All apps                                            |
| 3.6 | Add empty states to all list views                            | All apps                                            |
| 3.7 | Fix NomGap 454 hardcoded hex values                           | `learning_ai_fastgap/src/` (337) + `web/src/` (117) |
| 3.8 | Add hover/active states to interactive elements               | 4/7 apps with zero hover refs                       |

### Phase 4: Accessibility (Weeks 7-9) — Legal & Ethical Baseline

**Goal:** WCAG 2.1 AA compliance across all web surfaces.

| #   | Task                                         | Approach                                                           |
| --- | -------------------------------------------- | ------------------------------------------------------------------ |
| 4.1 | Add `@axe-core/playwright` to all E2E suites | Automated a11y assertions in existing Playwright specs             |
| 4.2 | Add ARIA labels to all icon-only buttons     | Grep for `<button>` with only SVG children, add `aria-label`       |
| 4.3 | Enforce semantic heading hierarchy           | Every page: exactly one `<h1>`, logical `<h2>`/`<h3>` nesting      |
| 4.4 | Add `<main>` landmark to all layouts         | Wrap content area in `<main>`                                      |
| 4.5 | Color contrast audit                         | Use `tokens.json` values to verify 4.5:1 ratio (text) and 3:1 (UI) |
| 4.6 | iOS VoiceOver pass                           | Add `accessibilityLabel` to all interactive SwiftUI elements       |
| 4.7 | Keyboard-only testing                        | Navigate every critical flow without a mouse                       |

### Phase 5: Polish (Weeks 9-12) — From Functional to Delightful

| #   | Task                                       | Approach                                                 |
| --- | ------------------------------------------ | -------------------------------------------------------- |
| 5.1 | Dark/light theme toggle in all web apps    | Shared `useTheme` hook from `@bytelyst/hooks`            |
| 5.2 | Responsive sidebar (collapsible on mobile) | CSS container queries + toggle button                    |
| 5.3 | Visual regression testing in CI            | Playwright `toHaveScreenshot()` on key pages             |
| 5.4 | Storybook for `@bytelyst/ui`               | Component catalog with all variants + a11y addon         |
| 5.5 | Token drift CI check                       | CI job: run `generate.ts`, diff output, fail if changed  |
| 5.6 | Adopt `react-hook-form` + Zod              | Shared form patterns for all apps with user input        |
| 5.7 | Design review PR template                  | `.github/pull_request_template.md` requiring screenshots |

---

## 11. Critical Recommendations (Prioritized)

### P0 — Blocking Quality (Sprint 1-2)

1. **Extend token generator for all products** — output per-product CSS, Swift, Kotlin, RN files
2. **Create `@bytelyst/ui` with 6 P0 components** — Button, Toast, Modal, ConfirmDialog, Badge, EmptyState
3. **Fix NomGap 454 hardcoded hex violations** — route through theme tokens
4. **Add `not-found.tsx` + `error.tsx` to all 7 product web apps** — branded error recovery
5. **Add focus-visible CSS + ARIA labels** — WCAG 2.1 AA baseline in all web apps
6. **Fix NomGap + NoteLett `--ml-*` prefix leaks** — should be `--ng-*` and `--nl-*` only

### P1 — UX Quality Bar (Sprint 3-5)

7. **Add `<ToastProvider>` to all apps** — feedback on every mutation
8. **Add confirmation dialogs before destructive actions** — 5/7 apps missing this
9. **Add empty states + loading states to all list views** — guides users, prevents confusion
10. **Pilot shadcn/Radix in ChronoMind + Admin Dashboard** — prove the shared component model
11. **Create `@bytelyst/react-native-theme`** — shared RN theme for NomGap, NoteLett, FlowMonk
12. **Extend Swift/Kotlin generators** for all products (not just MindLyst)

### P2 — Polish & Scale (Sprint 6-8)

13. **Dark/light theme toggle** in all web apps
14. **Responsive design** — collapsible sidebar, tablet viewport support
15. **`@axe-core/playwright` automated a11y** in all E2E suites
16. **Visual regression testing** — Playwright `toHaveScreenshot()` in CI
17. **Form validation library** — `react-hook-form` + Zod across all apps with forms
18. **Hover/active states** on all interactive elements in all apps

### P3 — Systematic (Sprint 9-12)

19. **Storybook** for `@bytelyst/ui` — living component catalog
20. **Token drift CI check** — auto-detect when tokens.json changes but generated files don't
21. **Design review PR template** — screenshots required for UI changes
22. **Scroll virtualization** for long lists (`react-virtuoso`)
23. **iOS VoiceOver + Dynamic Type pass** across all 5 apps
24. **Android TalkBack pass** across all 5 apps

---

## 12. Metrics Summary

| Metric                              | Count                                                                                   |
| ----------------------------------- | --------------------------------------------------------------------------------------- |
| **Total web apps**                  | 11 (7 product + 3 dashboards + 1 LLM lab)                                               |
| **Total iOS apps**                  | 5 (ChronoMind, JarvisJr, PeakPulse, MindLyst, ByteLyst Auth)                            |
| **Total Android apps**              | 5 (same products)                                                                       |
| **Total React Native apps**         | 3 (NomGap, NoteLett, FlowMonk)                                                          |
| **Total web components**            | ~122 (across all 11 apps)                                                               |
| **Total web pages**                 | ~163                                                                                    |
| **Total iOS Swift files**           | ~300                                                                                    |
| **Total iOS screens/views**         | ~77                                                                                     |
| **Total E2E spec files**            | 45                                                                                      |
| **Canonical design tokens**         | 211                                                                                     |
| **Product-specific color palettes** | 7 of 11 products                                                                        |
| **Hardcoded hex violations**        | ~620+ (NomGap 454, FlowMonk 29, LLM Lab 31, JarvisJr 27, ChronoMind iOS 46, others ~33) |
| **Apps with zero hardcoded hex**    | 3 web (ChronoMind, ActionTrail, LocalMemGPT), 1 iOS (PeakPulse)                         |
| **Apps with shadcn/ui**             | 0                                                                                       |
| **Apps with responsive design**     | ~0                                                                                      |
| **Apps with accessibility**         | 3 partial (ChronoMind, PeakPulse, NoteLett)                                             |

---

## Appendix A: Token Namespace Registry

| Product           | Web CSS Prefix   | iOS Theme                   | Android Theme      | RN Theme               |
| ----------------- | ---------------- | --------------------------- | ------------------ | ---------------------- |
| MindLyst          | `--ml-*`         | `MindLystTheme.swift` (gen) | `MindLystTheme.kt` | —                      |
| ChronoMind        | `--cm-*`         | `ChronoMindTheme.swift`     | `Theme.kt`         | —                      |
| JarvisJr          | `--jj-*`         | `JarvisJrTheme.swift`       | `Theme.kt`         | —                      |
| NomGap            | `--ng-*`         | —                           | —                  | `src/theme/` (6 files) |
| ActionTrail       | `--at-*`         | —                           | —                  | —                      |
| FlowMonk          | `--fm-*`         | —                           | —                  | —                      |
| NoteLett          | `--nl-*`         | —                           | —                  | —                      |
| LocalMemGPT       | `--lmg-*`        | —                           | —                  | —                      |
| LysnrAI           | (user-dashboard) | `Theme/` (3 files)          | `Theme.kt`         | —                      |
| PeakPulse         | —                | `PeakPulseTheme.swift`      | —                  | —                      |
| Local LLM Lab     | `--llm-*`        | —                           | —                  | —                      |
| Admin Dashboard   | Tailwind         | —                           | —                  | —                      |
| User Dashboard    | Tailwind         | —                           | —                  | —                      |
| Tracker Dashboard | Tailwind         | —                           | —                  | —                      |

## Appendix B: File Counts by Surface

| Surface           | Globals.css Lines | Components   | Pages | E2E Specs |
| ----------------- | ----------------- | ------------ | ----- | --------- |
| ChronoMind web    | 109               | 16           | 10    | 6         |
| JarvisJr web      | 58                | 1            | 8     | 6         |
| NomGap web        | 198               | 13           | 12    | 7         |
| ActionTrail web   | 88                | 4            | 10    | 8         |
| FlowMonk web      | 102               | 1            | 8     | 6         |
| NoteLett web      | 157               | 16           | 7     | 6         |
| LocalMemGPT web   | 155               | 7            | 1     | 6         |
| MindLyst web      | 2,485             | (API routes) | 9     | —         |
| Admin Dashboard   | 126               | 29           | 62    | —         |
| User Dashboard    | 126               | 32           | 22    | —         |
| Tracker Dashboard | 99                | 2            | 8     | —         |
| Local LLM Lab     | 182               | 5            | 6     | —         |

---

## Appendix C: UX Lab Assets (Existing but Disconnected)

The `dashboards/ux-lab/` directory contains 8 prototypes/prompts that were never integrated:

| Prototype                          | Type                    | Status      |
| ---------------------------------- | ----------------------- | ----------- |
| `bolt-command-palette-kit`         | Command palette (Cmd+K) | Prompt only |
| `bolt-ops-ui-kit`                  | Operations UI kit       | Prompt only |
| `bolt-telemetry-explorer`          | Telemetry dashboard     | Prompt only |
| `bolt-timeline-studio`             | Timeline component      | Prompt only |
| `lovable-onboarding-flow`          | Onboarding wizard       | Prompt only |
| `lovable-notify-states-kit`        | Notification states     | Prompt only |
| `lovable-settings-ux-kit`          | Settings patterns       | Prompt only |
| `lovable-design-tokens-playground` | Token playground        | Prompt only |

**Recommendation:** Extract patterns from these prompts into `@bytelyst/ui` component implementations. The command palette kit is particularly valuable — Cmd+K navigation is a power-user pattern that should be ecosystem-wide.

## Appendix D: Design System Adoption Dashboard (Proposed CI Metrics)

To track progress toward Level 3 maturity, add these automated checks to CI:

| Metric                                 | Current | Target     | How to Measure                               |
| -------------------------------------- | ------- | ---------- | -------------------------------------------- |
| Hardcoded hex in components            | 620+    | 0          | `grep -rn '#[0-9A-Fa-f]{6}' src/components/` |
| Apps importing @bytelyst/design-tokens | 0/11    | 11/11      | Check `package.json` deps                    |
| Apps with not-found.tsx                | 1/7     | 7/7        | `find src/app -name not-found.tsx`           |
| Apps with error.tsx                    | 1/7     | 7/7        | `find src/app -name error.tsx`               |
| ARIA labels per app                    | 2.7 avg | >20        | `grep -rn 'aria-label' src/`                 |
| Focus-visible refs per app             | 2.7 avg | >10        | `grep -rn 'focus-visible' src/`              |
| Components from @bytelyst/ui           | 0       | >6 per app | Check imports                                |
| Visual regression specs                | 0       | >5 per app | Count `toHaveScreenshot` calls               |
| Lighthouse a11y score                  | Unknown | >90        | Playwright + Lighthouse CI                   |

---

_Generated by Windsurf Cascade — full workspace scan of 16 repos._
_Principal review: design system maturity assessment, best practices audit, architecture blueprint, and remediation plan._