必须用 :root 声明 css 变量，因其语义明确、优先级高且在 shadow dom 和框架组件中更可靠；变量需加前缀如 --theme-primary 避免冲突；所有颜色引用必须用 var()，包括伪元素、表单控件和 svg；动态换肤应使用 setproperty() 而非 csstext；深色模式需用 @media 直接重写 :root，且默认值必须预先声明。
必须用 :root 声明，不能写在 html 或 body 里
浏览器把 :root 当作 CSS 作用域的顶层，它语义明确、优先级略高，且在 Shadow DOM 和现代框架组件中更可靠。写成 html { --primary: #007bff; } 虽然多数情况能用，但一旦遇到 Web Components 或 Vue 的 <style scoped></style>，变量可能无法透传到子树里。
变量名必须以两个连字符开头，比如 --theme-primary，写成 --primary 合法，但加前缀能避免和第三方库（如 Ant Design 的 --ad-primary-color）冲突。
:root 中定义的值支持所有合法 CSS 值：十六进制、hsl()、calc() 表达式都行，但不能是属性名或选择器。命名色（如 blue）要避开——JS 读不到它的数值，后续做深色模式计算或动画过渡会卡住。
所有颜色属性都得用 var(--theme-primary) 替换，包括伪元素和状态样式
只改 :root 里的值没用，关键在“引用”。哪怕只漏一个 .btn:hover 里还写着 background-color: #2563eb;，换主题时这个悬停色就永远卡在旧值上。
-
::before和::after里的background、color、border-color都得显式加var() - 表单控件的
input:focus、select:disabled、textarea::placeholder容易被跳过 - SVG 图标用内联
fill或stroke时，必须手动写fill: var(--theme-primary); - Font Awesome 这类图标字体，需在对应 class 上补
color: var(--theme-primary);
切换主题时别直接改 cssText，用 setProperty() 逐个设值
JavaScript 动态换肤最常见错误是用 document.documentElement.style.cssText = '...' ——这会清空所有已有内联样式，包括其他 JS 注入的动态样式或框架管理的 class。
正确做法是：
- 用
document.documentElement.style.setProperty('--theme-primary', '#1e40af'); - 每个变量单独调用
setProperty()，不拼接字符串 - 为需要过渡的属性（如
background-color）在 CSS 中提前加transition: background-color 0.2s;，否则重绘会生硬 - 如果用 class 切换（如
html.dark），确保.dark :root规则权重足够，且放在默认:root定义之后
深色模式别嵌套媒体查询，用 @media (prefers-color-scheme: dark) 直接重写 :root
不能写成 :root { @media (prefers-color-scheme: dark) { --theme-bg: #111827; } } ——语法非法，浏览器直接忽略。
正确结构是：
:root {
--theme-primary: #2563eb;
--theme-bg: #ffffff;
--theme-text: #1e293b;
}
@media (prefers-color-scheme: dark) {
:root {
--theme-bg: #111827;
--theme-text: #f9fafb;
}
}
注意：所有基础变量必须在默认 :root 中声明初始值，否则页面首次加载时，未覆盖的变量会退回到继承值或 initial，造成大面积空白或错色。媒体查询只覆盖差异项，不是重写整套。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
