tailwind-v4-+-shadcn/ui-stack

该 Skill 提供了一套经过生产环境验证的 Tailwind CSS v4 与 shadcn/ui 集成配置方案，核心采用强制性四步架构设计。第一步在根级别定义 CSS 变量（使用 hsl() 包装），第二步通过 @theme inline 将变量映射为 Tailwind 工具类，第三步在基础层应用样式，第四步实现自动暗黑模式切换。这种架构能有效预防 8 类常见配置错误，包括颜色失效、暗黑模式故障、构建失败等问题。

主要优势在于其完善的错误预防机制和详尽的迁移指南。针对从 Tailwind v3 迁移的用户，明确指导删除 tailwind.config.ts 文件，改用 CSS 原生配置；针对 v4 新特性，支持 OKLCH 色彩空间、内置容器查询和行高限制功能。此外，提供完整的 ThemeProvider 实现和 Vite 配置模板，大幅降低配置门槛。

局限性方面，该 Skill 主要面向 Vite + React 技术栈，对其他构建工具（如 Webpack）或框架（如 Vue/Svelte）支持有限。同时，四步架构要求严格执行，跳过任一步骤都会导致主题系统失效。对于需要多主题（非简单明暗切换）的复杂场景，@theme inline 的构建时烘焙特性可能限制灵活性，需改用标准 @theme 语法。

适合目标群体包括：正在启动新 React 项目的开发者、计划从 Tailwind v3 升级至 v4 的团队、遭遇 shadcn/ui 与 v4 兼容性问题的用户，以及希望实现零配置暗黑模式的工程师。尤其适合对 CSS 变量和现代 CSS 架构有一定了解的中高级前端开发者。

使用风险主要集中在依赖管理和配置严谨性。虽然所有依赖（tailwindcss、@tailwindcss/vite、tw-animate-css）均为知名 npm 包，但版本锁定至关重要，建议通过 lock 文件固定版本。配置过程中必须避免常见错误：切勿将 :root 置于 @layer base 内，禁止双重 hsl() 包装，确保 components.json 中 tailwind.config 设为空字符串。此外，由于来源为 T3 级个人开发者，建议在生产环境使用前审查模板代码安全性。

核心用法

本 Skill 提供 Tailwind CSS v4 与 shadcn/ui 的完整集成配置，采用强制四步架构确保主题系统稳定运行：

1. 定义 CSS 变量 — 在 :root 和 .dark 中使用 hsl() 包装定义语义化颜色变量
2. 映射 Tailwind 工具类 — 通过 @theme inline 将变量映射为 bg-background、text-primary 等工具类
3. 应用基础样式 — 在 @layer base 中直接引用变量（禁止双重 hsl() 包装）
4. 自动暗色切换 — 通过 ThemeProvider 实现无 dark: 前缀的自动主题切换

关键配置变更

• 删除 `tailwind.config.ts` — v4 完全基于 CSS 配置，保留旧文件会导致构建失败
• 更换动画包 — tailwindcss-animate → tw-animate-css
• Vite 插件化 — 使用 @tailwindcss/vite 替代 PostCSS
• components.json 关键设置 — "tailwind.config": "" 必须为空字符串

显著优点

| 维度 | 优势 |

|------|------|

| 错误预防 | 针对 8 类常见错误（构建失败、颜色失效、暗色模式失效等）提供明确的诊断与修复方案 |

| 语义化主题 | 从硬编码色值迁移至 `--primary`、`--info` 等语义变量，减少 `dark:` 代码量 80%+ |

| v4 新特性就绪 | 内置 OKLCH 色彩空间、容器查询（`@container`）、行数截断（`line-clamp`）等 v4 特性使用示例 |

| 迁移友好 | 提供 v3→v4 完整迁移指南，包括 `@apply` 语法变更（`@utility` 替代 `@layer components`） |

潜在局限性与注意事项

1. 单/多主题限制：@theme inline 在构建时固化值，多主题系统需改用无 inline 的 @theme 配合 @layer theme
2. 视觉差异：v4 默认 ring 宽度从 3px 改为 1px，Preflight 移除标题样式，需显式配置
3. 架构强制性：四步架构为强制顺序，跳过任一步骤（如将 :root 放入 @layer base）将导致主题失效
4. 生态成熟度：v4 于 2025 年初发布，部分第三方插件可能尚未完全适配

适合人群

• 新项目启动：使用 Vite + React 技术栈，希望直接采用 v4 现代架构的团队
• v3 迁移者：需系统性迁移指南，尤其涉及复杂主题配置的项目
• 调试场景：遇到 bg-primary 无效、暗色模式不切换、@theme inline 报错等具体问题的开发者
• 设计系统建设者：需要建立语义化颜色系统、支持自动暗色模式的产品团队

常规风险

• 配置覆盖风险：@theme inline 与内联 @apply 的层级冲突可能导致样式覆盖问题
• 构建工具链变更：v4 要求完全移除 PostCSS 配置，对已有 CI/CD 流程需调整
• 团队协作成本：四步架构虽有文档，但新成员仍可能因习惯 v3 模式而误配

生产验证

已通过 WordPress Auditor (wordpress-auditor.webfonts.workers.dev) 生产环境验证，版本锁定：tailwindcss@4.1.18、@tailwindcss/vite@4.1.18。