必须将所有主题变量定义在:root中，否则JS调用setProperty后组件不响应、颜色断层、刷新闪白；变量名严格区分大小写和拼写，漏写双短横或作用域错误会导致静默失效，且transition不能作用于变量名本身而需绑定具体属性。
直接改 :root 里的变量值就能一键切换全站主题，但前提是所有颜色、背景、边框等都用了 var(--x)，且没有 JS 硬编码、内联样式或第三方库绕过变量链——否则改了也白改。
为什么 var(--color) 改了没反应
不是语法错，大概率是变量根本没被定义，或作用域断了。浏览器不会报错，只会静默 fallback 到继承值或默认值（比如文字突然看不见）。
-
--color-primary必须在:root中声明，写在.theme-dark或body里会导致子元素取不到 - 大小写敏感：
--PrimaryColor≠--primarycolor≠--primary-color - 漏掉双短横线（比如写成
primary-color）会被浏览器完全忽略，不报错也不生效 - 开发者工具里检查「计算样式」，如果显示仍是
var(--x)而没展开成具体值，说明变量未定义或拼写错误
哪些地方必须手动替换成 var(--x)
CSS 变量不会自动扫描旧样式。你得逐个替换显式颜色值，否则那些地方永远不受控。
-
background-color、color、border-color、box-shadow、outline-color -
::before和::after里的background、color、border——图标类装饰最容易漏 - SVG 的
fill和stroke属性，必须显式写成fill: var(--icon-color) - 表单状态：
input:focus、button:active、select:disabled - 第三方 UI 库（如 Ant Design）若未开启 CSS 变量支持，其内部 class 不会响应你的变量
JS 切换主题时三个高发错误
只调 document.documentElement.style.setProperty() 并不能保证主题生效；很多闪屏、错色、回退失效都源于这几个疏漏。
立即学习“前端免费学习笔记（深入）”；
- 没在 HTML
<head>里预设初始data-theme：浏览器先按默认 CSS 渲染，JS 执行后再切，必然 FOUC。正确做法是：<script>document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light';</script> - 只改
dataset.theme却忘了localStorage.setItem()，刷新后变回默认 - 用
setProperty('--hue', '240')但:root里根本没声明--hue——此时var(--hue)无定义，fallback 失效，整页颜色崩掉
[data-theme="dark"] :root 比 :root.dark 更可靠
用属性选择器覆盖比 class 选择器更稳，尤其在复杂项目中。
-
[data-theme="dark"] :root权重固定为 110，远高于普通 class（10），不易被业务样式意外覆盖 - 避免命名冲突：业务代码里可能已有
.dark类，加 class 容易误触其他逻辑 - 支持多主题扩展：只要改
data-theme="amber"，就能无缝接入第三套配色，不用新增 class 名 - Safari 旧版本对
@media (prefers-color-scheme) .dark :root支持不稳定，但[data-theme]全系兼容
最常被忽略的点是：CSS 变量本身不触发重绘，只靠 setProperty 改值，页面不会自动更新样式；必须配合 data-theme class 切换或给具体属性（如 background-color）加 transition 才能真正“动起来”。
