CSS变量需在:root定义并语义化命名，所有用色处必须显式调用var()且带安全回退值；JS切换主题应修改HTML属性而非仅setProperty；第三方库需确认其变量名与加载顺序。
直接在 :root 里定义变量就能统一主题色，但光写 --primary-color: #3b82f6 不会自动生效——所有用到颜色的地方，都得显式写 color: var(--primary-color)，否则变量只是“存在”，没人“消费”。
变量必须在 :root 中声明，且命名要语义化
浏览器只认 :root 下的变量为全局作用域；其他选择器（比如 .theme-dark）里定义的变量，只对后代生效，无法被顶层样式引用。
-
:root是唯一能保证全页面可读的作用域起点，别用html或body替代 - 变量名推荐用短横线分隔 + 语义前缀，比如
--color-primary、--bg-surface，避免--blue-500这类具象命名 - 所有主题相关变量（哪怕浅色/深色值相同）都得在
:root块里一次性写全，不能靠 JS 动态注入后再用
每个 var() 都必须带回退值，否则样式会失效
变量未定义时，var(--text-primary) 不会继承或报错，而是直接 fallback 到 transparent 或父级继承值，导致文字消失、背景变白等 FOUC 现象。
- 写法必须是
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') 只改内联 style，对 [data-theme="dark"] :root 这类规则无效——它不触发选择器匹配，变量值变了但样式没重绘。
立即学习“前端免费学习笔记（深入）”；
- 正确做法是切换 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更快，但仍不如属性切换稳定
第三方框架或组件库的颜色可能绕过你的变量
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 文件必须在你自定义
:root块之后加载，否则你的变量会被覆盖 - SVG 图标、表单控件状态（
input:focus、button:active）、box-shadow等常被忽略的位置，需单独补上var()
真正难的不是“怎么定义变量”，而是确保每一处颜色都被 var() 覆盖、每一个回退值都经得起变量缺失考验、每一次 JS 切换都走对了 CSS 选择器路径——漏掉任何一个环节，主题就会局部失灵。
