bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: design system audit, onboarding guide, and AGENTS.md updates

Browse Source 
- Comprehensive audit report: DESIGN_SYSTEM_AUDIT_2026-03-03.md
  - Token consumption across all 7 repos
  - 594 hardcoded colors identified
  - Per-product breakdown with migration priorities

- Developer onboarding guide: ONBOARDING.md
  - Platform-specific setup instructions
  - Migration steps for each product
  - Token cheat sheet and troubleshooting

- Updated AGENTS.md with Design System section
  - Never hardcode colors rule
  - Platform usage patterns (Web, iOS, Android, RN)
  - Current adoption status table
  - Validation commands

- Added design-tokens package README
  - Quick start for all platforms
  - Usage examples (CSS, TS, Swift, Kotlin, RN)
  - CI integration examples
This commit is contained in:
saravanakumardb1 2026-03-03 21:55:02 -08:00
parent 2a0a59e56c
commit a33f3cfbd6
4 changed files with 1076 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
AGENTS.md
View File

@ -110,7 +110,88 @@ learning_ai_common_plat/
- Never delete existing comments or documentation unless explicitly asked
- Never add emojis to code unless explicitly asked
## 5. File Ownership Map
## 5. Design System (Critical)
### NEVER hardcode colors
**All colors MUST come from `@bytelyst/design-tokens`.** Hardcoded hex values create inconsistency and maintenance debt.
| Platform | ❌ DON'T | ✅ DO |
| ------------------ | ---------------------------- | ------------------------------------------- |
| **Web** | `color: '#5A8CFF'` | `color: var(--ml-accent-primary)` |
| **Web (Tailwind)** | `bg-[#5A8CFF]` | `bg-[var(--ml-accent-primary)]` |
| **iOS** | `Color(hex: 0x5A8CFF)` | `MindLystColors.darkAccentPrimary` |
| **Android/KMP** | `Color(0xFF5A8CFF)` | `Color(MindLystTokens.Dark.ACCENT_PRIMARY)` |
| **React Native** | `backgroundColor: '#5A8CFF'` | `tokens.colors.accentPrimary` |
### Token file locations
```
packages/design-tokens/
├── tokens/bytelyst.tokens.json # ← CANONICAL SOURCE (edit this)
├── generated/
│ ├── tokens.css # Web: CSS custom properties
│ ├── tokens.ts # TypeScript constants
│ ├── MindLystTokens.kt # Kotlin/KMP/Android
│ ├── MindLystTheme.swift # Swift/iOS
│ └── react-native/tokens.ts # React Native
└── scripts/
├── generate.ts # Main generator
├── generate-react-native.ts # RN generator
├── validate-tokens.cjs # Validation script
└── token-coverage.cjs # Coverage report
```
### How to update tokens
1. **Edit** `packages/design-tokens/tokens/bytelyst.tokens.json`
2. **Run** `pnpm --filter @bytelyst/design-tokens generate`
3. **Copy** generated files to consumer repos (see per-repo AGENTS.md)
4. **Commit** both the JSON source AND generated files
### Product-specific token sections
Each product has a dedicated section in `bytelyst.tokens.json`:
| Product | Token Section | Example |
| ---------- | ------------------ | ------------------------------------ |
| MindLyst | `color.brain` | `BRAIN_WORK`, `BRAIN_HOME` |
| JarvisJr | `color.jarvisjr` | `AGENT_COACH`, `AGENT_LINGUA` |
| PeakPulse | `color.peakpulse` | `ACTIVITY_HIKE`, `SPEED_ZONE_FAST` |
| ChronoMind | `color.chronomind` | `URGENCY_CRITICAL`, `FOCUS_MODE` |
| NomGap | `color.nomgap` | `STAGE_KETOSIS`, `AUTOPHAGY_METER` |
| LysnrAI | `color.lysnrai` | `RECORDING_ACTIVE`, `DICTATION_MODE` |
### Validation
Check for hardcoded colors before committing:
```bash
# In any product repo
node ../learning_ai_common_plat/packages/design-tokens/scripts/validate-tokens.cjs src/
# Get coverage report
node ../learning_ai_common_plat/packages/design-tokens/scripts/token-coverage.cjs src/
```
**CI Integration:** All PRs should run the validation script and fail if new hardcoded colors are introduced.
### Current adoption status (2026-03-03)
| Product | Token Adoption | Status |
| ---------------- | -------------- | --------------------------- |
| MindLyst iOS | 100% | ✅ Good |
| MindLyst Android | 100% | ✅ Good |
| ChronoMind Web | 0% | ❌ Critical |
| ChronoMind iOS | 0% | ❌ Critical |
| PeakPulse iOS | 0% | ❌ Needs tokens |
| NomGap | 0% | ❌ Critical (466 hardcoded) |
| LysnrAI iOS | 0% | ❌ Critical |
| JarvisJr iOS | 0% | ❌ Critical |
See full audit: [`docs/design-system/DESIGN_SYSTEM_AUDIT_2026-03-03.md`](docs/design-system/DESIGN_SYSTEM_AUDIT_2026-03-03.md)
## 6. File Ownership Map
| Domain | Location | Key Files |
| ----------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |

357
docs/design-system/DESIGN_SYSTEM_AUDIT_2026-03-03.md Normal file
View File

@ -0,0 +1,357 @@
# 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/`:
```bash
# 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:
```yaml
- 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
```tsx
// ❌ 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
```swift
// ❌ DON'T
Color(hex: 0x5A8CFF)
// ✅ DO
// Copy MindLystTheme.swift → ProductTheme.swift
ProductColors.darkAccentPrimary
```
### For React Native Developers
```tsx
// ❌ 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._

361
docs/design-system/ONBOARDING.md Normal file
View File

@ -0,0 +1,361 @@
# 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:**
```swift
// iosApp/MindLystTheme.swift
// Uses generated MindLystTheme.swift directly
Text("Hello").foregroundColor(MindLystColors.darkTextPrimary)
```
**Android:**
```kotlin
// 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:**
```bash
# In web/src/app/globals.css
@import '@bytelyst/design-tokens/generated/tokens.css';
```
```tsx
// Replace: style={{ backgroundColor: '#5A8CFF' }}
// With: style={{ backgroundColor: 'var(--cm-accent-primary)' }}
```
2. **iOS:**
```bash
# Copy theme file
cp mindlyst-native/iosApp/MindLystTheme.swift ios/ChronoMind/Shared/Theme/ChronoMindTheme.swift
```
```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:
```swift
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:**
```bash
# 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:**
```typescript
// src/theme/index.ts
import { tokens } from './tokens';
export const theme = {
colors: tokens.colors,
spacing: tokens.spacing,
radius: tokens.radius,
};
```
3. **Migrate styles:**
```typescript
// 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:
```bash
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:
```swift
// 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:
```swift
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`:
```json
"color": {
"yourproduct": {
"newColor": "#RRGGBB"
}
}
```
2. Regenerate:
```bash
pnpm --filter @bytelyst/design-tokens generate
```
3. Copy to your repo and use:
```swift
// iOS
YourProductColors.newColor
// Web
var(--yp-new-color)
```
---
### Validation Before Commit
Always run validation before committing UI changes:
```bash
# 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`:
```yaml
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:**
```bash
# 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:
```bash
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:
```css
/* ❌ 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`](../docs/design-system/DESIGN_SYSTEM_AUDIT_2026-03-03.md)
- **Token Reference:** [`packages/design-tokens/README.md`](../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_

276
packages/design-tokens/README.md Normal file
View File

@ -0,0 +1,276 @@
# @bytelyst/design-tokens
ByteLyst cross-platform design system tokens. Single source of truth for colors, typography, spacing, and more across Web, iOS, Android/KMP, and React Native.
## Quick Start
### Install
```bash
# This is a workspace package - use from source
# Copy generated files to your project
```
### Generate Tokens
```bash
# From the monorepo root
pnpm --filter @bytelyst/design-tokens generate
```
This regenerates all platform outputs from `tokens/bytelyst.tokens.json`.
---
## Token Structure
### Color Tokens
| Token Path | Example Value | Usage |
| ----------------------------------- | ------------- | -------------------------- |
| `color.semantic.dark.bgCanvas` | `#06070A` | Dark mode background |
| `color.semantic.dark.accentPrimary` | `#5A8CFF` | Primary brand color |
| `color.semantic.light.surfaceCard` | `#FFFFFF` | Light mode card background |
| `color.nomgap.stageKetosis` | `#5A8CFF` | Product-specific color |
### Typography Tokens
| Token Path | Value | CSS Output |
| -------------------------------- | ----------------- | ------------------- |
| `typography.fontFamily.display` | `'Space Grotesk'` | `--ml-font-display` |
| `typography.fontSize.lg` | `18` | `--ml-fs-lg: 18px` |
| `typography.fontWeight.semibold` | `600` | — |
### Spacing Tokens (8pt Grid)
| Token | Value | CSS |
| ----------- | ----- | -------------------- |
| `spacing.1` | `4` | `--ml-space-1: 4px` |
| `spacing.4` | `16` | `--ml-space-4: 16px` |
| `spacing.8` | `32` | `--ml-space-8: 32px` |
### Elevation Tokens
| Token | CSS Output |
| -------------- | ------------------------------------------------- |
| `elevation.sm` | `--ml-elevation-sm: 0 4px 12px rgba(0,0,0,0.12)` |
| `elevation.md` | `--ml-elevation-md: 0 12px 28px rgba(0,0,0,0.18)` |
---
## Platform Usage
### Web (CSS)
```css
/* Import the CSS file */
@import '@bytelyst/design-tokens/generated/tokens.css';
/* Use tokens */
.my-component {
background-color: var(--ml-bg-canvas);
color: var(--ml-text-primary);
padding: var(--ml-space-4);
border-radius: var(--ml-radius-md);
box-shadow: var(--ml-elevation-sm);
font-family: var(--ml-font-display);
font-size: var(--ml-fs-lg);
}
```
#### With Tailwind CSS
```html
<!-- Use arbitrary values with CSS variables -->
<div class="bg-[var(--ml-bg-canvas)] text-[var(--ml-text-primary)] p-[var(--ml-space-4)]">
Content
</div>
```
### Web (TypeScript)
```typescript
import { tokens } from '@bytelyst/design-tokens/generated/tokens';
// Access any token programmatically
const primaryColor = tokens.color.semantic.dark.accentPrimary;
const fontSize = tokens.typography.fontSize.lg;
```
### iOS (SwiftUI)
```swift
import SwiftUI
// Copy MindLystTheme.swift to your project
// Rename to YourProductTheme.swift
struct MyView: View {
var body: some View {
Text("Hello")
.foregroundColor(ProductColors.darkTextPrimary)
.background(ProductColors.darkBgCanvas)
.font(.system(size: ProductSpacing.x4))
}
}
```
### Android/KMP (Kotlin + Compose)
```kotlin
import com.mindlyst.shared.theme.MindLystTokens
@Composable
fun MyComponent() {
Box(
modifier = Modifier
.background(Color(MindLystTokens.Dark.BG_CANVAS))
.padding(MindLystTokens.Spacing.X4.dp)
) {
Text(
text = "Hello",
color = Color(MindLystTokens.Dark.TEXT_PRIMARY),
fontSize = MindLystTokens.Typography.SIZE_LG.sp
)
}
}
```
### React Native (Expo)
```typescript
import { tokens } from '@bytelyst/design-tokens/generated/react-native/tokens';
import { StyleSheet } from 'react-native';
const styles = StyleSheet.create({
container: {
backgroundColor: tokens.colors.bgCanvas,
padding: tokens.spacing['4'],
borderRadius: tokens.radius.md,
},
text: {
color: tokens.colors.textPrimary,
fontSize: tokens.typography.fontSize.lg,
},
});
```
---
## Product-Specific Tokens
Each product has dedicated color tokens:
```json
{
"color": {
"nomgap": {
"stageFed": "#FF9F43",
"stageKetosis": "#5A8CFF",
"autophagyMeter": "#5AE68C"
},
"chronomind": {
"urgencyCritical": "#FF6E6E",
"focusMode": "#7C6BFF"
},
"peakpulse": {
"activityHike": "#34D399",
"speedZoneFast": "#FFD166"
}
}
}
```
---
## Validation & Compliance
### Check for Hardcoded Colors
```bash
# From your product repo
node ../learning_ai_common_plat/packages/design-tokens/scripts/validate-tokens.cjs src/
```
This scans for `#RRGGBB`, `rgb()`, `rgba()`, and `hsl()` patterns.
### Get Token Coverage Report
```bash
# From your product repo
node ../learning_ai_common_plat/packages/design-tokens/scripts/token-coverage.cjs src/
```
Reports:
- Percentage of files using tokens
- Number of hardcoded colors found
- Token adoption rate
---
## CI Integration
### GitHub Actions Example
```yaml
- 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 instead."
exit 1
fi
```
### Pre-commit Hook
```bash
# .husky/pre-commit or .git/hooks/pre-commit
node packages/design-tokens/scripts/validate-tokens.cjs src/ || true
```
---
## Token Categories (v1.1.0)
| Category | Count | Description |
| -------------- | ----- | ------------------------------------------------ |
| **Color** | 80+ | Palette, semantic (dark/light), product-specific |
| **Typography** | 20+ | Font families, sizes, weights, line heights |
| **Spacing** | 13 | 8pt grid (0-64px) |
| **Radius** | 6 | Corner radii (xs to pill) |
| **Elevation** | 4 | Shadow depths |
| **Motion** | 7 | Durations, easings |
| **Z-Index** | 9 | Layer stacking |
| **Icon** | 6 | Icon sizes |
| **Grid** | 12 | 12-column system |
| **Opacity** | 11 | Alpha values |
---
## Version History
| Version | Date | Changes |
| ------- | ---------- | ------------------------------------------------------------------------------------------------- |
| 1.1.0 | 2026-03-03 | Added product tokens (PeakPulse, ChronoMind, NomGap, LysnrAI), z-index, icon sizes, grid, opacity |
| 1.0.0 | 2026-02-12 | Initial release with color, typography, spacing, radius, elevation, motion |
---
## Contributing
1. Edit `tokens/bytelyst.tokens.json` (canonical source)
2. Run `pnpm generate` to regenerate outputs
3. Copy generated files to consumer repos
4. Commit both source and generated files
**Never edit generated files directly** — they will be overwritten.
---
## See Also
- [Design System Audit Report](../../docs/design-system/DESIGN_SYSTEM_AUDIT_2026-03-03.md)
- [AGENTS.md](../../AGENTS.md) — Coding agent instructions
- [ECOSYSTEM_ARCHITECTURE.md](../../docs/ECOSYSTEM_ARCHITECTURE.md)