CSS 变量怎么整理：Design Token 提取、作用域、重复覆盖与缺失引用

接手一个旧主题、组件库或第三方模板时，经常能看到几百个 --color-*、--space-* 和 --font-*。直接搜索双横线可以找到名字，却看不出变量在哪个选择器生效、是否只属于深色主题、有没有媒体查询覆盖，也不知道哪些 var() 引用根本没有声明。

CSS 变量与 Design Token 提取器使用浏览器 CSSOM 解析当前样式，列出每条变量声明的值、类型、选择器、媒体条件、引用次数、重复定义和未解析引用，并导出 CSS、JSON 与 CSV。输入内容只在浏览器处理，@import 不会联网加载。

CSS 变量不是全局常量

自定义属性遵守 CSS 级联和继承。最常见的全局定义放在 :root：

:root {
  --color-brand: #0f766e;
  --space-card: 1rem;
}

组件可以覆盖：

.danger-panel {
  --color-brand: #b91c1c;
}

深色主题和断点也可以定义同名变量：

[data-theme="dark"] {
  --color-surface: #18181b;
}

@media (min-width: 768px) {
  :root { --space-card: 1.25rem; }
}

所以“变量重复三次”不等于有两条垃圾。必须一起看选择器、顺序、层和条件，判断这是有意覆盖还是历史残留。

为什么 CSSOM 比正则更合适

简单正则很容易把注释、字符串、data URI 和无效片段当成变量，也难以识别某条声明属于哪个 @media 或 @supports。

CSSOM 会让浏览器按规则结构解析样式表：样式规则包含选择器和声明，分组规则包含子规则。工具沿着规则树收集变量，同时记录外层条件。

CSSOM 也有边界。浏览器不支持的实验语法可能被忽略，构建工具专用嵌套、Sass/Less 源码和 PostCSS 插件语法不是普通 CSS。要审计源文件，应先用项目原有构建链生成标准 CSS，或者使用对应语言解析器。

重复定义应该怎样处理

先按变量名筛选，比较每个定义的选择器和上下文。如果一个变量只在同一 :root 中反复出现，后面的值覆盖前面，通常值得清理。

如果分别出现在 :root、[data-theme=dark] 和媒体查询中，它们很可能组成主题和响应式系统。此时应把命名、默认值和覆盖关系写进设计系统文档，而不是强行合成一条。

“每个变量只看最后定义”适合快速理解当前输入末尾的值，但不能代替浏览器对具体元素的计算结果。局部选择器的变量未必影响全局，媒体条件也未必当前成立。

未解析 var() 引用是什么

下面的 CSS 使用了一个当前文件没有声明的变量：

.button {
  border-color: var(--color-border);
}

它可能是拼写错误，也可能由另一个 CSS 文件、宿主应用、Shadow DOM 或运行时注入。若写了 fallback：

border-color: var(--color-border, #d4d4d8);

缺失时仍有备用值，但这不代表变量管理已经清楚。

工具只分析当前输入，不会加载 @import。看到未解析项时，应先搜索整个项目和构建产物，再判断是否需要补声明、改名字或保留外部依赖。

变量引用可以形成链和循环

别名让语义 Token 与基础 Token 分开：

:root {
  --blue-700: #0369a1;
  --color-action: var(--blue-700);
  --button-background: var(--color-action);
}

这种分层便于换主题。问题是错误配置可能形成循环：

--a: var(--b);
--b: var(--a);

循环变量在计算时会失效。审计时既要看原始值，也要尝试解析别名链，并对循环和缺失引用单独处理。

怎样给 Token 分类

颜色、尺寸、字体、阴影、时间和数字是常见类型。变量名可以提供线索，但值也要检查。例如 --brand 可能是颜色，也可能是图片 URL；--leading-tight: 1.2 是无单位数字，却属于排版。

自动分类适合快速筛选，不是最终 schema。建立设计系统时，应制定稳定命名，例如：

• 基础色阶：--blue-50 到 --blue-950；
• 语义颜色：--color-text-muted、--color-danger；
• 间距：--space-1、--space-2；
• 组件 Token：--button-radius、--card-shadow。

不要把当前所有 CSS 值都机械提升为 Token。只有需要复用、主题化或统一管理的决策才值得命名。

导出 JSON 后还要做什么

Design Token 平台并没有完全统一的导入细节。W3C Design Tokens、Tokens Studio、Figma Variables、Style Dictionary 和各类构建器，对层级、别名、复合阴影、字体对象和颜色格式可能有不同要求。

工具导出的 JSON 使用 $value、$type 和来源扩展，目的是保留可迁移信息。正式导入前，应按目标平台 schema 调整命名层级，把 var(--name) 别名转换为平台支持的引用格式，并用少量 Token 先跑通流程。

CSV 更适合审计和团队评审，可以排序、筛选和补负责人。整理后的 :root CSS 则是迁移草稿，会丢失主题与媒体查询上下文，不能直接替换原样式。

一套实际审计流程

从生产构建产物或明确的 CSS 文件开始，不要把 Sass、Less 和未处理插件语法直接混在一起。上传后先看唯一变量数、重复数和未解析引用。

按重复变量逐个检查作用域，区分主题覆盖与无效残留。按未解析引用搜索整个仓库，确认它来自外部依赖、运行时注入还是拼写错误。

筛选颜色 Token，配合颜色对比度检查器检查常用文字与背景组合。再筛尺寸、字体和阴影，找出命名重复但值相同、名称相似但值分裂的情况。

把结果导出 CSV 评审，确定最终命名与层级，再生成平台 JSON 和基础 CSS。替换项目时分批进行，保留视觉回归截图和实际组件测试。

总结

整理 CSS 变量不能只做字符串去重。真正需要理解的是级联作用域、主题与媒体覆盖、别名引用、缺失声明和目标设计系统格式。

先用结构化解析把现状看清，再决定哪些变量保留、重命名、合并或升级为 Design Token，迁移会比直接重写一份 :root 稳定得多。