必须将data-theme设在html元素上，因其确保CSS变量全局生效、伪元素精准命中、第三方库主题注入正确，并支持SSR直出避免闪屏；挂body会导致样式错乱与兼容问题。
直接用 data-theme 控制主题，而不是靠模板引擎动态渲染整套 HTML —— 后者成本高、易闪屏、难维护，且无法响应系统偏好或 localStorage 变更。
为什么不能把主题逻辑塞进模板里
模板引擎（如 Handlebars、Jinja2）在服务端或首次渲染时就把 HTML 固化了，一旦页面加载完成，再想“热切换”就得全量重渲染或手动 patch DOM，极易漏掉 ::before、::after、svg 填色、fixed 定位元素等——它们不参与模板的 DOM 重建，但恰恰最需要主题一致性。
- 服务端渲染时写死
<html data-theme="dark">是可行的，但仅限首屏；后续用户点击切换必须靠 JS 驱动，而非再次走模板流程 - React/Vue 等框架中若用
className或class绑定主题（如className={theme === 'dark' ? 'dark' : ''}），会和 Tailwind 的dark:前缀、BEM 的命名空间、第三方组件库的 class 冲突 - 模板里插值
{{ themeColor }}生成内联 style，会导致 CSS 变量无法继承、过渡失效、伪元素取不到值
data-theme 必须挂载在 document.documentElement 上
这是唯一能让所有 CSS 变量全局生效、且被伪元素 / fixed 元素 / SVG 正确读取的位置。设在 body 或某个容器上，等于白干。
- 错误写法：
document.body.setAttribute('data-theme', 'dark')—— 查看 DOM 会发现<html>根节点上根本没有data-theme，html[data-theme="dark"]选择器根本不会匹配 - 正确写法：
document.documentElement.setAttribute('data-theme', 'dark')，或更简洁：document.documentElement.dataset.theme = 'dark' - 必须同步更新
<meta name="color-scheme">，否则 Safari/Chrome 的系统级颜色适配（比如地址栏、表单控件）不会响应
CSS 中必须用 html[data-theme="xxx"] 而非 .theme-xxx
权重和作用域决定一切。漏掉 html 前缀，变量就只在局部生效，或者被子选择器压垮。
anything-to-html
下载
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
- ✅ 正确：
html[data-theme="dark"] { --bg: #111; --text: #eee; } - ❌ 错误：
.dark { --bg: #111; }—— 这个变量只对当前 class 元素有效，且无法被:root下其他规则继承 - ❌ 错误：
:root .dark { --bg: #111; }—— 这是两个独立选择器，不是嵌套，:root不会因此获得新变量 - 所有用到变量的地方都得显式调用：
background-color: var(--bg);、fill: var(--icon-fill);，漏一个就回退到浏览器默认值
切换前必须声明 transition 和回退值
浏览器不会自动给未声明的属性加动画，也不会在变量未定义时“智能兜底”。这两项不提前写死，切换就是生硬跳变或直接黑屏/白屏。
-
transition必须写在初始样式里，比如：body { background-color: var(--bg, #fff); color: var(--text, #000); transition: background-color 0.3s, color 0.3s; } - 每个
var()都要带回退值：var(--border-color, #ddd)，否则变量为空时会用currentColor或浏览器默认色，常导致文字看不见 - 不要指望 JS 改完
data-theme后再加 class 或改style来触发动画——CSS 已声明的过渡属性会自动响应变量变化，无需额外干预
真正热切换的关键不在模板，而在 CSS 变量的作用域控制、data-theme 的挂载位置、以及变量使用时的防御性写法。模板只负责输出初始结构，主题状态由 JS + CSS 共同接管，这才是轻量、可靠、无障碍兼容的做法。
