此命令：

• 下载组件源代码（根据您的配置适配：Radix 或 Base UI）
• 安装所需的依赖项
• 将文件放置在 components/ui/ 目录下
• 更新您的 components.json 配置

B. 手动集成

1. 使用 get_component 获取源代码
2. 在 components/ui/[component-name].tsx 中创建文件
3. 手动安装对等依赖项
4. 如果需要，调整导入语句

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+)
• Primitives：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

cn() 工具函数

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

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

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

这允许您：

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

自定义最佳实践

1. 主题自定义

在 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%;
    /* ... 深色模式覆盖 */
  }
}

2. 组件变体

使用 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",
    },
  }
)

3. 扩展组件

在 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 区块（认证表单、仪表板等）：

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

区块按类别组织：

• 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 版本
• 检查文档以了解版本间的破坏性变更

验证与质量

提交组件前：

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

资源

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

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

示例

查看 examples/ 目录以获取：

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

每周安装量

1

代码仓库

codereaper1/sti…h-skills

首次出现

1 天前

安全审计

Gen Agent Trust HubPassSocketFailSnykWarn

安装于

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1

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

1. Use get_component to retrieve the source code
2. Create the file in components/ui/[component-name].tsx
3. Install peer dependencies manually
4. 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.):

1. List available blocks : Use list_blocks with optional category filter
2. Get block source : Use get_block with the block name
3. 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:

1. Type check : Run tsc --noEmit to verify TypeScript
2. Lint : Run your linter to catch style issues
3. Test accessibility : Use tools like axe DevTools
4. Visual QA : Test in light and dark modes
5. 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

1

Repository

codereaper1/sti…h-skills

First Seen

1 day ago

Security Audits

Gen Agent Trust HubPassSocketFailSnykWarn

Installed on

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1