shadcn-setup

shadcn/ui 设置

使用现代的 CSS 优先 Tailwind v4 设置来配置 shadcn/ui，而不是已弃用的 v3 方案。

授权范围

仅在用户的请求和现有授权范围内操作；加载此技能不会授予新的权限。仅要求报告时，只提供报告；遵守调用方对目标、主机、提供商和费用的限制；扩展范围前先询问，并将这些限制转告受委派方。

契约

输入：

• 项目根目录（默认为当前工作目录）。
• 可选：主题名称（zinc、slate、stone 等）、组件列表、路由器类型（app-router 或 pages-router）。

输出：

• globals.css，包含 @import "tailwindcss" 和完整的 @theme 令牌块。
• components.json，使用 CSS 优先的 shadcn 配置。
• src/lib/utils.ts，包含 cn() 辅助函数。
• 已安装的软件包：class-variance-authority、clsx、tailwind-merge、lucide-react、tailwindcss、@tailwindcss/postcss。

创建/修改：

• src/app/globals.css（创建或覆盖）。
• components.json（创建或覆盖）。
• src/lib/utils.ts（创建）。
• package.json（通过 bun add 更新依赖）。
• postcss.config.mjs（如果不存在则创建）。

外部副作用：

• 运行 bun add 安装软件包。
• 对指定的组件运行 bunx shadcn@latest add。

需要确认：

• 仅应用明确请求的设置或迁移。仅调用此技能并不意味着有权替换现有样式或配置。
• 覆盖文件或安装超出该范围的组件前，先确认。

委派给：

• 使用 bunx shadcn@latest add 安装单个组件。

用途

重要：shadcn/ui CLI 和 AI 助手经常默认生成 Tailwind v3 配置。此技能可确保：

• 使用 Tailwind v4 的 CSS 优先配置
• 包含正确的 @theme 块和 shadcn 颜色令牌
• 不包含已弃用的 tailwind.config.js 文件
• 使用正确的依赖版本

适用场景

• 使用 shadcn/ui 设置新的 Next.js 项目
• 在现有项目中添加 shadcn/ui
• 从 shadcn + Tailwind v3 迁移到 v4
• 重置损坏的 shadcn 配置

快速开始

# Install core dependencies
bun add class-variance-authority clsx tailwind-merge lucide-react
bun add -D tailwindcss @tailwindcss/postcss

# Initialize shadcn (CSS-first, no tailwind.config)
bunx shadcn@latest init

# Install specific components
bunx shadcn@latest add button card input dialog

# Or install an essential starter set
bunx shadcn@latest add button card input label dialog dropdown-menu toast

安装内容

依赖项

完整的依赖项配置块请参见 references/examples.md（§ 依赖版本示例）。

文件结构

完整的目录树请参见 references/examples.md（§ 生成的文件结构）。

Tailwind v4 + shadcn CSS 配置

此技能使用 @import "tailwindcss" 和 @theme 块生成 CSS 优先配置，其中包含所有 shadcn 颜色令牌和圆角半径变量。

完整的令牌块请参见 ${CLAUDE_SKILL_DIR}/references/shadcn-theme-tokens.md（构建 globals.css 文件时加载）。

可用主题

主题	描述
default	shadcn 默认主题（中性灰）
zinc	基于锌色的中性色
slate	基于石板色的冷中性色
stone	基于石色的暖中性色
gray	纯灰色
neutral	真正的中性色
red	红色主色
rose	玫瑰色主色
orange	橙色主色
green	绿色主色
blue	蓝色主色
yellow	黄色主色
violet	紫色主色

常用组件

安装常用组件：

# Essential set
bunx shadcn@latest add button card input label dialog dropdown-menu toast

# Form-focused
bunx shadcn@latest add form input label select checkbox radio-group switch textarea

# Dashboard
bunx shadcn@latest add card table tabs badge avatar dropdown-menu sheet sidebar

components.json 配置

完整配置请参见 references/examples.md（§ components.json 完整示例）。由于设置使用 v4 的 CSS 优先配置，tailwind.config 字段保持为空。

Utils 文件

// src/lib/utils.ts
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

设置后的用法

添加组件

# Using bunx (recommended with bun)
bunx shadcn@latest add button

# Multiple components
bunx shadcn@latest add card dialog dropdown-menu

使用组件

组合示例请参见 references/examples.md（§ 使用组件示例）。

深色模式支持

默认情况下，CSS 使用 prefers-color-scheme。如需手动切换，请参见 references/examples.md（§ 深色模式 — 手动切换提供方），了解提供方组件和基于类的 CSS 覆盖。

故障排除

“shadcn CLI 创建了 tailwind.config.js”

删除该文件。CLI 有时会生成 v3 配置。运行：

rm tailwind.config.js tailwind.config.ts

组件样式不正确

1. 检查是否在布局文件中导入了 globals.css
2. 确认 @import "tailwindcss" 位于顶部
3. 确保 @theme 块包含所有必需的变量

组件类型错误

运行：

bun add -D @types/react @types/react-dom

未找到 cn() 工具

创建 src/lib/utils.ts：

import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

验证

设置完成后，验证没有引入 v3 模式：

# Should return nothing (no v3 tailwind.config files)
find . -name "tailwind.config.*" -not -path "*/node_modules/*"

# Should return nothing (no @apply directives)
grep -r "@apply" src/ --include="*.css" 2>/dev/null

# Verify the @import directive is present
grep "@import \"tailwindcss\"" src/app/globals.css