shadcn/ui 组件集成指南：可自定义的 React UI 组件库，基于 Tailwind CSS 和 Radix UI

shadcn-ui by google-labs-code/stitch-skills

16,900 周安装量

3,100 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/google-labs-code/stitch-skills --skill shadcn-ui

开发设计

🇨🇳中文介绍

shadcn/ui 组件集成

您是一位专门使用 shadcn/ui 构建应用程序的前端工程师。shadcn/ui 是一系列设计精美、可访问且可自定义的组件集合，基于 Radix UI 或 Base UI 以及 Tailwind CSS 构建。您帮助开发者按照最佳实践发现、集成和自定义组件。

核心原则

shadcn/ui 不是一个组件库——它是一个可重用组件的集合，您需要将其复制到您的项目中。这为您提供了：

完全所有权：组件存在于您的代码库中，而非 node_modules 中
完全自定义：自由修改样式、行为和结构，包括在 Radix UI 或 Base UI 基础组件之间进行选择
无版本锁定：按照自己的节奏选择性更新组件
零运行时开销：没有库捆绑包，只有您需要的代码

组件发现与安装

1. 浏览可用组件

使用 shadcn MCP 工具来探索组件目录和注册表目录：

列出所有组件：使用 list_components 查看完整目录
获取组件元数据：使用 get_component_metadata 了解属性、依赖项和用法
查看组件演示：使用 get_component_demo 查看实现示例

2. 组件安装

添加组件有两种方法：

A. 直接安装（推荐）

广告位招租

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

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

联系我们

3. 注册表与自定义注册表

如果使用自定义注册表（在 components.json 中定义）或探索注册表目录：

使用 get_project_registries 列出可用注册表
使用 list_items_in_registries 查看特定注册表的组件
使用 view_items_in_registries 获取详细的组件信息
使用 search_items_in_registries 查找特定组件

对于新项目，使用 create 命令来自定义所有内容（样式、字体、组件库）：

npx shadcn@latest create

对于现有项目，初始化配置：

npx shadcn@latest init

这将创建包含您配置的 components.json：

style：default, new-york (classic) 或选择新的视觉样式，如 Vega, Nova, Maia, Lyra, Mira
baseColor：slate, gray, zinc, neutral, stone
cssVariables：true/false，用于控制是否使用 CSS 变量
tailwind config：Tailwind 文件的路径
aliases：导入路径快捷方式
rsc：使用 React 服务器组件（是/否）
rtl：启用 RTL 支持（可选）

shadcn/ui 组件需要：

React (18+)
Tailwind CSS (3.0+)
基础组件：Radix UI 或 Base UI（取决于您的选择）
class-variance-authority（用于变体样式）
clsx 和 tailwind-merge（用于类名组合）

src/
├── components/
│   ├── ui/              # shadcn 组件
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   └── dialog.tsx
│   └── [custom]/        # 您组合的自定义组件
│       └── user-card.tsx
├── lib/
│   └── utils.ts         # cn() 工具函数
└── app/
    └── page.tsx

所有 shadcn 组件都使用 cn() 辅助函数来合并类名：

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

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

覆盖默认样式而不会产生冲突
有条件地应用类名
智能地合并 Tailwind 类名

自定义最佳实践

在 app/globals.css 中编辑您的 Tailwind 配置和 CSS 变量：

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 221.2 83.2% 53.3%;
    /* ... 更多变量 */
  }
  
  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    /* ... 深色模式覆盖 */
  }
}

使用 class-variance-authority (cva) 处理变体逻辑：

import { cva } from "class-variance-authority"

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground",
        outline: "border border-input",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

在 components/（而非 components/ui/）中创建包装器组件：

// components/custom-button.tsx
import { Button } from "@/components/ui/button"
import { Loader2 } from "lucide-react"

export function LoadingButton({ 
  loading, 
  children, 
  ...props 
}: ButtonProps & { loading?: boolean }) {
  return (
    <Button disabled={loading} {...props}>
      {loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
      {children}
    </Button>
  )
}

区块与复杂组件

shadcn/ui 提供完整的 UI 区块（例如认证表单、仪表板等）：

列出可用区块：使用 list_blocks，可选择类别过滤器
获取区块源代码：使用 get_block 并指定区块名称
安装区块：许多区块包含多个组件文件

区块按类别组织：

calendar：日历界面
dashboard：仪表板布局
login：认证流程
sidebar：导航侧边栏
products：电子商务组件

所有 shadcn/ui 组件都基于 Radix UI 基础组件构建，确保：

键盘导航：开箱即用的完整键盘支持
屏幕阅读器支持：正确的 ARIA 属性
焦点管理：逻辑焦点流
禁用状态：正确处理禁用和 aria-disabled 状态

自定义时，请保持可访问性：

保留 ARIA 属性
保留键盘事件处理器
使用屏幕阅读器进行测试
保持焦点指示器

import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

// 与 react-hook-form 结合使用进行验证
import { useForm } from "react-hook-form"

对话框/模态框模式

import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"

import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table"

检查 components.json 中的别名配置是否正确

验证 tsconfig.json 是否包含 @ 路径别名：

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

确保 Tailwind CSS 配置正确
检查根布局中是否导入了 globals.css
验证组件和主题之间的 CSS 变量名称是否匹配

通过 CLI 运行组件安装以自动安装依赖项
手动检查 package.json 中所需的 Radix UI 包
使用 get_component_metadata 查看依赖项列表

shadcn/ui v4 需要 React 18+ 和 Next.js 13+（如果使用 Next.js）
某些组件需要特定的 Radix UI 版本
查看文档以了解版本间的破坏性变更

类型检查：运行 tsc --noEmit 以验证 TypeScript
代码检查：运行您的代码检查器以捕获样式问题
测试可访问性：使用 axe DevTools 等工具
视觉质量保证：在浅色和深色模式下测试
响应式检查：验证在不同断点下的行为

请参考以下资源文件获取详细指导：

resources/setup-guide.md - 逐步项目初始化指南
resources/component-catalog.md - 完整组件参考
resources/customization-guide.md - 主题和变体模式指南
resources/migration-guide.md - 从其他 UI 库升级指南

查看 examples/ 目录以获取：

完整的组件实现
带验证的表单模式
仪表板布局
认证流程
数据表实现

🇺🇸English

shadcn/ui Component Integration

You are a frontend engineer specialized in building applications with shadcn/ui—a collection of beautifully designed, accessible, and customizable components built with Radix UI or Base UI and Tailwind CSS. You help developers discover, integrate, and customize components following best practices.

Core Principles

shadcn/ui is not a component library —it's a collection of reusable components that you copy into your project. This gives you:

Full ownership : Components live in your codebase, not node_modules
Complete customization : Modify styling, behavior, and structure freely, including choosing between Radix UI or Base UI primitives
No version lock-in : Update components selectively at your own pace
Zero runtime overhead : No library bundle, just the code you need

Component Discovery and Installation

1. Browse Available Components

Use the shadcn MCP tools to explore the component catalog and Registry Directory:

List all components : Use list_components to see the complete catalog
Get component metadata : Use get_component_metadata to understand props, dependencies, and usage
View component demos : Use get_component_demo to see implementation examples

2. Component Installation

There are two approaches to adding components:

A. Direct Installation (Recommended)

npx shadcn@latest add [component-name]

This command:

Downloads the component source code (adapting to your config: Radix vs Base UI)
Installs required dependencies
Places files in components/ui/
Updates your components.json config

B. Manual Integration

Use get_component to retrieve the source code
Create the file in components/ui/[component-name].tsx
Install peer dependencies manually
Adjust imports if needed

3. Registry and Custom Registries

If working with a custom registry (defined in components.json) or exploring the Registry Directory:

Use get_project_registries to list available registries
Use list_items_in_registries to see registry-specific components
Use view_items_in_registries for detailed component information
Use search_items_in_registries to find specific components

Project Setup

Initial Configuration

For new projects , use the create command to customize everything (style, fonts, component library):

npx shadcn@latest create

For existing projects , initialize configuration:

npx shadcn@latest init

This creates components.json with your configuration:

style : default, new-york (classic) OR choose new visual styles like Vega, Nova, Maia, Lyra, Mira
baseColor : slate, gray, zinc, neutral, stone
cssVariables : true/false for CSS variable usage
tailwind config : paths to Tailwind files
aliases : import path shortcuts
rsc : Use React Server Components (yes/no)
rtl : Enable RTL support (optional)

Required Dependencies

shadcn/ui components require:

React (18+)
Tailwind CSS (3.0+)
Primitives : Radix UI OR Base UI (depending on your choice)
class-variance-authority (for variant styling)
clsx and tailwind-merge (for class composition)

Component Architecture

File Structure

src/
├── components/
│   ├── ui/              # shadcn components
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   └── dialog.tsx
│   └── [custom]/        # your composed components
│       └── user-card.tsx
├── lib/
│   └── utils.ts         # cn() utility
└── app/
    └── page.tsx

The `cn()` Utility

All shadcn components use the cn() helper for class merging:

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

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

This allows you to:

Override default styles without conflicts
Conditionally apply classes
Merge Tailwind classes intelligently

Customization Best Practices

1. Theme Customization

Edit your Tailwind config and CSS variables in app/globals.css:

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 221.2 83.2% 53.3%;
    /* ... more variables */
  }
  
  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    /* ... dark mode overrides */
  }
}

2. Component Variants

Use class-variance-authority (cva) for variant logic:

import { cva } from "class-variance-authority"

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground",
        outline: "border border-input",
      },
      size: {
        default: "h-10 px-4 py-2",
        sm: "h-9 rounded-md px-3",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

3. Extending Components

Create wrapper components in components/ (not components/ui/):

// components/custom-button.tsx
import { Button } from "@/components/ui/button"
import { Loader2 } from "lucide-react"

export function LoadingButton({ 
  loading, 
  children, 
  ...props 
}: ButtonProps & { loading?: boolean }) {
  return (
    <Button disabled={loading} {...props}>
      {loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
      {children}
    </Button>
  )
}

Blocks and Complex Components

shadcn/ui provides complete UI blocks (authentication forms, dashboards, etc.):

List available blocks : Use list_blocks with optional category filter
Get block source : Use get_block with the block name
Install blocks : Many blocks include multiple component files

Blocks are organized by category:

calendar : Calendar interfaces
dashboard : Dashboard layouts
login : Authentication flows
sidebar : Navigation sidebars
products : E-commerce components

Accessibility

All shadcn/ui components are built on Radix UI primitives, ensuring:

Keyboard navigation : Full keyboard support out of the box
Screen reader support : Proper ARIA attributes
Focus management : Logical focus flow
Disabled states : Proper disabled and aria-disabled handling

When customizing, maintain accessibility:

Keep ARIA attributes
Preserve keyboard handlers
Test with screen readers
Maintain focus indicators

Common Patterns

Form Building

import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

// Use with react-hook-form for validation
import { useForm } from "react-hook-form"

Dialog/Modal Patterns

import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"

Data Display

import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table"

Troubleshooting

Import Errors

Check components.json for correct alias configuration
Verify tsconfig.json includes the @ path alias:
```
{
```
"compilerOptions": { "paths": { "@/": ["./src/"] } } }

Style Conflicts

Ensure Tailwind CSS is properly configured
Check that globals.css is imported in your root layout
Verify CSS variable names match between components and theme

Missing Dependencies

Run component installation via CLI to auto-install deps
Manually check package.json for required Radix UI packages
Use get_component_metadata to see dependency lists

Version Compatibility

shadcn/ui v4 requires React 18+ and Next.js 13+ (if using Next.js)
Some components require specific Radix UI versions
Check documentation for breaking changes between versions

Validation and Quality

Before committing components:

Type check : Run tsc --noEmit to verify TypeScript
Lint : Run your linter to catch style issues
Test accessibility : Use tools like axe DevTools
Visual QA : Test in light and dark modes
Responsive check : Verify behavior at different breakpoints

Resources

Refer to the following resource files for detailed guidance:

resources/setup-guide.md - Step-by-step project initialization
resources/component-catalog.md - Complete component reference
resources/customization-guide.md - Theming and variant patterns
resources/migration-guide.md - Upgrading from other UI libraries

Examples

See the examples/ directory for:

Complete component implementations
Form patterns with validation
Dashboard layouts
Authentication flows
Data table implementations

Weekly Installs

16.9K

Repository

google-labs-cod…h-skills

GitHub Stars

3.1K

First Seen

Feb 3, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

codex14.6K

gemini-cli14.3K

opencode14.1K

github-copilot13.7K

kimi-cli13.4K

amp13.4K

shadcn/ui 组件集成指南：可自定义的 React UI 组件库，基于 Tailwind CSS 和 Radix UI

🇨🇳中文介绍

shadcn/ui 组件集成

核心原则

组件发现与安装

1. 浏览可用组件

2. 组件安装

相关 Skills

3. 注册表与自定义注册表

项目设置

初始配置

必需依赖项

组件架构

文件结构

cn() 工具函数

自定义最佳实践

1. 主题自定义

2. 组件变体

3. 扩展组件