shadcn

Shadcn UI 开发指南

本技能提供了在此项目中使用 shadcn/ui 组件的指南、模式和最佳实践。

快速开始

1. 核心模式：阅读 references/patterns.md，了解完整的样式、主题和组件模式。
2. Tailwind 集成：如需了解 Tailwind CSS 模式，请使用 tailwindcss 技能。

核心理念

• 所有权：Shadcn 采用复制粘贴方式，而非依赖项——代码由你掌控。
• 自定义：组件旨在根据你的需求进行修改。
• 无障碍性：基于 Radix UI 原语构建，确保无障碍性。
• 灵活性：使用 Tailwind CSS 设置样式，便于自定义。

重要：设计令牌的使用

始终使用设计系统令牌，以确保兼容主题切换：

必需的令牌：

• 背景：bg-background、bg-card、bg-muted、bg-popover
• 文本：text-foreground、text-muted-foreground、text-card-foreground
• 边框：border-border、border-input、border-ring
• 操作：bg-primary text-primary-foreground、bg-secondary text-secondary-foreground
• 状态：bg-destructive text-destructive-foreground、bg-accent text-accent-foreground

切勿使用 bg-white、text-black、border-gray-200 等显式颜色——它们会破坏主题切换。

常见任务

添加组件

使用 CLI 添加组件，然后按需自定义：

npx shadcn@latest add button card dialog

扩展组件

在保留无障碍性的同时添加自定义属性和变体：

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  loading?: boolean
}

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, loading, children, ...props }, ref) => {
    return (
      <button
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        disabled={loading || props.disabled}
        {...props}
      >
        {loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
        {children}
      </button>
    )
  }
)

复合组件

始终使用单独的导出，而非命名空间属性：

// CORRECT
export const CardTech = CardTechRoot;
export const CardTechHeader = CardHeader;
export const CardTechTitle = CardTitle;
export const CardTechContent = CardContent;

// WRONG - Do not use
export const CardTech = Object.assign(CardTechRoot, {
  Header: CardHeader,
  Content: CardContent,
});

保留无障碍性

切勿移除 Radix UI 的无障碍属性：

<Dialog>
  <DialogTrigger asChild>
    <Button>Open Dialog</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Accessible Title</DialogTitle>
      <DialogDescription>
        This description helps screen readers understand the dialog's purpose
      </DialogDescription>
    </DialogHeader>
  </DialogContent>
</Dialog>

主题

在 globals.css 中为所有颜色值使用 CSS 变量：

@layer base {
  :root {
    --success: 142 76% 36%;
    --success-foreground: 355 100% 100%;
  }

  .dark {
    --success: 142 76% 46%;
    --success-foreground: 142 76% 10%;
  }
}

验证清单

完成涉及 shadcn/ui 的任务前：

• 确认所有颜色均使用设计令牌，而非显式值。
• 确保保留 Radix UI 的无障碍属性。
• 测试键盘导航是否正常。
• 为复合组件使用单独的导出（而非命名空间属性）。
• 运行类型检查（pnpm run typecheck）和测试（pnpm run test）。

如需了解完整模式、组件示例和详细指南，请阅读 references/patterns.md。