直接修改 :root 中的 CSS 变量可一键切换主题色，但需确保所有颜色均使用 var(--x)、无 JS 硬编码、内联样式或第三方库绕过；变量未定义、作用域错误、大小写/拼写失误、漏写双短横线均会导致静默失效。
直接改 :root 里的变量值就能一键切换全站主题色，但前提是所有颜色使用处都已替换成 var(--x)，且没有 JS 硬编码、内联样式或第三方库绕过变量链——否则改了也白改。
为什么 var(--color) 改了没反应
不是语法错，大概率是变量根本没被定义，或作用域断了。浏览器不会报错，只会静默 fallback 到继承值或默认值（比如 color 变成 inherit，文字突然看不见）。
-
--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 失效，整页颜色崩掉
:root[data-theme="dark"] 比 :root.dark 更可靠
用属性选择器覆盖比 class 选择器更稳，尤其在复杂项目中。
-
[data-theme="dark"] :root权重固定为 110，远高于普通 class（10），不易被业务样式意外覆盖 - 避免命名冲突：业务代码里可能已有
.dark类用于其他用途，加 class 容易误触 - 多主题扩展友好：只需新增
[data-theme="sepia"] :root，不用改 JS 或新增 class 名 - Safari 旧版对嵌套
@media (prefers-color-scheme) .dark :root支持不稳定，但[data-theme]全系兼容
真正难的不是“怎么切”，而是“切之前有没有把所有颜色出口都收口到变量里”——漏掉一个 svg fill 或一个 button:focus outline，主题就看起来像坏了一角。别指望浏览器帮你找，得靠人工走查或自动化工具扫样式表。
