必须把所有变量声明在:root里，因为css变量依赖继承传播，:root是文档唯一根节点，确保var()在伪元素、svg、shadow dom等所有场景正确取值；写在其他位置会导致漏色、失效或静默错误。
为什么必须把所有变量声明在 :root 里
因为 CSS 变量靠继承传播，而 :root 等价于 html 元素，是整个文档树的唯一根节点。只有挂在这里，var(--bg-color) 才能在任意层级（包括 ::before、svg、contenteditable 区域）正确取值。
写在 .theme-dark 里：变量只在该 class 子树生效，JS 修改 document.documentElement.style 完全无效；写在组件级选择器如 .card：会覆盖根变量，但兄弟组件读不到，且无法被全局切换逻辑控制；没声明就 setProperty：浏览器找不到定义，var(--bg-color) 回退为 transparent 或继承值，整页瞬间“失色”。
[data-theme="dark"] 比 .dark 更可靠的原因
用属性选择器比 class 选择器更可控，核心是权重和作用域：
-
[data-theme="dark"]权重为 110，远高于普通 class（10），不易被业务样式意外覆盖 -
document.documentElement.dataset.theme = 'dark'操作明确，不与其他 class（如lang="zh"或第三方库注入的 class）冲突 -
.dark容易误加在body上，导致:root层变量未变，fixed 导航栏或弹窗背景色错位 - 服务端渲染时可直接在 HTML 模板中写死
，避免 FOUC
切换主题时页面闪动或颜色错乱的三个关键点
用户点按钮后白屏、跳色、部分区域不变——90% 是这三处漏了：
- 没加
transition：至少给background-color、color、border-color加transition: all 0.2s ease，写在body或顶层容器上 - 变量没定义回退值：比如
color: var(--color-text-primary, #333)，万一 JS 执行失败或变量名拼错，不至于全黑/全白 - localStorage 读取时机太晚：必须在
里内联脚本，读取localStorage.getItem('ui-theme')后立刻设dataset.theme，否则浏览器先按默认主题渲染一遍再重绘
transition 不能写在变量名上，只能作用于具体属性
transition: --bg-color 0.3s 是无效语法，浏览器直接忽略，连警告都不报。真正生效的方式是把变量用在支持过渡的属性上，再对那个属性加 transition：
✅ 正确：background-color: var(--bg-color); transition: background-color 0.3s ease;
❌ 错误：transition: --bg-color 0.3s;
仅对原生可插值属性加 transition：包括 color、background-color、opacity、transform、box-shadow 等。别指望 font-size 或 margin 自动过渡，除非你显式写了对应属性的 transition。
最容易被忽略的是表单控件、滚动条、SVG 填充色这些边界场景——它们不会自动响应 --bg-color，必须单独用变量接管并加 transition。还有，prefers-color-scheme 只能当兜底，不能替代手动切换逻辑，尤其在 WebView 或旧 Safari 中支持不稳定。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
