npm package: @l3mpire/tokens
Description: Design tokens for the lemDS design system. Built with **Style Dictionary v4** using the **DTCG** (Design Tokens Community Group) format.
Latest version: 0.7.0

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

```bash
pnpm add @l3mpire/tokens
```

## Usage

### CSS Custom Properties

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

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

### TypeScript

```ts
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:

```json
{
  "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

```bash
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