Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add yonatangross/orchestkit --skill design-system-tokens -a claude-code
Open on GitHub

What 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.json files 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.json structure 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-code

2Manually: put the files in place

~/.claude/skills/design-system-tokens/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/design-system-tokens/

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

Similar skills

All skills for Frontend and UI →

From the same set86

The whole set →
llm-integration llm-integration — a collection of 20 production rules for LLM workflows: strict function calling, SSE streaming endpoints, local Ollama deployments, and LoRA tuning. CX Codex +1 218installs fix-issue The fix-issue skill investigates a GitHub issue, applies a tested fix, opens a linked PR, and records ways to prevent the bug from returning. CX Codex +1 217installs review-pr review-pr is a Claude Code skill that reviews a pull request, branch, or diff range with parallel agents. It returns an approve or request-changes verdict before a merge. CX Codex +1 217installs i18n-date-patterns i18n-date-patterns guides an agent through React translations and locale-aware formatting. Use it when adding languages, handling dates or currency, or writing pluralized messages. CX Codex +1 216installs task-dependency-patterns task-dependency-patterns is a Claude Code skill for splitting complex work into linked tasks. It covers status tracking and coordination across parallel work. CX Codex +1 214installs api-design api-design establishes design standards for REST, GraphQL, and gRPC contracts when editing endpoints or OpenAPI files. Triggers on route definitions and schema changes. CX Codex +1 211installs assess The assess skill rates code or design decisions 0-10 across seven dimensions: correctness, readability, complexity, performance, security, maintainability and compliance. CX Codex +1 211installs verify verify is a skill that checks whether work is ready to merge by running tests, security and type checks, then assigns a 0–10 score. CX Codex +1 210installs

Project sponsors

Companies that keep this analytics open