不能靠 tailwind.config.js 直接绑定 var(--x) 构建可运行时切换的设计系统，因 Tailwind 需静态解析 RGB 生成变体类，而 var() 是运行时机制；theme.extend.colors 中写 var(--primary) 必然失败，因其无法提取 r/g/b 分量，导致带后缀类缺失、深色模式无效。
不能靠 tailwind.config.js 直接绑定 var(--x) 来构建可运行时切换的设计系统——Tailwind 的颜色系统需要静态解析 RGB 值生成变体类，而 var() 是运行时机制，两者底层不兼容。
为什么 theme.extend.colors 里写 var(--primary) 必然失败
Tailwind 在构建阶段就要把每个颜色值拆解成 r/g/b，才能生成 bg-primary-500、hover:bg-primary-600、bg-primary/20 这些类。当你写 primary: 'var(--primary)'，它拿到的只是一个字符串字面量，根本抽不出数字分量。
- 现象：能生成
bg-primary，但所有带后缀（如-500、/70）的类全部缺失 - 错误提示常见：
Cannot read property 'r' of undefined或控制台显示color: rgb(NaN) - 深色模式类（如
dark:bg-primary）完全无效，因为变量本身没切换逻辑
真正可行的路径：绕过 Tailwind 颜色系统，用 @layer + 任意值语法
把 CSS 变量当“皮肤层”独立出来，Tailwind 只负责结构和原子类，变量负责主题状态。关键在 CSS 层定义，不在配置文件里硬塞。
- 在
src/index.css里用@layer base声明变量：:root { --primary: #3b82f6; --primary-alpha: 0.8; } - 用
@layer utilities手动绑定工具类：.text-primary { @apply text-[color:var(--primary)]; } .bg-primary { @apply bg-[var(--primary)]; } .bg-primary\/alpha { @apply bg-[color:var(--primary)/var(--primary-alpha)]; } - 必须在
tailwind.config.js的safelist中放行这些类名：safelist: [/^text-[.*]$/, /^bg-[.*]$/]
- 任意值语法要求 Tailwind v3.0+，v2.x 会静默忽略
JS 切换主题时最容易漏掉的三件事
只改 --primary 的 RGB 值远远不够，CSS 变量是纯字符串，不会自动推导亮度、透明度或对比度。
立即学习“前端免费学习笔记（深入）”；
- alpha 通道必须单独设变量（如
--primary-alpha），否则bg-primary/70类失效 - 深色模式媒体查询（
@media (prefers-color-scheme: dark)）和 JS 设置会冲突，需明确优先级：JS 应覆盖媒体查询，推荐用data-theme="dark"控制作用域 - 变量名必须符合 CSS 自定义属性规范：以
--开头，全小写+连字符，比如--text-primary，不能写成textPrimary或primaryColor
最易被忽略的是变量作用域和层级顺序——:root 没声明、组件 scoped style 里重复定义、或者 @layer base 写在了 @layer utilities 后面，都会导致 var(--x) 计算为 transparent 或继承值，且控制台不报错，排查极难。
