shadcn-ui-expert

用途

shadcn-ui-expert 是一个面向 shadcn/ui 的高级 UI 工程与设计系统技能，定位为资深 UI 工程师与设计系统专家（2026 版）。其核心目标是在 Radix UI 2026、Tailwind CSS 4（CSS-First）与 React 19 的技术栈下，构建可访问、高度可定制且性能良好的组件库，并强调组件所有权、模块化架构与类型安全的 UI 模式。

主要能力

组件策略：不把 shadcn/ui 当作普通库，而是当作代码生成模板，要求开发者拥有代码。
Tailwind 4 工作流：优先使用 @theme 与 @utility 的 CSS 优先配置；新项目避免使用 tailwind.config.js。
可访问性优先：每个组件必须继承 Radix 原语，以获得键盘导航与 ARIA 合规。
验证方式：使用 bun x shadcn-ui@canary add 添加新组件，并对照 2026 Bento Grid 标准验证样式。
强制协议（2026 标准）：
- Tailwind 4（CSS-First）：在 globals.css 中用 @theme 块定义设计令牌（颜色、间距）；用 @import "tailwindcss"; 替换 @tailwind base;。
- React 19 兼容：使用直接 ref 属性，forwardRef 已弃用；将 useFormStatus 与 useFormState 集成到 shadcn/ui 表单组件，以获得原生 Server Action 反馈。
- Canary CLI：初始化与添加组件时始终使用 bun x shadcn-ui@canary，以确保与 Tailwind 4 和 React 19 兼容。

使用方式

资料提供了实现模式示例。

Tailwind 4 / CSS-First 主题快速开始：

/* 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}
    />
  );
}

反模式清单（Do Not List）：

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

进阶主题（Progressive Disclosure）：

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 原语

适用场景

适用于使用 shadcn/ui 构建组件库、设计系统或前端界面的团队与开发者，尤其是需要可访问性、可定制性与性能，并采用 Tailwind CSS 4、React 19 与 Radix UI 2026 的项目。也适用于从 Tailwind JS 配置迁移到 CSS 优先配置、以及需要将 UI 主题与 Figma 设计令牌同步的场景。

限制

资料未提供该技能的收费、价格、平台支持范围、具体效果指标或完整安装步骤等事实，暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制