Back to Details

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

快速参考

CategoryRule FileImpactWhen to Use
W3C Token Format
tokens-w3c-format.md
CRITICALCreating or reading 
.tokens.json
files
Contrast Enforcement
tokens-contrast-enforcement.md
CRITICALValidating WCAG contrast at token definition time
Three-Tier Hierarchy
tokens-three-tier.md
HIGHOrganizing tokens into global/alias/component layers
OKLCH Color Space
tokens-oklch-color.md
HIGHDefining colors with perceptual uniformity
Spacing & Depth
tokens-spacing-depth.md
HIGHDefining elevation shadows and spacing scales as tokens
Style Dictionary
tokens-style-dictionary.md
HIGHTransforming tokens to CSS/Tailwind/iOS/Android
Theming & Dark Mode
tokens-theming-darkmode.md
HIGHImplementing theme switching and dark mode
Versioning
tokens-versioning.md
HIGHEvolving 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:
TierPurposeExample
GlobalRaw values
color.blue.500 = oklch(0.55 0.18 250)
AliasSemantic meaning
color.primary = {color.blue.500}
ComponentScoped 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

核心决策

DecisionRecommendation
Token formatW3C DTCG 
.tokens.json
with 
$type
/
$value
Color spaceOKLCH for perceptual uniformity
HierarchyThree-tier: global, alias, component
Build toolStyle Dictionary 4.x with W3C parser
ThemingCSS custom properties with 
data-theme
attribute
Token referencesUse 
{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

参考资源

ResourceDescription
references/w3c-token-spec.mdW3C DTCG specification overview
references/style-dictionary-config.mdStyle Dictionary 4.x configuration guide
references/token-naming-conventions.mdNaming patterns and conventions
资源描述
references/w3c-token-spec.mdW3C DTCG规范概述
references/style-dictionary-config.mdStyle 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
技能协作进行对比度验证。

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
  • ork:ui-components
    — 组件库模式（shadcn/ui、Radix）
  • ork:accessibility
    — WCAG合规性、对比度比率
  • ork:responsive-patterns
    — 响应式断点、流体排版
  • ork:figma-design-handoff
    — Figma变量转令牌流水线