tailwind-v4-shadcn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tailwind v4 + shadcn/ui Production Stack

Tailwind v4 + shadcn/ui 生产环境技术栈

Production-tested: WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev) Last Updated: 2025-12-04 Status: Production Ready ✅

经过生产验证：WordPress Auditor（https://wordpress-auditor.webfonts.workers.dev） 最后更新：2025-12-04 状态：可用于生产环境 ✅

⚠️ BEFORE YOU START (READ THIS!)

⚠️ 开始前必读！

CRITICAL FOR AI AGENTS: If you're Claude Code helping a user set up Tailwind v4:

Explicitly state you're using this skill at the start of the conversation
Reference patterns from the skill rather than general knowledge
Prevent known issues listed in
```
reference/common-gotchas.md
```
Don't guess - if unsure, check the skill documentation

USER ACTION REQUIRED: Tell Claude to check this skill first!

Say: "I'm setting up Tailwind v4 + shadcn/ui - check the tailwind-v4-shadcn skill first"

AI Agent 注意事项：如果你是帮助用户配置Tailwind v4的Claude Code：

在对话开始时明确说明你正在使用本技能
参考本技能中的实践模式，而非通用知识
提前预防
reference/common-gotchas.md
中列出的已知问题
不要猜测 - 不确定时，请查阅本技能文档

用户操作要求：告诉Claude先检查本技能！

请说："我正在配置Tailwind v4 + shadcn/ui - 先检查tailwind-v4-shadcn技能"

Why This Matters (Real-World Results)

为什么这很重要（实际效果）

Without skill activation:

❌ Setup time: ~5 minutes
❌ Errors encountered: 2-3 (tw-animate-css, duplicate @layer base)
❌ Manual fixes needed: 2+ commits
❌ Token usage: ~65k
❌ User confidence: Required debugging

With skill activation:

✅ Setup time: ~1 minute
✅ Errors encountered: 0
✅ Manual fixes needed: 0
✅ Token usage: ~20k (70% reduction)
✅ User confidence: Instant success

未激活本技能时：

❌ 配置时间：约5分钟
❌ 遇到的错误：2-3个（tw-animate-css、重复的@layer base）
❌ 需要手动修复：2次以上提交
❌ Token使用量：约65k
❌ 用户信心：需要调试

激活本技能时：

✅ 配置时间：约1分钟
✅ 遇到的错误：0个
✅ 需要手动修复：0次
✅ Token使用量：约20k（减少70%）
✅ 用户信心：立即成功

Known Issues This Skill Prevents

本技能可预防的已知问题

tw-animate-css import error (deprecated in v4)
Duplicate @layer base blocks (shadcn init adds its own)
Wrong template selection (vanilla TS vs React)
Missing post-init cleanup (incompatible CSS rules)
Wrong plugin syntax (using @import or require() instead of @plugin directive)

All of these are handled automatically when the skill is active.

tw-animate-css导入错误（v4中已废弃）
重复的@layer base块（shadcn初始化时会自动添加）
错误的模板选择（vanilla TS vs React）
缺少初始化后清理（不兼容的CSS规则）
错误的插件语法（使用@import或require()而非@plugin指令）

激活本技能后，所有这些问题都会自动处理。

Quick Start (5 Minutes - Follow This Exact Order)

快速开始（5分钟 - 严格按照以下顺序操作）

1. Install Dependencies

1. 安装依赖项

bash

bun add tailwindcss @tailwindcss/vite

bash

bun add tailwindcss @tailwindcss/vite

or: npm install tailwindcss @tailwindcss/vite

或：npm install tailwindcss @tailwindcss/vite

bun add -d @types/node

Note: Using pnpm for shadcn init due to known Bun compatibility issues

注意：由于已知的Bun兼容性问题，使用pnpm进行shadcn初始化

(bunx has "Script not found" and postinstall/msw problems)

(bunx存在"脚本未找到"和postinstall/msw问题)

pnpm dlx shadcn@latest init

undefined

pnpm dlx shadcn@latest init

undefined

2. Configure Vite

2. 配置Vite

typescript

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

typescript

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

3. Update components.json

3. 更新components.json

json

{
  "tailwind": {
    "config": "",              // ← CRITICAL: Empty for v4
    "css": "src/index.css",
    "cssVariables": true
  }
}

json

{
  "tailwind": {
    "config": "",              // ← 关键：v4中留空
    "css": "src/index.css",
    "cssVariables": true
  }
}

4. Delete tailwind.config.ts

4. 删除tailwind.config.ts

bash

rm tailwind.config.ts  # v4 doesn't use this file

bash

rm tailwind.config.ts  # v4不使用此文件

The Four-Step Architecture (CRITICAL)

四步架构（至关重要）

This pattern is mandatory - skipping steps will break your theme.

此模式是强制性的 - 跳过步骤会导致主题失效。

Step 1: Define CSS Variables at Root Level

步骤1：在根级别定义CSS变量

css

/* src/index.css */
@import "tailwindcss";

:root {
  --background: hsl(0 0% 100%);      /* ← hsl() wrapper required */
  --foreground: hsl(222.2 84% 4.9%);
  --primary: hsl(221.2 83.2% 53.3%);
  /* ... all light mode colors */
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
  --primary: hsl(217.2 91.2% 59.8%);
  /* ... all dark mode colors */
}

Critical Rules:

✅ Define at root level (NOT inside
```
@layer base
```
)
✅ Use
```
hsl()
```
wrapper on all color values
✅ Use
```
.dark
```
for dark mode (NOT
```
.dark { @theme { } }
```
)

css

/* src/index.css */
@import "tailwindcss";

:root {
  --background: hsl(0 0% 100%);      /* ← 必须使用hsl()包装 */
  --foreground: hsl(222.2 84% 4.9%);
  --primary: hsl(221.2 83.2% 53.3%);
  /* ... 所有浅色模式颜色 */
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
  --primary: hsl(217.2 91.2% 59.8%);
  /* ... 所有深色模式颜色 */
}

关键规则：

✅ 在根级别定义（不要在
```
@layer base
```
内部）
✅ 所有颜色值都使用
```
hsl()
```
包装
✅ 使用
```
.dark
```
实现暗黑模式（不要使用
```
.dark { @theme { } }
```
）

Step 2: Map Variables to Tailwind Utilities

步骤2：将变量映射到Tailwind工具类

css

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  /* ... map ALL CSS variables */
}

Why This Is Required:

Generates utility classes (
```
bg-background
```
,
```
text-primary
```
)
Without this,
```
bg-primary
```
etc. won't exist

css

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  /* ... 映射所有CSS变量 */
}

为什么这是必须的：

生成工具类（
```
bg-background
```
、
```
text-primary
```
）
没有这一步，
```
bg-primary
```
等类将不存在

Step 3: Apply Base Styles

步骤3：应用基础样式

css

@layer base {
  body {
    background-color: var(--background);  /* NO hsl() here */
    color: var(--foreground);
  }
}

Critical Rules:

✅ Reference variables directly:
```
var(--background)
```
❌ Never double-wrap:
```
hsl(var(--background))
```

css

@layer base {
  body {
    background-color: var(--background);  /* 此处不要使用hsl() */
    color: var(--foreground);
  }
}

关键规则：

✅ 直接引用变量：
```
var(--background)
```
❌ 不要双重包装：
```
hsl(var(--background))
```

Step 4: Result - Automatic Dark Mode

步骤4：效果 - 自动暗黑模式

tsx

<div className="bg-background text-foreground">
  {/* No dark: variants needed - theme switches automatically */}
</div>

tsx

<div className="bg-background text-foreground">
  {/* 不需要dark:变体 - 主题会自动切换 */}
</div>

Dark Mode Setup

暗黑模式配置

1. Create ThemeProvider

1. 创建ThemeProvider

See

reference/dark-mode.md

for full implementation or use template:

typescript

// Copy from: templates/theme-provider.tsx

查看

reference/dark-mode.md

获取完整实现，或使用模板：

typescript

// 复制自：templates/theme-provider.tsx

2. Wrap Your App

2. 包裹你的应用

typescript

// src/main.tsx
import { ThemeProvider } from '@/components/theme-provider'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ThemeProvider defaultTheme="dark" storageKey="vite-ui-theme">
      <App />
    </ThemeProvider>
  </React.StrictMode>,
)

typescript

// src/main.tsx
import { ThemeProvider } from '@/components/theme-provider'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ThemeProvider defaultTheme="dark" storageKey="vite-ui-theme">
      <App />
    </ThemeProvider>
  </React.StrictMode>,
)

3. Add Theme Toggle

3. 添加主题切换器

bash

pnpm dlx shadcn@latest add dropdown-menu

See

reference/dark-mode.md

for ModeToggle component code.

bash

pnpm dlx shadcn@latest add dropdown-menu

查看

reference/dark-mode.md

获取ModeToggle组件代码。

Critical Rules (MUST FOLLOW)

关键规则（必须遵守）

✅ Always Do:

✅ 必须做的事：

Wrap color values with
hsl()
in
:root
and
.dark

css

--background: hsl(0 0% 100%);  /* ✅ Correct */

Use
@theme inline
to map all CSS variables

css

@theme inline {
  --color-background: var(--background);
}

Set
"tailwind.config": ""
in components.json

json

{ "tailwind": { "config": "" } }

Delete
tailwind.config.ts
if it exists
Use
@tailwindcss/vite
plugin (NOT PostCSS)

Use
cn()
for conditional classes

typescript

import { cn } from "@/lib/utils"
<div className={cn("base", isActive && "active")} />

在
:root
和
.dark
中用
hsl()
包装颜色值

css

--background: hsl(0 0% 100%);  /* ✅ 正确 */

使用
@theme inline
映射所有CSS变量

css

@theme inline {
  --color-background: var(--background);
}

在components.json中设置
"tailwind.config": ""

json

{ "tailwind": { "config": "" } }

如果存在
tailwind.config.ts
，请删除它
使用
@tailwindcss/vite
插件（不要使用PostCSS）

使用
cn()
处理条件类

typescript

import { cn } from "@/lib/utils"
<div className={cn("base", isActive && "active")} />

❌ Never Do:

❌ 绝对不要做的事：

Put
:root
or
.dark
inside
@layer base

css

/* WRONG */
@layer base {
  :root { --background: hsl(...); }
}

Use
.dark { @theme { } }
pattern

css

/* WRONG - v4 doesn't support nested @theme */
.dark {
  @theme {
    --color-primary: hsl(...);
  }
}

Double-wrap colors

css

/* WRONG */
body {
  background-color: hsl(var(--background));
}

Use
tailwind.config.ts
for theme colors

typescript

/* WRONG - v4 ignores this */
export default {
  theme: {
    extend: {
      colors: { primary: 'hsl(var(--primary))' }
    }
  }
}

Use
@apply
directive (deprecated in v4)

Use
dark:
variants for semantic colors

tsx

/* WRONG */
<div className="bg-primary dark:bg-primary-dark" />

/* CORRECT */
<div className="bg-primary" />

将
:root
或
.dark
放在
@layer base
内部

css

/* 错误 */
@layer base {
  :root { --background: hsl(...); }
}

使用
.dark { @theme { } }
模式

css

/* 错误 - v4不支持嵌套@theme */
.dark {
  @theme {
    --color-primary: hsl(...);
  }
}

双重包装颜色

css

/* 错误 */
body {
  background-color: hsl(var(--background));
}

使用
tailwind.config.ts
定义主题颜色

typescript

/* 错误 - v4会忽略此配置 */
export default {
  theme: {
    extend: {
      colors: { primary: 'hsl(var(--primary))' }
    }
  }
}

使用
@apply
指令（v4中已废弃）

为语义化颜色使用
dark:
变体

tsx

/* 错误 */
<div className="bg-primary dark:bg-primary-dark" />

/* 正确 */
<div className="bg-primary" />

Semantic Color Tokens

语义化颜色令牌

Always use semantic names for colors:

css

:root {
  --destructive: hsl(0 84.2% 60.2%);        /* Red - errors, critical */
  --success: hsl(142.1 76.2% 36.3%);        /* Green - success states */
  --warning: hsl(38 92% 50%);               /* Yellow - warnings */
  --info: hsl(221.2 83.2% 53.3%);           /* Blue - info, primary */
}

Usage:

tsx

<div className="bg-destructive text-destructive-foreground">Critical</div>
<div className="bg-success text-success-foreground">Success</div>
<div className="bg-warning text-warning-foreground">Warning</div>
<div className="bg-info text-info-foreground">Info</div>

始终为颜色使用语义化名称：

css

:root {
  --destructive: hsl(0 84.2% 60.2%);        /* 红色 - 错误、关键状态 */
  --success: hsl(142.1 76.2% 36.3%);        /* 绿色 - 成功状态 */
  --warning: hsl(38 92% 50%);               /* 黄色 - 警告 */
  --info: hsl(221.2 83.2% 53.3%);           /* 蓝色 - 信息、主色 */
}

用法：

tsx

<div className="bg-destructive text-destructive-foreground">关键提示</div>
<div className="bg-success text-success-foreground">成功提示</div>
<div className="bg-warning text-warning-foreground">警告提示</div>
<div className="bg-info text-info-foreground">信息提示</div>

Common Issues & Quick Fixes

常见问题与快速修复

Symptom	Cause	Fix
`bg-primary` doesn't work	Missing `@theme inline` mapping	Add `@theme inline` block
Colors all black/white	Double `hsl()` wrapping	Use `var(--color)` not `hsl(var(--color))`
Dark mode not switching	Missing ThemeProvider	Wrap app in `<ThemeProvider>`
Build fails	`tailwind.config.ts` exists	Delete the file
Text invisible	Wrong contrast colors	Check color definitions in `:root` / `.dark`

See

reference/common-gotchas.md

for complete troubleshooting guide.

症状	原因	修复方案
`bg-primary` 不生效	缺少 `@theme inline` 映射	添加 `@theme inline` 块
颜色全为黑/白	双重 `hsl()` 包装	使用 `var(--color)` 而非 `hsl(var(--color))`
暗黑模式不切换	缺少ThemeProvider	用 `<ThemeProvider>` 包裹应用
构建失败	存在 `tailwind.config.ts` 文件	删除该文件
文本不可见	颜色对比度错误	检查 `:root` / `.dark` 中的颜色定义

查看

reference/common-gotchas.md

获取完整故障排除指南。

File Templates

文件模板

All templates are available in the

templates/

directory:

index.css - Complete CSS setup with all color variables
components.json - shadcn/ui v4 configuration
vite.config.ts - Vite + Tailwind plugin setup
tsconfig.app.json - TypeScript with path aliases
theme-provider.tsx - Dark mode provider with localStorage
utils.ts -
```
cn()
```
utility for class merging

Copy these files to your project and customize as needed.

所有模板都在

templates/

目录中：

index.css - 包含所有颜色变量的完整CSS配置
components.json - shadcn/ui v4配置
vite.config.ts - Vite + Tailwind插件配置
tsconfig.app.json - 带路径别名的TypeScript配置
theme-provider.tsx - 带localStorage的暗黑模式提供者
utils.ts - 用于类合并的
```
cn()
```
工具函数

将这些文件复制到你的项目中并根据需要自定义。

Complete Setup Checklist

配置检查清单

Vite + React + TypeScript project created
```
@tailwindcss/vite
```
installed (NOT postcss)
```
vite.config.ts
```
uses
```
tailwindcss()
```
plugin
```
tsconfig.json
```
has path aliases configured
```
components.json
```
exists with
```
"config": ""
```
NO
```
tailwind.config.ts
```
file exists
```
src/index.css
```
follows v4 pattern:
- ```
:root
```
  and
```
.dark
```
  at root level (not in @layer)
- Colors wrapped with
```
hsl()
```
- ```
@theme inline
```
  maps all variables
- ```
@layer base
```
  uses unwrapped variables
Theme provider installed and wrapping app
Dark mode toggle component created
Test theme switching works in browser

已创建Vite + React + TypeScript项目
已安装
```
@tailwindcss/vite
```
（不要安装postcss版本）
```
vite.config.ts
```
使用
```
tailwindcss()
```
插件
```
tsconfig.json
```
已配置路径别名
存在
```
components.json
```
且
```
"config": ""
```
不存在
```
tailwind.config.ts
```
文件
```
src/index.css
```
遵循v4模式：
- ```
:root
```
  和
```
.dark
```
  在根级别（不在@layer中）
- 颜色用
```
hsl()
```
  包装
- ```
@theme inline
```
  映射所有变量
- ```
@layer base
```
  使用未包装的变量
已安装ThemeProvider并包裹应用
已创建暗黑模式切换组件
已测试主题切换在浏览器中正常工作

Advanced Topics

进阶主题

Load

references/advanced-usage.md

for advanced patterns including:

Custom Colors: Add semantic colors beyond default palette
v3 Migration: See
```
references/migration-guide.md
```
for complete guide
Component Best Practices: Semantic tokens, cn() utility, composition patterns

Quick Example:

css

:root { --brand: hsl(280 65% 60%); }
@theme inline { --color-brand: var(--brand); }

Usage:

<div className="bg-brand">Branded</div>

For detailed patterns and component composition examples, load

references/advanced-usage.md

加载

references/advanced-usage.md

获取进阶模式，包括：

自定义颜色：添加默认调色板之外的语义化颜色
v3迁移：查看
```
references/migration-guide.md
```
获取完整指南
组件最佳实践：语义化令牌、cn()工具函数、组件组合模式

快速示例：

css

:root { --brand: hsl(280 65% 60%); }
@theme inline { --color-brand: var(--brand); }

用法：

<div className="bg-brand">品牌色区域</div>

如需详细模式和组件组合示例，请加载

references/advanced-usage.md

。

Dependencies

依赖项

✅ Install These

✅ 请安装这些

json

{
  "dependencies": {
    "tailwindcss": "^4.1.17",
    "@tailwindcss/vite": "^4.1.17",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.3.1",
    "@radix-ui/react-*": "latest",
    "lucide-react": "^0.554.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@types/node": "^24.10.1",
    "@vitejs/plugin-react": "^5.1.1",
    "vite": "^7.2.4",
    "typescript": "~5.9.3"
  }
}

json

{
  "dependencies": {
    "tailwindcss": "^4.1.17",
    "@tailwindcss/vite": "^4.1.17",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.3.1",
    "@radix-ui/react-*": "latest",
    "lucide-react": "^0.554.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@types/node": "^24.10.1",
    "@vitejs/plugin-react": "^5.1.1",
    "vite": "^7.2.4",
    "typescript": "~5.9.3"
  }
}

❌ NEVER Install These (Deprecated in v4)

❌ 绝对不要安装这些（v4中已废弃）

bash

undefined

bash

undefined

These packages will cause build errors:

这些包会导致构建错误：

bun add tailwindcss-animate # ❌ Deprecated

bun add tailwindcss-animate # ❌ 已废弃

or: npm install tailwindcss-animate # ❌ Deprecated

或：npm install tailwindcss-animate # ❌ 已废弃

bun add tw-animate-css # ❌ Doesn't exist


**If you see import errors for these packages**, remove them and use native CSS animations or `@tailwindcss/motion` instead.

---

bun add tw-animate-css # ❌ 不存在


**如果看到这些包的导入错误**，请删除它们，改用原生CSS动画或`@tailwindcss/motion`。

---

Tailwind v4 Plugins

Tailwind v4 插件

Tailwind v4 supports official plugins using the

@plugin

directive in CSS.

Quick Example:

css

@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

Common Error: ❌ WRONG:

@import "@tailwindcss/typography"

(doesn't work) ✅ CORRECT:

@plugin "@tailwindcss/typography"

(use @plugin directive)

Built-in Features: Container queries are now core (no

@tailwindcss/container-queries

plugin needed).

Load

references/plugins-reference.md

for complete documentation including Typography plugin (prose classes), Forms plugin, installation steps, and common plugin errors.

Tailwind v4支持在CSS中使用

@plugin

指令加载官方插件。

快速示例：

css

@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

常见错误： ❌ 错误写法：

@import "@tailwindcss/typography"

（无效） ✅ 正确写法：

@plugin "@tailwindcss/typography"

（使用@plugin指令）

内置功能： 容器查询现在是核心功能（不需要

@tailwindcss/container-queries

插件）。

加载

references/plugins-reference.md

获取完整文档，包括排版插件（prose类）、表单插件、安装步骤和常见插件错误。

Reference Documentation

参考文档

For deeper understanding, see:

common-gotchas.md - All the ways it can break (and fixes)
dark-mode.md - Complete dark mode implementation
migration-guide.md - Migrating hardcoded colors to CSS variables
plugins-reference.md - Official Tailwind v4 plugins (Typography, Forms)
advanced-usage.md - Custom colors and advanced patterns

如需深入了解，请查看：

common-gotchas.md - 所有可能出错的情况及修复方案
dark-mode.md - 完整的暗黑模式实现
migration-guide.md - 将硬编码颜色迁移到CSS变量的指南
plugins-reference.md - 官方Tailwind v4插件（排版、表单）
advanced-usage.md - 自定义颜色和进阶模式

When to Load References

何时加载参考文档

Load reference files based on user's specific needs:

根据用户的具体需求加载参考文件：

Load

references/common-gotchas.md

when:

当以下情况时加载

references/common-gotchas.md

：

User reports "colors not working" or "bg-primary doesn't exist"
Dark mode not switching properly
Build fails with Tailwind errors
User encounters any CSS/configuration issue
Debugging theme problems

用户反馈"颜色不生效"或"bg-primary不存在"
暗黑模式无法正常切换
构建时出现Tailwind错误
用户遇到任何CSS/配置问题
调试主题问题

Load

references/dark-mode.md

when:

当以下情况时加载

references/dark-mode.md

：

User asks to implement dark mode
Theme switching not working
Need ThemeProvider component code
Questions about system theme detection

用户询问如何实现暗黑模式
主题切换不工作
需要ThemeProvider组件代码
关于系统主题检测的问题

Load

references/migration-guide.md

when:

当以下情况时加载

references/migration-guide.md

：

Migrating from Tailwind v3 to v4
User has hardcoded colors to migrate
Questions about v3 → v4 changes
Need migration checklist

从Tailwind v3迁移到v4
用户有硬编码颜色需要迁移
关于v3 → v4变更的问题
需要迁移检查清单

Load

references/plugins-reference.md

when:

当以下情况时加载

references/plugins-reference.md

：

User needs Typography plugin (prose class)
User needs Forms plugin
Questions about @plugin directive
Plugin installation errors

用户需要排版插件（prose类）
用户需要表单插件
关于@plugin指令的问题
插件安装错误

Load

references/advanced-usage.md

when:

当以下情况时加载

references/advanced-usage.md

：

User asks about custom colors beyond defaults
Need advanced component patterns
Questions about component best practices
Component composition questions

用户询问默认之外的自定义颜色
需要进阶组件模式
关于组件最佳实践的问题
组件组合相关问题

Official Documentation

官方文档

shadcn/ui Vite Setup: https://ui.shadcn.com/docs/installation/vite
shadcn/ui Tailwind v4 Guide: https://ui.shadcn.com/docs/tailwind-v4
shadcn/ui Dark Mode (Vite): https://ui.shadcn.com/docs/dark-mode/vite
Tailwind v4 Docs: https://tailwindcss.com/docs
shadcn/ui Theming: https://ui.shadcn.com/docs/theming

shadcn/ui Vite配置：https://ui.shadcn.com/docs/installation/vite
shadcn/ui Tailwind v4指南：https://ui.shadcn.com/docs/tailwind-v4
shadcn/ui 暗黑模式（Vite）：https://ui.shadcn.com/docs/dark-mode/vite
Tailwind v4文档：https://tailwindcss.com/docs
shadcn/ui 主题化：https://ui.shadcn.com/docs/theming

Production Example

生产环境示例

This skill is based on the WordPress Auditor project:

Live: https://wordpress-auditor.webfonts.workers.dev
Stack: Vite + React 19 + Tailwind v4 + shadcn/ui + Cloudflare Workers
Dark Mode: Full system/light/dark support
Version: Tailwind v4.1.17 + shadcn/ui latest (Nov 2025)

All patterns in this skill have been validated in production.

Questions? Issues?

Check
```
reference/common-gotchas.md
```
first
Verify all steps in the 4-step architecture
Ensure
```
components.json
```
has
```
"config": ""
```
Delete
```
tailwind.config.ts
```
if it exists
Check official docs: https://ui.shadcn.com/docs/tailwind-v4

本技能基于WordPress Auditor项目：

在线地址：https://wordpress-auditor.webfonts.workers.dev
技术栈：Vite + React 19 + Tailwind v4 + shadcn/ui + Cloudflare Workers
暗黑模式：完整支持系统/浅色/深色模式
版本：Tailwind v4.1.17 + 最新版shadcn/ui（2025年11月）

本技能中的所有模式都已在生产环境中验证。

有问题？遇到故障？

先查看
```
reference/common-gotchas.md
```
验证四步架构中的所有步骤
确保
```
components.json
```
中
```
"config": ""
```
如果存在
```
tailwind.config.ts
```
请删除它
查看官方文档：https://ui.shadcn.com/docs/tailwind-v4

tailwind-v4-shadcn

Original

Translation

Tailwind v4 + shadcn/ui Production Stack

Tailwind v4 + shadcn/ui 生产环境技术栈

Table of Contents

目录

⚠️ BEFORE YOU START (READ THIS!)

⚠️ 开始前必读！

Why This Matters (Real-World Results)

为什么这很重要（实际效果）

Known Issues This Skill Prevents

本技能可预防的已知问题

Quick Start (5 Minutes - Follow This Exact Order)

快速开始（5分钟 - 严格按照以下顺序操作）

1. Install Dependencies

1. 安装依赖项

or: npm install tailwindcss @tailwindcss/vite

或：npm install tailwindcss @tailwindcss/vite

Note: Using pnpm for shadcn init due to known Bun compatibility issues

注意：由于已知的Bun兼容性问题，使用pnpm进行shadcn初始化

(bunx has "Script not found" and postinstall/msw problems)

(bunx存在"脚本未找到"和postinstall/msw问题)

2. Configure Vite

2. 配置Vite

3. Update components.json

3. 更新components.json

4. Delete tailwind.config.ts

4. 删除tailwind.config.ts

The Four-Step Architecture (CRITICAL)

四步架构（至关重要）

Step 1: Define CSS Variables at Root Level

步骤1：在根级别定义CSS变量

Step 2: Map Variables to Tailwind Utilities

步骤2：将变量映射到Tailwind工具类

Step 3: Apply Base Styles

步骤3：应用基础样式

Step 4: Result - Automatic Dark Mode

步骤4：效果 - 自动暗黑模式

Dark Mode Setup

暗黑模式配置

1. Create ThemeProvider

1. 创建ThemeProvider

2. Wrap Your App

2. 包裹你的应用

3. Add Theme Toggle

3. 添加主题切换器

Critical Rules (MUST FOLLOW)

关键规则（必须遵守）

✅ Always Do:

✅ 必须做的事：

❌ Never Do:

❌ 绝对不要做的事：

Semantic Color Tokens

语义化颜色令牌

Common Issues & Quick Fixes

常见问题与快速修复

File Templates

文件模板

Complete Setup Checklist

配置检查清单

Advanced Topics

进阶主题

Dependencies

依赖项

✅ Install These

✅ 请安装这些

❌ NEVER Install These (Deprecated in v4)

❌ 绝对不要安装这些（v4中已废弃）

These packages will cause build errors:

这些包会导致构建错误：

or: npm install tailwindcss-animate # ❌ Deprecated

或：npm install tailwindcss-animate # ❌ 已废弃

Tailwind v4 Plugins

Tailwind v4 插件

Reference Documentation

参考文档

When to Load References

何时加载参考文档

Load references/common-gotchas.md when:

Load
`references/common-gotchas.md`
when:

当以下情况时加载
`references/common-gotchas.md`
：

Load
`references/dark-mode.md`
when:

当以下情况时加载
`references/dark-mode.md`
：

Load
`references/migration-guide.md`
when:

当以下情况时加载
`references/migration-guide.md`
：

Load
`references/plugins-reference.md`
when:

当以下情况时加载
`references/plugins-reference.md`
：

Load
`references/advanced-usage.md`
when:

当以下情况时加载
`references/advanced-usage.md`
：