@theme 是 Tailwind CSS v4 唯一推荐的主题声明方式，需置于主 CSS 文件顶层且在 @tailwind base 之前，支持标准颜色格式并自动推导色阶与变体；混用 theme.extend.colors 会被覆盖，config 中禁用 var(--x) 颜色值，否则导致亮度计算失败和渲染异常。
@theme 规则是 v4 唯一推荐的声明方式
Tailwind CSS v4 原生支持 @theme at-rule，它让 CSS 变量直接参与色阶推导、变体生成和 data-theme 切换，无需插件或 hack。这是目前最干净、最可控的方案。
关键点：@theme 必须写在你的主 CSS 文件（如 src/index.css）中，且要在 @tailwind base 之前；变量名必须以 -- 开头；格式支持 oklch、rgb、hsl 等标准颜色表示法。
-
@theme声明后，text-primary、bg-primary-600、hover:bg-primary全部自动生效，Tailwind 会解析变量并生成对应亮度层级 - 不要把
@theme塞进@layer utilities或单独的 scoped style 里——它必须位于全局 CSS 上下文顶层 - 多主题切换时，直接用
[data-theme="purple"] { --color-primary: oklch(0.55 0.27 304); }覆盖即可，无需修改 JS 逻辑 - 如果项目里混用
@theme和theme.extend.colors，后者会被前者覆盖，建议彻底移除 config 中的颜色扩展
tailwind.config.js 里禁止写 var(--x) 作为颜色值
哪怕你只写 primary: 'var(--color-primary)'，也会导致 bg-primary-500 类不生成、hover:bg-primary 渲染为透明或白底黑字——因为 Tailwind 构建时根本不会执行 CSS，parseColor() 拿到的是字符串，后续所有亮度计算都崩了，报错通常是 Cannot read property 'r' of undefined。
- 现象很典型：类名存在但没效果，DevTools 里看到
color: rgb(NaN)或background-color: rgba(NaN, NaN, NaN, 1) - 如果你只是固定用一个品牌色，直接写死
primary: '#1677FF'最稳，别绕路 - v4 不再需要
safelist来保活bg-[var(--x)]类——@theme声明的变量会被原生识别，任意值语法（如bg-[var(--color-bg)]）仍需 safelist，但主题色工具类不需要
:root + @layer base 是备用方案（仅限 v3 或特殊控制需求）
如果你还在用 v3，或需要精细控制某个变量只用于背景、不参与文本色变体，那就放弃 colors 扩展，改用 @layer base 显式绑定：
立即学习“前端免费学习笔记（深入）”；
- 变量必须定义在
:root或[data-theme="xxx"]内部，不能写在@layer base块顶层 -
@layer base必须出现在@tailwind base之前，否则 Tailwind 解析工具类时变量还没注册 - 像
bg-[var(--color-bg)]这种任意值写法，必须配safelist: [/^bg-\[.*\]$/]，且括号内不能有空格或中文字符 - 变量命名要统一：全项目只用
--color-primary，别混--primary、--theme-primary，否则切换时部分组件不动
JS 切换主题时最容易漏掉的三件事
运行时调用 document.documentElement.dataset.theme = 'dark' 看似简单，但实际常因以下细节失效：
- 没把
data-theme设在<html>标签上——设在<body>或组件容器里会导致子元素继承不到 - CSS 文件加载慢于 JS 执行，首帧渲染用的是未定义的变量值，出现闪动；建议在
<head>里内联默认变量：<style>:root { --color-bg: #fff; --color-text: #1f2937; }</style> - 没同步设置 alpha 通道：若用了
bg-primary/70这类带透明度的类，JS 修改--color-primary时也得同时设--color-primary-alpha，否则透明度规则失效
真正难的不是写几行 JS，而是让变量作用域、注入时机、命名一致性全部对齐——这些地方错一个，主题就断在某一层。
