dark:bg-gray-900在data-theme="dark"下不生效，因dark:仅映射prefers-color-scheme或class="dark"，不解析data-theme；混用会导致样式冲突，第三方库也不识别data-theme。
不能靠 dark: 实现多套主题切换，必须用 data-theme + CSS 变量 + @layer base + bg-[var(--color-bg)] 这一套组合拳。
为什么 dark:bg-gray-900 在 data-theme="dark" 下完全不生效
dark: 是 Tailwind 对 prefers-color-scheme: dark 或硬编码 class="dark" 的静态映射，它根本不解析 data-theme 属性。哪怕你写了 <html data-theme="dark">，dark:bg-gray-900 也永远不会匹配——因为它的选择器是 .dark .dark\:bg-gray-900，不是 [data-theme="dark"]。
混用两者会导致 DevTools 里样式忽明忽暗：系统暗色检测、JS 设置的 data-theme、手动加的 class="dark" 三者优先级打架，最终谁赢取决于加载顺序和 specificity。
- 第三方库（如 Headless UI）默认只生成
dark:类，不会识别data-theme，必须额外 patch 或绕过 - 想支持 “深蓝/棕褐/高对比度” 多种可选主题，
dark:就是死路一条 -
darkMode: 'class'配置项只影响dark:的触发方式（从 media query 切到 class 检测），仍不支持任意data-theme值
如何在 @layer base 中正确声明多主题 CSS 变量
所有变量必须写在 @layer base 块内，且作用域为 :root 或 [data-theme="xxx"]，否则会被 Tailwind 默认样式覆盖或子元素无法继承。
立即学习“前端免费学习笔记（深入）”；
变量名要统一规范（全用 --color-bg，别混 --bg 或 --theme-bg），且必须设在 <html> 标签上——设在 <body> 或组件内部，子元素拿不到。
首次渲染前建议内联默认值防闪动：
<style>
:root { --color-bg: #fff; --color-text: #1f2937; }
</style>
完整示例（放在全局 CSS 文件中）：
@layer base {
:root {
--color-bg: #ffffff;
--color-text: #1f2937;
}
[data-theme="dark"] {
--color-bg: #111827;
--color-text: #f9fafb;
}
[data-theme="sepia"] {
--color-bg: #f4f0e5;
--color-text: #4a3f35;
}
}
怎样让 bg-[var(--color-bg)] 安全通过构建且不报错
Tailwind 默认忽略无法静态分析的 var()，必须显式放行。不配置 safelist，它就当没看见，编译后压根不生成对应 CSS 规则。
推荐两种方式：
- 宽泛但省心：
safelist: [/^bg-\[.*\]$/, /^text-\[.*\]$/]—— 允许所有带方括号的bg-和text-类 - 精确但需维护：
safelist: ['bg-[var(--color-bg)]', 'text-[var(--color-text)]']—— 只放行实际用到的变量
注意细节：
- 方括号必须是英文半角，
bg-[var(--color-bg)]不能写成bg-[var( --color-bg )]（空格、中文引号都会导致构建失败） - VS Code 插件可能标红，但只要
safelist匹配且字符串真实出现在源码中（比如 JSX 里写了这个 class），就能正常编译 -
content配置必须扫描到这些字符串，例如：content: ['./src/**/*.{js,jsx,ts,tsx}']
JS 切换 data-theme 时最易忽略的初始化时机问题
执行 document.documentElement.setAttribute('data-theme', 'dark') 后页面闪白，根本原因不是 JS 慢，而是 CSS 变量定义还没加载完，浏览器先按无变量状态渲染了一帧。
解决办法只有一个：兜底。要么在 <head> 内联默认变量，要么用 document.documentElement.style.setProperty() 批量初始化。
更隐蔽的问题是变量作用域覆盖：如果 @layer base 块写在 Tailwind 默认样式之后，[data-theme="dark"] 里的变量可能被其他 CSS 覆盖。务必确保变量声明在全局样式链最前面，且只用 :root 和 [data-theme] 这两级作用域。
