必须用 html[data-theme="dark"] 是因为 :root 变量需由高权重、作用域覆盖全局的选择器直接定义，.theme-dark 作为普通类选择器无法作用于 :root，导致变量不生效；html[data-theme="dark"] 合法、语义清晰、无冲突且支持服务端渲染。
直接用 :root 定义变量 + data-theme 属性切换 + localStorage 持久化，是最稳、最易维护的方案；别用 .theme-dark class 塞进 :root 里，那根本不会生效。
为什么必须用 html[data-theme="dark"] 而不是 .theme-dark
核心是作用域和隔离性：:root 是文档根，但它的变量值会被更具体的选择器覆盖。如果只写 .theme-dark { --bg: #111; }，这个规则挂载在普通元素上，var(--bg) 在子元素里取不到——因为没挂到 :root 上。
-
html[data-theme="dark"]是合法且高权重的选择器，能直接覆盖:root中同名变量 - 第三方库或组件常操作
body.className，用data-theme可完全避开冲突 -
data-属性语义清晰，服务端渲染时可直接写死，首屏不闪 - 错误写法示例：
:root .theme-dark { --bg: #111; }—— 这是两个独立选择器，不是嵌套，变量不生效
localStorage 读取时机不对会导致白屏或闪一下
浏览器先按默认主题渲染一次，JS 再改 data-theme，中间就有视觉断层。必须在 DOM 构建前就设好。
- 把初始化脚本放在
<head>里，用内联<script>执行 - 顺序必须是：读
localStorage.getItem('theme')→ 立即设document.documentElement.setAttribute('data-theme', value)→ 再设<meta name="color-scheme"> - 别等
DOMContentLoaded，那时重绘已发生；也别放</body>底部，太晚 - 加回退值防变量未定义：
color: var(--color-text-primary, #333)
哪些 CSS 属性适合用变量控制，哪些会卡顿
变量本身不触发重排，但用它驱动的属性会。关键看是否影响布局流。
立即学习“前端免费学习笔记（深入）”；
- ✅ 安全（仅重绘）：
color、background-color、border-color、box-shadow - ❌ 危险（可能重排）：
width、height、padding、margin、font-size（除非你明确要响应式缩放） - 过渡必须提前写死：
body { transition: background-color 0.2s ease, color 0.2s ease; }，不能靠 JS 动态加 - 别在媒体查询里嵌套变量声明：
@media (prefers-color-scheme: dark) { :root { --bg: #111; } }是非法语法，浏览器直接忽略
真正容易被忽略的是 <meta name="color-scheme"> —— 页面主题变了，但 Chrome 地址栏、Safari 表单控件还是亮色，用户会觉得“没切成功”。每次 JS 切主题，这行 meta 必须同步更新，且初始加载时就得设对。
