@bytelyst/design-tokens (0.2.1)

2026-07-27T04:51:19Z

Setup this registry in your project .npmrc file:

@bytelyst:registry=

To install the package using npm, run the following command:

npm install @bytelyst/design-tokens@0.2.1

or add it to the package.json file:

"@bytelyst/design-tokens": "0.2.1"

For more information on the npm registry, see the documentation.

@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

pnpm add @bytelyst/design-tokens@0.2.1

Generate Tokens

# From the monorepo root
pnpm --filter @bytelyst/design-tokens generate

This regenerates every supported platform output from tokens/bytelyst.tokens.json, including React Native. Never edit generated files directly.

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/css';

/* Use tokens */
.my-component {
  background-color: var(--bl-bg-canvas);
  color: var(--bl-text-primary);
  padding: var(--bl-space-4);
  border-radius: var(--bl-radius-card);
  box-shadow: var(--bl-shadow-sm);
  font-family: var(--bl-font-display);
}

With Tailwind CSS

<!-- Use arbitrary values with CSS variables -->
<div class="bg-[var(--bl-bg-canvas)] text-[var(--bl-text-primary)] p-[var(--bl-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/react-native';
import { StyleSheet } from 'react-native';

const styles = StyleSheet.create({
  container: {
    backgroundColor: tokens.colorsDark.bgCanvas,
    padding: tokens.spacing['4'],
    borderRadius: tokens.radius.md,
  },
  text: {
    color: tokens.colorsDark.textPrimary,
    fontSize: tokens.typography.fontSize.lg,
  },
});

Flutter (Dart)

// Copy generated/bytelyst_tokens.dart into your Flutter app
// (e.g. lib/theme/bytelyst_tokens.dart), or a per-product file from
// generated/native/<product>_tokens.dart.
import 'theme/bytelyst_tokens.dart';

Container(
  color: BytelystColorsDark.bgCanvas,
  padding: const EdgeInsets.all(BytelystSpacing.x4),
  child: const Text(
    'Hello',
    style: TextStyle(color: BytelystColorsDark.textPrimary, fontSize: BytelystFontSize.slg),
  ),
);

// Gradients + motion
const LinearGradient(colors: BytelystGradients.work);
AnimatedContainer(duration: BytelystMotion.base);

Generated Dart classes are abstract final with static const fields — never hand-edit; regenerate from bytelyst.tokens.json. See ../../AI.dev/SKILLS/flutter-development.md.

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 (schema v1.2.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)
Density	3	Compact, comfortable, spacious
Border	4	None, thin, strong, focus
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.2.0	2026-07-26	Added semantic states, density, borders, readable layout, safe-area, and complete React Native theme generation
1.1.0	2026-03-03	Added product tokens, z-index, icon sizes, grid, and opacity
1.0.0	2026-02-12	Initial release with color, typography, spacing, radius, elevation, and motion

Contributing

Edit tokens/bytelyst.tokens.json (canonical source)
Run pnpm generate to regenerate outputs
Run bash ../../scripts/check-token-drift.sh
Commit both source and generated files
Publish and pin an exact package version in external consumers

Never edit generated files directly — they will be overwritten.