learning_ai_common_plat/packages/design-tokens

@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

# This is a workspace package - use from source
# Copy generated files to your project

Generate Tokens

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

/* 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

<!-- 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)

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)

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)

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)

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:

{
  "color": {
    "nomgap": {
      "stageFed": "#FF9F43",
      "stageKetosis": "#5A8CFF",
      "autophagyMeter": "#5AE68C"
    },
    "chronomind": {
      "urgencyCritical": "#FF6E6E",
      "focusMode": "#7C6BFF"
    },
    "peakpulse": {
      "activityHike": "#34D399",
      "speedZoneFast": "#FFD166"
    }
  }
}

---

Validation & Compliance

Check for Hardcoded Colors

# 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

# 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

- 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

# .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
• AGENTS.md — Coding agent instructions
• ECOSYSTEM_ARCHITECTURE.md