@l3mpire/tokens

Design tokens for the lemDS design system. Built with Style Dictionary v4 using the DTCG (Design Tokens Community Group) format.

Outputs CSS custom properties and TypeScript constants.

Installation

pnpm add @l3mpire/tokens

Usage

CSS Custom Properties

/* Import all tokens */
@import "@l3mpire/tokens/css";

/* Import dark mode overrides */
@import "@l3mpire/tokens/css/tokens-dark";

TypeScript

import tokens from "@l3mpire/tokens";

Token Structure

src/
├── primitives/
│   ├── light.json       Base color scales (blue, red, green, yellow, pink, grey)
│   ├── dark.json        Dark mode color overrides
│   └── shadows.json     Shadow definitions
├── semantic/
│   ├── light.json       Semantic color mappings (core.bg, core.text, interactive.*)
│   └── dark.json        Dark mode semantic overrides
├── fonts/
│   └── font.json        Font size, line-height, weight, letter-spacing
├── sizing/
│   └── sizing.json      Spacing, radius, gap, stroke scales
└── components/
    └── *.json           Per-component token files (button, badge, toast...)

Token Categories

Colors

Primitives — Raw color scales (50–900):

• blue, red, green, yellow, pink, grey
• Brand blue: #316bff (blue-500)

Semantic — Purpose-based color references:

• core.bg.main.primary — Main background
• core.text.main.primary — Primary text
• core.border.main.default — Default border
• interactive.bg.primary.dark.default — Interactive element background

Component — Per-component tokens:

• Pattern: comp.{component}.{variant}.{property}.{state}
• Example: comp.btn.solid.brand.bg.default
• CSS output: --comp-btn-solid-brand-bg-default

Spacing

| Token | Value | |-------|-------| | --spacing-none | 0px | | --spacing-2xs | 2px | | --spacing-xs | 4px | | --spacing-sm | 6px | | --spacing-base | 8px | | --spacing-md | 12px | | --spacing-lg | 16px | | --spacing-xl | 24px | | --spacing-2xl | 32px | | --spacing-3xl | 40px | | --spacing-4xl | 48px | | --spacing-5xl | 56px |

Border Radius

| Token | Value | |-------|-------| | --radius-none | 0px | | --radius-2xs | 2px | | --radius-xs | 4px | | --radius-sm | 6px | | --radius-base | 8px | | --radius-md | 12px | | --radius-lg | 16px | | --radius-xl | 24px | | --radius-full | 9999px |

Typography

Font sizes:

| Token | Value | |-------|-------| | --font-size-size-xxs | 10px | | --font-size-size-xs | 12px | | --font-size-size-sm | 14px | | --font-size-size-base | 16px | | --font-size-size-md | 18px | | --font-size-size-lg | 20px | | --font-size-size-xl | 24px |

Font weights:

| Token | Value | |-------|-------| | --font-weight-regular | 400 | | --font-weight-semibold | 600 | | --font-weight-bold | 700 |

Shadows

| Token | Description | |-------|-------------| | --shadow-sm | Subtle elevation | | --shadow-md | Medium elevation | | --shadow-lg | High elevation | | --shadow-focus-ring | Focus indicator ring |

Token Format (DTCG)

Tokens use the Design Tokens Community Group specification:

{
  "comp": {
    "badge": {
      "solid": {
        "primary": {
          "bg": {
            "$type": "color",
            "$value": "{interactive.bg.primary.dark.default}"
          },
          "text": {
            "$type": "color",
            "$value": "{core.text.mainInvert.primary}"
          }
        }
      }
    }
  }
}

• $type — Token type (color, dimension, fontWeight, shadow, etc.)
• $value — Either a raw value or a reference to another token using {path.to.token}

Building

pnpm --filter @l3mpire/tokens build

Outputs to dist/:

• dist/css/tokens.css — Light mode CSS custom properties
• dist/css/tokens-dark.css — Dark mode overrides
• dist/ts/tokens.ts — TypeScript constants

Adding New Tokens

1. Add tokens to the appropriate JSON file in src/
2. For component tokens, create src/components/{component}.json
3. Follow the naming convention: comp.{component}.{axis}.{property}.{state}
4. Reference semantic tokens — never hardcode hex values
5. Run pnpm --filter @l3mpire/tokens build to regenerate outputs