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
277 lines
7.4 KiB
Markdown
277 lines
7.4 KiB
Markdown
# @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)
|