暗黑模式class切换必须作用在<html>标签上，因prefers-color-scheme和CSS变量继承均依赖根元素状态；若仅加在<body>或wrapper中，:root规则不响应，主题色失效。
暗黑模式的 class 切换必须作用在 <html> 标签上
浏览器的 prefers-color-scheme 媒体查询和 CSS 变量继承都依赖根元素状态，如果只给 <body> 加 dark 类，CSS 中的 :root 规则不会响应变化，导致主题色、背景色等失效。实际开发中常见错误是把 class 加在 body 或某个 wrapper div 上，结果切换后样式毫无反应。
正确做法是直接操作 document.documentElement：
document.documentElement.classList.toggle('dark');
同时确保你的 CSS 顶层变量定义写在 :root 下，暗黑模式覆盖写在 .dark :root 或 .dark 选择器下（后者更稳妥，避免嵌套层级干扰）。
prefers-color-scheme 检测要配合手动切换逻辑
仅靠媒体查询只能读取系统偏好，无法支持用户主动点按钮切回亮色——这是最常被忽略的设计断点。系统设为暗色时，matchMedia('(prefers-color-scheme: dark)') 返回 true，但用户点了“切到亮色”后，你得覆盖掉这个默认行为。
立即学习“前端免费学习笔记（深入）”；
推荐做法是：用 localStorage 记录用户最后一次手动选择，优先级高于系统设置：
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
- 首次加载时，先读
localStorage.getItem('theme') - 为空则 fallback 到
matchMedia结果 - 点击切换按钮时，同时写入 localStorage 并更新
document.documentElement的 class
这样既尊重初始系统偏好，又允许用户覆盖。
CSS 变量应集中定义在 :root，避免重复声明
很多人在每个组件里单独写 .dark .button { background: #333 }，结果维护成本飙升。正确结构是统一用 CSS 自定义属性控制颜色体系：
:root {
--bg: #fff;
--text: #333;
--border: #ddd;
}
.dark :root {
--bg: #1a1a1a;
--text: #e0e0e0;
--border: #333;
}
body {
background-color: var(--bg);
color: var(--text);
border-color: var(--border);
}
注意：.dark :root 写法比 .dark 更安全，它确保变量在所有后代元素中都能被继承；若用 .dark { --bg: #1a1a1a }，某些深层嵌套组件可能因层叠顺序或 shadow DOM 隔离而读不到。
切换按钮需处理 aria-pressed 和系统色感依赖
纯视觉图标（比如 ☀️/?）对屏幕阅读器不友好，且在高对比度模式下可能不可见。必须补充语义化状态：
- 按钮
role="switch"或role="button" - 动态设置
aria-pressed="true/false" - 用
sr-only类包裹“切换至暗色模式”文字（不可见但可读）
另外，不要用 color-scheme: dark 声明强制系统控件变暗——它只影响表单元素默认样式，且 Safari 支持不稳定，容易导致 checkbox/radio 在暗色下反白失焦。老实用 CSS 覆盖更可控。
