必须将 data-theme 放在 html 元素上，否则会导致伪元素失效、CSS 框架主题错乱、SSR 首屏闪屏；初始化需用 document.documentElement.dataset.theme = "dark"，清空用 delete；CSS 变量须全局定义并覆盖，按钮必须用原生 button + aria-pressed。
直接用 prefers-color-scheme 检测系统偏好，配合 data-theme 属性 + localStorage 存用户选择，就能做出不闪屏、无障碍、兼容 SSR 的黑白/暗黑模式——不需要框架，也不靠内联样式硬切。
为什么必须把 data-theme 放在 html 元素上
挂 body 或其他元素会出三类问题：CSS 伪元素（比如 input::-webkit-inner-spin-button）无法命中；Tailwind/Bootstrap 等库的主题注入错乱；服务端渲染时无法直出主题状态，首屏必闪白或闪黑。Safari 14–15 对嵌套媒体查询有 bug，但 html[data-theme="dark"] 稳定可靠。
初始化必须写成：document.documentElement.dataset.theme = "dark"
而不是 document.body.setAttribute("data-theme", "dark")。清空时用 delete document.documentElement.dataset.theme，别设成空字符串或 "light"——CSS 里 [data-theme=""] 不会匹配空属性。
如何避免页面加载时闪白/闪黑
闪屏本质是 CSS 渲染完才执行 JS 切主题。解决方案只有一个：在所有 CSS 加载前就设置好 data-theme。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
- 把初始化脚本写成内联
<script>，放在<head>最顶部、<link rel="stylesheet">之前 - 代码必须用
??处理localStorage返回的null，不能用||（空字符串会被转成false） - 示例：
const saved = localStorage.getItem('theme'); const systemPrefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches; document.documentElement.dataset.theme = saved ?? (systemPrefersDark ? 'dark' : 'light');
button 按钮怎么写才支持键盘和读屏器
别用 <div onclick=> 或 <input type="checkbox"> 套样式——可访问性全丢。必须用原生 <button>，并同步更新 aria-pressed。
- HTML 结构：
<button id="theme-toggle" aria-label="切换深色模式">?</button> - JS 里点击后立刻更新：
btn.setAttribute('aria-pressed', theme === 'dark') - 存值必须同步：
localStorage.setItem('theme', theme)，且theme必须是字符串"light"或"dark"，别用布尔或数字 - 不要等
DOMContentLoaded再绑定 click——按钮可能已渲染，而 JS 还没加载完
CSS 变量怎么定义才不漏样式
只改背景和文字色，按钮边框、输入框焦点、SVG 图标全乱套。所有颜色相关属性都得走变量，否则切换后视觉不一致。
- 基础变量写在
:root，暗黑覆盖写在html[data-theme="dark"]里，别写.dark .btn这种依赖 class 层级的规则 - 示例：
:root { --bg-color: #fff; --text-color: #000; } html[data-theme="dark"] { --bg-color: #121212; --text-color: #eaeaea; } body { background-color: var(--bg-color); color: var(--text-color); } - 别给
html[data-theme="dark"]加!important，靠选择器权重或变量覆盖更干净
最易被忽略的是：media 查询只响应系统设置，不响应手动切换；localStorage 存的值必须优先于系统偏好；data-theme 必须在 HTML 解析阶段就设好——晚一毫秒，闪屏就来了。
