不能直接赋值 body.className 切换主题，因为会清空所有已有 class 导致 JS 行为异常、布局错乱；应使用 classList.toggle() 精准操作主题类，并确保 CSS 前缀与 DOM 操作目标（html 或 body）一致，同时全面覆盖变量和选择器。
为什么不能直接改 body.className 切换主题
直接赋值 body.className = 'dark' 会清空所有已有 class，比如 js-loaded、has-sidebar 或框架注入的 hydrated，导致 JS 行为异常、布局错乱或第三方组件失效。它不是状态切换，而是覆盖写入。
常见错误现象：document.body.className = 'theme-dark' 后，原本的 container grid-cols-12 消失，响应式栅格崩了；或者 Tailwind 的 dark:border-gray-700 规则因缺少 dark: 前缀触发条件而完全不生效。
正确做法是用 classList.toggle() 或 classList.add()/remove() 精准操作主题标识类：
-
document.body.classList.toggle('theme-dark')—— 自动识别当前状态，一行完成“有则去，无则加” - 若需兼容旧逻辑，先
document.body.classList.remove('theme-light', 'theme-blue')，再.add('theme-dark') - 务必确认你的 CSS 主题规则前缀一致：如果写的是
body.theme-dark .btn，就操作body；如果写的是html.theme-dark :root，就得操作document.documentElement
class 和 data-theme 混用时谁优先级更高
CSS 选择器权重决定最终效果，不是“谁后设谁赢”。[data-theme="dark"] 是属性选择器（权值 10），.theme-dark 是类选择器（权值 10），两者相等；但 html[data-theme="dark"] 权值是 20，高于 body.theme-dark（10）。
立即学习“前端免费学习笔记（深入）”；
容易踩的坑：
- 同时存在
body.theme-dark和html[data-theme="dark"]，且都定义了--bg-color，但后者作用域更广（影响::before、fixed元素、SVGfill），实际生效的是html[data-theme="dark"] :root下的变量值 - 用
classList加了theme-dark，但 CSS 里只写了[data-theme="dark"]规则，结果样式完全不响应——因为 class 和 data 属性是两套独立机制，不会自动映射 - 第三方库（如某些 UI 组件）可能监听
data-theme，但忽略 class，导致局部组件不随主题变化
主题类名必须挂载在 html 还是 body 上
取决于你是否用 CSS 变量，以及是否要覆盖所有渲染层。如果用了 :root 定义变量，且希望 position: fixed 导航栏、::selection、svg 填色、meta name="color-scheme" 同步更新，就必须把主题类名设在 document.documentElement（即 html 标签）上。
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
原因很实在：
-
:root等价于html，变量定义在此才真正全局；设在body上，html子元素中未继承的伪元素或 SVG 就拿不到新值 - 浏览器对
body有默认 margin、background 等 UA 样式，部分老版本 Safari 甚至会忽略body.dark对:root的影响 - 无障碍支持要求
color-schememeta 标签与 DOM 状态一致，而meta只能靠html层级的 class 或 data 属性驱动
示例：若你写 html.theme-dark :root { --text-color: #eee; }，就必须用 document.documentElement.classList.toggle('theme-dark')，而不是操作 body。
切换后部分组件颜色没变，class 控制到底有没有用
有，但前提是所有相关样式都显式依赖该 class。很多人以为加了 body.theme-dark，所有子元素就自动变暗——其实只是“规则存在”，真正起效还得看每条 CSS 是否被该 class 触发。
典型漏点：
- 组件内部硬编码了
color: #333，没写body.theme-dark .component { color: var(--text-color); } - 父容器设置了
color: inherit，但祖先链上某处写了color: black !important，把变量继承链掐断了 - 用到了
border-color、box-shadow、fill、stroke，却只在主题 class 里改了background和color - 伪元素如
.btn::after没加body.theme-dark前缀，导致 hover 动画颜色不变
验证方法：打开 DevTools，选中一个没变色的元素，在 Styles 面板里搜索 var(--，看是否命中变量；再检查 computed 值，确认 color / background 等是否来自预期规则。
复杂点在于：主题不是开关，而是整套样式契约。哪怕只漏掉一个 svg icon 的 fill，用户一眼就能感知“没切干净”。所以别指望 class 一加就全变，得逐层核对变量调用和选择器覆盖范围。
