（1715期）Tailwind v4 Shadcn – Tailwind v4 + shadcn 生产级配置

Tailwind v4 + shadcn 生产级配置 Tailwind v4 + shadcn/ui 生产级配置方案，通过强制性四步架构预防 8 种常见错误，支持自动暗色模式与 CSS 变量主题系统。 使用说明 核心用法 本 Skill 提供 Tailwind v4 与 shadcn/ui 的完整配置方案，采用强制性四步架构： 定义 CSS 变量：在 :root 和 .dark 中使用 hsl() 包裹颜色值，禁止放在 @layer base 内 映射到 Tailwind：通过 @theme inline 将变量转换为工具类，生成 bg-background、text-primary 等语义化类名 应用基础样式：在 @layer base 中直接使用 var(--background)，禁止双包裹如 hsl(var(--background)) 自动暗色模式：无需 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 项目实测 | 潜在局限 学习曲线陡峭：四步架构顺序严格，跳步即破坏主题；v4 完全摒弃 JS 配置，需重新适应 CSS-first 思维 多主题限制：@theme inline 在构建时固化值，多主题系统需改用无 inline 的 @theme 配合 @layer theme 生态兼容性：部分 v3 插件尚未适配，需确认 @plugin 支持状态 隐式视觉变更：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 | 原始说明 Configures Tailwind v4 with shadcn/ui using a mandatory four-step CSS variable theming to enable automatic dark mode and prevent common errors.