Tailwind v4 + shadcn/ui 生产级技术栈配置指南：5分钟快速搭建，避免常见错误

tailwind-v4-shadcn by secondsky/claude-skills

447 周安装量

90 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/secondsky/claude-skills --skill tailwind-v4-shadcn

开发 JavaScript 框架

🇨🇳中文介绍

Tailwind v4 + shadcn/ui 生产级技术栈

生产环境验证 : WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev) 最后更新 : 2025-12-04 状态 : 生产就绪 ✅

⚠️ 开始之前（请务必阅读！）

对 AI 助手至关重要 : 如果你是 Claude Code 正在帮助用户设置 Tailwind v4：

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

用户需要执行的操作 : 告诉 Claude 首先检查此技能！

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

为何这很重要（实际效果）

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

此技能可防止的已知问题

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

当技能激活时，所有这些都会自动处理。

快速开始（5 分钟 - 严格按照此顺序）

bun add tailwindcss @tailwindcss/vite
# 或: npm install tailwindcss @tailwindcss/vite

bun add -d @types/node

# 注意：由于已知的 Bun 兼容性问题，使用 pnpm 进行 shadcn init
# (bunx 存在 "Script not found" 和 postinstall/msw 问题)
pnpm dlx shadcn@latest init

// 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. 更新 components.json

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

4. 删除 tailwind.config.ts

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

四步架构（关键）

此模式是强制性的 - 跳过步骤会破坏你的主题。

步骤 1：在根级别定义 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 { } }）

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

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

为何需要此步骤：

生成工具类 (bg-background, text-primary)
没有此步骤，bg-primary 等将不存在

步骤 3：应用基础样式

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

✅ 直接引用变量：var(--background)
❌ 切勿双重包装：hsl(var(--background))

步骤 4：结果 - 自动深色模式

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

1. 创建 ThemeProvider

完整实现请查看 reference/dark-mode.md 或使用模板：

// 从以下位置复制：templates/theme-provider.tsx

2. 包装你的应用

// 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. 添加主题切换

pnpm dlx shadcn@latest add dropdown-menu

ModeToggle 组件代码请查看 reference/dark-mode.md。

关键规则（必须遵守）

✅ 始终要做的：

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

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

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

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

在 components.json 中设置 "tailwind.config": ""
```
{ "tailwind": { "config": "" } }
```
如果存在则删除 tailwind.config.ts
使用 @tailwindcss/vite 插件（而不是 PostCSS）

使用 cn() 处理条件类

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

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

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

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

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

双重包装颜色

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

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

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

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

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

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

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

语义化颜色令牌

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

: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%);           /* 蓝色 - 信息、主要 */
}

<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>

常见问题与快速修复

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

完整故障排除指南请查看 reference/common-gotchas.md。

所有模板都可在 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() 工具函数

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

完整设置检查清单

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 使用未包装的变量
主题提供者已安装并包装应用
深色模式切换组件已创建
在浏览器中测试主题切换是否正常工作

加载 references/advanced-usage.md 以获取高级模式，包括：

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

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

用法：<div className="bg-brand">品牌化</div>

有关详细模式和组件组合示例，请加载 references/advanced-usage.md。

{
  "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"
  }
}

❌ 切勿安装这些（v4 中已弃用）

# 这些包会导致构建错误：
bun add tailwindcss-animate  # ❌ 已弃用
# 或: npm install tailwindcss-animate  # ❌ 已弃用

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

如果你看到这些包的导入错误，请移除它们并使用原生 CSS 动画或 @tailwindcss/motion 替代。

Tailwind v4 支持使用 CSS 中的 @plugin 指令的官方插件。

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

常见错误： ❌ 错误：@import "@tailwindcss/typography" (不起作用) ✅ 正确：@plugin "@tailwindcss/typography" (使用 @plugin 指令)

内置功能： 容器查询现在是核心功能（不需要 @tailwindcss/container-queries 插件）。

完整文档请加载 references/plugins-reference.md，包括 Typography 插件 (prose 类)、Forms 插件、安装步骤和常见插件错误。

如需更深入理解，请查看：

common-gotchas.md - 所有可能出错的方式（及修复方法）
dark-mode.md - 完整的深色模式实现
migration-guide.md - 将硬编码颜色迁移到 CSS 变量
plugins-reference.md - 官方 Tailwind v4 插件 (Typography, Forms)
advanced-usage.md - 自定义颜色和高级模式

何时加载参考文档

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

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

用户报告"颜色不起作用"或"bg-primary 不存在"
深色模式无法正常切换
构建因 Tailwind 错误而失败
用户遇到任何 CSS/配置问题
调试主题问题

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

用户要求实现深色模式
主题切换不起作用
需要 ThemeProvider 组件代码
关于系统主题检测的问题

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

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

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

用户需要 Typography 插件 (prose 类)
用户需要 Forms 插件
关于 @plugin 指令的问题
插件安装错误

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

用户询问超出默认值的自定义颜色
需要高级组件模式
关于组件最佳实践的问题
组件组合问题

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

此技能基于 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

🇺🇸English

Tailwind v4 + shadcn/ui Production Stack

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

Before You Start
Quick Start
Four-Step Architecture
Dark Mode Setup
Critical Rules
Semantic Color Tokens
Common Issues & Fixes
File Templates
Setup Checklist
Advanced Topics
Dependencies
Tailwind v4 Plugins
Reference Documentation
When to Load References

⚠️ 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"

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

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.

Quick Start (5 Minutes - Follow This Exact Order)

1. Install Dependencies

bun add tailwindcss @tailwindcss/vite
# or: npm install tailwindcss @tailwindcss/vite

bun add -d @types/node

# Note: Using pnpm for shadcn init due to known Bun compatibility issues
# (bunx has "Script not found" and postinstall/msw problems)
pnpm dlx shadcn@latest init

2. Configure Vite

// 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

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

4. Delete tailwind.config.ts

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

The Four-Step Architecture (CRITICAL)

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

Step 1: Define CSS Variables at Root Level

/* 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 { } })

Step 2: Map Variables to Tailwind Utilities

@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

Step 3: Apply Base Styles

@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))

Step 4: Result - Automatic Dark Mode

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

Dark Mode Setup

1. Create ThemeProvider

See reference/dark-mode.md for full implementation or use template:

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

2. Wrap Your App

// 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

pnpm dlx shadcn@latest add dropdown-menu

See reference/dark-mode.md for ModeToggle component code.

Critical Rules (MUST FOLLOW)

✅ Always Do:

Wrap color values withhsl() in :root and .dark

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

Use@theme inline to map all CSS variables

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

Set"tailwind.config": "" in components.json
```
{ "tailwind": { "config": "" } }
```
Deletetailwind.config.ts if it exists

❌ Never Do:

Put:root or .dark inside @layer base

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

Use.dark { @theme { } } pattern

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

Double-wrap colors

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

Usetailwind.config.ts for theme colors

Semantic Color Tokens

Always use semantic names for colors:

: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:

<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>

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>`

See reference/common-gotchas.md for complete troubleshooting guide.

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.

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)

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:

: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.

Dependencies

✅ Install These

{
  "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)

# These packages will cause build errors:
bun add tailwindcss-animate  # ❌ Deprecated
# or: npm install tailwindcss-animate  # ❌ Deprecated

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.

Tailwind v4 Plugins

Tailwind v4 supports official plugins using the @plugin directive in CSS.

Quick Example:

@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.

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

When to Load References

Load reference files based on user's specific needs:

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

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

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

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

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

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

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

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

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

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

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

Weekly Installs

447

Repository

secondsky/claude-skills

GitHub Stars

First Seen

Jan 22, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode401

codex383

gemini-cli382

cursor372

claude-code358

github-copilot356

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

103,800 周安装

Use@tailwindcss/vite plugin (NOT PostCSS)

Usecn() for conditional classes

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

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

Use@apply directive (deprecated in v4)

Usedark: variants for semantic colors

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

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

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