design-system-tokens — Claude Code skill: tokens and setup
design-system-tokens builds W3C token files for colors, spacing, and themes. It applies while creating .tokens.json files or setting up dark mode.
MIT 215 installs ★ 305 updated 2026-11-14
npx skills add yonatangross/orchestkit --skill design-system-tokens -a claude-codeWhat design-system-tokens does
This skill organizes design values into global, alias, and component layers. Global tokens hold raw values, aliases attach semantic meaning, and component tokens scope those references to UI parts. That structure lets a theme swap alias mappings instead of changing every component token. Color examples use OKLCH, with lightness changes forming shade scales.
Eight rule files cover the W3C format, contrast, token tiers, OKLCH, spacing and depth, Style Dictionary, themes, and versioning. Style Dictionary turns one token source into CSS custom properties, a Tailwind theme, iOS Swift, or Android XML. The declared Style Dictionary target is >=5.5.5.
The skill also covers dark-mode mappings and token migration through deprecation metadata and codemods. Claude Code compatibility starts at version 2.1.277, so an older Claude Code release does not meet that requirement.
What it helps with
- organize raw, semantic, and component design values
- write
.tokens.jsonfiles in the W3C DTCG format - define perceptually even color scales with OKLCH
- turn one token source into CSS, Tailwind, Swift, and Android XML
- map aliases across dark and other themes
Example prompts for the agent
- Create a
.tokens.jsonstructure with global, alias, and component tokens for this interface. - Convert these colors to OKLCH and build a shade scale by adjusting lightness.
- Configure Style Dictionary to emit CSS custom properties and a Tailwind theme from the token source.
How to install design-system-tokens
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill design-system-tokens -a claude-code2Manually: put the files in place
~/.claude/skills/design-system-tokens/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/design-system-tokens/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill design-system-tokens -a codex2Manually: put the files in place
.agents/skills/design-system-tokens/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill design-system-tokens -a cursor2Manually: put the files in place
.cursor/skills/design-system-tokens/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install yonatangross/orchestkit src/skills/design-system-tokens2Manually: put the files in place
.github/skills/design-system-tokens/SKILL.md1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill design-system-tokens -a gemini-cli2Platform CLI
gemini skills install https://github.com/yonatangross/orchestkit --path src/skills/design-system-tokensManually: put the files in place
.devin/skills/design-system-tokens/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill design-system-tokens -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about design-system-tokens
How do I install design-system-tokens in Claude Code?
Run npx skills add yonatangross/orchestkit --skill design-system-tokens -a claude-code, then open ~/.claude/skills/design-system-tokens/SKILL.md.
What does design-system-tokens do?
It guides W3C token work for colors, spacing, typography, and themes. The skill uses three token tiers, OKLCH colors, Style Dictionary outputs, and alias mappings for dark mode.
Which versions are required?
The declared Style Dictionary target is >=5.5.5. Claude Code compatibility starts at version 2.1.277.
Source text
SKILL.md · MIT
---
name: design-system-tokens
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "W3C design tokens: global, alias and component tiers, OKLCH color, Style Dictionary, dark mode. Use when creating token files or theme systems."
user-invocable: false
targets:
- library: "style-dictionary"
version: ">=5.5.5"
metadata:
owner-agent: "frontend-ui-developer"
category: document-asset-creation
dtcg-version: "v2025.10"
version: "1.1.0"
author: "OrchestKit"
complexity: "medium"
tags: "design-tokens, w3c-tokens, oklch, style-dictionary, theming, dark-mode, css-variables, tailwind-theme, design-system, color-spaces"
allowed-tools: "Read Glob Grep WebFetch WebSearch"
---
# 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-extras:ui-components` — Component library patterns (shadcn/ui, Radix)
- `ork-extras:accessibility` — WCAG compliance, contrast ratios
- `ork-extras:responsive-patterns` — Responsive breakpoints, fluid typography
- `ork-extras:figma-design-handoff` — Figma Variables to tokens pipeline
© OrchestKit · MIT · yonatangross/orchestkit