Tailwind v4 + shadcn/ui 生产级配置方案，通过强制性四步架构预防 8 种常见错误，支持自动暗色模式与 CSS 变量主题系统。
说明：
## 核心用法
本 Skill 提供 Tailwind v4 与 shadcn/ui 的完整配置方案，采用**强制性四步架构**：
1. **定义 CSS 变量**：在 `:root` 和 `.dark` 中使用 `hsl()` 包裹颜色值，**禁止**放在 `@layer base` 内
2. **映射到 Tailwind**：通过 `@theme inline` 将变量转换为工具类，生成 `bg-background`、`text-primary` 等语义化类名
3. **应用基础样式**：在 `@layer base` 中直接使用 `var(–background)`，**禁止**双包裹如 `hsl(var(–background))`
4. **自动暗色模式**：无需 `dark:` 变体，通过 `.dark` 类自动切换主题
### 关键配置变更
– **删除 `tailwind.config.ts`**：v4 完全基于 CSS 配置
– **使用 `@tailwindcss/vite` 插件**：替代 PostCSS 方案
– **切换动画包**：`tailwindcss-animate` → `tw-animate-css`
– **components.json 关键设置**：`”tailwind.config”: “”`
## 显著优点
| 优势 | 说明 |
|——|——|
**错误预防** | 文档化 8 种高频错误（颜色失效、构建失败、`@apply` 损坏等）及对应解决方案 |
| **零配置主题** | 语义化颜色系统自动处理亮/暗模式，代码量减少 50%+ |
| **现代特性开箱即用** | OKLCH 色域、容器查询 `@container`、内置 `line-clamp`、无需插件 |
| **迁移友好** | 提供 v3→v4 完整迁移指南，含视觉差异对照表 |
| **生产验证** | 已在 WordPress Auditor 项目实测 |
## 潜在局限
1. **学习曲线陡峭**：四步架构顺序严格，跳步即破坏主题；v4 完全摒弃 JS 配置，需重新适应 CSS-first 思维
2. **多主题限制**：`@theme inline` 在构建时固化值，多主题系统需改用无 `inline` 的 `@theme` 配合 `@layer theme`
3. **生态兼容性**：部分 v3 插件尚未适配，需确认 `@plugin` 支持状态
4. **隐式视觉变更**：v4 默认 ring 宽度 3px→1px，Preflight 移除标题样式，升级需主动适配
## 适合人群
– **新建项目**：React + Vite + Tailwind v4 + shadcn/ui 技术栈
– **v3 迁移者**：需系统性升级方案而非碎片化补丁
– **主题系统开发者**：追求 CSS 变量驱动的设计令牌体系
– **排查专家**：遇 `colors not working`、`dark mode broken`、`@theme inline` 报错时的速查手册
## 常规风险
| 风险 | 后果 | 规避 |
|——|——|——|
| `tailwind.config.ts` 残留 | 构建失败 “Unexpected config file” | 强制删除，不保留备份 |
| 双包裹颜色 | 显示纯黑/白 | 仅用 `var(–color)`，拒绝 `hsl(var(–color))` |
| `@theme inline` 遗漏 | 工具类生成失败 | 必须映射**全部** CSS 变量 |
| `@apply` 误用 | “unknown utility class” | 改用 `@utility` 自定义类 |
| 动画包混淆 | 模块找不到 | 严格使用 `tw-animate-css`，禁装 `tailwindcss-animate` |
会员专属
