HTML的data-theme仅作状态标记，主题切换需同步更新data-theme属性和CSS变量，否则样式不响应；必须用JS触发重绘，localStorage alone无效。
HTML变量（data-属性）本身不参与主题切换逻辑
单纯在<html>标签上加data-theme="dark"，浏览器不会自动变色——它只是个静态标记，没绑定样式或行为。真正起作用的是CSS变量（--color-bg这类）和JavaScript对它的读写，data-属性只适合做“状态快照”或跨JS/CSS通信的桥梁。
常见错误现象：
– 页面切了data-theme="light"，但背景还是黑的
– 切换后需要刷新才生效
– 多个组件各自维护主题状态，互相不同步
- 用
data-theme记录当前主题，仅作为“真相源”（source of truth），避免JS里用字符串硬编码判断 - 所有主题相关CSS必须基于
:root或[data-theme]选择器定义，例如：:root[data-theme="dark"] { --color-bg: #1a1a1a; } - 切换时务必同步更新
document.documentElement.dataset.theme和CSS变量，缺一不可
为什么不能只靠localStorage + data-属性完成切换
因为localStorage只存字符串，不触发重绘；data-属性变更也不会自动通知CSS。如果只改localStorage、不调用document.documentElement.setAttribute('data-theme', '...')，页面样式根本不会响应。
使用场景：用户关闭再打开页面，需恢复上次主题
立即学习“前端免费学习笔记（深入）”；
- 初始化时优先读
localStorage，再写入data-theme，最后调用一次applyTheme()（哪怕值没变） - 监听系统偏好（
prefers-color-scheme）时，若用户未手动设置主题，才自动同步到data-theme和localStorage - 避免在
DOMContentLoaded之前读localStorage，否则可能被后续JS覆盖
data-theme和CSS自定义属性（--*）怎么配合才不掉链子
关键在作用域和更新时机：data-是DOM状态，--*是CSS计算值，两者必须严格对齐。一旦错位（比如JS改了data-theme但忘了重设--color-text），就会出现“主题名对但颜色错”的诡异现象。
参数差异：
– data-theme只能是字符串（"light"/"dark"）
– --color-bg可以是颜色值、hsl()、甚至var(--fallback)
- 推荐把所有主题色集中定义在
:root[data-theme="..."]块内，不要分散在各组件里 - 如果用CSS-in-JS（如Emotion），仍需保留
data-theme用于服务端渲染（SSR）首屏一致性 - 调试时直接检查
getComputedStyle(document.documentElement).getPropertyValue('--color-bg')，比看data-theme更可靠
暗色模式下data-属性容易被忽略的兼容性坑
某些老版本iOS Safari（≤15.4）不支持[data-theme="dark"] .card这种属性选择器匹配动态插入的data-，但支持.dark .card类名写法。这不是bug，是CSS选择器引擎限制。
- 生产环境建议双保险：同时写
[data-theme="dark"]和.theme-dark，用JS同步增删class - 避免嵌套过深的
data-选择器，比如html[data-theme] body div[data-loaded] .ui-button，性能差且难调试 - SSR框架（如Next.js）中，首次渲染必须让
data-theme和服务端输出的CSS变量完全一致，否则会闪屏
data-属性，或者媒体查询与JS逻辑打架。盯住documentElement这一个节点的状态，比分散管理十个组件的主题props更可控。 
