zhaoxuya520 Design Tokens（设计令牌）
参考来源：W3C DTCG 2025.10、GitLab Design Tokens
适用场景
- 设计系统从零建立
- 多产品/多品牌的设计一致性
- 设计和代码的单一数据源
- 主题切换（暗黑模式、品牌切换）
核心思想
Design Tokens 是设计决策的单一数据源，用机器可读的格式存储：
颜色 / 字体 / 间距 / 圆角 / 阴影 / 动效时长
→ 写成 JSON
→ 设计工具和代码都从同一份 JSON 读取
→ 改一处 = 全产品同步
三层 Token 架构
1. 全局 Token（Global / Primitive）
原始值，不带语义
{
"color": {
"blue": {
"50": { "$value": "#eff6ff", "$type": "color" },
"500": { "$value": "#2563eb", "$type": "color" },
"900": { "$value": "#1e3a8a", "$type": "color" }
}
},
"spacing": {
"1": { "$value": "4px", "$type": "dimension" },
"2": { "$value": "8px", "$type": "dimension" },
"4": { "$value": "16px", "$type": "dimension" }
}
}
2. 语义 Token（Semantic / Alias）
按用途命名，引用全局 Token
{
"color": {
"text": {
"primary": { "$value": "{color.gray.900}", "$type": "color" },
"secondary": { "$value": "{color.gray.600}", "$type": "color" },
"danger": { "$value": "{color.red.600}", "$type": "color" }
},
"bg": {
"surface": { "$value": "{color.white}", "$type": "color" },
"muted": { "$value": "{color.gray.50}", "$type": "color" }
}
}
}
3. 组件 Token（Component）
组件专用，引用语义 Token
{
"button": {
"primary": {
"bg": { "$value": "{color.brand.500}", "$type": "color" },
"text": { "$value": "{color.white}", "$type": "color" },
"padding": {
"x": { "$value": "{spacing.4}", "$type": "dimension" },
"y": { "$value": "{spacing.2}", "$type": "dimension" }
}
}
}
}
命名规范（DTCG）
[类别].[属性].[变体].[状态]
color.text.primary
color.bg.surface.hover
spacing.inline.sm
font.weight.bold
button.primary.bg
border.radius.md
完整 Token 集（最小集）
{
"color": {
"text": {
"primary": { "$value": "#1a1a1a", "$type": "color" },
"secondary": { "$value": "#6b7280", "$type": "color" },
"tertiary": { "$value": "#9ca3af", "$type": "color" },
"inverse": { "$value": "#ffffff", "$type": "color" },
"danger": { "$value": "#dc2626", "$type": "color" },
"success": { "$value": "#16a34a", "$type": "color" }
},
"bg": {
"surface": { "$value": "#ffffff", "$type": "color" },
"muted": { "$value": "#f9fafb", "$type": "color" },
"subtle": { "$value": "#f3f4f6", "$type": "color" }
},
"border": {
"default": { "$value": "#e5e7eb", "$type": "color" },
"focus": { "$value": "#2563eb", "$type": "color" },
"danger": { "$value": "#dc2626", "$type": "color" }
}
},
"spacing": {
"xs": { "$value": "4px", "$type": "dimension" },
"sm": { "$value": "8px", "$type": "dimension" },
"md": { "$value": "16px", "$type": "dimension" },
"lg": { "$value": "24px", "$type": "dimension" },
"xl": { "$value": "32px", "$type": "dimension" }
},
"font": {
"size": {
"xs": { "$value": "12px", "$type": "dimension" },
"sm": { "$value": "13px", "$type": "dimension" },
"base": { "$value": "14px", "$type": "dimension" },
"lg": { "$value": "16px", "$type": "dimension" },
"xl": { "$value": "18px", "$type": "dimension" },
"2xl": { "$value": "24px", "$type": "dimension" }
},
"weight": {
"normal": { "$value": "400", "$type": "fontWeight" },
"medium": { "$value": "500", "$type": "fontWeight" },
"bold": { "$value": "600", "$type": "fontWeight" }
}
},
"radius": {
"sm": { "$value": "4px", "$type": "dimension" },
"md": { "$value": "8px", "$type": "dimension" },
"lg": { "$value": "12px", "$type": "dimension" },
"full": { "$value": "9999px", "$type": "dimension" }
},
"shadow": {
"sm": { "$value": "0 1px 2px rgba(0,0,0,0.05)", "$type": "shadow" },
"md": { "$value": "0 4px 6px rgba(0,0,0,0.1)", "$type": "shadow" },
"lg": { "$value": "0 10px 15px rgba(0,0,0,0.1)", "$type": "shadow" }
}
}
工作流程
1. 收集设计需求（颜色/字体/间距）
2. 设计全局 Token（原始值）
3. 提炼语义 Token（按用途）
4. 为高频组件创建组件 Token
5. 输出 JSON 文件
6. 在设计工具同步（Figma Variables）
7. 在代码中实现（Tailwind config / CSS variables）
质量自检
□ 是否分了三层（全局/语义/组件）
□ 命名是否符合 DTCG 规范
□ 语义 Token 是否引用全局 Token（不直接写值）
□ 是否覆盖了所有设计原语（颜色/间距/字体/圆角/阴影）
□ 是否考虑了主题切换（暗黑模式）
常见坑
- 没有分层——直接在组件用原始值
- 命名不一致——color.primary vs color.brand.primary
- 语义层缺失——直接用 color.blue.500 代替 color.text.link
- 不可机器读取——只在 Figma 里有，代码用不了
- 手动维护——设计改了忘记同步代码
配套模板
templates/tokens-base.json— 基础 Token JSON 模板templates/tokens-dark-mode.json— 暗黑模式扩展模板
与其他 skill 的协作
上游：
visual-style → 提供视觉风格指引
平行：
atomic-design → Atoms 使用 Tokens
responsive-design → 断点 Tokens
下游：
design-handoff → JSON 直接交给前端