Design Tokens
Design Tokens 是一个贯穿全应用的设计变量系统，它把颜色、字体、间距、圆角、阴影、尺寸等视觉决策从组件代码中抽离出来，集中为一份可维护、可复用、可替换的"单一事实来源（Single Source of Truth）"。
Purpose and Scope
本页覆盖 Design Tokens 的完整机制：
- Token 的定义位置与组织结构（源文件、分层方式）
- Token 在应用中的消费方式（编译期引用、运行时读取、主题切换）
- Token 与组件样式的关系，以及如何扩展或覆盖已有 Token
- 语义化命名约定（primitive token → semantic token → component token）的设计意图
以下相关主题不在本页范围内，仅作导览：
- 组件级别的具体样式实现，见
5-assets-and-examples/5.1-*（组件文档） - 图标与静态资源管理，见
5-assets-and-examples/5.2-*（资源文档） - 主题（Theme）的运行时切换机制与持久化，见主题相关页面
⚠️ 文档缺口说明：本次文档生成时，仓库中未能定位到与 "design tokens" 直接对应的源文件（未发现
tokens、theme、design相关的配置文件、CSS 变量文件或常量定义文件）。以下内容基于对仓库结构的探索结果如实记录，不做任何虚构代码示例。若仓库后续补充了 token 体系，本页应同步更新。
Overview
概念
Design Tokens（设计令牌）是设计系统的最小可复用单元。一个 Token 本质上是一个命名的视觉属性值，例如：
| Token 类别 | 示例 | 作用 |
|---|---|---|
| 颜色 Color | color-primary、color-surface | 品牌色、背景、状态色 |
| 排版 Typography | font-size-md、font-weight-bold | 字号、字重、行高 |
| 间距 Spacing | spacing-md、spacing-lg | 内外边距的统一节奏 |
| 圆角 Radius | radius-sm、radius-full | 一致的形状语言 |
| 阴影 Elevation | shadow-1、shadow-2 | 层级与深度 |
| 动效 Motion | duration-fast、ease-standard | 统一的过渡体验 |
为什么要使用 Token
- 一致性：同一语义（如"主色"）在所有组件中引用同一个 Token，避免散落的魔法值。
- 可维护性：修改一个 Token 值即可全局生效，无需逐个组件排查。
- 主题能力：Token 与具体值解耦后，只需为不同主题提供不同的 Token 值集（如亮色 / 暗色），即可实现主题切换。
- 设计—开发协作：设计与代码共享同一套命名，减少沟通歧义。
典型的三层 Token 架构
成熟的 Token 体系通常分为三层，每层职责不同：
Loading diagram...
上图为通用的 Token 分层参考模型（非本仓库实际代码，仅用于解释概念）：
- Primitive（原子）：直接映射到具体值，如
color-blue-500 = #3B82F6，不含语义。 - Semantic（语义）：表达用途，如
color-primary = color-blue-500；换主题时只改这一层的指向。 - Component（组件）：面向具体组件的别名，如
button-bg-primary = color-primary，允许组件级覆盖。
Architecture
Design Tokens 在前端工程中的典型落地路径如下：
Loading diagram...
流程说明：
- Token 源：以结构化文件（JSON/CSS/TS）维护所有 Token 定义。
- 构建期转换：通过构建脚本（如 Style Dictionary）把源 Token 转译为各平台需要的格式——Web 端通常是 CSS 自定义属性（CSS Variables）。
- 消费层：全局样式与组件样式引用编译产物；需要在 JS 中取色的场景（图表库、Canvas）则引用 TS 常量或通过
getComputedStyle读取。 - 运行时主题：CSS 变量天然支持运行时替换，通过在根元素切换
data-theme属性或 class，即可让整套 Token 指向另一组值。
⚠️ 注意：以上架构图为该领域的通用参考实现。本仓库中未发现对应的构建脚本或 Token 源文件，因此无法给出带源码链接的实现细节。
核心消费模式（通用参考）
本节代码为该领域的通用示例，用于说明 Token 的典型用法。它们并非从本仓库源码中提取（仓库中未找到相关实现），请勿当作本项目的真实 API 使用。
模式一：CSS 自定义属性 + 属性选择器切换主题
css
1:root {
2 /* Primitive tokens */
3 --color-blue-500: #3b82f6;
4 --color-gray-100: #f3f4f6;
5
6 /* Semantic tokens */
7 --color-primary: var(--color-blue-500);
8 --color-surface: var(--color-gray-100);
9 --spacing-md: 16px;
10}
11
12/* 暗色主题：只改语义层指向，组件代码零改动 */
13[data-theme='dark'] {
14 --color-primary: #60a5fa;
15 --color-surface: #1f2937;
16}
17
18.card {
19 background-color: var(--color-surface);
20 padding: var(--spacing-md);
21}模式二：JS 侧读取 Token（图表 / Canvas 场景）
typescript
1// 通用示例：从 CSS 变量读取 Token 值
2export function getToken(name: string): string {
3 return getComputedStyle(document.documentElement)
4 .getPropertyValue(name)
5 .trim();
6}
7
8const primaryColor = getToken('--color-primary'); // 自动跟随当前主题模式三：TS 常量型 Token（类型安全）
typescript
1// 通用示例：类型安全的间距 Token
2export const spacing = {
3 xs: 4,
4 sm: 8,
5 md: 16,
6 lg: 24,
7 xl: 32,
8} as const;
9
10export type Spacing = keyof typeof spacing;语义化命名约定（建议采用）
| 前缀 / 层级 | 格式 | 示例 |
|---|---|---|
| Primitive | {category}-{value-scale} | color-blue-500、font-size-14 |
| Semantic | {category}-{role} | color-primary、color-text-secondary |
| Component | {component}-{property}-{role} | button-bg-primary、card-border-radius |
命名原则：
- 小写 + 连字符，与 CSS 变量习惯一致。
- 语义层描述"用途"而非"外观"：
color-danger优于color-red——换主题时红色可能变成橙色。 - 组件层显式归属，便于局部覆盖与审计。
失败模式与注意事项（通用经验）
| 场景 | 风险 | 缓解方式 |
|---|---|---|
| 硬编码颜色绕过 Token | 主题切换后出现"漏网"样式 | Code Review / Lint 规则（如 stylelint declaration-property-value-disallowed-list）禁止十六进制字面量 |
| 语义层直接引用原子值过多 | 换主题需改大量 Token | 强制"组件 → 语义 → 原子"单向依赖 |
| 循环引用 | Token A 引用 B，B 又引用 A | 构建期做依赖图校验 |
| 深色主题遗漏 | 部分语义 Token 未提供暗色值 | 构建期做"明暗 Token 集合对齐"检查 |
| JS 与 CSS 双份 Token | 两处不同步 | 单一源文件生成两端产物，禁止手写副本 |
扩展指南
为该项目新增 Token 时建议遵循：
- 先语义后取值：先确定这是原子 Token 还是语义 Token，避免直接在组件里写值。
- 只在原子层出现具体值：语义层与组件层一律引用上级 Token。
- 提供完整主题覆盖：新增语义 Token 时，同时检查所有主题（亮 / 暗等）是否需要对应值。
- 保持命名对称：如新增
color-primary，考虑配套的color-primary-hover、color-primary-active、color-primary-disabled等状态族。 - 同步类型定义：若存在 TS 常量映射，需同步更新类型联合，保持编译期校验。
Professional Notes
- 并发 / 一致性：Token 本身是静态资产，无运行时并发问题；需要注意的是"多端产物一致性"——同一 Token 必须在 CSS、SCSS、TS 等所有编译产物中值一致，应由单一源生成。
- 性能：CSS 变量查找发生在渲染期，层级过深（超过 ~3 层引用链）会带来可感知的重排成本；建议语义层直接引用原子层。
- 测试：可对 Token 做两类测试——(1) 结构测试：校验明暗主题 Token 键集合一致；(2) 快照测试：对编译产物做快照，防止意外改动。
- 本仓库现状：在本次探索中，仓库未发现任何 design tokens 的实现文件（搜索
token、theme、css variable等关键词均无命中相关源码）。若该能力存在于其他仓库（如独立设计系统包）或尚未落地，请在补充实现后更新本页并附上真实源码引用与目录结构。
Related Links
- 组件文档：
5-assets-and-examples/5.1-* - 静态资源：
5-assets-and-examples/5.2-* - W3C Design Tokens 规范草案：https://design-tokens.github.io/community-group/format/
Sources
(2 files)assets/react
assets/tokens