shadcn-ui 项目架构与设计深度分析报告#

packages:
  - "apps/*"
  - "packages/*"
  - "!**/test/**"
  - "!**/fixtures/**"
  - "!**/temp/**"
  - "!packages/tests/temp/**"
  - "!deprecated/**"

// Registry Item 类型层级
export const registryItemTypeSchema = z.enum([
  "registry:lib",       // 工具库 (utils.ts)
  "registry:block",     // 页面块 (完整的页面区块)
  "registry:component", // 通用组件
  "registry:ui",        // UI 组件 (Button, Input 等)
  "registry:hook",      // 自定义 hooks
  "registry:page",      // 完整页面
  "registry:file",      // 静态文件
  "registry:theme",     // 主题配置
  "registry:style",     // 样式定义
  "registry:item",      // 通用 Item
  "registry:base",      // 基础配置
  "registry:font",      // 字体资源

  // Internal use only.
  "registry:example",   // 内部示例
  "registry:internal",  // 内部组件
])

// Registry Item 通用字段
export const registryItemCommonSchema = z.object({
  $schema: z.string().optional(),                      // JSON Schema URL
  extends: z.string().optional(),                      // 继承其他 item
  name: z.string(),                                    // 组件名称
  title: z.string().optional(),                        // 显示标题
  author: z.string().min(2).optional(),                // 作者
  description: z.string().optional(),                  // 描述
  dependencies: z.array(z.string()).optional(),        // npm 依赖
  devDependencies: z.array(z.string()).optional(),     // 开发依赖
  registryDependencies: z.array(z.string()).optional(),// Registry 内部依赖
  files: z.array(registryItemFileSchema).optional(),   // 文件列表
  tailwind: registryItemTailwindSchema.optional(),     // Tailwind 配置
  cssVars: registryItemCssVarsSchema.optional(),       // CSS 变量
  css: registryItemCssSchema.optional(),               // CSS 样式
  envVars: registryItemEnvVarsSchema.optional(),       // 环境变量
  meta: z.record(z.string(), z.any()).optional(),      // 元数据
  docs: z.string().optional(),                         // 文档
  categories: z.array(z.string()).optional(),          // 分类
})

export const registryItemFileSchema = z.discriminatedUnion("type", [
  z.object({
    path: z.string(),           // 源文件路径
    content: z.string().optional(), // 文件内容
    type: z.enum(["registry:file", "registry:page"]),
    target: z.string(),         // 目标安装路径 (必需)
  }),
  z.object({
    path: z.string(),
    content: z.string().optional(),
    type: registryItemTypeSchema.exclude(["registry:file", "registry:page"]),
    target: z.string().optional(), // 目标路径 (可选)
  }),
])

export const registryItemCssVarsSchema = z.object({
  theme: z.record(z.string(), z.string()).optional(),  // 主题级变量
  light: z.record(z.string(), z.string()).optional(),  // 亮色模式
  dark: z.record(z.string(), z.string()).optional(),   // 暗色模式
})

// components.json 中可配置自定义 registry
export const registryConfigSchema = z.record(
  z.string().refine((key) => key.startsWith("@"), {
    message: "Registry names must start with @ (e.g., @v0, @acme)",
  }),
  registryConfigItemSchema  // 支持简单 URL 或高级配置
)

// 高级配置示例
{
  "@acme": {
    "url": "https://acme.com/registry/{name}.json",
    "params": { "version": "latest" },
    "headers": { "Authorization": "Bearer token" }
  }
}

const buttonVariants = cva(
  // 基础类（始终应用）
  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
  {
    variants: {
      // variant 轴
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
        outline: "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",
        link: "text-primary underline-offset-4 hover:underline",
      },
      // size 轴
      size: {
        default: "h-9 px-4 py-2 has-[>svg]:px-3",
        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",
        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",
        icon: "size-9",
        "icon-sm": "size-8",
        "icon-lg": "size-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

function Button({
  className,
  variant = "default",
  size = "default",
  asChild = false,
  ...props
}: React.ComponentProps<"button"> &
  VariantProps<typeof buttonVariants> & {
    asChild?: boolean
  }) {
  const Comp = asChild ? Slot : "button"

  return (
    <Comp
      data-slot="button"
      data-variant={variant}
      data-size={size}
      className={cn(buttonVariants({ variant, size, className }))}
      {...props}
    />
  )
}

// Compound Component Pattern
<Dialog>
  <DialogTrigger>Open</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Title</DialogTitle>
      <DialogDescription>Description</DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <Button>Action</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

// 使用 react-hook-form 的 Context API
<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <FormField
      control={form.control}
      name="username"
      render={({ field }) => (
        <FormItem>
          <FormLabel>Username</FormLabel>
          <FormControl>
            <Input placeholder="shadcn" {...field} />
          </FormControl>
          <FormDescription>This is your public display name.</FormDescription>
          <FormMessage />
        </FormItem>
      )}
    />
  </form>
</Form>

// 双层 Context 架构
const FormFieldContext = React.createContext<FormFieldContextValue>({} as FormFieldContextValue)
const FormItemContext = React.createContext<FormItemContextValue>({} as FormItemContextValue)

// useFormField Hook 统一管理状态
const useFormField = () => {
  const fieldContext = React.useContext(FormFieldContext)
  const itemContext = React.useContext(FormItemContext)
  const { getFieldState } = useFormContext()
  const formState = useFormState({ name: fieldContext.name })
  const fieldState = getFieldState(fieldContext.name, formState)

  const { id } = itemContext

  return {
    id,
    name: fieldContext.name,
    formItemId: `${id}-form-item`,
    formDescriptionId: `${id}-form-item-description`,
    formMessageId: `${id}-form-item-message`,
    ...fieldState,  // error, invalid, isDirty 等
  }
}

// FormControl 自动关联 ARIA 属性
function FormControl({ ...props }: React.ComponentProps<typeof Slot>) {
  const { error, formItemId, formDescriptionId, formMessageId } = useFormField()

  return (
    <Slot
      id={formItemId}
      aria-describedby={
        !error
          ? `${formDescriptionId}`
          : `${formDescriptionId} ${formMessageId}`
      }
      aria-invalid={!!error}
      {...props}
    />
  )
}

// 焦点管理
"outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]"

// 错误状态
"aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive"

// 禁用状态
"disabled:pointer-events-none disabled:opacity-50"

// 屏幕阅读器
<span className="sr-only">Close</span>

/* 基础变量 (HSL 格式) */
:root {
  --background: 0 0% 100%;
  --foreground: 240 10% 3.9%;
  --primary: 240 5.9% 10%;
  --primary-foreground: 0 0% 98%;
  --secondary: 240 4.8% 95.9%;
  --muted: 240 4.8% 95.9%;
  --accent: 240 4.8% 95.9%;
  --destructive: 0 84.2% 60.2%;
  --border: 240 5.9% 90%;
  --input: 240 5.9% 90%;
  --ring: 240 5.9% 10%;
  --radius: 0.5rem;
}

@media (prefers-color-scheme: dark) {
  :root {
    --background: 240 10% 3.9%;
    --foreground: 0 0% 98%;
    /* ... */
  }
}

// tailwind.config.ts
theme: {
  extend: {
    colors: {
      background: "hsl(var(--background))",
      foreground: "hsl(var(--foreground))",
      primary: {
        DEFAULT: "hsl(var(--primary))",
        foreground: "hsl(var(--primary-foreground))",
      },
      // ...
    },
    borderRadius: {
      lg: "var(--radius)",
      md: "calc(var(--radius) - 2px)",
      sm: "calc(var(--radius) - 4px)",
    },
  },
}

// next.config.mjs
const config = {
  experimental: {
    turbo: { /* Turbopack 配置 */ },
  },
  images: {
    remotePatterns: [
      { protocol: "https", hostname: "avatars.githubusercontent.com" },
      { protocol: "https", hostname: "images.unsplash.com" },
    ],
  },
}

// source.config.ts
export const docs = defineDocs({
  dir: "content/docs"
})

// lib/source.ts
export const source = loader({
  baseUrl: "/docs",
  source: docs.toFumadocsSource()
})

export function ComponentPreview({
  name,
  styleName = "new-york-v4",
  type,  // "block" | "component" | "example"
  hideCode = false,
}) {
  const Component = Index[styleName]?.[name]?.component

  if (type === "block") {
    // Block 类型：PNG 预览图 + iframe
    return (
      <div>
        {/* 移动端显示静态图片 (light/dark 两个版本) */}
        <Image src={`/r/styles/new-york-v4/${name}-light.png`} className="md:hidden dark:hidden" />
        <Image src={`/r/styles/new-york-v4/${name}-dark.png`} className="md:hidden dark:block" />

        {/* 桌面端 iframe 预览 */}
        <iframe src={`/view/${styleName}/${name}`} className="hidden md:block" />
      </div>
    )
  }

  // Component 类型：实时渲染 + 代码展示
  return (
    <ComponentPreviewTabs
      component={<Component />}
      source={<ComponentSource name={name} styleName={styleName} />}
    />
  )
}

const highlightCache = new LRUCache<string, string>({
  max: 500,
  ttl: 1000 * 60 * 60  // 1 小时
})

export async function highlightCode(code: string, lang: string) {
  const cacheKey = createHash("sha256").update(code + lang).digest("hex")

  if (highlightCache.has(cacheKey)) {
    return highlightCache.get(cacheKey)
  }

  const highlightedCode = await codeToHtml(code, {
    lang,
    theme: {
      light: "github-light",
      dark: "github-dark",
    },
  })

  highlightCache.set(cacheKey, highlightedCode)
  return highlightedCode
}

const registryCache = new LRUCache<string, any>({
  max: 500,
  ttl: 1000 * 60 * 5,  // 5 分钟（开发模式快速更新）
})

export async function getRegistryItem(name: string, styleName: Style["name"]) {
  const cacheKey = `${styleName}:${name}`

  if (registryCache.has(cacheKey)) {
    return registryCache.get(cacheKey)
  }

  // 并行读取所有文件
  const files = await Promise.all(
    item.files.map(async (file) => {
      const content = await getFileContent(file)
      return { ...file, content }
    })
  )

  registryCache.set(cacheKey, parsed.data)
  return parsed.data
}

export const mdxComponents = {
  ComponentPreview,
  ComponentSource,
  CodeTabs,
  Callout,
  Steps,
  DirectoryList,
  Image: (props) => <Image {...props} />,  // Next.js Image
  // ... 30+ 自定义组件
}

# 1. 初始化项目
npx shadcn@latest init
  ↓ 创建 components.json
  ↓ 安装 Tailwind CSS
  ↓ 配置 CSS 变量
  ↓ 设置路径别名

# 2. 添加组件
npx shadcn@latest add button
  ↓ 解析 registryDependencies (如 label)
  ↓ 下载组件源代码
  ↓ 安装 npm 依赖 (@radix-ui/react-slot)
  ↓ 更新 Tailwind 配置
  ↓ 写入 components/ui/button.tsx

# 3. 查看差异
npx shadcn@latest diff button
  ↓ 对比本地版本和 Registry 版本
  ↓ 显示 diff (类似 git diff)

// 从 style-{name}.css 提取样式映射
const styleMap = createStyleMap(styleContent)

// AST 转换：替换 className
const transformed = await transformStyle(source, { styleMap })

// 基础组件 (base)
<div className="rounded-md border">

// ↓ 转换为 new-york 风格
<div className="rounded-lg border-2">

// ↓ 转换为 miami 风格
<div className="rounded-xl border-4">

// 示例：Dialog 组件
{
  name: "dialog",
  dependencies: ["@radix-ui/react-dialog"],  // npm 包
  registryDependencies: ["button", "label"],  // 其他组件
  devDependencies: [],                        // 开发依赖
}

// 检测代码块中的安装命令
if (raw.startsWith("npm install")) {
  node.properties["__npm__"] = raw
  node.properties["__yarn__"] = raw.replace("npm install", "yarn add")
  node.properties["__pnpm__"] = raw.replace("npm install", "pnpm add")
  node.properties["__bun__"] = raw.replace("npm install", "bun add")
}

const [packageManager, setPackageManager] = useLocalStorage("packageManager", "npm")

// 自动显示用户偏好的包管理器
<CodeBlockCommand value={code[`__${packageManager}__`]} />

// packages/shadcn/src/mcp/
- server.ts       # MCP 服务器
- tools.ts        # 工具定义
- prompts.ts      # 提示模板

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "registry": {
      "outputs": ["public/r/**", "registry/__index__.tsx"]
    }
  }
}

// 1. 构建基础索引
await buildBasesIndex(BASES)
  ↓ 读取 registry/bases/{base}/registry.ts
  ↓ 验证 Zod schema
  ↓ 生成 registry/bases/__index__.tsx (React.lazy 导入)

// 2. 构建所有风格
for (const base of BASES) {
  for (const style of STYLES) {
    const styleName = `${base.name}-${style.name}`

    // 读取样式映射
    const styleContent = await fs.readFile(`registry/styles/style-${style.name}.css`)
    const styleMap = createStyleMap(styleContent)

    // 转换所有组件
    for (const file of registryItem.files) {
      const source = await fs.readFile(file.path)
      const transformed = await transformStyle(source, { styleMap })
      await fs.writeFile(`registry/${styleName}/${file.path}`, transformed)
    }
  }
}

// 3. 生成 public/r/ 输出
await buildRegistry(styleName)
  ↓ 调用 shadcn build 命令
  ↓ 生成压缩的 JSON 文件
  ↓ 输出到 public/r/styles/{styleName}/

// 4. 清理中间文件
await cleanUp()
  ↓ 删除非白名单风格目录
  ↓ 删除临时 registry-*.json 文件