必须用语义名（如--color-primary）而非具体色值命名，因品牌色变更时语义名保持稳定、避免grep误伤；变量须分三层组织：底层基础色阶、中层语义映射、顶层主题覆盖，确保修改解耦、互不污染。
直接在 :root 里定义语义化变量（如 --color-primary）并全局替换所有硬编码颜色，才能真正实现“改一处、全站变”。不提前建体系，只靠后期 patch，90% 的按钮、SVG、伪元素和第三方组件都会漏掉。
为什么必须用语义名而不是具体色值命名
CSS 变量不是“换色工具”，而是“设计系统接口”。写 --blue-500: #3b82f6 看似直观，但一旦品牌从蓝色切到紫色，所有 blue 相关变量名就失效，grep 替换会误伤文案或注释；而 --color-primary 指向什么色值，由设计规范决定，前端只管引用。
-
--color-primary代表主操作色（按钮、链接、重点边框） -
--color-bg和--color-text是基础层，必须成对出现且对比度达标 -
--color-border不应直接等于--color-bg或--color-text，要预留视觉层次（比如#e5e7eb而非#ffffff） - 避免
--main-blue、--header-color这类耦合 DOM 结构或场景的命名，它们无法跨组件复用
如何分层组织变量避免失控
把变量塞进一个 :root 块里看似简单，实际维护时会迅速变成颜色沼泽。必须分三层声明，且加载顺序严格：
- 底层：设计系统基础色阶（
--color-blue-50,--color-blue-500），只在此处写具体十六进制值 - 中层：语义映射（
--color-primary: var(--color-blue-500)），全站样式只读这一层 - 顶层：主题覆盖（
.theme-dark :root { --color-primary: var(--color-indigo-400); }），通过 class 触发重计算
这样改品牌主色，只需动中层一行；调设计蓝阶，只改底层；切深色模式，只改顶层选择器——互不污染。
立即学习“前端免费学习笔记（深入）”；
哪些地方最容易漏掉 var() 替换
变量生效的前提是“所有用色处都显式调用 var()”。浏览器不会自动扫描旧样式去替换，漏一处，那一块就卡在旧主题里。
-
::before/::after里的background和color—— 图标装饰、下划线、状态标记常在这里硬编码 -
svg标签内联的fill和stroke，必须写成fill: var(--color-primary)，不能依赖继承 - 表单控件状态：
input:focus的outline-color、button:disabled的background-color - 第三方库（如 Ant Design）若未开启 CSS 变量支持，其内部 class 不响应你的变量，需额外加覆盖规则或启用其主题插件
JS 切换时为什么 setProperty 不一定生效
调用 document.documentElement.style.setProperty('--color-primary', '#ef4444') 看似正确，但实际可能无效——因为该写法只修改 style 属性上的变量，而你 CSS 中的 .theme-dark :root 规则优先级更高，会压掉它。
- 如果用 class 切换方案（推荐），JS 应只操作
document.documentElement.classList，让 CSS 自己接管变量重赋值 - 如果用纯 JS 动态写变量，确保没有更高优先级的
:root声明（比如框架自带的:root块在你之前加载） - 检查变量名拼写：大小写敏感、双破折号不可省略、结尾分号不能丢（
--Color-Primary≠--color-primary） - 用
getComputedStyle(document.documentElement).getPropertyValue('--color-primary')实时验证是否真被写入
最易被忽略的是：变量名和 CSS 中使用的名称必须完全一致，且所有用到它的样式规则必须已加载完毕——否则即使 JS 执行成功，渲染时仍取回退值。
