Design token management with the W3C Design Token spec, three-tier hierarchy (global/alias/component), OKLCH color, Style Dictionary transforms, and dark mode theming. Use when creating token files, implementing theme systems, or building design-to-code pipelines.
Design token management with the W3C Design Token spec, three-tier hierarchy (global/alias/component), OKLCH color, Style Dictionary transforms, and dark mode theming. Use when creating token files, implementing theme systems, or building design-to-code pipelines.
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.
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.550.18250);
--color-primary-hover: oklch(0.500.18250); /* Just reduce L for darker */
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).
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:
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
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.
