使用 CSS 变量统一主题颜色时，必须先在:root中完成定义并采用语义化命名；所有涉及颜色的样式都要显式通过var()调用，并补充安全回退值。若用 JS 实现深色模式或主题切换，应优先修改 HTML 属性，而不是只用 setProperty 改单个变量；接入第三方组件库时，还要确认其实际使用的变量名以及 CSS 加载顺序是否正确。
很多人以为只要在 :root 中定义变量，就能自动完成主题色统一，比如写下 --primary-color: #3b82f6。实际上这一步只是声明变量，并不会自动作用到页面。所有需要使用颜色的地方，都必须明确写成 color: var(--primary-color) 这类形式，否则变量虽然存在，但样式并没有真正引用它。
变量必须在 :root 中声明，且命名要语义化
浏览器会把 :root 中声明的 CSS 自定义属性视为全局可访问变量；如果变量写在其他选择器里，例如 .theme-dark，它通常只对对应作用域及其后代元素生效，无法稳定作为全站主题变量使用。
:root是最适合定义全局主题变量的作用域入口，尽量不要用html或body来替代- 变量命名建议采用短横线分隔并配合语义前缀，例如
--color-primary、--bg-surface，避免使用--blue-500这类仅描述颜色值的命名方式 - 所有与主题切换相关的变量，即使浅色与深色模式下当前值相同，也应在
:root中提前完整声明，不要等到 JS 运行后再动态注入
每个 var() 都必须带回退值，否则样式会失效
当变量未定义时，var(--text-primary) 不会主动报错，也不一定按预期继承，而可能退回到 transparent 或父级值，进而引发文字不可见、背景异常、页面闪烁等问题。因此，CSS 变量的安全回退值是主题系统里非常关键的一层保障。
- 规范写法应为
color: var(--text-primary, #333)，逗号后面必须是可直接使用的 CSS 值，不能再嵌套另一个var() - 回退值应选择业务场景中可靠的默认色，例如正文常用
#333，背景常用#fff，不要随意填一个black了事 - 像 SVG 的
fill和stroke、伪元素::before的background-color这类位置，也同样要加上var()与回退值，它们往往最容易被遗漏
JS 切换主题时，别只调 setProperty，要触发 CSS 选择器重计算
document.documentElement.style.setProperty('--color-primary', '#1e40af') 本质上只是修改了根元素的内联样式。如果你的主题系统依赖的是诸如 [data-theme="dark"] :root 之类的 CSS 规则，那么单独改变量并不会让这类选择器重新匹配。结果就是变量值可能变了，但对应样式未必能按预期联动刷新。
- 更稳妥的方式是直接切换 HTML 属性：
document.documentElement.setAttribute('data-theme', 'dark')，让 CSS 主题规则自动生效 - 如果项目采用 class 方案控制主题，例如
html.theme-dark，就应使用classList.toggle('theme-dark')，而不是手动逐个覆盖变量 - 当确实需要批量更新变量时，使用
Object.entries(theme).forEach(([k, v]) => el.style.setProperty(k, v))会比连续多次调用setProperty更高效，但从稳定性看，依然不如直接切换属性或 class
第三方框架或组件库的颜色可能绕过你的变量
在实际开发中，Tailwind、Bootstrap 5+、Ant Design 等前端框架虽然都支持 CSS 变量，但真正影响主题统一效果的关键是：它们内部是否真的在用你定义的变量。比如 Bootstrap 5.3 默认使用的是 --bs-primary，并不是 --primary-color；而 Tailwind 中像 bg-primary 这样的类，也只有在 tailwind.config.js 中正确配置 colors.primary 后才会按预期输出。
- 建议用开发者工具查看目标元素的
computed样式，确认background-color等属性究竟来自var(--bs-primary)还是某个硬编码颜色 - 框架样式文件与自定义主题变量的加载顺序必须确认清楚；如果框架 CSS 在后面覆盖了你的定义，主题颜色就可能失效
- SVG 图标、表单控件状态（
input:focus、button:active）、box-shadow等细节区域经常被忽略，这些位置也需要单独补齐var()变量引用
真正困难的地方，并不只是“如何定义 CSS 变量”，而是要确保页面中每一处颜色都正确接入 var()、每一个回退值都能在变量缺失时稳定兜底、每一次 JS 主题切换都走在正确的 CSS 选择器机制上。只要任何一个环节遗漏，统一主题颜色这件事就很容易出现局部失效。
