不能靠dark:前缀实现用户可选的多主题切换，因其仅为prefers-color-scheme: dark硬编码映射，不响应data-theme="blue"等自定义值；混用会导致优先级混乱和第三方库不兼容，必须统一使用CSS变量+@layer base+data-theme挂载于<html>并配置safelist。
不能靠 dark: 前缀实现用户可选的多主题切换——它只响应系统偏好或 class="dark"，对 data-theme="blue" 完全无效。
为什么直接用 dark: 会失效
dark: 是 Tailwind 对 prefers-color-scheme: dark 的硬编码映射，不是通用主题开关。哪怕你把 data-theme 设为 "dark"，dark:bg-gray-900 也不会触发。混用还会导致 DevTools 里颜色忽明忽暗，优先级混乱。
第三方库（如 Headless UI、Varlet）默认只生成 dark: 类，不会识别 data-theme ——想让它们同步，必须 patch class 生成逻辑或改用 CSS 变量桥接。
必须把变量定义在 @layer base 且挂载到 :root
所有主题变量（比如 --color-bg、--color-text）必须写在 @layer base 块里，并放在 :root 或 [data-theme="xxx"] 下。否则会被 Tailwind 默认样式覆盖，bg-[var(--color-bg)] 就是白屏或 fallback 颜色。
立即学习“前端免费学习笔记（深入）”；
-
data-theme必须设在<html>标签上，确保继承链完整；设在<body>或组件上会漏继承 - 变量名必须以
--开头，且括号内不能有空格：var(--color-bg)✅，var( --color-bg )❌ - 首次渲染前建议内联默认变量，比如在
<head>里加<style>:root { --color-bg: #fff; --color-text: #1f2937; }</style>，避免闪动
配置 safelist 让 bg-[var(--x)] 生效
Tailwind 默认忽略无法静态分析的 var() 值，不配置就会被 PurgeCSS 删除，构建后没效果。
推荐在 tailwind.config.js 中加入：
safelist: [ /^bg-\[.*\]$/, /^text-\[.*\]$/, ]
更精确的做法是列出具体值：
safelist: [ 'bg-[var(--color-bg)]', 'text-[var(--color-text)]', 'border-[var(--border-color)]' ]
VS Code 插件可能标红，但只要 safelist 放行了字符串，构建就能通过。
JS 切换时同步处理 alpha 通道和命名一致性
运行时切换主色调，只改 --primary 的 RGB 值不够：bg-primary/70 这类带透明度的 class 依赖 rgb(var(--primary) / var(--primary-alpha, 1)) 结构，如果没设 --primary-alpha，就失效。
- 安全做法：JS 设置时同步调用
document.documentElement.style.setProperty('--primary-alpha', '0.7') - 或者干脆避开
/70后缀，改用bg-primary opacity-70组合 - 最易被忽略的是变量命名不统一：项目里混用
--primary、--color-primary、--theme-primary，会导致部分组件换色、部分不动
变量必须集中收口到一套命名，全部写在 @layer base，比写十个切换函数重要得多。
