design-tokens

设计令牌专家

提供有关如何依据设计令牌社区组（DTCG）规范使用设计令牌的专家指导。

快速参考

主题	参考资料
令牌类型、结构、验证	reference/format.md
颜色空间、分量、透明度、常见错误	reference/color.md
集合、修饰符、解析顺序	reference/resolver.md
jq、JSONata、Figma 导出、Terrazzo 配置	reference/tools.md
常见模式和示例	examples/use-cases.md

**入门：**请参阅入门指南，了解分步工作流。

规范来源

依据最新的 DTCG 社区组报告草案：

• 格式模块
• 颜色模块
• 解析器模块

核心概念

令牌结构

令牌是一个带有 $value 的 JSON 对象。特殊属性以 $ 为前缀：

{
  "brand-blue": {
    "$type": "color",
    "$value": {
      "colorSpace": "srgb",
      "components": [0.15, 0.39, 0.92],
      "hex": "#2563eb"
    },
    "$description": "Primary brand color"
  }
}

令牌类型

**原子类型：**颜色、尺寸、fontFamily、fontWeight、duration、cubicBezier、number

**复合类型：**strokeStyle、border、shadow、gradient、typography、transition

完整的类型定义请参阅 reference/format.md。

颜色格式

颜色使用结构化对象（而非十六进制字符串）：

{
  "$type": "color",
  "$value": {
    "colorSpace": "srgb",
    "components": [1, 0, 0.5],
    "alpha": 0.8,
    "hex": "#ff0080"
  }
}

支持的空间：srgb、display-p3、oklch、oklab、hsl、hwb、lab、lch 等。请参阅 reference/color.md。

引用（别名）

支持两种语法：

1. 花括号 - 令牌级引用："{path.to.token}"
2. JSON Pointer（$ref） - 属性级访问：{"$ref": "#/path/to/$value/property"}

令牌引用示例：

{
  "color": {
    "primary": {"$type": "color", "$value": {"colorSpace": "srgb", "components": [0, 0.4, 0.8]}}
  },
  "button": {
    "background": {"$type": "color", "$value": "{color.primary}"}
  }
}

JSON Pointer 示例（访问数组元素）：

{
  "blue": {
    "$type": "color",
    "$value": {"colorSpace": "okhsl", "components": [0.733, 0.8, 0.5]}
  },
  "blue-hue": {
    "$type": "number",
    "$ref": "#/blue/$value/components/0"
  }
}

完整的引用语法详情请参阅 reference/format.md。

分组和类型继承

分组用于组织令牌。分组上的 $type 会应用于所有子项：

{
  "spacing": {
    "$type": "dimension",
    "sm": {"$value": {"value": 8, "unit": "px"}},
    "md": {"$value": {"value": 16, "unit": "px"}},
    "lg": {"$value": {"value": 24, "unit": "px"}}
  }
}

用于主题的解析器

解析器用于管理不同上下文（主题、平台、密度）中的令牌：

{
  "name": "my-system",
  "version": "2025.10",
  "sets": {
    "core": {"sources": [{"$ref": "tokens/base.json"}]}
  },
  "modifiers": {
    "theme": {
      "contexts": {
        "light": [{"$ref": "themes/light.json"}],
        "dark": [{"$ref": "themes/dark.json"}]
      },
      "default": "light"
    }
  },
  "resolutionOrder": [
    {"$ref": "#/sets/core"},
    {"$ref": "#/modifiers/theme"}
  ]
}

完整文档请参阅 reference/resolver.md。

入门指南

快速开始：将 CSS 变量转换为 DTCG

**起点：**现有的 CSS 自定义属性

:root {
  --color-primary: #2563eb;
  --color-background: #ffffff;
  --spacing-sm: 8px;
  --spacing-md: 16px;
}

**步骤 1：**创建 primitives.tokens.json

{
  "color": {
    "primitive": {
      "$type": "color",
      "blue-500": {
        "$value": { "colorSpace": "srgb", "components": [0.145, 0.388, 0.922], "hex": "#2563eb" }
      },
      "white": {
        "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" }
      }
    }
  },
  "spacing": {
    "$type": "dimension",
    "scale": {
      "sm": { "$value": { "value": 8, "unit": "px" } },
      "md": { "$value": { "value": 16, "unit": "px" } }
    }
  }
}

**步骤 2：**创建包含引用的 semantic.tokens.json

{
  "color": {
    "interactive": {
      "$type": "color",
      "primary": { "$value": "{color.primitive.blue-500}" }
    },
    "background": {
      "$type": "color",
      "page": { "$value": "{color.primitive.white}" }
    }
  },
  "spacing": {
    "$type": "dimension",
    "component": {
      "padding": { "$value": "{spacing.scale.sm}" },
      "gap": { "$value": "{spacing.scale.md}" }
    }
  }
}

转换提示：

• RGB 十六进制值转为 sRGB：将每个通道除以 255（例如，37/255 = 0.145）
• 在 hex 属性中保留十六进制值作为后备值
• 创建语义层，以用途为导向进行命名

---

快速开始：使用深色模式配置 Terrazzo

**步骤 1：**安装依赖项

npm install -D @terrazzo/cli @terrazzo/plugin-css

**步骤 2：**使用模式扩展创建令牌文件

tokens/themes/light.tokens.json：

{
  "$extensions": { "mode": "light" },
  "color": {
    "background": {
      "$type": "color",
      "page": { "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" } }
    },
    "text": {
      "$type": "color",
      "primary": { "$value": { "colorSpace": "srgb", "components": [0.07, 0.07, 0.07], "hex": "#121212" } }
    }
  }
}

tokens/themes/dark.tokens.json：

{
  "$extensions": { "mode": "dark" },
  "color": {
    "background": {
      "$type": "color",
      "page": { "$value": { "colorSpace": "srgb", "components": [0.07, 0.07, 0.07], "hex": "#121212" } }
    },
    "text": {
      "$type": "color",
      "primary": { "$value": { "colorSpace": "srgb", "components": [0.95, 0.95, 0.95], "hex": "#f2f2f2" } }
    }
  }
}

**步骤 3：**创建 terrazzo.config.mjs

import { defineConfig } from "@terrazzo/cli";
import pluginCSS from "@terrazzo/plugin-css";

export default defineConfig({
  tokens: [
    "./tokens/primitives.tokens.json",
    "./tokens/themes/light.tokens.json",
    "./tokens/themes/dark.tokens.json"
  ],
  outDir: "./dist/",
  plugins: [
    pluginCSS({
      filename: "tokens.css",
      modeSelectors: [
        { mode: "light", selectors: [":root", "[data-theme='light']"] },
        { mode: "dark", selectors: ["[data-theme='dark']", "@media (prefers-color-scheme: dark)"] }
      ]
    })
  ]
});

**步骤 4：**构建并使用

npx terrazzo build

在 HTML 中：

<html data-theme="light">

---

快速开始：导入 Figma 变量导出文件

**步骤 1：**从 Figma 导出

• 在 Figma 中打开 Variables 面板
• 使用 DTCG 导出插件或 Figma 内置的导出功能
• 保存为 figma-export.json

**步骤 2：**验证导出文件

# Check JSON is valid
jq '.' figma-export.json > /dev/null && echo "Valid JSON"

# List all token paths
jq -r 'paths(has("$value")) | join(".")' figma-export.json

**步骤 3：**按需添加模式扩展

如果 Figma 导出了单独的模式文件，请添加 $extensions.mode：

# Add mode to light theme file
jq '. + {"$extensions": {"mode": "light"}}' light.json > light.tokens.json

**步骤 4：**添加十六进制后备值（如果缺失）

Figma 会导出 sRGB 分量，但可能不会包含十六进制值：

# Quick check if hex values exist
jq '.. | objects | select(.colorSpace == "srgb") | select(.hex == null)' figma-export.json

**步骤 5：**配置 Terrazzo

创建 terrazzo.config.mjs，指定导入文件并进行构建。

常见的 Figma 导出问题：

• 扁平结构（未区分原始值和语义值）——手动重新组织
• 令牌名称中包含空格——使用 jq 转换为 kebab-case
• 分组缺少 $type——添加类型继承

---

工作流

创建令牌文件

Token File Creation:
- [ ] Step 1: Define file structure (primitives → semantic → components)
- [ ] Step 2: Create primitive tokens with explicit types
- [ ] Step 3: Create semantic tokens referencing primitives
- [ ] Step 4: Validate structure and references
- [ ] Step 5: Test with target tools (Terrazzo, etc.)

步骤 1：定义结构

按层组织：

tokens/
├── primitives.tokens.json   # Raw values (colors, spacing scales)
├── semantic.tokens.json     # Purpose-driven aliases
└── components.tokens.json   # Component-specific tokens

步骤 2：创建原始令牌

{
  "color": {
    "primitive": {
      "$type": "color",
      "blue": {
        "500": {"$value": {"colorSpace": "srgb", "components": [0.15, 0.39, 0.92], "hex": "#2563eb"}}
      }
    }
  }
}

步骤 3：创建语义令牌

{
  "color": {
    "interactive": {
      "$type": "color",
      "default": {"$value": "{color.primitive.blue.500}"}
    }
  }
}

步骤 4：验证

检查以下内容：

• 所有令牌都有可解析的 $type
• 没有循环引用
• 每种类型的值格式都有效
• 名称不包含 {、}、.，也不以 $ 开头

步骤 5：使用工具测试

terrazzo validate tokens.json
terrazzo build --input tokens.json --output test.css --format css

---

设置主题解析器

Resolver Setup:
- [ ] Step 1: Organize token files by concern
- [ ] Step 2: Create resolver.json with version and sets
- [ ] Step 3: Define theme modifier with contexts
- [ ] Step 4: Configure resolution order
- [ ] Step 5: Test with different inputs

步骤 1：整理文件

tokens/
├── resolver.json
├── base.tokens.json
└── themes/
    ├── light.tokens.json
    └── dark.tokens.json

步骤 2：创建解析器

{
  "name": "my-design-system",
  "version": "2025.10",
  "sets": {
    "foundation": {
      "sources": [{"$ref": "base.tokens.json"}]
    }
  }
}

步骤 3：定义主题修饰符

{
  "modifiers": {
    "theme": {
      "contexts": {
        "light": [{"$ref": "themes/light.tokens.json"}],
        "dark": [{"$ref": "themes/dark.tokens.json"}]
      },
      "default": "light"
    }
  }
}

步骤 4：设置解析顺序

{
  "resolutionOrder": [
    {"$ref": "#/sets/foundation"},
    {"$ref": "#/modifiers/theme"}
  ]
}

步骤 5：测试

terrazzo build --resolver resolver.json --output light.css
terrazzo build --resolver resolver.json --input theme=dark --output dark.css

---

验证令牌文件

Validation Checklist:
- [ ] Step 1: Check JSON syntax
- [ ] Step 2: Verify type declarations
- [ ] Step 3: Validate value formats
- [ ] Step 4: Check reference resolution
- [ ] Step 5: Verify naming constraints

步骤 1：JSON 语法

jq '.' tokens.json > /dev/null && echo "Valid JSON"

步骤 2：类型声明

每个令牌都需要一个可解析的 $type（显式声明，或从父级分组继承）。

步骤 3：值格式

类型	有效格式
color	{colorSpace, components, [alpha], [hex]}
dimension	`{value: number, unit: "px"
duration	`{value: number, unit: "ms"
cubicBezier	[P1x, P1y, P2x, P2y]，其中 P1x、P2x ∈ [0,1]
fontWeight	1-1000 或字符串（"normal"、"bold" 等）

步骤 4：引用

• 所有 {path.to.token} 引用都必须可解析
• 不得存在循环引用（A → B → A）
• 不得自引用

步骤 5：命名

• 名称不能以 $ 开头
• 名称不能包含 {、}、.

---

从其他格式迁移

Migration Workflow:
- [ ] Step 1: Export existing tokens to JSON
- [ ] Step 2: Map types to DTCG equivalents
- [ ] Step 3: Convert color values to structured format
- [ ] Step 4: Update reference syntax
- [ ] Step 5: Validate and test

常见转换：

源格式	转换为 DTCG
"#ff0000"	{colorSpace: "srgb", components: [1,0,0], hex: "#ff0000"}
"16px"	{value: 16, unit: "px"}
"$colors.primary" 或 {colors.primary}	"{colors.primary}"

Terrazzo 转换：

terrazzo convert --from style-dictionary --to dtcg input.json output.tokens.json

最佳实践

令牌层级

1. 原始令牌 - 不带语义含义的原始值
2. 语义令牌 - 引用原始令牌、由用途驱动的令牌
3. 组件令牌 - 引用语义令牌的特定组件令牌

命名约定

• 使用小写字母和连字符：color.brand.primary
• 结构：[category].[subcategory].[variant].[state]
• 优先使用语义名称，而非外观描述：color.interactive.default，而不是 color.blue-500

主题策略

使用解析器处理主题（推荐优于分组扩展）：

• 更清晰地分离关注点
• 令牌路径在不同主题间保持一致
• 便于组合主题（例如，深色 + 高对比度）
• 为构建工具提供标准化的输入处理

无障碍

色彩对比度： 在 $extensions 中记录对比度：

{
  "$extensions": {
    "com.example.a11y": {"contrastRatio": 7.5, "wcagLevel": "AA"}
  }
}

减少动态效果： 使用解析器修饰符：

{
  "modifiers": {
    "motion": {
      "contexts": {
        "full": [{"$ref": "motion/full.json"}],
        "reduced": [{"$ref": "motion/reduced.json"}]
      },
      "default": "full"
    }
  }
}

文件约定

• 令牌文件：.tokens 或 .tokens.json
• 解析器文件：.resolver.json
• 编码：UTF-8

常见任务

任务	方法
格式验证	对照 DTCG 规范检查，使用 Terrazzo validate
结构优化	按原始 → 语义 → 组件层级组织
别名解析	跟踪引用，检查循环依赖
解析器配置	定义集合、修饰符和解析顺序
主题实现	将解析器修饰符与上下文文件搭配使用
多上下文构建	按主题/平台/密度生成输出
工具集成	使用 jq 查询，使用 Terrazzo 转换
迁移	将颜色转换为结构化格式，更新引用

你的角色

在协助处理设计令牌时：

1. 先核实，再下结论——先检查参考文件，再说明 DTCG 支持或不支持什么。切勿假设规范的限制。
2. 使用最新的 DTCG 规范——采用结构化颜色格式和正确的类型。
3. 验证结构——检查 $value、$type 和引用。
4. 提出最佳实践建议——包括命名、组织和分层。
5. 协助使用工具——提供 jq 查询、Terrazzo 命令和 JSONata 转换。
6. 考虑不同平台——通过 $extensions 支持 Web、iOS 和 Android。
7. 考虑可扩展性——确保设计易于维护。
8. 优先考虑无障碍性——关注对比度、动态效果和焦点指示器。
9. 连接设计与代码——衔接工具和实现。

**重要：**当用户询问规范支持哪些功能（哪些语法有效、有哪些功能）时，务必先阅读相关参考文件。不要依赖对规范的假设或先前了解。

始终提供清晰的示例，并解释建议背后的理由。