design-system-tokens

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);
  --color-on-surface: oklch(0.15 0.00 0);
}

[data-theme="dark"] {
  --color-surface: oklch(0.15 0.00 0);
  --color-on-surface: oklch(0.95 0.00 0);
}

See rules/tokens-theming-darkmode.md for full theme switching patterns.

Versioning & Migration

Tokens evolve. Use semantic versioning for your token packages, deprecation annotations in token files, and codemods for breaking changes.

{
  "color": {
    "brand": {
      "$type": "color",
      "$value": "oklch(0.55 0.18 250)",
      "$extensions": {
        "com.tokens.deprecated": {
          "since": "2.0.0",
          "replacement": "color.primary.500",
          "removal": "3.0.0"
        }
      }
    }
  }
}

See rules/tokens-versioning.md for migration strategies.

shadcn/ui v4 Preset Integration

shadcn CLI v4 encodes style + theme + fonts + icons into a shareable preset code. Presets generate globals.css with CSS variables that map to the token hierarchy:

npx shadcn@latest init --preset b2D0xPaDb  # Luma + Emerald + Geist

Luma elevation tokens (the most token-rich style):

/* Luma elevation system — soft depth hierarchy */
--shadow-card: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);  /* shadow-md */
--ring-card: 0 0 0 1px var(--foreground) / 0.05;  /* ring-1 ring-foreground/5 */
--shadow-dropdown: 0 4px 6px -1px rgb(0 0 0 / 0.1);  /* shadow-lg */
--shadow-dialog: 0 10px 15px -3px rgb(0 0 0 / 0.1);  /* shadow-xl */
--radius-button: var(--radius-4xl);  /* pill-shaped */
--radius-card: var(--radius-4xl);
--radius-input: var(--radius-3xl);

Detection: Read components.json → "style" field to determine which elevation/radius tokens are active. Map preset-generated CSS variables to W3C DTCG tokens via Style Dictionary transforms.

Key Decisions

Decision	Recommendation
Token format	W3C DTCG .tokens.json with $type/$value
Color space	OKLCH for perceptual uniformity
Hierarchy	Three-tier: global, alias, component
Build tool	Style Dictionary 4.x with W3C parser
Theming	CSS custom properties with data-theme attribute
Token references	Use {path.to.token} alias syntax

Anti-Patterns (FORBIDDEN)

• Hardcoded values in components: Always reference tokens, never raw #hex or 16px
• Flat token structure: Use three-tier hierarchy for theme-ability
• HSL for shade scales: OKLCH produces perceptually uniform scales; HSL does not
• Skipping $type: Every token must declare its type for tooling compatibility
• Theme via class toggling raw values: Use semantic alias tokens that remap per theme
• Unversioned token packages: Token changes break consumers; use semver

References

Resource	Description
references/w3c-token-spec.md	W3C DTCG specification overview
references/style-dictionary-config.md	Style Dictionary 5.x configuration guide
references/token-naming-conventions.md	Naming patterns and conventions

Agent Integration

The design-system-architect agent orchestrates token workflows end-to-end — from Figma Variables extraction through Style Dictionary transformation to theme deployment. When working on token architecture decisions, the agent coordinates with frontend-ui-developer for component token consumption and accessibility skills for contrast validation.

Related Skills

• ork:ui-components — Component library patterns (shadcn/ui, Radix)
• ork:accessibility — WCAG compliance, contrast ratios
• ork:responsive-patterns — Responsive breakpoints, fluid typography
• ork:figma-design-handoff — Figma Variables to tokens pipeline