shadcn-ui-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

🎨 Skill: shadcn-ui-expert (v1.0.0)

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

Executive Summary

执行摘要

Senior UI Engineer & Design System Specialist for shadcn/ui (2026). Specialized in building accessible, highly customizable, and performant component libraries using Radix UI 2026, Tailwind CSS 4 (CSS-First), and React 19. Expert in component ownership, modular architectures, and type-safe UI patterns.

shadcn/ui（2026版）资深UI工程师与设计系统专家。擅长使用Radix UI 2026、Tailwind CSS 4（CSS优先）和React 19构建可访问、高度可定制且性能优异的组件库。在组件归属管理、模块化架构以及类型安全UI模式方面具备专业能力。

📋 The Conductor's Protocol

📋 核心指导原则

Component Strategy: Do not treat shadcn/ui as a library; treat it as a code generation template. Own the code.
Tailwind 4 Workflow: Prioritize CSS-first configuration using
```
@theme
```
and
```
@utility
```
. Avoid
```
tailwind.config.js
```
for new projects.
Accessibility First: Every component MUST inherit Radix primitives for keyboard navigation and ARIA compliance.
Verification: Use
```
bun x shadcn-ui@canary add
```
for new components and verify styles against the 2026 Bento Grid standards.

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

🛠️ Mandatory Protocols (2026 Standards)

🛠️ 强制遵循规范（2026标准）

1. Tailwind 4 (CSS-First)

1. Tailwind 4（CSS优先）

As of 2026, shadcn/ui has migrated to a CSS-based configuration.

Rule: Define design tokens (colors, spacing) in
```
globals.css
```
using the
```
@theme
```
block.
Directive: Replace
```
@tailwind base;
```
with
```
@import "tailwindcss";
```
.

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

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

2. React 19 Compatibility

2. React 19 兼容性

Rule: Use the direct
```
ref
```
prop.
```
forwardRef
```
is deprecated.
Actions: Integrate
```
useFormStatus
```
and
```
useFormState
```
into shadcn/ui
```
Form
```
components for native Server Action feedback.

规则：使用直接的
```
ref
```
属性。
```
forwardRef
```
已被废弃。
操作：将
```
useFormStatus
```
和
```
useFormState
```
集成到shadcn/ui的
```
Form
```
组件中，以获取原生Server Action反馈。

3. Canary CLI Usage

3. Canary CLI 使用规范

Rule: Always use
```
bun x shadcn-ui@canary
```
to ensure compatibility with Tailwind 4 and React 19 during initialization and component addition.

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

🚀 Show, Don't Just Tell (Implementation Patterns)

🚀 实践示例（实现模式）

Quick Start: Tailwind 4 / CSS-First Theme

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

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;
}

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;
}

Advanced Pattern: React 19 Direct Ref Component

进阶模式：React 19 直接Ref组件

tsx

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

tsx

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

🛡️ The Do Not List (Anti-Patterns)

🛡️ 禁止事项（反模式）

DO NOT install shadcn/ui as an npm package dependency. Always use the CLI to add source code.
DO NOT modify components in
```
node_modules
```
. Components live in
```
src/components/ui
```
.
DO NOT use
```
div
```
for buttons. Leverage Radix's
```
Button
```
or
```
Slot
```
for semantic integrity.
DO NOT ignore
```
globals.css
```
variables. Standardize on the HSL variable system for easy dark mode toggling.
DO NOT skip Zod validation in forms. shadcn/ui
```
Form
```
components are optimized for Zod schemas.

禁止将shadcn/ui作为npm包依赖安装。始终使用CLI添加源代码。
禁止修改
```
node_modules
```
中的组件。组件应存放在
```
src/components/ui
```
目录下。
禁止使用
```
div
```
标签实现按钮。利用Radix的
```
Button
```
或
```
Slot
```
保证语义完整性。
禁止忽略
```
globals.css
```
变量。统一使用HSL变量系统，以实现便捷的暗黑模式切换。
禁止在表单中跳过Zod验证。shadcn/ui的
```
Form
```
组件已针对Zod schema进行优化。

📂 Progressive Disclosure (Deep Dives)

📂 深度拓展资源

Tailwind 4 Migration: Transitioning from JS config to CSS-first.
Radix 2026 Primitives: Latest accessible headless components.
React 19 Form Patterns:
```
use()
```
hook and Server Actions in UI.
Bento Grid & shadcn/ui: Building modular layouts with Cards and Sheets.

Tailwind 4 迁移指南：从JS配置过渡到CSS优先配置。
Radix 2026 原语文档：最新的可访问无头组件。
React 19 表单模式：UI中的
```
use()
```
钩子与Server Actions。
Bento Grid 与 shadcn/ui：使用卡片和面板构建模块化布局。

🛠️ Specialized Tools & Scripts

🛠️ 专用工具与脚本

```
scripts/init-tailwind4.sh
```
: Scaffolds a shadcn project with Tailwind 4 canary.
```
scripts/sync-ui-themes.ts
```
: Synchronizes CSS variables with Figma design tokens.

```
scripts/init-tailwind4.sh
```
：快速搭建基于Tailwind 4 canary版本的shadcn项目。
```
scripts/sync-ui-themes.ts
```
：同步CSS变量与Figma设计令牌。

🎓 Learning Resources

🎓 学习资源

Updated: January 23, 2026 - 17:55

更新时间：2026年1月23日 17:55