大型项目必须使用语义化 css 变量设计系统，否则 ui 一致性无法保障：硬编码颜色/间距（如 #007bff、12px）切断设计与实现映射，导致搜索替换不可靠、语义混淆、主题切换失效、构建无校验；所有 token 必须统一收口至 :root 声明的单一文件，禁止嵌套 var()，fallback 需语义化且仅用于降级场景，确保变量全局生效、js 可读写、构建可校验。
大型项目里，不引入 CSS 设计系统（即基于 --color-primary、--spacing-md 等语义化变量的 Token 体系），UI 一致性就只能靠人盯、靠搜、靠运气——改一个蓝色，漏掉三个按钮、两个禁用态、一个 Tooltip 背景，视觉就裂了。
为什么直接写死颜色/间距在组件里等于埋雷
硬编码如 #007bff 或 12px 看似简单，实则切断了设计与实现的映射关系：
- 搜索替换不可靠：正则匹配
#007bff可能误伤注释、JS 字符串或十六进制颜色值（如#007bffaa） - 无法区分语义：同一色值在不同上下文含义不同（主按钮背景 ≠ 危险文字颜色），但代码里看不出区别
- 主题切换失效：暗色模式需要整套颜色重映射，硬编码必须手动改 N 处，且无法通过 JS 动态切换
- 构建时无校验：PostCSS 插件（如
postcss-custom-properties）对硬编码完全无感，错漏静默存在
:root 声明 + design-tokens.css 是唯一可靠入口
所有设计 Token 必须收口到单一文件（如 src/styles/design-tokens.css），并在 :root 下声明：
:root {
--color-primary: #007bff;
--color-danger: #dc3545;
--spacing-xs: 4px;
--spacing-sm: 8px;
--spacing-md: 12px;
--radius-sm: 4px;
--font-size-body: 14px;
}
这样做不是为了“规范”，而是解决实际问题：
- 全局生效：只有
:root下的变量才能被任意组件内var(--color-primary)正确读取 - 支持 JS 运行时读写：
document.documentElement.style.setProperty('--color-primary', '#0056b3')立刻生效 - 便于构建工具介入：可配合插件做未定义变量警告（
warnWhenMissing）、单位标准化（如自动补px）、甚至生成 TS 类型定义 - 禁止在组件 scoped 样式或
<style scoped></style>中重复定义变量——那只是局部作用域，其他组件根本看不到
变量嵌套和 fallback 是最常踩的两个坑
var(--bg-hover, var(--bg-default)) 看似优雅，但浏览器不会递归解析第二层 var()，JS 读取时返回空字符串；而 var(--color-error, red) 的 red 是硬编码，脱离设计系统管控。
- 避免嵌套：所有变量值必须是原始值（
#007bff、12px），不要用var(--other-var)当右值 - fallback 要语义化：写成
var(--color-error, var(--color-danger))，确保降级也走 Token 链路 - 仅对真正需降级的场景用 fallback：比如暗色模式 CSS 文件尚未加载完成时，临时用
var(--color-text, #333)；日常开发中应让缺失变量报错可见，而不是静默兜底 - 检查是否生效：在 DevTools 的 Computed 面板里看目标元素的
color值，如果显示的是var(--color-text)而非计算后的rgb(51, 51, 51)，说明变量未被正确解析——大概率是作用域没覆盖到或拼写错误
真正难的从来不是定义几十个变量，而是让每个新成员写的第一个组件，都天然遵循同一套 Token；让设计师改一次 Figma 主题，前端不用改一行样式代码就能同步。这要求 Token 文件成为事实标准，而非可选文档——它得出现在 CI 流程里、出现在 Code Review 检查项里、出现在新人入职第一天的 git clone 后第一条命令里。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
