# @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)