必须写在 :root 里，因为其优先级高于 html 且语义准确，适配 XHTML/SVG 等环境；定义在 html、body 或组件中会导致作用域受限或变量不可访问，:root 是全局变量唯一可靠位置。
为什么必须写在 :root 里，而不是 html？
因为 :root 的优先级高于 html，且语义上更准确——它匹配的是“文档根元素”，不依赖于标签名。哪怕你用 XHTML 或 SVG 当主文档，:root 依然生效；而直接写 html 选择器，在非 HTML 环境下就失效了。
常见错误现象：
– 在 html 里定义 --primary-color，又在 :root 里重定义，结果后者覆盖前者，但开发者误以为没生效
– 把变量写在 body 或某个组件选择器里，导致 var(--xxx) 在其他地方报错或回退为初始值
-
:root是唯一能保证全局可访问、且被所有现代浏览器（Chrome 49+、Firefox 31+、Safari 9.1+）稳定支持的位置 - 不要嵌套：不能把
:root写在媒体查询内部再定义变量（那样只是局部作用域），如需响应式变量，请在@media里重新给:root赋值 - 变量名必须以
--开头，中间只允许字母、数字、-、_，比如--font-size-base合法，--12px或--bg color非法
var() 引用时最常见的失败原因
不是语法写错，而是变量根本没定义，或者定义位置不对。浏览器遇到未声明的 var(--xxx) 会直接忽略该属性值（或回退到 inherit / initial），不会报错，所以很难察觉。
使用场景举例：
– 想让按钮文字颜色随主题变，但 .btn { color: var(--text-color); } 始终是黑色 → 检查 :root 是否真有 --text-color
– 多个文件拆分 CSS，theme.css 里定义变量，base.css 里引用 → 确保 theme.css 在 base.css 之前加载
立即学习“前端免费学习笔记（深入）”；
- 变量可以链式引用，比如
--link-color: var(--primary-color);，但不能循环引用（--a: var(--b); --b: var(--a);） -
var()不支持运算符，如var(--spacing) * 2是非法的；要计算请用calc(var(--spacing) * 2) - 如果变量值本身含空格（如字体族
'Inter', sans-serif），直接赋值即可，不需要额外引号包裹
暗色模式切换时，:root 变量怎么动态更新？
核心原则：别删改 CSS 文件，而是通过 JS 修改 :root 上的自定义属性，或切换预设类名触发动态重算。
性能影响很小——修改 document.documentElement.style.setProperty('--bg-color', '#1a1a1a') 是同步、低开销操作，比切换整个 CSS 文件快得多。
- 推荐做法：预先在 CSS 中写好两套变量，用类名控制，例如
[data-theme="dark"] :root { --bg-color: #1a1a1a; }，JS 只需document.documentElement.setAttribute('data-theme', 'dark') - 避免做法：在 JS 中遍历所有变量逐个
setProperty，容易漏、难维护；也不要用innerHTML替换整个style标签，破坏样式隔离 - 兼容性注意：IE 完全不支持 CSS 变量，如有需要，得用 PostCSS 插件降级，或干脆放弃 IE
变量命名和组织容易被忽略的细节
变量不是越多越好，命名混乱反而增加维护成本。真正关键的是层级清晰、意图明确，而不是追求“全部抽成变量”。
比如有人把每个按钮的 padding 都做成独立变量：--btn-primary-padding-y、--btn-secondary-padding-y……这反而让系统更难统一调整。
- 建议按语义分组：颜色用
--color-*，间距用--space-*，字体用--font-*，避免混用前缀（如--main-bg和--bg-main并存） - 基础值优先：定义
--space-xs: 4px、--space-sm: 8px，再组合出--space-md: calc(var(--space-sm) * 2)，而不是直接写死所有尺寸 - 别用中文或拼音命名变量，虽然技术上支持，但协作、搜索、工具链（如 VS Code 自动补全）都会出问题
最常被跳过的一步：没给变量加注释说明用途和取值范围。比如 --border-radius 是指圆角基数，还是最大圆角？是否所有组件都应严格遵守？这些隐含约定，光靠变量名说不清。
