必须将语义化颜色变量定义在 :root 中，因为只有 :root 作用域才能全局访问，确保改一处、全站同步；其他方式如组件内声明、预处理器生成或多套 CSS 均无法真正实现统一换肤与维护。
直接在 :root 里定义语义化颜色变量，并确保所有样式都通过 var() 引用——这是唯一能真正实现“改一处、全站同步”的方式。其他做法，比如在组件里局部声明变量、靠预处理器生成多套 CSS、或 JS 硬编码颜色值，都会在换肤、维护或协作时暴露裂痕。
为什么必须把变量写在 :root 而不是某个 class 或组件里？
变量作用域决定它能不能被全局访问。:root 是文档根节点，等价于 html 元素但语义更明确、优先级更高，浏览器从 IE11 起就稳定支持。一旦你把 --color-primary 写进 .theme-dark 或 .button 里，那它只在该选择器作用域内生效，.header 或 .card 根本读不到——所谓“统一”就成空话。
常见错误包括：
- 在 Vue 的
<style scoped>或 Shadow DOM 里声明--primary，结果父容器样式无法继承 - 用
!important覆盖变量，破坏级联逻辑，后续 JS 动态修改会失效 - 默认主题没定义变量，只在
.dark类里写--color-bg: #121212，页面一加载就是白底黑字乱套
var() 必须带 fallback，否则文字可能直接消失
CSS 变量不报错也不警告——如果 --color-text 根本没定义，Chrome 会回退到 inherit，Firefox 可能渲染为透明，用户看到的是空白段落。这不是 bug，是规范行为。
立即学习“前端免费学习笔记（深入）”；
正确写法是：color: var(--color-text, #333);，其中 #333 是兜底色。尤其在微前端场景下，子应用可能没加载主题 CSS，父容器又没设默认值，fallback 就是最后一道防线。
注意：
- fallback 只接受单个值，不能写
var(--color-text, #333, #000) - 不要依赖浏览器自动降级（比如先写
color: #333; color: var(--color-text);），某些旧版 Safari 在 SSR 渲染后会丢掉变量缓存，导致闪屏 - ESLint 插件
stylelint-custom-property-no-outside-root可检查变量是否误写在非:root区域
深色模式切换别新建一套变量名，只重设同一变量
别搞 --color-primary-dark 这种命名。它会让 JS 主题切换逻辑爆炸式增长，也违背“单一数据源”原则。正确做法是在媒体查询或 class 中覆盖原变量：
:root {
--color-primary: hsl(210, 70%, 55%);
--color-bg: #fff;
}
@media (prefers-color-scheme: dark) {
:root {
--color-primary: hsl(210, 70%, 40%);
--color-bg: #121212;
}
}
/* 或手动切换 */
html.theme-dark {
--color-primary: hsl(210, 70%, 40%);
}这样 JS 只需切 class 或 media 查询状态，所有组件自动响应。关键点在于：变量名完全一致，CSS 层级自然接管，无需额外 JS 干预。
JS 动态换肤要批量注入，别逐个 setProperty
用 document.documentElement.style.setProperty('--color-primary', '#ff6b35') 看似简单，但遇到“蓝调/墨绿/暖灰”三套皮肤时，极易漏掉 --color-border 或 --color-icon 等次要变量，导致部分区域颜色错乱。
更可靠的做法是把整套主题存成对象，一次性注入：
const themes = {
light: {
'--color-primary': '#007bff',
'--color-bg': '#fff',
'--color-text': '#333'
},
dark: {
'--color-primary': '#6a9cff',
'--color-bg': '#121212',
'--color-text': '#e0e0e0'
}
};
function applyTheme(name) {
Object.entries(themes[name]).forEach(([k, v]) =>
document.documentElement.style.setProperty(k, v)
);
}容易被忽略的细节：
- 变量名大小写必须完全一致（
--Color-Primary和--color-primary是两个变量） - 旧版 Safari（iOS 15.4 之前）在 JS 修改变量后可能触发一次重排闪屏，建议加
transition: background-color .2s, color .2s缓解 - HSL 比 HEX 更适合动态调整（比如 hover 用
hsl(210, 70%, 45%)），但 CSS 不支持运行时颜色运算，hsl(var(--h), var(--s), calc(var(--l) - 10%))是无效写法
真正卡住人的从来不是怎么定义变量，而是组件里有没有彻底剔除硬编码颜色、SVG 的 fill 是否用了 var()、第三方库是否允许透传 CSS 变量——这些地方不扫干净，“统一配色”就只是幻觉。
