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`): ```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. ```json { "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. ```css /* 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). ```css :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. ```json { "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: ```bash npx shadcn@latest init --preset b2D0xPaDb # Luma + Emerald + Geist ``` **Luma elevation tokens** (the most token-rich style): ```css /* 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](references/w3c-token-spec.md) | W3C DTCG specification overview | | [references/style-dictionary-config.md](references/style-dictionary-config.md) | Style Dictionary 5.x configuration guide | | [references/token-naming-conventions.md](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