技能介绍

你要解决的问题

从 Tailwind v3 升到 v4 之后，很多项目的配色会突然失控：@apply 开始报错，tailwind.config.ts 里精心维护的颜色值不再生效，dark: 变体和 CSS 变量互相打架，暗色模式下的对比度也莫名其妙地崩掉。根因在于 v4 把配置模型从 JS 配置文件搬到了 CSS 本身——主题应该用 :root 里的语义化 CSS 变量定义，再通过 @theme inline 映射成工具类。这个技能就是专门处理这条迁移路径的。

它做了什么

该技能扮演一位 Tailwind v4 + shadcn/ui 的主题工程师，在已装好 Vite + React 的项目里按固定四步产出一套可运行的主题方案：

安装依赖：引入 tailwindcss 与 @tailwindcss/vite 插件、tw-animate-css、@types/node，初始化 shadcn；如果项目里还残留 v3 的 tailwind.config.ts，直接删掉——v4 不再需要它。
配置 Vite：在 vite.config 中注册 react 与 tailwindcss 插件，并配置 @ 指向 ./src 的路径别名。
四步 CSS（顺序强制）：先在 :root 与 .dark 中用 hsl() 包裹定义变量；再用 @theme inline 把变量映射为 --color-background 这样的工具类键，让 bg-background 自动可用；接着在 @layer base 里给 body 应用前景与背景色（此处不再包 hsl()）；最后落实语义命名——用 --primary 而不是 --blue-500，每个背景色配一个前景色，图表色单独留变量。
暗色模式：挂上主题 Provider，切换 <html> 上的 .dark 类，UI 随变量自动更新，不再依赖 dark: 变体，同时补一个切换按钮。

产出物包括四步 CSS 片段、暗色配置和一份避坑检查表，核心结构会以 ThemeConfig 的形式返回，其中包含语义 token 的亮暗 HSL 值、已完成步骤与对比度检查结果。

适用边界与注意点

它只服务于 Tailwind v4 的技术栈。如果你的项目用的是纯 CSS 框架、或者尚未迁移到 v4，这套流程并不适用。实际依赖版本请以官方文档为准，技能不会替你锁定版本号。另外，对比度遵循 WCAG 标准：正文 4.5:1、大字 3:1、UI 组件 3:1，contrast_ok 字段只是检查结果，最终的视觉验收仍需要人眼确认。