docs: design system audit, onboarding guide, and AGENTS.md updates
- 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
parent
2a0a59e56c
commit
a33f3cfbd6
83
AGENTS.md
83
AGENTS.md
@ -110,7 +110,88 @@ learning_ai_common_plat/
|
|||||||
- Never delete existing comments or documentation unless explicitly asked
|
- Never delete existing comments or documentation unless explicitly asked
|
||||||
- Never add emojis to code 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 |
|
| Domain | Location | Key Files |
|
||||||
| ----------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
|
| ----------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
|
||||||
|
|||||||
357
docs/design-system/DESIGN_SYSTEM_AUDIT_2026-03-03.md
Normal file
357
docs/design-system/DESIGN_SYSTEM_AUDIT_2026-03-03.md
Normal 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
361
docs/design-system/ONBOARDING.md
Normal 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
276
packages/design-tokens/README.md
Normal 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)
|
||||||
Loading…
Reference in New Issue
Block a user