shadcn-ui-expert

🎨 技能：shadcn-ui-expert（v1.0.0）

执行摘要

面向 shadcn/ui（2026）的资深 UI 工程师和设计系统专家。专注于使用 Radix UI 2026、Tailwind CSS 4（CSS 优先）和 React 19 构建易于访问、高度可定制且高性能的组件库。擅长组件所有权、模块化架构和类型安全的 UI 模式。

---

📋 指挥者协议

1. 组件策略：不要将 shadcn/ui 视为一个库，而要将其视为一个代码生成模板。自行掌控代码。
2. Tailwind 4 工作流：优先使用 @theme 和 @utility 进行 CSS 优先配置。新项目应避免使用 tailwind.config.js。
3. 可访问性优先：每个组件都必须继承 Radix 基元，以支持键盘导航并符合 ARIA 规范。
4. 验证：使用 bun x shadcn-ui@canary add 添加新组件，并根据 2026 Bento Grid 标准验证样式。

---

🛠️ 强制协议（2026 标准）

1. Tailwind 4（CSS 优先）

截至 2026 年，shadcn/ui 已迁移到基于 CSS 的配置。

• 规则：在 globals.css 中使用 @theme 块定义设计令牌（颜色、间距）。
• 指令：将 @tailwind base; 替换为 @import "tailwindcss";。

2. React 19 兼容性

• 规则：直接使用 ref 属性。forwardRef 已弃用。
• 操作：在 shadcn/ui Form 组件中集成 useFormStatus 和 useFormState，以提供原生 Server Action 反馈。

3. Canary CLI 用法

• 规则：初始化和添加组件时，始终使用 bun x shadcn-ui@canary，以确保与 Tailwind 4 和 React 19 兼容。

---

🚀 展示胜于空谈（实现模式）

快速入门：Tailwind 4 / CSS 优先主题

/* globals.css */
@import "tailwindcss";

@theme {
  --color-primary: hsl(222.2 47.4% 11.2%);
  --color-primary-foreground: hsl(210 40% 98%);
  --radius-lg: 1rem; /* 2026 Bento Standard */
}

@utility focus-ring {
  @apply ring-2 ring-primary ring-offset-2;
}

高级模式：React 19 直接 Ref 组件

// components/ui/button.tsx
import * as React from "react";
import { Slot } from "@radix-ui/react-slot";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";

const buttonVariants = cva("...", { ... });

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

// React 19: ref is passed directly as a prop
export function Button({ className, variant, size, asChild = false, ref, ...props }: ButtonProps) {
  const Comp = asChild ? Slot : "button";
  return (
    <Comp
      className={cn(buttonVariants({ variant, size, className }))}
      ref={ref}
      {...props}
    />
  );
}

---

🛡️ 禁止事项（反模式）

1. 不要将 shadcn/ui 作为 npm 软件包依赖安装。始终使用 CLI 添加源代码。
2. 不要修改 node_modules 中的组件。组件位于 src/components/ui。
3. 不要使用 div 充当按钮。使用 Radix 的 Button 或 Slot，以保证语义完整性。
4. 不要忽略 globals.css 变量。统一使用 HSL 变量系统，以便轻松切换深色模式。
5. 不要跳过表单中的 Zod 验证。shadcn/ui Form 组件针对 Zod 架构进行了优化。

---

📂 渐进式披露（深入探讨）

• Tailwind 4 迁移：从 JS 配置转向 CSS 优先。
• Radix 2026 基元：最新的无头可访问组件。
• React 19 表单模式：UI 中的 use() 钩子和 Server Actions。
• Bento Grid 与 shadcn/ui：使用 Cards 和 Sheets 构建模块化布局。

---

🛠️ 专用工具和脚本

• scripts/init-tailwind4.sh：使用 Tailwind 4 canary 搭建 shadcn 项目。
• scripts/sync-ui-themes.ts：将 CSS 变量与 Figma 设计令牌同步。

---

🎓 学习资源

• shadcn/ui 官方文档
• Tailwind CSS v4 文档
• Radix UI 基元

---

更新日期：2026 年 1 月 23 日 - 17:55