核心用法
本 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` |