直接用 data-theme + @layer base + var(--color-bg) 支持任意主题；dark: 仅响应系统偏好或 class="dark"，不识别 data-theme="dark"；需在 theme.extend.colors 中透传 CSS 变量、配置 safelist、将变量声明于 @layer base 并挂载到 :root，且 data-theme 必须设在 <html> 上。
直接用 data-theme + @layer base + var(--color-bg) 就能支持深色模式以外的任意主题，包括深色模式本身。别被 dark: 带偏——它只认系统偏好或 class="dark"，没法响应 data-theme="dark"。
为什么 dark: 不能用于自定义深色主题
dark: 是 Tailwind 对 prefers-color-scheme: dark 的硬编码映射，不是通用“主题前缀”。哪怕你写 data-theme="dark"，dark:bg-gray-900 也完全不生效。
- 混用
dark:和data-theme会导致样式优先级混乱，DevTools 里看到颜色忽明忽暗 - 第三方 UI 库（如 Headless UI）默认只生成
dark:类，不会识别data-theme - 想让“深色”成为可切换主题之一（比如 light / dark / blue），就必须绕过
dark:，统一走 CSS 变量
如何在 tailwind.config.js 中桥接深色主题变量
关键不是重写颜色数组，而是把 --color-bg 这类变量名“透传”进 class 生成逻辑：
- 在
theme.extend.colors里写bg: 'var(--color-bg)'或更安全的bg: withOpacityValue('--color-bg') - 必须配置
safelist，否则bg-[var(--color-bg)]会被 PurgeCSS 删除：safelist: [/^bg-\[.*\]$/, /^text-\[.*\]$/] -
var(--color-bg)中括号内不能有空格，且必须是英文半角字符，var( --color-bg )会编译失败
主题变量必须挂载到 :root 且用 @layer base 声明
变量作用域错位是 text-[var(--color-primary)] 不生效的最常见原因：
立即学习“前端免费学习笔记（深入）”；
- 所有主题变量必须写在
@layer base块里，否则会被 Tailwind 默认样式覆盖 -
data-theme必须设在<html>标签上，保证继承链完整；设在<body>或组件上会漏继承 - 首次渲染前建议内联一组默认变量，比如在
<head>里加<style>:root { --color-bg: #fff; --color-text: #1f2937; }</style>，避免闪动
最容易被忽略的是变量初始化时机：JS 执行 document.documentElement.setAttribute('data-theme', 'dark') 时，如果 CSS 文件还没解析完，浏览器会先按旧变量渲染一帧。内联默认变量 + 统一命名（别混用 --primary 和 --color-primary）比写十个切换函数更重要。
