data-theme 必须设在 document.documentelement 上，否则 fixed 元素、伪元素等因继承链断点导致样式不一致；css 变量需显式使用且成对调整，主题切换应以 data-theme 为唯一状态源，手动切换后需禁用系统偏好自动响应。
data-theme 必须设在 document.documentElement 上
很多人把 data-theme 加到 或某个容器上，结果 fixed 导航栏、伪元素（比如 ::before）、position: fixed 的弹窗背景色不一致——因为 CSS 变量定义在 :root，而 :root 对应的就是 元素。只有改 document.documentElement，才能让所有层级的 var(--xxx) 统一响应。
常见错误写法：document.body.setAttribute('data-theme', 'dark')，看似生效，但 标签上没这个属性，[data-theme="dark"] 选择器根本不会匹配。
正确写法：
document.documentElement.setAttribute('data-theme', 'dark');
初始化时也要写在 HTML 源码里：（服务端渲染或首屏直出更稳）。
CSS 变量必须显式调用，不能只定义不使用
CSS 自定义属性本身只是“存值”，不是“开关”。写了 --bg: #fff 却没在任何样式规则里写 background-color: var(--bg)，等于白定义。尤其容易漏掉这些地方：
border-color: var(--border-color)box-shadow: 0 1px 3px var(--shadow-color)svg fill: var(--icon-fill)opacity: var(--disabled-opacity)
深色模式下，--text-color 和 --background-color 往往要成对调整，否则出现白字配白底；动画过渡要加在使用 var() 的属性上，比如：transition: background-color 0.2s, color 0.2s。
使用 Puppeteer + Chrome 将 HTML 渲染为中文 PDF，自动处理图表等待、Tab 展开、动画、测高、白边消除、防分页，适用于看板、报表、网页和交互图表转 PDF。
主题切换后 fixed 元素颜色错乱？检查继承链断点
你在 .card 里写了 color: var(--text-color)，但它的父容器设置了 color: black，变量值就被覆盖了——这不是变量失效，是 CSS 层叠优先级问题。
安全做法是：
- 所有颜色相关样式都从
:root或body开始声明，避免中间层重置 - 切换时用
document.documentElement.style.setProperty('--bg-color', '#121212')，不是document.body.style.setProperty - 如果主题差异大（比如字体、行高也变），纯变量不如类名切换直观——类名能一并控制
font-family、line-height等非颜色属性
用户手动切换后系统偏好变化失效？data-theme 是唯一可信状态源
prefers-color-scheme: dark 是只读媒体查询，无法被 JS 触发重计算。如果仅靠它做主题，用户点按钮切了暗黑模式，再切回浅色，系统设置没变，页面就卡死在暗黑状态。
正确做法是：
- 加载时读
localStorage.getItem('theme')，有则直接设data-theme - 没有则查
window.matchMedia('(prefers-color-scheme: dark)').matches，设初始值并存入localStorage - 监听系统变化：
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', ...)，但仅当用户未手动切换过时才响应（可用一个布尔标志位记录是否手动干预过）
复杂点在于：手动切换和系统偏好必须共存，且不能互相覆盖；最容易被忽略的是「手动切换后禁用系统监听响应」这个逻辑，漏掉就会导致用户点了亮色按钮，5秒后又自动跳回暗色。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
