必须用:root声明，因其是css自定义属性唯一能保证全局继承的合法作用域；html兼容性差（如ie11不支持），body或class内声明则变量作用域受限，导致dialog、tooltip等脱离其流的元素回退失效。
必须在 :root 中声明所有基础色变量，且每个变量都要带语义化前缀和默认值，否则换肤必然断层或失效。
为什么只能用 :root，不能用 html 或 body
浏览器中 :root 等价于 html 元素但优先级更高，且是 CSS 自定义属性唯一能保证全局继承的合法作用域。写成 html { --color-primary: #007bff; } 在 IE11 里可能不生效；写在 body 或某个 class 下，则变量只对该选择器及其子元素有效，var(--color-primary) 在 header 或弹窗里会回退到继承值甚至透明——尤其在微前端或 Shadow DOM 场景下极易漏色。
常见错误现象：
-
body.theme-dark { --bg: #121212; }—— 切换后只有 body 内部元素变色，dialog、tooltip等脱离 body 流的元素仍为白底 -
.skin-blue { --primary: #1890ff; }—— 该类没加在根节点上，变量根本不会被继承
正确做法是统一收口：
:root {
--color-primary: #007bff;
--color-text: #333;
--color-bg: #fff;
--color-border: #e0e0e0;
}
--color-primary 这类命名该怎么定，才不容易冲突或混乱
变量名不是越短越好，也不是越具体越好。重点是“语义稳定 + 范围可控”。比如 --primary 太模糊，--theme-blue-500 又绑死了色值，都不利于后期维护。
推荐结构：--{domain}-{role}-{state?}，例如：
-
--color-primary（主品牌色，非具体蓝） -
--color-text-primary（正文主文字） -
--color-bg-surface（卡片/面板背景） -
--color-border-divider（分隔线边框）
避免这些坑：
- 混用
--primary-color和--color-primary—— 大小写+顺序不一致，JS 和 CSS 里稍一拼错就静默失效 - 用数字后缀如
--color-1—— 完全丢失语义，半年后没人记得它对应按钮还是警告框 - 在变量值里带单位缩写，如
--spacing-xs: 4px;—— 后期想切 rem 或 em 就得全局改值，不如统一用--space-xxs这种无单位抽象名
深色模式覆盖时，为什么 @media (prefers-color-scheme: dark) 不够用
系统偏好只是兜底，用户手动切换皮肤才是真实需求。只靠媒体查询，一旦用户点了“深色开关”，刷新页面又回浅色，体验断裂。
真正要做的，是让三套逻辑共存且有明确优先级：
- 最高：用户显式选择（存在
localStorage，并应用html.skin-dark类） - 其次：系统暗色偏好（
@media (prefers-color-scheme: dark)） - 最低：
:root默认浅色值
关键点在于选择器权重：必须让 html.skin-dark 的规则写在媒体查询之后，且不依赖 !important。例如：
:root {
--color-bg: #fff;
}
<p>@media (prefers-color-scheme: dark) {
:root {
--color-bg: #121212;
}
}</p><p>html.skin-dark {
--color-bg: #0d1117; /<em> 手动选的深色，比媒体查询权重高 </em>/
}</p>
如果把 html.skin-dark 规则写在 @media 前面，或者写成 .skin-dark :root（错误！:root 永远是顶层），就会被覆盖或失效。
JS 动态切换皮肤时，document.documentElement.style.setProperty 为什么容易出问题
直接调用 setProperty 看似简单，但实际项目里几乎不可维护：
- 换一套皮肤要设 20+ 个变量，漏一个就破色
- 无法回滚 —— 没有快照机制，切错主题只能刷新
- Safari 旧版本（iOS 15.4 前）在批量 setProperty 时可能丢缓存，导致闪屏
- 变量名拼错（比如
--color-bg写成--bg-color）浏览器完全不报错，只当未定义
更稳的做法是预设好 class，JS 只管切换：
function switchSkin(name) {
document.documentElement.className = `skin-${name}`;
localStorage.setItem('preferred-skin', name);
}
<p>// 页面加载时还原
const saved = localStorage.getItem('preferred-skin') || 'light';
document.documentElement.className = <code>skin-${saved}</code>;
</p>
对应的 CSS 就是：
:root {
--color-bg: #fff;
}
<p>html.skin-dark {
--color-bg: #121212;
--color-text: #e0e0e0;
}</p><p>html.skin-blue {
--color-bg: #f0f9ff;
--color-primary: #0dcaf5;
}</p>
这种写法把变量值的管理交给 CSS，JS 只负责状态同步，调试时一眼能看出当前激活哪套规则，也方便后续加动画或服务端渲染支持。
最后提醒一句：所有消费变量的地方，比如 color: var(--color-text);，务必确保 fallback 写到位 —— color: var(--color-text, #333);。否则某套皮肤 CSS 加载失败或变量名拼错时，文字直接消失，连 QA 都测不出来。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
