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("${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.
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/oklchtransform required in 4.x is no longer needed; the built-incss/variablesformatter 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/registerFormatglobal 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
#hexor16px - 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 ratiosork:responsive-patterns— Responsive breakpoints, fluid typographyork:figma-design-handoff— Figma Variables to tokens pipeline
More from yonatangross/orchestkit
responsive-patterns
Responsive design with Container Queries, fluid typography, cqi/cqb units, subgrid, intrinsic layouts, foldable devices, and mobile-first patterns for React applications. Use when building responsive layouts or container queries.
464ui-components
UI component library patterns for shadcn/ui and Radix Primitives. Use when building accessible component libraries, customizing shadcn components, using Radix unstyled primitives, or creating design system foundations.
443devops-deployment
Use when setting up CI/CD pipelines, containerizing applications, deploying to Kubernetes, or writing infrastructure as code. DevOps & Deployment covers GitHub Actions, Docker, Helm, and Terraform patterns.
401rag-retrieval
Retrieval-Augmented Generation patterns for grounded LLM responses. Use when building RAG pipelines, embedding documents, implementing hybrid search, contextual retrieval, HyDE, agentic RAG, multimodal RAG, query decomposition, reranking, or pgvector search.
340architecture-decision-record
Use this skill when documenting significant architectural decisions. Provides ADR templates following the Nygard format with sections for context, decision, consequences, and alternatives. Use when writing ADRs, recording decisions, or evaluating options.
326domain-driven-design
DDD tactical patterns for complex business modeling including entities, value objects, aggregates, domain services, repositories, specifications, and bounded contexts. Python dataclass implementations with TypeScript alternatives. Use when building rich domain models, enforcing invariants, or separating domain logic from infrastructure.
326