所有主题变量必须定义在 :root 中，否则 JS 调用 setProperty 后组件不响应、颜色断层、刷新闪白；:root 是全局继承根，确保 var(--x) 在任意层级（含伪元素、SVG）正确取值。
必须把所有主题变量定义在 :root 里，否则 JS 调用 setProperty 后部分组件不响应、颜色断层、刷新闪白——这是最常被跳过的硬性前提。
为什么 :root 是唯一安全的声明位置
CSS 变量靠继承链传播，:root 等价于 html 元素，是整个文档树的根，只有挂在这里，var(--primary-color) 才能在任意层级（包括 ::before、SVG fill、伪类）正确取值。
- 写在
.theme-dark里：变量只在该 class 子树生效，JS 修改document.documentElement.style完全无效 - 写在组件级选择器如
.button：会覆盖根变量，但兄弟组件读不到，且无法被全局切换逻辑控制 - 用
html[data-theme="dark"]替代.dark类：CSS 权重更稳（110 vs 10），避免和业务 class 冲突，Safari 兼容更好
setProperty 修改变量的正确姿势
不能用 cssText 或直接赋值 style 字符串，否则会清空已有内联样式，导致其他自定义属性丢失。
- ✅ 正确：
document.documentElement.style.setProperty('--bg-color', '#121212') - ❌ 错误：
document.documentElement.style.cssText = '--bg-color: #121212' - 批量更新建议封装：
function setTheme(vars) { Object.entries(vars).forEach(([k, v]) => document.documentElement.style.setProperty(k, v)); } - 必须确保变量已在
:root中预先声明，否则var(--x)会 fallback 到inherit或transparent，页面瞬间“失色”
如何避免深色模式下对比度崩坏和抖动
直接替换十六进制值（如 #4a90e2 → #1e3a5f）会导致按钮悬停、禁用态、文字灰度全部脱节。HSL 拆解才是可控路径。
立即学习“前端免费学习笔记（深入）”；
- 把主色拆成
--primary-h、--primary-s、--primary-l三个变量，换肤时只调h，s和l保持协调性 - 用
calc()衍生状态色：color: hsl(var(--primary-h), var(--primary-s), calc(var(--primary-l) - 20%))（悬停变暗） - 所有尺寸/圆角/间距变量也得在初始 CSS 中定义，否则切换时 layout 抖动
-
transition不能写在变量名上（transition: --primary-color无效），要作用于具体属性：background-color: var(--bg-color); transition: background-color 0.3s ease;
用户手动切换 + 系统偏好 + 刷新持久化的闭环
仅靠 @media (prefers-color-scheme: dark) 无法满足真实场景：用户可能系统是亮色但点开了深色开关，或切完深色后刷新变回默认。
-
初始化必须前置：在
<head>里执行<script>document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light';</script>，防 FOUC - 用户点击切换时，既要改
dataset.theme，也要同步localStorage.setItem('ui-theme', 'dark')，否则刷新失效 - 监听系统变化：
matchMedia('(prefers-color-scheme: dark)').addEventListener('change', ...)，但仅作兜底，不替代用户主动选择 - 深色模式真正要动的不只是背景和文字——边框、阴影、SVG 图标、表单控件、代码块高亮都得有对应变量，漏一个就露馅
变量不是设完就自动联动的魔法，每个 var(--x) 都依赖上游声明、JS 修改时机、CSS 层叠顺序和属性可过渡性。最容易被忽略的是：没在 :root 里预定义所有主题变量，导致某些组件永远 fallback 到初始值；以及把 transition 错加在变量名上，以为能平滑动画。
