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

Total: 8 rules across 8 categories

Quick Start

W3C DTCG token format (.tokens.json):

jsonCopy code
{
  "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:

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

jsonCopy code
{
  "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.

cssCopy code
/* 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).

cssCopy code
: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.

jsonCopy code
{
  "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:

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

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

cssCopy code
/* 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

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

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