来自 WordPress Auditor 生产验证的 Tailwind v4 配置指南，通过四步架构预防 8 类常见错误，实现暗黑模式与主题系统无缝集成。
说明：
该 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 级个人开发者，建议在生产环境使用前审查模板代码安全性。
会员专属
