learning_ai_common_plat/docs/design-system/ONBOARDING.md

Design System Onboarding Guide

For developers and AI coding agents working on ByteLyst products.

Overview

ByteLyst uses a unified design system via @bytelyst/design-tokens. This ensures consistent colors, typography, spacing, and motion across all platforms (Web, iOS, Android, React Native).

Key Principle: Never hardcode colors. Always use design tokens.

---

Platform Quick Reference

Platform	Token Source	Import Path	Primary Usage
Web (CSS)	tokens.css	@bytelyst/design-tokens/generated/tokens.css	CSS custom properties (var(--ml-*))
Web (TS)	tokens.ts	@bytelyst/design-tokens/generated/tokens	TypeScript constants
iOS	MindLystTheme.swift	Copy & rename to ProductTheme.swift	ProductColors.dark*, ProductSpacing
Android/KMP	MindLystTokens.kt	Copy to shared/.../theme/	MindLystTokens.Dark.*
React Native	react-native/tokens.ts	@bytelyst/design-tokens/generated/react-native/tokens	tokens.colors.*, tokens.spacing.*

---

Per-Product Setup

MindLyst (Reference Implementation)

iOS:

// iosApp/MindLystTheme.swift
// Uses generated MindLystTheme.swift directly
Text("Hello").foregroundColor(MindLystColors.darkTextPrimary)

Android:

// shared/src/commonMain/kotlin/.../theme/MindLystTokens.kt
// Uses generated MindLystTokens.kt directly

Status: ✅ 100% token adoption — use as reference.

---

ChronoMind (Needs Migration)

Current: Hardcoded colors in Web (#5A8CFF)

Migration Steps:

1. Web:

   # In web/src/app/globals.css
   @import '@bytelyst/design-tokens/generated/tokens.css';
   

   // Replace: style={{ backgroundColor: '#5A8CFF' }}
   // With:    style={{ backgroundColor: 'var(--cm-accent-primary)' }}
   

2. iOS:

   # Copy theme file
   cp mindlyst-native/iosApp/MindLystTheme.swift ios/ChronoMind/Shared/Theme/ChronoMindTheme.swift
   

   // Find/replace: Color(hex: 0x5A8CFF)
   // With:        ChronoMindColors.darkAccentPrimary
   

Priority: High (26 hardcoded colors)

---

PeakPulse (Needs Migration)

Current: No tokens detected, but no hardcoded colors either

Migration Steps:

1. Copy MindLystTheme.swift → PeakPulse/Theme/PeakPulseTheme.swift
2. Use product-specific tokens:

   PeakPulseColors.activityHike
   PeakPulseColors.speedZoneFast
   

Priority: Medium (clean slate — easier migration)

---

NomGap (Critical — 466 Hardcoded Colors)

Current: React Native StyleSheet with inline hex values

Migration Steps:

1. Install tokens:

   # Copy generated file to your repo
   cp learning_ai_common_plat/packages/design-tokens/generated/react-native/tokens.ts nomgap/src/theme/
   

2. Create theme provider:

   // src/theme/index.ts
   import { tokens } from './tokens';
   
   export const theme = {
     colors: tokens.colors,
     spacing: tokens.spacing,
     radius: tokens.radius,
   };
   

3. Migrate styles:

   // Before:
   const styles = StyleSheet.create({
     container: { backgroundColor: '#5A8CFF' },
   });
   
   // After:
   import { tokens } from '../theme';
   const styles = StyleSheet.create({
     container: { backgroundColor: tokens.colors.accentPrimary },
   });
   

Tools: Use token-coverage.js to track progress:

node ../learning_ai_common_plat/packages/design-tokens/scripts/token-coverage.cjs src/

Priority: Critical (466 colors in 36 files)

---

LysnrAI (Needs Migration)

Current: 34 hardcoded colors in iOS, unknown Android state

Migration Steps:

1. Integrate with existing ByteLystPlatformSDK
2. Use color.lysnrai tokens:

   // Available tokens:
   LysnrAIColors.recordingActive    // #FF6E6E
   LysnrAIColors.processing         // #5A8CFF
   LysnrAIColors.transcribed       // #34D399
   

Priority: High

---

JarvisJr (Needs Migration)

Current: 8 hardcoded colors

Migration Steps:

1. Copy theme file from MindLyst pattern
2. Use existing color.jarvisjr tokens:

   JarvisJrColors.agentCoach
   JarvisJrColors.agentLingua
   

Priority: Low (only 8 colors — quick fix)

---

Common Patterns

Adding a New Color

1. Edit packages/design-tokens/tokens/bytelyst.tokens.json:

   "color": {
     "yourproduct": {
       "newColor": "#RRGGBB"
     }
   }
   

2. Regenerate:

   pnpm --filter @bytelyst/design-tokens generate
   

3. Copy to your repo and use:

   // iOS
   YourProductColors.newColor
   
   // Web
   var(--yp-new-color)
   

---

Validation Before Commit

Always run validation before committing UI changes:

# From your product repo root
node ../learning_ai_common_plat/packages/design-tokens/scripts/validate-tokens.cjs src/

Exit codes:

• 0 — No hardcoded colors found ✅
• 1 — Hardcoded colors detected ❌

---

CI Integration

Add to your .github/workflows/ci.yml:

design-system-check:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Check for hardcoded colors
      run: |
        node ../learning_ai_common_plat/packages/design-tokens/scripts/validate-tokens.cjs src/
        if [ $? -ne 0 ]; then
          echo "❌ Hardcoded colors found. Use design tokens."
          exit 1
        fi        

---

Token Cheat Sheet

Semantic Colors (Dark Mode)

Token	Hex	Usage
--ml-bg-canvas	#06070A	Page background
--ml-surface-card	#121725	Card backgrounds
--ml-text-primary	#EFF4FF	Main text
--ml-text-secondary	#A5B1C7	Secondary text
--ml-accent-primary	#5A8CFF	Primary actions
--ml-accent-secondary	#2EE6D6	Secondary accent
--ml-success	#34D399	Success states
--ml-warning	#F59E0B	Warnings
--ml-danger	#FF6E6E	Errors/danger

Spacing (8pt Grid)

Token	Value	Common Use
--ml-space-1	4px	Tight gaps
--ml-space-2	8px	Small padding
--ml-space-4	16px	Standard padding
--ml-space-6	24px	Large padding
--ml-space-8	32px	Section gaps

Typography

Token	Value	Usage
--ml-font-display	Space Grotesk	Headlines
--ml-font-body	DM Sans	Body text
--ml-fs-lg	18px	Large text
--ml-fs-xl	22px	Headlines

---

Troubleshooting

"Tokens not found" error

Cause: Generated files not copied to consumer repo.

Fix:

# Regenerate and copy
pnpm --filter @bytelyst/design-tokens generate
cp packages/design-tokens/generated/MindLystTheme.swift ../your-repo/ios/

"Validation script fails with parsing error"

Cause: ES module vs CommonJS mismatch.

Fix: Use .cjs extension for scripts:

node scripts/validate-tokens.cjs src/

"Colors look wrong in dark mode"

Cause: Using static hex instead of semantic tokens.

Fix: Use dark/light semantic tokens, not palette colors directly:

/* ❌ Bad - always same color */
color: #5a8cff;

/* ✅ Good - adapts to theme */
color: var(--ml-accent-primary);

---

Resources

• Full Audit: docs/design-system/DESIGN_SYSTEM_AUDIT_2026-03-03.md
• Token Reference: packages/design-tokens/README.md
• AGENTS.md: Coding conventions for AI agents
• Audit Report: Current adoption status across all products

---

Migration Priority Matrix

Product	Hardcoded Colors	Priority	Effort
NomGap	466	🔴 Critical	High (1 week)
ChronoMind Web	26	🟠 High	Low (1 day)
LysnrAI iOS	34	🟠 High	Medium (2 days)
Admin Dashboard	60	🟠 High	Low (1 day)
JarvisJr iOS	8	🟡 Medium	Low (2 hours)
PeakPulse iOS	0	🟢 Low	Low (1 day)

---

Contact

For questions about the design system:

• Check the audit report for current status
• Review MindLyst implementation as reference
• Run validation scripts to check compliance

---

Last updated: 2026-03-03