Tailwind 中直接修改 theme.colors 无效，因构建时静态生成 class；需用 CSS 变量 + text-[var(--primary)] + safelist 显式放行，并在 :root 初始化变量、统一命名、设 data-theme 于 。
为什么直接改tailwind.config.js里的theme.colors没用
Tailwind 是构建时工具，所有 class（比如 bg-primary、text-blue-500）都在打包阶段静态生成。你在配置里把 theme.extend.colors.primary 改成 var(--primary)，它不会生效——构建器直接忽略这种运行时变量，甚至可能报错或静默跳过。最终生成的 CSS 里压根没有对应规则，DevTools 里搜不到 bg-primary 的声明。
必须用 CSS 变量 + text-[var(--primary)] + safelist
真正能运行时切换的路径只有一条：在 HTML/CSS 中定义 --primary 等变量，在 JSX/HTML 里显式写出 text-[var(--primary)] 这类任意值语法，并在 tailwind.config.js 中放行它。
-
--primary必须定义在:root或[data-theme="dark"]这类全局作用域下，不能只写在组件<style scoped></style>里 -
safelist必须显式包含该字符串，例如：safelist: ['text-[var(--primary)]', 'bg-[var(--bg-surface)]']；正则写法更省事：/^text-\[.*\]$/，但要注意括号必须是英文半角、中间不能有空格 - VS Code 插件标红 ≠ 编译失败，只要
safelist放行了，就能生成对应 CSS 规则 - 混用
text-blue-500和text-[var(--primary)]时，前者会覆盖后者（它同时设置了color和font-weight）
JS 切换主题时最常漏掉的三件事
只调 document.documentElement.setAttribute('data-theme', 'blue') 不够，页面大概率闪一下白底或颜色错乱。
- 没提前初始化变量：CSS 文件加载前，浏览器按无变量状态渲染一帧。应在
内联默认值，比如<style>:root { --primary: 96 165 250; --bg-surface: #fff; }</style> - 只改 RGB，不设 alpha：像
bg-primary/70这种写法依赖rgb(var(--primary) / var(--primary-alpha, 1))结构。JS 修改--primary时，必须同步document.documentElement.style.setProperty('--primary-alpha', '0.7')，否则透明度失效 - 变量命名不统一：项目里混用
--primary、--color-primary、--theme-primary，会导致部分组件换色、部分不动。所有变量必须收口到@layer base块中，且命名严格一致
data-theme 要设在 上，别和 dark: 混用
dark: 是 Tailwind 对 prefers-color-scheme 的快捷映射，只响应系统设置，跟自定义主题无关。如果你在 [data-theme="blue"] 下写了 dark:bg-blue-900，它根本不会触发。
立即学习“前端免费学习笔记（深入）”；
-
data-theme必须设在标签上，确保所有子元素继承 - 不要同时用
class="dark"和data-theme="custom"，CSS 优先级容易冲突，调试时颜色忽明忽暗 - 第三方组件库（如 Headless UI）默认只认
dark:，需 patch 其 class 生成逻辑才能适配data-theme - 想缓解切换闪动，可在
:root加过渡：transition: background-color 200ms, color 200ms
