Tailwind 主题必须用对象嵌套定义色阶（如 primary: { '500': '#3b82f6' }），否则不生成梯度类；data-theme 需挂载 html 元素并配合 @layer base 声明 CSS 变量，且须内联默认值防闪动；safelist 必须正则匹配动态插值类（如 /^bg-[.*]$/），禁用第三方主题插件以保可调试性。
theme.extend.colors 必须用对象嵌套，否则色阶类不生成
直接写 extend: { colors: { primary: '#3b82f6' } } 只会生成 bg-primary，但 bg-primary-500 这类带明暗梯度的类根本不会出现。Tailwind 不会为你自动推导色阶。
- 必须显式定义为对象：
primary: { '50': '#f9fafb', '500': '#3b82f6', '900': '#1e293b' } - 键名必须是字符串（
'500'，不是500），值必须含# - 如果只想要单色变量（比如用于 CSS 变量桥接），就别用色阶命名法，改用
brand: 'var(--color-brand)'配合 safelist - JIT 模式下，没在模板里写过的类（如
bg-primary-500）不会输出，临时加个测试<div class="bg-primary-500"></div>再刷新
data-theme 要挂 <html> 上，且变量必须在 @layer base 声明
dark: 是硬编码响应系统偏好或 class="dark"，它不认识 data-theme="dark" ——哪怕你写了 data-theme="dark"，dark:bg-gray-900 也完全不生效。想让深色成为可切换主题之一（比如 light/dark/blue），就得绕过 dark:，统一走 data-theme + CSS 变量。
-
data-theme必须设在<html data-theme="light">，设在<body>或组件上会导致继承链断裂 - 所有主题变量（如
--color-bg、--color-text）必须写在@layer base块里，并挂载到:root，否则会被 Tailwind 默认样式覆盖 - 首次渲染前建议内联默认变量：
<style>:root { --color-bg: #fff; --color-text: #1f2937; }</style>，避免闪动 -
var(--color-bg)中括号内不能有空格，var( --color-bg )会编译失败
safelist 必须包含 bg-\[.*\]，否则 bg-[var(--color-bg)] 被 PurgeCSS 删除
Tailwind 的 PurgeCSS 在构建时会删掉“没在源码中显式出现”的类。像 bg-[var(--color-bg)] 这种动态插值写法，JIT 编译器无法静态分析，不加白名单就会被干掉。
- 在
tailwind.config.js中配：safelist: [/^bg-\[.*\]$/, /^text-\[.*\]$/, /^border-\[.*\]$/] - 正则要覆盖所有可能用到的属性前缀，别只写
bg-；text-和border-同理 - 变量名必须全小写、无空格、半角字符，
--Color-Bg或--color bg都会失效 - 如果用了
withOpacityValue('--color-bg')，也要确保对应 opacity 类（如bg-[var(--color-bg)]/50）被 safelist 涵盖
别用第三方主题插件，它们破坏变量可追踪性
像 tailwindcss-theming 这类插件会劫持 theme.colors 解析逻辑，导致你在 DevTools 里点开 bg-primary 样式，根本看不到它最终指向哪个 CSS 变量——值可能是运行时动态拼接的，调试成本陡增。
立即学习“前端免费学习笔记（深入）”；
- 插件与
@apply、group-等组合使用时容易丢失上下文，生成冗余 CSS - 升级 Tailwind 4 后大概率失效，因为插件依赖内部 AST 解析细节，官方不承诺这部分 API 稳定
- 原生方案只需三步：①
@layer base定义变量；②theme.extend.colors桥接var(--xxx)；③ JS 切换document.documentElement.setAttribute('data-theme', 'xxx') - 所有主题变量命名保持一致（统一用
--color-primary，别混用--primary），初始化时机比切换函数更重要
data-theme 时，如果 CSS 文件还没解析完，浏览器会按旧变量渲染一帧。内联默认变量 + 统一命名 + @layer base 声明，这三件事做扎实了，比堆十个切换函数都管用。 
