data-theme优于class="dark"因其权重更高、语义更明确、避免样式冲突，且支持DevTools调试；必须在html[data-theme]中完整重定义所有变量，同步localStorage，并确保SVG及第三方组件接入变量体系。
为什么用 data-theme 而不是 class="dark"
直接操作 document.documentElement.className 看似简单，但会和 CSS 选择器权重、继承链、第三方组件样式产生隐性冲突。比如：:root.dark { --bg: #111; } 在某些嵌套较深的组件里可能被 .card .header 的 specificity 覆盖，导致变量未生效；而 html[data-theme="dark"] 是属性选择器，天然比多数类名权重高，且语义明确——它声明的是“当前主题类型”，不是“这个页面看起来像暗色”。更重要的是，dataset.theme 可被 DevTools 的 Styles 面板直接识别为状态标记，调试时一眼可见当前激活的主题上下文。
html[data-theme] 规则必须完整覆盖所有变量
常见错误是只在 :root 定义默认值，再在 :root.dark 里只改几个颜色，结果切换后按钮变黑了，但边框、阴影、SVG fill 还是亮色——因为那些属性没被新变量接管。正确做法是：每个 html[data-theme="xxx"] 块内，必须重新声明整套基础变量（通常 5–8 个），包括 --color-primary、--color-bg、--color-text、--color-border、--shadow-sm 等。不要依赖“继承旧值”，CSS 变量不支持 partial override。
- 错误写法：
:root { --color-bg: #fff; --color-text: #333; } html[data-theme="dark"] { --color-bg: #121212; }（--color-text仍为 #333） - 正确写法：
html[data-theme="dark"] { --color-bg: #121212; --color-text: #eee; --color-primary: #bb8f00; --color-border: #333; --shadow-sm: 0 1px 3px rgba(0,0,0,0.2); }
JS 切换时必须同步 localStorage 并提前注入
用户点一次按钮就闪一下白屏，大概率是 JS 改完 dataset.theme 后，浏览器才开始解析新 CSS 规则，中间存在渲染空档。解决方法不是加 transition，而是让主题类在 HTML 解析阶段就存在：
- 页面加载初期（如
<head>内或DOMContentLoaded第一帧），先读localStorage.getItem('theme')，若有值，立即执行document.documentElement.setAttribute('data-theme', value) - 切换时只调用一次
setAttribute，不要先removeAttribute再setAttribute，避免短暂回退到无主题状态 - 存值用字符串（
"light"或"dark"），不是对象或 JSON —— 后者徒增序列化开销，且和 CSS 规则不直接对应 - Safari 对
dataset.theme大小写敏感，务必用小写theme，别写成Theme或THEME
第三方组件和 SVG 的变量穿透问题
很多 UI 库（如 Ant Design、Element Plus）或图标库（如 Heroicons）默认用硬编码色值，不会响应你的 --color-text。这不是你 CSS 写错了，而是它们没接入变量体系。解决方案分三层：
立即学习“前端免费学习笔记（深入）”；
- 对纯 CSS 组件：用更高权重选择器强制接管，例如
html[data-theme="dark"] .ant-btn { color: var(--color-primary); border-color: var(--color-border); } - 对内联 SVG：
svg path { fill: var(--color-icon, currentColor); }，并在根级补上--color-icon变量 - 对 React/Vue 组件库：优先查文档是否支持
cssVars配置项（如 Mantine 的theme.colorScheme），而非自己 patch 样式
最易被忽略的是：变量 fallback 值必须写全。比如 color: var(--color-text); 在未定义主题时会退成 inherit，可能意外继承父级灰色；应写成 color: var(--color-text, #333);，确保兜底可用。
