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("${CLAUDE_SKILL_DIR}/rules/tokens-w3c-format.md")

Read("${CLAUDE_SKILL_DIR}/rules/tokens-contrast-enforcement.md")

Read("${CLAUDE_SKILL_DIR}/rules/tokens-three-tier.md")

Read("${CLAUDE_SKILL_DIR}/rules/tokens-oklch-color.md")

Read("${CLAUDE_SKILL_DIR}/rules/tokens-spacing-depth.md")

Read("${CLAUDE_SKILL_DIR}/rules/tokens-style-dictionary.md")

Read("${CLAUDE_SKILL_DIR}/rules/tokens-theming-darkmode.md")

Read("${CLAUDE_SKILL_DIR}/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.

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.

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 4.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