/design-system-tokens

name: design-system-tokens
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "W3C design tokens: global, alias and component tiers, OKLCH color, Style Dictionary, dark mode. Use when creating token files or theme systems."
user-invocable: false
targets:
  - library: "style-dictionary"
    version: ">=5.5.5"
metadata:
  owner-agent: "frontend-ui-developer"
  category: document-asset-creation
  dtcg-version: "v2025.10"
  version: "1.1.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "design-tokens, w3c-tokens, oklch, style-dictionary, theming, dark-mode, css-variables, tailwind-theme, design-system, color-spaces"
allowed-tools: "Read Glob Grep WebFetch WebSearch"

Design System Tokens

Design token management following the W3C Design Token Community Group (DTCG) specification. Tokens provide a single source of truth for design decisions — colors, spacing, typography, elevation — shared between design tools (Figma, Penpot) and code (CSS, Tailwind, iOS, Android). Major adopters include Figma (Variables API), Google (Material Design 3), Microsoft (Fluent UI), and Shopify (Polaris).

Quick Reference

| Category | Rule File | Impact | When to Use | |----------|-----------|--------|-------------| | W3C Token Format | `tokens-w3c-format.md` | CRITICAL | Creating or reading `.tokens.json` files | | Contrast Enforcement | `tokens-contrast-enforcement.md` | CRITICAL | Validating WCAG contrast at token definition time | | Three-Tier Hierarchy | `tokens-three-tier.md` | HIGH | Organizing tokens into global/alias/component layers | | OKLCH Color Space | `tokens-oklch-color.md` | HIGH | Defining colors with perceptual uniformity | | Spacing & Depth | `tokens-spacing-depth.md` | HIGH | Defining elevation shadows and spacing scales as tokens | | Style Dictionary | `tokens-style-dictionary.md` | HIGH | Transforming tokens to CSS/Tailwind/iOS/Android | | Theming & Dark Mode | `tokens-theming-darkmode.md` | HIGH | Implementing theme switching and dark mode | | Versioning | `tokens-versioning.md` | HIGH | Evolving tokens without breaking consumers |

**Total: 8 rules across 8 categories**

Quick Start

W3C DTCG token format (`.tokens.json`):

{
  "color": {
    "primary": {
      "50": {
        "$type": "color",
        "$value": "oklch(0.97 0.01 250)",
        "$description": "Lightest primary shade"
      },
      "500": {
        "$type": "color",
        "$value": "oklch(0.55 0.18 250)",
        "$description": "Base primary"
      },
      "900": {
        "$type": "color",
        "$value": "oklch(0.25 0.10 250)",
        "$description": "Darkest primary shade"
      }
    }
  },
  "spacing": {
    "sm": {
      "$type": "dimension",
      "$value": "8px"
    },
    "md": {
      "$type": "dimension",
      "$value": "16px"
    },
    "lg": {
      "$type": "dimension",
      "$value": "24px"
    }
  }
}

Three-Tier Token Hierarchy

Tokens are organized in three layers — each referencing the layer below:

| Tier | Purpose | Example | |------|---------|---------| | **Global** | Raw values | `color.blue.500 = oklch(0.55 0.18 250)` | | **Alias** | Semantic meaning | `color.primary = {color.blue.500}` | | **Component** | Scoped usage | `button.bg = {color.primary}` |

This separation enables theme switching (swap alias mappings) without touching component tokens.

{
  "color": {
    "blue": {
      "500": { "$type": "color", "$value": "oklch(0.55 0.18 250)" }
    },
    "primary": { "$type": "color", "$value": "{color.blue.500}" },
    "action": {
      "default": { "$type": "color", "$value": "{color.primary}" }
    }
  }
}

OKLCH Color Space

OKLCH (Oklab Lightness, Chroma, Hue) provides perceptual uniformity — equal numeric changes produce equal visual changes. This solves HSL's problems where `hsl(60, 100%, 50%)` (yellow) appears far brighter than `hsl(240, 100%, 50%)` (blue) at the same lightness.

/* OKLCH: L (0-1 lightness), C (0-0.4 chroma/saturation), H (0-360 hue) */
--color-primary: oklch(0.55 0.18 250);
--color-primary-hover: oklch(0.50 0.18 250);  /* Just reduce L for darker */

Key advantage: adjusting lightness channel alone creates accessible shade scales with consistent contrast ratios.

Detailed Rules

Each rule file contains incorrect/correct code pairs and implementation guidance.

Read("rules/tokens-w3c-format.md")

Read("rules/tokens-contrast-enforcement.md")

Read("rules/tokens-three-tier.md")

Read("rules/tokens-oklch-color.md")

Read("rules/tokens-spacing-depth.md")

Read("rules/tokens-style-dictionary.md")

Read("rules/tokens-theming-darkmode.md")

Read("rules/tokens-versioning.md")

Style Dictionary Integration

Style Dictionary transforms W3C tokens into platform-specific outputs (CSS custom properties, Tailwind theme, iOS Swift, Android XML). Configure a single `config.json` to generate all platform outputs from one token source.

> **Style Dictionary 5.x (current)** — pin `style-dictionary >= 5.3.0`. Relevant deltas vs the 4.x documented elsewhere: > > - **Native OKLCH output** — the custom `color/oklch` transform required in 4.x is **no longer needed**; the built-in `css/variables` formatter emits OKLCH directly when the input token uses `$type: "color"` with an OKLCH value. Remove hand-rolled transforms. > - **DTCG v2025.10 dimension object** — `$type: "dimension"` now takes an object `{ "value": 16, "unit": "px" }` instead of the bare string `"16px"`. 5.3+ parses both, but new tokens should use the object form. > - **Hooks API** replaces the 4.x `registerTransform` / `registerFormat` global calls — pass hooks in the config instead for better tree-shaking.

See `rules/tokens-style-dictionary.md` for configuration patterns and custom transforms.

Dark Mode & Theming

Token-based theming maps alias tokens to different global values per theme. Dark mode is one theme — you can support any number (high contrast, brand variants, seasonal).

:root {
  --color-surface: oklch(0.99 0.00 0);