🔍 为什么你应该使用全局 Token 开发组件样式

[xiaosansiji]

为什么 PR review 时经常会被提醒使用 Token 变量？

很多初次贡献代码的同学，可能经常会被提醒没有正确使用 Token 变量，原因如截图中所示，如果直接 hard code 写值，后续就不能通过修改全局 Token 变量的方式，快速修改所有组件的表现。如这里所描述的 主题配置

除了截图中的 radius 圆角相关的 Token 变量，目前 TDesign 中提取的全局变量有如下几类：

• 色彩
• 文字
• 圆角
• 尺寸/间距

全局 Design Token 变量在哪里？

见 https://github.com/Tencent/tdesign-common/blob/develop/style/web/theme/_index.less

注意 style/web/theme 下文件中均为命名以 --td- 开头的 CSS 变量，例如：
https://github.com/Tencent/tdesign-common/blob/develop/style/web/theme/_light.less

这里是借用了高级浏览器本身支持 CSS variables 的特性，可以达到 TDesign 组件库官网在线实时主题修改和定制的能力。

但请你不要在组件样式中直接使用 --td- 的 CSS 变量，而应该使用 https://github.com/Tencent/tdesign-common/blob/develop/style/web/_variables.less 中包装后的 Less 变量。

// Good
background-color: @brand-color;

// Bad
background-color: --td-brand-color;

// Bad
background-color: #0052d9;

不直接使用 CSS 变量而使用包了一层的 Less 变量的原因：

1. 统一风格
2. 还可以继续使用 Less 提供的更丰富的函数来做进一步的加工处理

（后续可能会统一替换为所有样式都直接使用 CSS 变量，去掉 Less 依赖，但在目前相当长的一段时间内都会是以上实现方式）

从设计稿还原时，怎样找到对应的 Token 变量

以设计师常用的 Codesign 设计稿为例（Figma 资源类似）
https://codesign.woa.com/app/design/OYDgGjYoDN0wEVQ/qxWyZ12BJJjmVXk/inspect

设计会给出如图填充背景色标注为：#0052D9

你不应当直接在组件实现代码中使用这个值，而是需要在 https://github.com/Tencent/tdesign-common/blob/develop/style/web/theme/_light.less 文件中找到对应的色板变量 --td-brand-color-7

然后找到对应的语义化的 Token --td-brand-color，最终的代码中应该使用的就是对应的 Less Token @brand-color。

为什么不能直接使用色板中的 Token？

@brand-color 和 @brand-color-7 在浅色模式下效果是一样的，因为它们的值是一样：
https://github.com/Tencent/tdesign-common/blob/develop/style/web/theme/_light.less#L69

但在暗色模式下却不是相等的：
https://github.com/Tencent/tdesign-common/blob/develop/style/web/theme/_dark.less#L68

为了在浅色和暗色模式下都达到最好的展示效果，两种模式下会分别取浅色/暗色两套色板不同色阶的位置颜色，但语义化的 Token 含义是稳定的，就是 @brand-color 它表示了整个组件库的主色调。当你在组件样式中使用了 @brand-color 时，就可以在不同默认切换时自动使用最合适的色板值。

类似的还有尺寸/间距相关的 token：https://github.com/Tencent/tdesign-common/blob/develop/style/web/theme/_size.less

// Good
padding: @pop-padding-m;

// Bad
padding: @size-3;

你应该也能体会到，语义化的 @pop-padding-m 可读性和可维护性都要高于看不出什么含义的 @size-3