为什么你的 design tokens 和 CSS 可能不同步（以及如何检查）

Source: Dev.to

问题：Tokens 与 CSS 不同步

你已经定义了 token，完成了文档编写，甚至可能已经在 Storybook 页面上展示了完整的调色板及其变量名。六个月后，代码库里出现了大量硬编码的值，例如 color: #1A1A1A，以及散落在各组件中的 12px 间距值，还有自上一次品牌重塑后再也没有被引用的 token。

这些不匹配并非有意为之，而是悄悄累积的：

• 截止日期压力 – 某个组件快速上线后，只更新了部分 CSS 文件中的 token 名称。
• 新人入职 – 新开发者看到几个组件里使用了硬编码值，便误以为这是约定俗成。
• 品牌重塑 – token 值被修改，但硬编码的值仍然保留，因为没人知道它们的存在。

这种漂移是不可见的，因为它并不会导致错误，但当你需要审计系统时，就会变成维护噩梦。

漂移出现的迹象

• token 值已更改，但硬编码的版本仍保持不变。
• 你无法定位 CSS 中隐藏的直接数值。
• 新来的设计师问：“真正的唯一真相来源是什么？”而你无法给出明确答案。

此时，审计只能手动且痛苦地进行：在 CSS 中 grep，交叉对照 token 文件，并制作覆盖率电子表格。

需要了解的内容

在处理这个问题时，问自己：

• 哪些 token 已定义却从未在 CSS 中使用？
• 硬编码的值藏在哪里？
• 各类别（颜色、间距、排版等）的覆盖率如何？
• 哪些组件的 token 覆盖率最差？

介绍 TokenLens

TokenLens 是一款基于浏览器的审计工具，接受：

1. 你的设计 token 定义（JSON 格式）。
2. 你的 CSS 文件。

工作原理

• 支持多个 JSON 与 CSS 文件（适用于拆分的 token 集或基于组件的 CSS）。

• 无需账号、安装或构建步骤。

• 生成报告，内容包括：

  • 每个类别的 token 覆盖率（引用 token 的 CSS 属性占比 vs. 硬编码值）。
  • 未使用的 token – 在 JSON 中定义但未在任何 CSS 文件中出现。
  • 硬编码值实例 – 直接使用数值的具体行，按属性类型分组。
  • 组件细分 – 按选择器（从类名推断）的最低覆盖率组件。

示例输出

假设有一个包含 40 个颜色 token 的文件以及若干组件 CSS 文件。运行 TokenLens 后可能得到：

• 40 个颜色 token 中有 28 个 被 CSS 引用。
• 12 个 token 只存在于定义中，却未被使用。
• 23 处硬编码十六进制值 分布在 8 个组件文件 中。

这让你清晰地看到需要重点清理的地方，以及该向设计团队提出哪些问题。

为什么重要

设计师和开发者都可以使用这份报告作为共同的语言。与其模糊地说“我们的设计系统没有被遵循”，不如指向具体实例：“这里有 23 处硬编码值，已按组件分组”。

推荐

如果你维护或接手一个设计系统，请使用 TokenLens 进行审计。结果往往比预期更具可操作性。

试用地址： https://tokenlens.app

欢迎在评论区告诉我你的使用感受！