@lime-soda/tokens

v0.1.0

Published

6 months ago

Design tokens for the Lime Soda design system, built with Style Dictionary. Features a modern two-layer token architecture with primitive and semantic tokens, supporting both light and dark themes with WCAG 2.1 AA accessibility compliance.

0High
0Medium
0Low

p-m-p

@lime-soda/tokens

Overview

This package provides a comprehensive color design system with:

🎨 Two-layer Architecture - Primitive colors + semantic mappings
🌓 Theme Support - Light and dark mode with automatic switching
♿ Accessibility First - All combinations meet WCAG 2.1 AA standards
🎯 Modern Colors - RGB format with future OKLCH/P3 support ready
⚡ Multiple Outputs - Individual theme files + combined responsive CSS

Token Architecture

Primitives Layer (`primitives/color.json`)

Foundation color palette with no semantic meaning:

Green (50-950) - Primary brand color
Pink (50-950) - Secondary brand color
Gray (50-950) - Neutral colors for text, borders, surfaces
Red (50-950) - Error/danger states
Amber (50-950) - Warning states
Emerald (50-950) - Success states
Blue (50-950) - Info/focus states

Semantic Layer (`theme/`)

Context-aware tokens that reference primitives:

color-light.json - Light mode semantic mappings
color-dark.json - Dark mode semantic mappings

Semantic Categories:

primary-* / secondary-* - Brand colors with full scales
background-* / surface-* - Page and component backgrounds
text-* - Typography colors (primary, secondary, tertiary, disabled)
border-* / outline-* - Dividers and focus states
error-* / warning-* / success-* / info-* - State colors

Generated CSS Files

The build generates multiple CSS files for different use cases:

dist/css/
├── tokens.css           # Combined light + dark using light-dark() function
├── tokens-light.css     # Light mode only
└── tokens-dark.css      # Dark mode only

Example Generated CSS

Modern approach with light-dark() function (tokens.css):

:root {
  color-scheme: light dark;

  /* Primitive Colors - Foundation palette */
  --color-green-700: #15803d;
  --color-green-400: #4ade80;
  --color-pink-600: #db2777;
  --color-pink-400: #f472b6;

  /* Semantic tokens - Automatic theme switching */
  --color-primary-500: light-dark(#15803d, #4ade80);
  --color-secondary-500: light-dark(#db2777, #f472b6);
  --color-background-default: light-dark(#ffffff, #030712);
  --color-text-primary: light-dark(#111827, #f3f4f6);
}

The semantic tokens use the exact hex values from primitives for optimal performance, while maintaining the two-layer architecture conceptually through the Style Dictionary token definitions.

Legacy approach with media queries (for older browsers):

/* Light mode (default) */
:root {
  --color-primary-500: #15803d; /* Green 700 - accessible */
  --color-secondary-500: #db2777; /* Pink 600 - accessible */
  --color-background-default: #ffffff;
  --color-text-primary: #111827;
}

/* Dark mode */
@media (prefers-color-scheme: dark) {
  :root {
    --color-primary-500: #4ade80; /* Green 400 - bright for dark */
    --color-secondary-500: #f472b6; /* Pink 400 - bright for dark */
    --color-background-default: #030712;
    --color-text-primary: #f3f4f6;
  }
}

Usage

Automatic Theme Switching (Recommended)

Modern browsers with light-dark() support:

// Import combined CSS with light-dark() functions
import '@lime-soda/tokens/tokens.css'

const styles = css`
  .button {
    background: var(
      --color-primary-500
    ); /* Automatically adapts to light/dark */
    color: var(--color-primary-on-primary);
  }
`

The light-dark() function automatically switches between light and dark values based on the user's system preference or the color-scheme property.

Manual Theme Control

<html data-theme="light">
  <!-- Force light -->
  <html data-theme="dark">
    <!-- Force dark -->
  </html>
</html>

Individual Theme Files

// Light mode only
import '@lime-soda/tokens/tokens-light.css'

// Dark mode only
import '@lime-soda/tokens/tokens-dark.css'

Component Usage Examples

Using Component Token Exports

import * as styles from '@lime-soda/tokens/button'

// Use CSS custom properties
styles.props // :host { --button-sm-padding: 0.375rem 0.75rem; ... }

// Use grouped token objects
styles.sm.padding // css`var(--button-sm-padding)`
styles.primary.backgroundColor // css`var(--button-primary-background-color)`
styles.transition // css`var(--button-transition)`

Traditional CSS Custom Properties

// Button component
const buttonStyles = css`
  .button {
    background: var(--color-primary-500);
    color: var(--color-primary-on-primary);
    border: 1px solid var(--color-border-default);
  }

  .button:hover {
    background: var(--color-primary-600);
  }

  .button--secondary {
    background: var(--color-secondary-500);
    color: var(--color-secondary-on-secondary);
  }
`

// Form validation
const formStyles = css`
  .input--error {
    border-color: var(--color-error-500);
    background: var(--color-error-50);
  }

  .input--success {
    border-color: var(--color-success-500);
    background: var(--color-success-50);
  }
`

Accessibility

All color combinations are tested to meet WCAG 2.1 AA standards:

Normal text: 4.5:1 minimum contrast ratio
Large text: 3.0:1 minimum contrast ratio

The semantic tokens ensure accessible color usage by default:

primary-500 / secondary-500 on white: ≥4.5:1 contrast
White text on primary-500 / secondary-500: ≥4.5:1 contrast
All text-* tokens on backgrounds: ≥4.5:1 contrast

Development

# Build all token CSS files and component exports (includes light-dark() combined version)
pnpm run build

# Build individual themes
pnpm run build:light    # Light mode only
pnpm run build:dark     # Dark mode only
pnpm run build:combined # Generate light-dark() combined tokens only

# Lint tokens
pnpm run lint

The build process now generates both CSS files and TypeScript/JavaScript component token exports with DTCG descriptions included as CSS comments.

File Structure

support/tokens/
├── primitives/
│   ├── color.json           # Primitive color palette
│   ├── size.json           # Spacing/sizing values
│   ├── font.json           # Typography tokens
│   ├── border.json         # Border values
│   └── transition.json     # Animation tokens
├── theme/
│   ├── color-light.json    # Light mode semantic colors
│   ├── color-dark.json     # Dark mode semantic colors
│   └── light/
│       └── components/
│           └── button.json # Component-specific tokens with DTCG descriptions
├── scripts/
│   ├── build-combined.js   # Combines light/dark CSS
│   └── check-accessibility.js # WCAG compliance checker
├── config.json             # Light mode build config
├── config-dark.json        # Dark mode build config
├── config-combined.json    # Combined build config
└── dist/
    ├── css/
    │   ├── tokens.css      # Combined light/dark with media queries
    │   ├── tokens-light.css # Light mode only
    │   └── tokens-dark.css  # Dark mode only
    ├── button.js           # Button component token exports (ES modules)
    └── button.d.ts         # TypeScript declarations for button tokens

Integration

Style Dictionary 5.0 - Token transformation and CSS generation with custom JavaScript/TypeScript formats
DTCG Compliant - Design Token Community Group specification with $description properties
Monorepo - Shared across all Lime Soda component packages via @lime-soda/tokens
Component Integration - Automatic Custom Elements Manifest enhancement with design token CSS properties
MCP Server - Design tokens accessible via Model Context Protocol for AI tools
Turbo - Integrated build pipeline for efficient development
Future Ready - Architecture supports OKLCH and P3 color spaces when tooling matures

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@lime-soda/tokens

Overview

Token Architecture

Primitives Layer (primitives/color.json)

Semantic Layer (theme/)

Generated CSS Files

Example Generated CSS

Usage

Automatic Theme Switching (Recommended)

Manual Theme Control

Individual Theme Files

Component Usage Examples

Using Component Token Exports

Traditional CSS Custom Properties

Accessibility

Development

File Structure

Integration

Primitives Layer (`primitives/color.json`)

Semantic Layer (`theme/`)