必须把所有设计变量声明在:root里，因为它是CSS规范唯一指定的全局锚点，特异性更高且强制继承；body或html声明的变量无法被input、button、伪元素或Shadow DOM读取，且在SSR、微前端或iframe中继承链易断裂。
必须把所有设计变量声明在 :root 里，否则变量无法穿透到 <input>、<button>、伪元素或 Shadow DOM 内部——这不是风格偏好，是 CSS 自定义属性的作用域硬约束。
为什么不能用 html 或 body 替代 :root
:root 是 CSS 规范唯一指定的全局锚点，特异性为 (0,1,0)，高于 html 的 (0,0,1)；更重要的是它强制继承，而 body { --color: red; } 声明的变量，<input> 根本读不到——表单控件不自动继承 body 的自定义属性。html 虽然能工作，但在 SSR 渲染或某些 polyfill 场景下继承链可能断裂，尤其当页面被嵌入微前端或 iframe 时更不稳定。
:root 中该放什么、不该放什么
适合放语义化、静态、跨主题复用的设计 token：
-
--color-primary、--space-md、--radius-sm—— 名称带前缀，避免裸色值如--red -
--font-size-base、--line-height-base—— 字体基准值，配合rem构建弹性系统 -
--shadow-sm、--border-color—— 所有主题下都会用到的通用样式值
不该放：
立即学习“前端免费学习笔记（深入）”；
- 组件级样式（如
--button-padding），应由组件自身控制 - 需 JS 实时响应的值（如
calc(100vw - var(--sidebar-width))），CSS 变量不监听 resize - 裸运算表达式（如
--size: 1rem * 2），CSS 不支持，得写成--size: 2rem或用calc(var(--unit) * 2)
:root[data-theme="dark"] 覆盖失败的三个常见原因
主题切换不是“写了就生效”，必须同时满足：
- 所有变量必须在默认
:root块中完整声明——哪怕深色模式下值相同，漏一个，渲染即 fallback 到浏览器默认值（比如margin变成0） - 变量名大小写敏感：
--Text-Primary和--text-primary是两个变量 - JS 切换必须用
document.documentElement.setAttribute('data-theme', 'dark')，不能用className = 'dark'——后者会清掉其他 class（如 SSR 标记或 A/B 测试 class）
另外，@media (prefers-color-scheme: dark) 单独使用不可靠：首次渲染可能取错值，且与用户手动切换冲突。
var() 静默失效却无报错，怎么排查
浏览器不会提示错误，只会 fallback 到属性默认值（color 变成 inherit，background 变成 transparent），排查重点在：
- 拼写或大小写不一致：声明了
--spacing-xs，却写了var(--spacing-s) - 声明顺序错：CSS 文件里
.card { color: var(--text); }出现在:root块之前 → 渲染时变量尚未定义 - 值非法：比如
--font-size: 16缺单位，或--size: calc(1rem * 2)写成--size: 1rem * 2 - 最易忽略的一点：
var(--x, #fff)的 fallback 必须写实。不写 fallback，一旦变量未定义，样式就崩，控制台毫无提示
真正稳定的做法，是把所有变量声明收口到单一 :root 块，命名统一、覆盖完整、fallback 显式，再通过 data-theme 层叠切换——别指望运行时补漏或靠 JS 动态 setProperty 拼凑。
