# 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_