CSS变量必须声明在:root，因其是唯一被浏览器认可、覆盖整个文档树的全局作用域锚点，确保所有后代元素（含伪元素、SVG、Shadow DOM）可继承，且主题切换时能动态响应；相对颜色语法如color-mix()、oklch()依赖这些已定义在:root的变量值进行计算，否则无法生效或退化失效。
CSS变量必须声明在:root，相对颜色语法（如color-mix()、oklch()、relative color syntax）只能基于已定义的变量计算，否则无法动态响应主题切换。
为什么:root是唯一安全的声明位置
所有主题变量必须挂载在:root上，写在.dark、body或组件类里会导致子元素取不到值——CSS变量作用域由选择器决定，而主题需要全局覆盖。例如：
:root { --bg: #fff; --text: #1f2937; }
[data-theme="dark"] :root { --bg: #111827; --text: #f9fafb; }如果误写成.dark { --bg: #111827; }，那么button里color: var(--text)仍会取:root默认值，因为.dark不是祖先链上的有效作用域。
- 浏览器首次渲染时只读
:root，不会“预判”后续class切换 -
data-theme属性选择器必须配合:root使用，不能单独作用于body或html - SSR/服务端渲染场景下，
:root是唯一能被服务端注入并保证首屏一致的位置
color-mix()和oklch()依赖变量值，不能硬编码
相对颜色函数本身不存储状态，它每次计算都依赖当前var()解析出的实际值。所以必须确保基础色变量已定义在:root，且主题切换后这些变量已更新：
立即学习“前端免费学习笔记（深入）”；
/* 正确：基于变量动态计算 */
:root {
--primary: oklch(65% 0.25 270);
}
.button {
background-color: color-mix(in oklch, var(--primary), white 20%);
color: oklch(from var(--primary) l c h / 0.9);
}如果把oklch(65% 0.25 270)直接写死在color-mix()里，就失去主题可替换性；如果--primary未在:root定义，color-mix()会退回到white或无效值。
-
color-mix()不支持回退值，var(--primary, #007bff)必须显式提供，否则整个表达式失效 -
oklch()中from var(--x)语法要求--x必须是完整颜色值（含空间信息），不能是十六进制或rgb() - 旧版Chrome不支持
oklch()中的from语法，需用@supports降级
JS切换时，setProperty()比setAttribute()更可控但有陷阱
用document.documentElement.style.setProperty('--primary', 'oklch(40% 0.3 300)')可立即生效，但要注意：
- 必须在
DOMContentLoaded之后执行，否则document.documentElement可能未就绪 - 不要批量调用
setProperty()重置所有变量——只改真正变化的，避免覆盖用户自定义主题色 - 若同时用
data-theme+ CSS规则覆盖，style内联样式优先级高于CSS，会导致[data-theme="dark"] :root被忽略 - 切换前可用
getComputedStyle(document.documentElement).getPropertyValue('--primary')读默认值，便于还原
回退值不是可选，而是主题系统存活的关键
每个var()调用都必须带回退值，否则变量未定义时会触发浏览器默认行为（如color变透明、background-color变白色），造成视觉断裂：
.card {
background-color: var(--surface-bg, #f9fafb);
color: var(--text-primary, #1f2937);
border-color: var(--border-muted, #e5e7eb);
}尤其在主题加载异步、SSR与CSR不一致、或用户禁用JS时，回退值是唯一能兜底的防线。
最易被忽略的是SVG图标：fill: var(--icon-primary)若没回退，图标可能直接消失；还有box-shadow: 0 1px 3px var(--shadow-sm)，缺失回退会让阴影彻底失效。
