design-system-tokens

设计系统令牌

遵循 W3C 设计令牌社区组（DTCG）规范进行令牌管理。令牌为设计决策（颜色、间距、字体排版、层级）提供单一事实来源，并在设计工具（Figma、Penpot）和代码（CSS、Tailwind、iOS、Android）之间共享。主要采用者包括 Figma（Variables API）、Google（Material Design 3）、Microsoft（Fluent UI）和 Shopify（Polaris）。

快速参考

类别	规则文件	影响	适用场景
W3C 令牌格式	tokens-w3c-format.md	CRITICAL	创建或读取 .tokens.json 文件
对比度约束	tokens-contrast-enforcement.md	CRITICAL	在定义令牌时验证 WCAG 对比度
三层级结构	tokens-three-tier.md	HIGH	将令牌组织为全局/别名/组件层
OKLCH 色彩空间	tokens-oklch-color.md	HIGH	使用感知均匀的方式定义颜色
间距与深度	tokens-spacing-depth.md	HIGH	将层级阴影和间距比例定义为令牌
Style Dictionary	tokens-style-dictionary.md	HIGH	将令牌转换为 CSS/Tailwind/iOS/Android
主题与深色模式	tokens-theming-darkmode.md	HIGH	实现主题切换和深色模式
版本管理	tokens-versioning.md	HIGH	演进令牌，同时避免破坏使用方

总计：8 个类别，共 8 条规则

快速入门

W3C DTCG 令牌格式（.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"
    }
  }
}

三层令牌层级结构

令牌分为三层，每层都引用其下方的层：

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

这种分离方式可以在不修改组件令牌的情况下切换主题（替换别名映射）。

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

OKLCH（Oklab 明度、色度、色相）具有感知均匀性——数值变化相同，视觉变化也相同。这解决了 HSL 的问题：在相同明度下，hsl(60, 100%, 50%)（黄色）看起来比 hsl(240, 100%, 50%)（蓝色）亮得多。

/* 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 */

主要优势：只调整明度通道，即可创建对比度一致且易于访问的色阶。

详细规则

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

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

Style Dictionary 可将 W3C 令牌转换为特定平台的输出（CSS 自定义属性、Tailwind 主题、iOS Swift、Android XML）。只需配置一个 config.json，即可从单一令牌源生成所有平台的输出。

Style Dictionary 5.x（当前版本）——固定使用 style-dictionary >= 5.3.0。与其他地方记录的 4.x 相比，相关变化如下：

• 原生 OKLCH 输出——4.x 所需的自定义 color/oklch 转换已不再需要；当输入令牌使用 $type: "color" 和 OKLCH 值时，内置的 css/variables 格式化器会直接输出 OKLCH。移除手动编写的转换。
• DTCG v2025.10 维度对象——$type: "dimension" 现在接受对象 { "value": 16, "unit": "px" }，而不是简单字符串 "16px"。5.3+ 可以解析两种格式，但新令牌应使用对象格式。
• Hooks API 取代了 4.x 的 registerTransform / registerFormat 全局调用——为获得更好的摇树优化，请改为在配置中传入 hooks。

有关配置模式和自定义转换，请参阅 rules/tokens-style-dictionary.md。

深色模式与主题

基于令牌的主题机制会将别名令牌映射到各主题下不同的全局值。深色模式只是其中一个主题——你可以支持任意数量的主题（高对比度、品牌变体、季节主题）。

: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。

版本控制与迁移

令牌会不断演进。请对令牌包使用语义化版本控制，在令牌文件中添加弃用注解，并为破坏性变更编写 codemod。

{
  "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。

shadcn/ui v4 预设集成

shadcn CLI v4 会将样式、主题、字体和图标编码为可分享的预设代码。预设会生成带有 CSS 变量的 globals.css，这些变量映射到令牌层级：

npx shadcn@latest init --preset b2D0xPaDb  # Luma + Emerald + Geist

Luma 阴影令牌（令牌最丰富的样式）：

/* 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);

**检测：**读取 components.json 中的 "style" 字段，以确定启用的是哪些阴影／圆角令牌。通过 Style Dictionary 转换，将预设生成的 CSS 变量映射到 W3C DTCG 令牌。

关键决策

决策	建议
令牌格式	使用带有 $type／$value 的 W3C DTCG .tokens.json
色彩空间	使用 OKLCH，确保感知均匀性
层级	三级：全局、别名、组件
构建工具	使用带有 W3C 解析器的 Style Dictionary 4.x
主题	使用带有 data-theme 属性的 CSS 自定义属性
令牌引用	使用 {path.to.token} 别名语法

反模式（禁止）

• 在组件中硬编码值：始终引用令牌，不要使用原始的 #hex 或 16px
• 扁平的令牌结构：使用三级层级，以支持主题切换
• 用 HSL 创建色阶：OKLCH 可生成感知均匀的色阶；HSL 则不能
• 省略 $type：每个令牌都必须声明类型，以确保工具兼容性
• 通过切换类来使用原始值设置主题：使用可按主题重新映射的语义别名令牌
• 未做版本控制的令牌包：令牌变更会破坏使用方；请使用语义化版本控制

参考资料

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

Agent 集成

design-system-architect Agent 负责端到端协调令牌工作流——从提取 Figma Variables，到通过 Style Dictionary 进行转换，再到部署主题。在处理令牌架构决策时，该 Agent 会与负责组件令牌使用的 frontend-ui-developer 协作，并与 accessibility 技能协作进行对比度验证。

相关技能

• ork:ui-components — 组件库模式（shadcn/ui、Radix）
• ork:accessibility — WCAG 合规性、对比度
• ork:responsive-patterns — 响应式断点、流体排版
• ork:figma-design-handoff — 从 Figma Variables 到令牌的工作流