Design Tokens 标准命名与结构对照手册 #

Design Tokens（设计令牌）是将设计决策（颜色、间距、字体、圆角、阴影等）抽象并存储为跨平台代码键值对的标准规范。在企业级设计系统中，合理的 Tokens 架构能够抹平设计师在 Figma 中的定义与前端工程师在 CSS / iOS / Android 代码中的实现鸿沟。

本文档遵循 W3C Design Tokens Community Group (DTCG) 规范提案，梳理了企业级三层 Token 分层架构体系与标准化命名对照字典。

1. 企业级 Design Tokens 三层分层模型 #

一个健壮且可长期维护的 Tokens 体系严格划分为三个层级，下层引用上层，杜绝在组件中直接硬编码底层裸值：

┌────────────────────────────────────────────────────────┐
│  Tier 1: Global Tokens (全局基础层 / 原始物理值)          │
│  例如: blue-500 = #3B82F6, spacing-4 = 16px, font-14  │
└──────────────────────────┬─────────────────────────────┘
                           │ 映射与语义别名 (Alias)
                           ▼
┌────────────────────────────────────────────────────────┐
│  Tier 2: Semantic Tokens (语义决策层 / 语境抽象)         │
│  例如: surface-brand = blue-500, text-primary = gray-900│
│  支持根据主题模式 (Light / Dark) 动态切换映射引用         │
└──────────────────────────┬─────────────────────────────┘
                           │ 绑定与作用域限制 (Scopes)
                           ▼
┌────────────────────────────────────────────────────────┐
│  Tier 3: Component Tokens (组件专属层 / 私有属性)        │
│  例如: button-primary-bg = surface-brand               │
│        card-header-padding = spacing-4                 │
└────────────────────────────────────────────────────────┘

各层级职责与权限边界 #

Token 层级 谁负责维护 包含的内容 是否允许业务侧直接覆盖
Tier 1: Global Tokens 核心设计系统团队 调色板阶梯、无语境间距数值、原始字体族 严禁。全局原子字典，不具备主题感知
Tier 2: Semantic Tokens 核心设计系统 + 体验架构师 表面背景、文本可读性层级、边框、状态反馈 推荐使用。支撑 90% 的业务界面设计，自适应浅深色模式
Tier 3: Component Tokens 组件开发与模块设计师 按钮、输入框、表格专属尺寸与状态变化 局部受控。用于高定制业务组件，防止全局样式污染

2. 标准命名公式语法 (Naming Convention) #

推荐采用 Kebab-case 连接的结构化命名公式：

$$ \text{[Category]}-\text{[Concept]}-\text{[Property]}-\text{[Variant]}-\text{[State]} $$

  • Category（分类）: color、spacing、size、radius、shadow、font
  • Concept（语义概念 / 语境）: surface（表面/背景）、text（文本）、border（边框）、action（交互行为）
  • Property（属性类型）: brand、neutral、success、danger、primary、secondary
  • Variant（变体/层级）: subtle、muted、strong、inverse
  • State（交互状态）: default、hover、active、focus、disabled

3. 色彩系统 Token 对照字典 (Color Tokens) #

3.1 表面背景层 (Surface & Background) #

语义 Token 标识 Light 模式映射 (Global) Dark 模式映射 (Global) CSS 变量名称 用途说明
surface-default white (#FFFFFF) gray-950 (#0B0F19) --color-surface-default 页面最底层主画布背景
surface-subtle gray-50 (#F9FAFB) gray-900 (#111827) --color-surface-subtle 浅灰斑马纹、次级底栏背景
surface-elevated white (#FFFFFF) gray-800 (#1F2937) --color-surface-elevated 悬浮卡片、下拉菜单、Dialog 弹窗
surface-inverse gray-900 (#111827) gray-100 (#F3F4F6) --color-surface-inverse 反色气泡 Tooltip、黑底横幅
surface-brand blue-600 (#2563EB) blue-500 (#3B82F6) --color-surface-brand 主品牌操作按钮、选定激活块
surface-success emerald-50 (#ECFDF5) emerald-950/40 --color-surface-success 成功提示 Alert 浅色背景
surface-error red-50 (#FEF2F2) red-950/40 --color-surface-error 报错警告 Alert 浅色背景
surface-disabled gray-100 (#F3F4F6) gray-800 (#1F2937) --color-surface-disabled 置灰不可点控件背景

3.2 文本与图标层 (Text & Icon) #

语义 Token 标识 Light 模式映射 Dark 模式映射 WCAG 对比度 用途说明
text-primary gray-900 (#111827) gray-50 (#F9FAFB) $\ge 12:1$ (AAA) 正文大标题、主要文本、高对比强调
text-secondary gray-600 (#4B5563) gray-400 (#9CA3AF) $\ge 4.5:1$ (AA) 次级说明文案、副标题、元数据
text-tertiary gray-400 (#9CA3AF) gray-500 (#6B7280) $\ge 3:1$ 输入框占位符 (Placeholder)、辅助提示
text-disabled gray-300 (#D1D5DB) gray-600 (#4B5563) 不计 禁用状态文字
text-inverse white (#FFFFFF) gray-900 (#111827) $\ge 15:1$ (AAA) 深色/高亮背景上的反色白字
text-brand blue-600 (#2563EB) blue-400 (#60A5FA) $\ge 4.5:1$ (AA) 品牌高亮链接、导航选中文字
text-error red-600 (#DC2626) red-400 (#F87171) $\ge 4.5:1$ (AA) 表单验证报错红字

3.3 描边与分割线层 (Border & Divider) #

语义 Token 标识 Light 模式映射 Dark 模式映射 CSS 变量名称 用途说明
border-subtle gray-100 (#F3F4F6) gray-800 (#1F2937) --color-border-subtle 列表轻量分割线、次级内边框
border-default gray-200 (#E5E7EB) gray-700 (#374151) --color-border-default 默认卡片外框、表格边界
border-strong gray-400 (#9CA3AF) gray-500 (#6B7280) --color-border-strong 表单输入框默认边框、勾选框边框
border-focus blue-600 (#2563EB) blue-400 (#60A5FA) --color-border-focus 聚焦状态外光晕 (Ring) 基础色
border-error red-600 (#DC2626) red-500 (#EF4444) --color-border-error 表单报错红框

4. 间距与空间 Token (Spacing & Sizing) #

间距遵循 8pt / 4pt 梯级，统一使用 REM 单位与 CSS 变量交付：

间距 Token 像素值 (px) rem 基准 ($1\text{rem}=16\text{px}$) Tailwind Class 作用域限制 (Figma Scopes)
spacing-1 4 px 0.25 rem gap-1 / p-1 Gap, Padding
spacing-2 8 px 0.5 rem gap-2 / p-2 Gap, Padding
spacing-3 12 px 0.75 rem gap-3 / p-3 Gap, Padding
spacing-4 16 px 1.0 rem gap-4 / p-4 Gap, Padding, Margin
spacing-5 20 px 1.25 rem gap-5 / p-5 Gap, Padding, Margin
spacing-6 24 px 1.5 rem gap-6 / p-6 Gap, Padding, Margin
spacing-8 32 px 2.0 rem gap-8 / p-8 Gap, Padding, Margin
spacing-10 40 px 2.5 rem gap-10 / p-10 Padding, Margin
spacing-12 48 px 3.0 rem gap-12 / p-12 Padding, Margin
spacing-16 64 px 4.0 rem gap-16 / p-16 Margin (仅限 Section 外边距)

5. 圆角与边框 Token (Border Radius) #

圆角 Token 像素值 (px) Tailwind 映射 推荐应用场景
radius-none 0 px rounded-none 直角表格单元格、全屏抽屉边框
radius-sm 2 px rounded-sm 微型 Checkbox、紧凑提示标签
radius-default 4 px rounded 紧凑型按钮、下拉菜单选项浮层
radius-md 6 px rounded-md 标准表单输入框、通用按钮
radius-lg 8 px rounded-lg 内容卡片 (Card)、警告框 Alert
radius-xl 12 px rounded-xl 模态弹窗 (Modal Dialog)、浮动面板
radius-2xl 16 px rounded-2xl 移动端底栏抽屉卡片、运营活动 Banner
radius-full 9999 px rounded-full 胶囊按钮 (Pill Button)、圆形头像 Avatar

6. 标高与阴影 Token (Elevation & Box Shadow) #

通过多层环境光与直射光叠加，模拟物理层级质感：

:root {
  /* Elevation 1: 基础卡片轻量浮起 */
  --shadow-elevation-1: 0 1px 2px 0 rgba(0, 0, 0, 0.05);

  /* Elevation 2: 悬停态 / 下拉菜单 Dropdown */
  --shadow-elevation-2: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.06);

  /* Elevation 3: 对话框 Dialog / 浮动导航栏 */
  --shadow-elevation-3: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.08);

  /* Elevation 4: 侧滑抽屉 Drawer / 全局通知 Toast */
  --shadow-elevation-4: 0 20px 25px -5px rgba(0, 0, 0, 0.12), 0 8px 10px -6px rgba(0, 0, 0, 0.08);
}

7. 从 Figma Variables 到前端工程化代码同步 #

借助开源工具 Style Dictionary，可以将 Figma 导出的 DTCG JSON 文件一键编译为全平台代码产物：

{
  "color": {
    "surface": {
      "brand": {
        "value": "{color.blue.600.value}",
        "type": "color",
        "description": "主要品牌操作按钮背景色"
      }
    }
  }
}

自动化生成的前端代码产物 #

CSS Variables 输出 (tokens.css) #

:root {
  --color-surface-brand: #2563eb;
}
[data-theme='dark'] {
  --color-surface-brand: #3b82f6;
}

TypeScript 常量与类型守卫 (tokens.ts) #

export const DesignTokens = {
  color: {
    surfaceBrand: 'var(--color-surface-brand)',
    textPrimary: 'var(--color-text-primary)',
  },
  spacing: {
    4: '1rem',
    8: '2rem',
  }
} as const;

export type DesignTokenKeys = typeof DesignTokens;
上一篇 UI 设计规范与设备尺寸速查表 下一篇 Figma 常见报错与疑难故障诊断手册

🔥 相关教程推荐

查看更多教程
Variables 2024-06-02

基于 Figma Variables 的企业级 Design Tokens 架构与工程化同步

深度探讨企业级 Design Tokens 架构设计，详解 DTCG 标准协议、Style Dictionary 自动化...

阅读全文
设计系统 2024-06-15

企业级组件库架构法则：属性化变体 (Component Properties)、嵌套与槽位插槽

系统剖析现代 Figma 组件架构原则，利用 Boolean、Text、Instance Swap 及 Variant...

阅读全文
Dev Mode 2024-06-04

变量作用域 (Scopes) 与别名嵌套最佳实践：从设计系统到代码无缝映射

系统阐述 Figma Variables 的 Scopes 作用域控制与别名 (Alias) 引用拓扑，建立 Globa...

阅读全文

🛠️ 核心手册与速查工具

高频手册与实用设计生产力工具直达
📘
Figma 中文用户指南 官方精译
系统化官方中文指南，零基础上手到进阶排版与组件管理。
🎯
FigJam 白板协作指南 团队协作
头脑风暴、敏捷站会、流程图与用户旅程图实战画板。
⌨️
全平台快捷键速查表 效率翻倍
macOS 与 Windows 双平台核心高频快捷键中英文对照。
📐
界面与画布上手指南 基础必读
图层面板、画布工具栏、右侧属性检查器全面图解。
🛠️
浏览器与环境优化配置 故障排查
WebGL 渲染、硬件加速开启与本地字体同步解决方案。
💡
最佳实践精选教程 深度进阶
Auto Layout v5、Variables 设计令牌与 Dev Mode 研发协同。

❓ 常见问题与答疑 (FAQ)

高频疑难解析与避坑指南
A

macOS 上主要使用 Command (⌘) 键，Windows 上对应 Ctrl 键；Option 键对应 Windows 的 Alt 键。建议使用快捷键 Ctrl + Shift + ?（Windows）或 Cmd + Shift + ?（Mac）随时调出内置快捷键助手。