a33f3cfbd6
- 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
362 lines
9.0 KiB
Markdown
362 lines
9.0 KiB
Markdown
# 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_
|