页面未响应 data-theme 变更，因 CSS 自定义属性不监听 HTML 属性变化；需同步设置 data-theme 属性、在对应选择器内重声明 :root 变量，并确保 @media (prefers-color-scheme: dark) 块置于 :root 默认声明之后且不嵌套。
为什么只改 data-theme 属性页面没反应
常见错误是执行了 document.documentElement.setAttribute('data-theme', 'dark')，但样式没变。CSS 自定义属性不会监听 HTML 属性变化——它只在解析时求值，后续属性变更不触发重计算。
多数 CSS 框架（如 Bootstrap 5.3+、Tailwind 的 @layer base 主题类）依赖两层机制：一是选择器匹配 html[data-theme="dark"]，二是该选择器内重新声明 :root 变量值。漏掉变量重声明，var(--bs-body-bg) 还是浅色值。
- 检查 DevTools → Elements →
:root节点，确认切换后变量值是否更新 - 必须同步设置属性 + 触发框架更新方法，例如 Bootstrap 需调用
bootstrap.Theme.getOrCreateInstance().update() - Tailwind 用户需确保启用了
darkMode: 'class'并在html上加class="dark"，而非仅靠data-theme
@media (prefers-color-scheme: dark) 必须写在 :root 默认定义之后
媒体查询本身不提升优先级，只靠声明顺序覆盖。如果深色规则写在浅色规则前，或嵌套在其他媒体查询里（比如 @media (max-width: 768px) { @media (prefers-color-scheme: dark) { ... } }），旧版 Safari 会直接忽略。
正确结构只有这一种写法：
立即学习“前端免费学习笔记（深入）”；
:root {
--bg-primary: #ffffff;
--text-primary: #1a1a1a;
}
@media (prefers-color-scheme: dark) {
:root {
--bg-primary: #121212;
--text-primary: #e0e0e0;
}
}
- 所有变量必须先在
:root中声明默认值，否则系统设为no-preference或不支持时，var(--bg-primary)会回退到浏览器默认（通常是白底黑字） - 不能只覆盖部分变量：漏定义
--border，而组件用了border: 1px solid var(--border, #ccc)，深色下就会显示亮灰边框 - 务必把
@media块放在所有:root声明之后，且不嵌套
手动切换和系统偏好如何共存不打架
用户点“深色模式”按钮，和系统设为浅色时，两者必须分层处理。用 JS 直接调用 document.documentElement.style.setProperty('--bg-primary', '#121212') 会彻底屏蔽 @media (prefers-color-scheme: dark) 的自动响应——下次用户切系统主题，页面毫无反应。
推荐做法是状态分离：
- 系统偏好兜底：用
@media (prefers-color-scheme: dark)设置初始值，但加:root:not([data-theme])限定，避免干扰手动选择 - 用户主动选择：用
html[data-theme="dark"]覆盖变量，JS 只操作dataset.theme - 初始化时优先读
localStorage.getItem('theme')，fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches
边框、focus outline 在深色下为啥刺眼或消失
不是颜色反色就行。浅色下的 #ccc 对应深色不是 #333，而是 #444 或带灰度的 #3a3a3a；outline: 2px solid #fff 在黑背景上会跳脱。
更稳妥的做法是用 HSL 表达并统一管理：
- 聚焦 outline 推荐用
outline: 2px solid var(--focus-ring)，并在 JS 切换主题时一并设--focus-ring: hsl(250, 80%, 60%) - 边框别漏
solid：写成border: 1px var(--border)是无效语法，整条声明被忽略，边框就没了 - 检查 DevTools 的 Computed 面板，确认最终计算值，而不是只看 Styles 里的变量引用
真正容易被忽略的是：所有颜色路径都得走变量，包括 disabled 状态、svg fill、box-shadow 的 color 部分——漏一个，深色下就露馅。
