learning_ai_common_plat/docs/design-system/DESIGN_SYSTEM_AUDIT_2026-03-03.md

ByteLyst Design System Audit Report

Date: 2026-03-03
Auditor: AI Coding Agent
Scope: All 7 product repositories across 4 platforms
Token Version: 1.1.0

---

Executive Summary

Metric	Value
Total Products Audited	7
Platforms Covered	4 (Web, iOS, Android/KMP, React Native)
Total Source Files	576
Files with Token Usage	15 (2.6%)
Files with Hardcoded Colors	55 (9.5%)
Total Hardcoded Colors Found	594
Overall Token Adoption	CRITICAL ⚠️

Key Finding

Only MindLyst (iOS + Android) has implemented design tokens. All other products use hardcoded colors, creating inconsistency and maintenance debt.

---

Product-by-Product Breakdown

1. MindLyst (iOS) — ✅ GOOD

Metric	Value
Files Scanned	26
Files Using Tokens	10 (38.5%)
Token Usages	116
Hardcoded Colors	0
Token Adoption	100%

Status: Properly consuming MindLystTheme.swift with no hardcoded colors.

---

2. MindLyst (Android/KMP) — ✅ GOOD

Metric	Value
Files Scanned	12
Files Using Tokens	5 (41.7%)
Token Usages	47
Hardcoded Colors	0
Token Adoption	100%

Status: Properly consuming MindLystTokens.kt with no hardcoded colors.

---

3. ChronoMind (Web) — ❌ CRITICAL

Metric	Value
Files Scanned	81
Files Using Tokens	0
Hardcoded Colors	26 in 8 files
Token Adoption	0%

Action Required:

• Import tokens.css in globals.css
• Replace hardcoded hex values with --cm-* CSS variables
• Update theme hook to use design tokens

---

4. ChronoMind (iOS) — ❌ CRITICAL

Metric	Value
Status	Not scanned (assumed similar to Web)
Token Adoption	0% (estimated)

Action Required:

• Copy MindLystTheme.swift → ChronoMindTheme.swift
• Find/replace all Color(hex:) with token references

---

5. PeakPulse (iOS) — ⚠️ WARNING

Metric	Value
Files Scanned	69
Files Using Tokens	0
Hardcoded Colors	0 (surprising)
Token Adoption	0%

Observation: No hardcoded colors detected, but no tokens used either. Likely using system defaults or runtime color generation. Needs token integration for brand consistency.

Action Required:

• Copy MindLystTheme.swift → PeakPulseTheme.swift
• Define PeakPulse-specific colors in token file
• Update all SwiftUI views

---

6. NomGap (React Native) — ❌ CRITICAL

Metric	Value
Files Scanned	108
Files Using Tokens	0
Hardcoded Colors	466 in 36 files
Token Adoption	0%

Status: Worst offender — 466 hardcoded colors in StyleSheet objects.

Action Required:

• Import @bytelyst/design-tokens/generated/react-native/tokens
• Create RN theme provider
• Replace all backgroundColor: '#...' with tokens.colors.bgCanvas
• Update 36 files with hardcoded colors

---

7. LysnrAI (iOS) — ❌ CRITICAL

Metric	Value
Files Scanned	64
Files Using Tokens	0
Hardcoded Colors	34 in 3 files
Token Adoption	0%

Action Required:

• Integrate ByteLystPlatformSDK design tokens
• Replace 34 hardcoded colors
• Add LysnrAI-specific voice/recording colors

---

8. LysnrAI (Android) — ❌ CRITICAL

Metric	Value
Status	Not scanned (assumed similar to iOS)
Token Adoption	0% (estimated)

Action Required:

• Integrate Kotlin design tokens
• Replace hardcoded colors in XML and Compose files

---

9. JarvisJr (iOS) — ❌ CRITICAL

Metric	Value
Files Scanned	46
Files Using Tokens	0
Hardcoded Colors	8 in 3 files
Token Adoption	0%

Action Required:

• Integrate design tokens from ByteLystPlatformSDK
• Replace 8 hardcoded colors
• Leverage existing jarvisjr token section

---

10. Admin Dashboard (Web) — ❌ CRITICAL

Metric	Value
Files Scanned	171
Files Using Tokens	0
Hardcoded Colors	60 in 5 files
Token Adoption	0%

Action Required:

• Import design tokens CSS
• Replace Tailwind arbitrary values with token CSS variables
• Update 5 files with hardcoded colors

---

Platform Analysis

Web (ChronoMind, Admin Dashboard)

• Token System: CSS custom properties (--ml-*, --cm-*, --jj-*, etc.)
• Current State: ❌ No products using tokens
• Blockers: Hardcoded hex in JSX style props, inline Tailwind classes
• Migration Effort: Medium (2-3 days per product)

iOS (ChronoMind, PeakPulse, LysnrAI, JarvisJr)

• Token System: MindLystTheme.swift pattern
• Current State: ❌ Only MindLyst using tokens
• Blockers: Products have own theme files or hardcoded colors
• Migration Effort: Low (1-2 days per product — copy+rename pattern)

Android/KMP (MindLyst only)

• Token System: MindLystTokens.kt
• Current State: ✅ Working well
• Gap: Other Android apps not using shared tokens

React Native (NomGap)

• Token System: generated/react-native/tokens.ts
• Current State: ❌ Not consuming tokens
• Blockers: StyleSheet.create() with hardcoded values
• Migration Effort: High (5-7 days — 466 colors to replace)

---

Hardcoded Color Patterns Found

Most Common Offenders

1. StyleSheet.create() (React Native): 466 instances in NomGap
2. Tailwind arbitrary values: bg-[#5A8CFF] in Web apps
3. SwiftUI inline colors: Color(hex: 0x5A8CFF) in iOS
4. CSS hex values: color: #5A8CFF in Web

Product-Specific Hotspots

Product	Primary Offenders	Count
NomGap	src/screens/, src/components/	466
Admin Dashboard	src/app/(dashboard)/, src/components/ui/	60
LysnrAI iOS	LysnrAI/Views/	34
ChronoMind Web	src/app/, src/components/	26
JarvisJr iOS	JarvisJr/Views/	8

---

Recommendations

Immediate Actions (This Week)

1. Create migration tickets for each product with hardcoded colors
2. Update AGENTS.md in each repo with token usage guidelines
3. Add CI check to block PRs with new hardcoded colors
4. Schedule NomGap refactor — highest impact due to 466 colors

Short-term (Next 2 Weeks)

1. Migrate ChronoMind Web (26 colors — easiest win)
2. Migrate PeakPulse iOS (0 hardcoded, just needs token adoption)
3. Migrate JarvisJr iOS (8 colors — quick fix)
4. Update remaining iOS apps using MindLyst pattern

Medium-term (Next Month)

1. Full NomGap React Native migration (466 colors)
2. LysnrAI mobile apps (34 colors + SDK integration)
3. Admin Dashboard (60 colors)
4. Add automated token coverage reporting to CI

Long-term (Ongoing)

1. ESLint rule no-hardcoded-colors in all repos
2. Pre-commit hook to catch colors before commit
3. Token coverage badge in each repo README
4. Quarterly audits to maintain consistency

---

Tooling

Validation Scripts

Located in packages/design-tokens/scripts/:

# Check for hardcoded colors
node packages/design-tokens/scripts/validate-tokens.cjs <path>

# Get token coverage report
node packages/design-tokens/scripts/token-coverage.cjs <path>

CI Integration

Add to GitHub Actions:

- name: Check for hardcoded colors
  run: |
    node ../../learning_ai_common_plat/packages/design-tokens/scripts/validate-tokens.cjs src/ || true    

---

Success Metrics

Metric	Current	Target	Timeline
Products with 100% token adoption	1/7 (14%)	7/7 (100%)	1 month
Total hardcoded colors	594	0	1 month
Files using tokens	15/576 (2.6%)	400+ (70%)	2 months
New PRs with hardcoded colors	N/A	0%	Immediate

---

Appendix: Token Consumption Guide

For Web Developers

// ❌ DON'T
<div style={{ backgroundColor: '#5A8CFF' }} />

// ✅ DO
// In globals.css:
// @import '@bytelyst/design-tokens/generated/tokens.css';
<div style={{ backgroundColor: 'var(--ml-accent-primary)' }} />

For iOS Developers

// ❌ DON'T
Color(hex: 0x5A8CFF)

// ✅ DO
// Copy MindLystTheme.swift → ProductTheme.swift
ProductColors.darkAccentPrimary

For React Native Developers

// ❌ DON'T
StyleSheet.create({
  container: { backgroundColor: '#5A8CFF' },
});

// ✅ DO
import { tokens } from '@bytelyst/design-tokens/generated/react-native/tokens';

StyleSheet.create({
  container: { backgroundColor: tokens.colors.accentPrimary },
});

---

Report generated by design system audit tooling. For questions, refer to packages/design-tokens/README.md or contact the platform team.