必须将主题变量声明在 :root 中，因其是文档唯一根节点，确保所有元素（含伪元素、svg、表单控件等）稳定继承；使用 data-theme 切换更可靠，需同步更新 dataset、localstorage 和 css 加载，并为每个 var() 提供合法回退值。
必须把所有主题变量声明在 :root 里，否则切换必然失效——这不是优化建议，是 CSS 继承机制的硬性限制。
为什么只能用 :root 声明主题变量
CSS 变量靠继承传播，而 :root 等价于 元素，是整个文档树的唯一根节点。只有挂在这里，var(--bg-color) 才能在任意层级（包括 ::before、<svg></svg>、contenteditable 区域）稳定取值。
常见错误现象：
-
.theme-dark { --bg-color: #121212; }→ 只在该 class 子树生效，<input>或兄弟节点读不到，直接 fallback 到透明或浏览器默认值 -
body { --text-color: #eee; }→上求值时根本找不到定义，变量未声明 - 写在 Vue/React 组件的
<style scoped></style>里 → Shadow DOM 或子组件无法继承，主题断色
如何用 data-theme 切换多套主题（推荐）
比 class 切换更可靠：权重固定为 110，避开命名冲突，支持 data-theme="amber" 这类扩展，且 SSR 友好。
实操要点：
- CSS 中写成
[data-theme="dark"] :root { --bg-color: #1e1e1e; --text-color: #eee; }，注意是:root被覆盖，不是直接改html[data-theme] - JS 切换时必须同步三件事：
document.documentElement.dataset.theme = 'dark'、localStorage.setItem('ui-theme', 'dark')、确保对应 CSS 规则已加载（不能漏） - 初始化必须在
内联脚本中执行：<script>document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light';</script>，否则首屏必闪
动态替换 <link> 主题文件（轻量兼容方案）
适合主题差异大、变量数量多、或需彻底隔离样式逻辑的场景，浏览器原生支持，无 JS 计算负担。
关键约束：
- 所有主题 CSS 文件都必须平铺定义同一套
:root变量（如--bg-base、--text-emphasis），结构不一致会导致运行时 fallback -
中只保留一个带id="theme-link"的<link>，其他主题文件不预加载 - 切换时用
linkEl.href = '/css/theme-dark.css'，别用setAttribute('href', ...)，避免重复加载 - 主题文件内禁用
@media (prefers-color-scheme: dark)，让 JS 完全掌控时机
容易被忽略的“变量生效”细节
主题变量本身不自动渲染，真正起作用的是每一处样式声明是否显式用了 var()。
高频遗漏点：
-
<input>、<textarea></textarea>的::placeholder必须单独写color: var(--text-placeholder); -
contenteditable元素不自动继承color和background，需显式设置color: var(--text-primary); background-color: var(--bg-editor); caret-color: var(--text-primary); - SVG 的
fill、stroke是内联属性，不走继承，必须写成fill: var(--icon-primary); - 按钮的
:hover、:focus、:disabled状态也得用变量，否则悬停色永远不变 - 每个
var()都要带合法回退值：color: var(--text-primary, #333);，unset或initial不是颜色值，不能当 fallback
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
