[!info] related notes

• 所属：shadcn/ui React MOC
• 历史：旧版学习记录
• 相邻实现：shadcn/vue
• 相关: Tailwind CSS
• 实践: BodySense 项目 MOC

shadcn/ui 组件库

核心理念

传统组件库（Ant Design、Material UI）通过 npm install 引入打包后的 JS。shadcn/ui 反其道：把组件源码复制到你的项目里。

好处：

• 源码就是你的代码，随意改
• 只包含你实际使用的组件
• 组件源码可独立修改，但更新上游源码时仍需审阅并合并本地定制
• CLI 会按组件需要安装依赖；源码分发不等于没有 node_modules 依赖

使用方式

已有项目先按对应框架指南检查 Tailwind、路径别名及配置；CLI 初始化会修改配置和安装依赖。下列命令使用当前 CLI 包名 shadcn：

npx shadcn@latest init
npx shadcn@latest add button card input

生成路径由 components.json 和项目别名决定，并非固定写入 /components/ui。React 的组件源码与 Vue 移植版不能直接互换。

组件变体

以下为用 class-variance-authority 定义变体的独立简化示例；不是某个版本生成组件的完整源码：

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

const buttonVariants = cva("inline-flex items-center", {
  variants: {
    variant: {
      default: "bg-primary text-primary-foreground",
      destructive: "bg-destructive text-destructive-foreground",
      outline: "border border-input",
      ghost: "hover:bg-accent",
    },
    size: {
      default: "h-10 px-4 py-2",
      sm: "h-9 px-3",
      lg: "h-11 px-8",
    },
  },
});

与 Tailwind CSS 4.x 配合

Tailwind CSS 4.x 使用 CSS-first 配置。主题变量可通过 @theme inline 映射到工具类，下面仅示范主色：

:root {
  --primary: oklch(0.65 0.24 275);
  --primary-foreground: white;
}
@theme inline {
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
}

修改这些变量会影响使用对应 token 的组件；完整主题还包含背景、文字、边框等变量及暗色覆盖。主题映射不等于自动启用 .dark，详见 主题与 token 和 暗色模式。

定制

组件源码由项目维护，可直接修改或包装。依赖升级、重新生成源码和可访问性回归都仍需验证：

// components/ui/button.tsx
// 改默认样式、加新变体、调整布局，随意

与 Ant Design 的对比

维度	shadcn/ui	Ant Design
安装方式	复制源码	npm install
定制	直接改源码	主题 token
包体积	取决于所选组件、依赖及构建	取决于导入方式及构建
设计语言	中性	Ant Design 风格

选型应结合所需组件、设计语言、已有团队经验和后续源码维护成本，不能仅凭“定制”或“快速”二选一。

来源

• shadcn/ui 介绍
• CLI
• 主题