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 级个人开发者，建议在生产环境使用前审查模板代码安全性。