design-system-tokens

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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).

遵循W3C设计令牌社区组（DTCG）规范的设计令牌管理。令牌为设计决策（颜色、间距、排版、层级）提供单一事实来源，可在设计工具（Figma、Penpot）与代码（CSS、Tailwind、iOS、Android）之间共享。主要采用者包括Figma（Variables API）、Google（Material Design 3）、Microsoft（Fluent UI）和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

类别	规则文件	重要程度	适用场景
W3C令牌格式	`tokens-w3c-format.md`	关键	创建或读取 `.tokens.json` 文件时
对比度强制校验	`tokens-contrast-enforcement.md`	关键	在令牌定义阶段验证WCAG对比度时
三级令牌层级	`tokens-three-tier.md`	高	将令牌组织为全局/别名/组件层级时
OKLCH色彩空间	`tokens-oklch-color.md`	高	定义具有感知一致性的颜色时
间距与层级	`tokens-spacing-depth.md`	高	将层级阴影和间距尺度定义为令牌时
Style Dictionary	`tokens-style-dictionary.md`	高	将令牌转换为CSS/Tailwind/iOS/Android格式时
主题与暗色模式	`tokens-theming-darkmode.md`	高	实现主题切换与暗色模式时
版本管理	`tokens-versioning.md`	高	在不影响消费者的前提下迭代令牌时

总计：8个类别下的8条规则

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"
    }
  }
}

W3C DTCG令牌格式（

.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}" }
    }
  }
}

令牌分为三个层级，每个层级引用下一层级的内容：

层级	用途	示例
全局	原始值	`color.blue.500 = oklch(0.55 0.18 250)`
别名	语义化命名	`color.primary = {color.blue.500}`
组件	作用域化使用	`button.bg = {color.primary}`

这种分离方式支持在不修改组件令牌的前提下切换主题（替换别名映射）。

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色彩空间

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.

OKLCH（Oklab明度、色度、色相）提供感知一致性——数值上的等幅变化对应视觉上的等幅变化。这解决了HSL的问题：在相同明度下，

hsl(60, 100%, 50%)

（黄色）看起来比

hsl(240, 100%, 50%)

（蓝色）亮得多。

css

/* OKLCH: L（0-1明度）、C（0-0.4色度/饱和度）、H（0-360色相） */
--color-primary: oklch(0.55 0.18 250);
--color-primary-hover: oklch(0.50 0.18 250);  /* 仅降低L值实现深色效果 */

核心优势：仅调整明度通道即可创建具有一致对比度的可访问色阶。

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")

每个规则文件包含错误/正确代码示例以及实现指南。

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集成

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.

See

rules/tokens-style-dictionary.md

for configuration patterns and custom transforms.

Style Dictionary可将W3C令牌转换为特定平台的输出（CSS自定义属性、Tailwind主题、iOS Swift、Android XML）。通过单个

config.json

配置，即可从单一令牌源生成所有平台的输出文件。

配置模式与自定义转换请参考

rules/tokens-style-dictionary.md

。

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.

基于令牌的主题可根据不同主题将别名令牌映射到不同的全局值。暗色模式是其中一种主题，你还可以支持任意数量的主题（高对比度、品牌变体、季节性主题等）。

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);
}

完整的主题切换模式请参考

rules/tokens-theming-darkmode.md

。

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.

令牌会不断演进。为你的令牌包使用语义化版本控制，在令牌文件中添加弃用注解，并通过代码修改工具处理破坏性变更。

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"
        }
      }
    }
  }
}

迁移策略请参考

rules/tokens-versioning.md

。

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

决策项	推荐方案
令牌格式	带 `$type` / `$value` 的W3C DTCG `.tokens.json`
色彩空间	采用OKLCH以实现感知一致性
层级结构	三级：全局、别名、组件
构建工具	带W3C解析器的Style Dictionary 4.x
主题配置	结合 `data-theme` 属性的CSS自定义属性
令牌引用	使用 `{path.to.token}` 别名语法

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

组件中硬编码值：始终引用令牌，切勿直接使用原始
```
#hex
```
或
```
16px
```
扁平令牌结构：使用三级层级以支持主题切换
HSL色阶：OKLCH可生成感知一致的色阶，HSL无法做到
省略
$type
：每个令牌必须声明类型以兼容工具链
通过类切换原始值实现主题：使用可根据主题重新映射的语义化别名令牌
未版本化的令牌包：令牌变更会影响消费者，需使用语义化版本控制

References

参考资源

Resource	Description
references/w3c-token-spec.md	W3C DTCG specification overview
references/style-dictionary-config.md	Style Dictionary 4.x configuration guide
references/token-naming-conventions.md	Naming patterns and conventions

资源	描述
references/w3c-token-spec.md	W3C DTCG规范概述
references/style-dictionary-config.md	Style Dictionary 4.x配置指南
references/token-naming-conventions.md	命名模式与规范

Agent Integration

Agent集成

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.

design-system-architect

Agent可端到端协调令牌工作流——从Figma变量提取，到Style Dictionary转换，再到主题部署。在处理令牌架构决策时，该Agent会与

frontend-ui-developer

协作以保障组件令牌的消费，同时与

accessibility

技能协作进行对比度验证。

design-system-tokens

Original

Translation

Design System Tokens

设计系统令牌

Quick Reference

快速参考

Quick Start

快速开始

Three-Tier Token Hierarchy

三级令牌层级

OKLCH Color Space

OKLCH色彩空间

Detailed Rules

详细规则

Style Dictionary Integration

Style Dictionary集成

Dark Mode & Theming

暗色模式与主题配置

Versioning & Migration

版本管理与迁移

Key Decisions

核心决策

Anti-Patterns (FORBIDDEN)

反模式（禁止）

References

参考资源

Agent Integration

Agent集成

Related Skills

相关技能