设计 Token 评审：语义颜色不能退化成色阶编号

设计 Token 评审：语义颜色不能退化成色阶编号

Token 要给颜色、间距和字号一个稳定来源。如果组件里不断冒出相近字面量，主题切换时就只能逐个猜哪些值代表同一种语义。

代码评审不必把每个数值都当错误，而要明确哪些属性必须走语义 Token，哪些值可以作为布局例外，并把规则交给工具执行。

评审语义 Token 的使用边界

在 CI/CD 阶段或者本地提交时，直接运行分析脚本扫描样式代码中的硬编码漏洞。

# 检索样式源码中未通过 Token 命名的硬编码色值数量 grep -rE "#[a-fA-F0-9]{3,6}|rgba?\(" src/styles/ --exclude-dir=tokens # 使用 stylelint 运行严格的设计 Token 规则校验 npx stylelint "src/**/*.css" --config .stylelintrc.json --formatter verbose

扫描结果只是线索。先区分第三方样式、一次性排版和应复用的组件样式，再决定是引入 Token 还是配置例外。

Design Tokens CI/CD 自动化流水线与防腐架构

Token 的导出、编译、校验与发布可以串成一条可追踪的流水线：

Style Dictionary 与 Stylelint 配置示例

下面是 Style Dictionary 编译和 Stylelint 规则的示例。规则范围需要随组件库成熟度逐步收紧：

// style-dictionary.config.js - 多端 Token 编译配置文件 module.exports = { source: ['tokens/**/*.json'], platforms: { css: { transformGroup: 'css', buildPath: 'build/css/', files: [ { destination: 'variables.css', format: 'css/variables', options: { outputReferences: true // 保留 Token 引用关系 } } ] }, js: { transformGroup: 'js', buildPath: 'build/js/', files: [ { destination: 'tokens.ts', format: 'javascript/es6' } ] } } };

// .stylelintrc.js - 严格拦截硬编码值的 Stylelint 规则 module.exports = { plugins: ['stylelint-declaration-strict-value'], rules: { // 强制颜色、间距、字号必须使用 var(--token-*) 格式，禁止硬编码 'scale-unlimited/declaration-strict-value': [ ['/color/', 'font-size', 'margin', 'padding', 'border-radius'], { ignoreValues: ['0', 'transparent', 'inherit', 'auto'], message: '【CR 阻断】禁止在样式中使用硬编码值 "${value}"，必须替换为 Design Token 变量！' } ] } };

代码评审（CR）应关注的细节

审查组件样式时，重点看：

• 组件优先使用语义 Token，例如var(--color-primary-action)，而不是直接引用某个色阶。
• 间距是否来自项目约定的尺度；确有特殊对齐需要时，在代码旁说明原因，而不是偷偷拼常量。
• 主题通过 Token 映射完成。切换主题后，检查文字、边框、阴影和遮罩的对比度是否仍然可用。

工具管分发，评审管语义

Token 工具负责分发，评审与自动校验负责守边界。先覆盖常见组件，再逐步收紧规则；一次把所有数值都判成错误，只会催生更多绕过。