shadcn-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

shadcn/ui patterns

shadcn/ui 模式

Use existing shadcn components from

@/components/ui

. Do not reinvent primitives.

使用

@/components/ui

中现有的shadcn组件。不要重新实现基础组件。

Dialog vs Sheet

Dialog 与 Sheet

Use	Component
Desktop modal, short forms	`Dialog`
Mobile-first, filters, long forms	`Sheet` (side or bottom)

Always include

DialogTitle

SheetTitle

for accessibility.

使用场景	组件
桌面端模态框、短表单	`Dialog`
移动端优先、筛选器、长表单	`Sheet` （侧边或底部）

始终包含

DialogTitle

SheetTitle

以满足无障碍要求。

Data tables

数据表

Use
```
@tanstack/react-table
```
with shadcn
```
Table
```
,
```
DataTable
```
pattern.
Column headers sortable when list is large.
Row actions in
```
DropdownMenu
```
, not 5 inline buttons.
Empty/error states via
```
error-states-and-empty-ui
```
skill.

将
```
@tanstack/react-table
```
与shadcn的
```
Table
```
、
```
DataTable
```
模式配合使用。
当列表数据量大时，列标题需支持排序。
行操作放在
```
DropdownMenu
```
中，不要使用5个内联按钮。
空状态/错误状态参考
```
error-states-and-empty-ui
```
技能。

Forms

表单

Form

FormField

FormItem

FormLabel

FormControl

FormMessage

Pair with Zod + react-hook-form (
```
typed-api-hooks-forms
```
skill).

使用

Form

、

FormField

、

FormItem

、

FormLabel

、

FormControl

、

FormMessage

。

搭配Zod + react-hook-form（参考
```
typed-api-hooks-forms
```
技能）。

Buttons and actions

按钮与操作

One primary action per section; destructive uses
```
variant="destructive"
```
.
```
Button
```
+
```
disabled={isPending}
```
during mutations.

每个区域仅保留一个主要操作；破坏性操作使用
```
variant="destructive"
```
。
数据变更期间，
```
Button
```
需添加
```
disabled={isPending}
```
属性。

Command palette

命令面板

Command

CommandInput

CommandList

CommandItem

for search/navigation.

Keyboard: Cmd/Ctrl+K when spec asks for it.

使用
```
Command
```
、
```
CommandInput
```
、
```
CommandList
```
、
```
CommandItem
```
实现搜索/导航功能。
若需求中指定，支持键盘快捷键Cmd/Ctrl+K。

Toasts and notifications

提示框与通知

Use Sonner (
```
<Toaster />
```
once at the root) for transient feedback.
One toast per action; don't stack 5 success toasts.
Errors: short message + optional retry; never raw
```
error.message
```
from Supabase.

import { toast } from "sonner";

toast.success("Project created");
toast.error("Could not save changes", { description: "Please try again." });

使用Sonner（在根节点处仅渲染一次
```
<Toaster />
```
）提供临时反馈。
每个操作仅显示一个提示框；不要堆叠5个成功提示框。
错误提示：简短消息 + 可选重试按钮；绝不要直接显示Supabase返回的原始
```
error.message
```
。

import { toast } from "sonner";

toast.success("Project created");
toast.error("Could not save changes", { description: "Please try again." });

Navigation patterns

导航模式

Persistent left
```
Sidebar
```
for app shell;
```
Tabs
```
inside a route for sub-views.
```
Breadcrumb
```
once routes go ≥ 3 levels deep.
Mobile: bottom nav or
```
Sheet
```
drawer — never desktop sidebar squeezed onto phones.

应用外壳使用固定左侧
```
Sidebar
```
；路由内使用
```
Tabs
```
切换子视图。
当路由层级≥3级时，使用
```
Breadcrumb
```
面包屑。
移动端：使用底部导航或
```
Sheet
```
抽屉——绝不要将桌面端侧边栏压缩适配手机。

Responsive

响应式设计

Stack filters in
```
Sheet
```
on mobile; inline on
```
md+
```
.
Touch targets ≥ 44px where possible.
Test at 375px width.

移动端将筛选器堆叠在
```
Sheet
```
中；
```
md+
```
尺寸（中等及以上屏幕）时使用内联布局。
触摸目标尽可能≥44px。
在375px宽度下测试。

Theming

主题

Use CSS variables from shadcn (
```
bg-background
```
,
```
text-foreground
```
) — never hardcoded
```
#fff
```
.
Dark mode: see
```
dark-mode-and-theming
```
skill.

使用shadcn提供的CSS变量（
```
bg-background
```
、
```
text-foreground
```
）——绝不要硬编码
```
#fff
```
。
深色模式：参考
```
dark-mode-and-theming
```
技能。

Avoid

注意避免

Raw HTML
```
<button>
```
styled ad hoc when shadcn exists.
Nested dialogs without clear close path.
Missing
```
aria
```
labels on icon-only buttons.
Multiple toast libraries (Sonner + react-hot-toast + custom) in one app.

当shadcn组件存在时，不要使用自定义样式的原生HTML
```
<button>
```
。
不要使用没有清晰关闭路径的嵌套对话框。
纯图标按钮不要缺失
```
aria
```
标签。
同一应用中不要使用多个提示框库（Sonner + react-hot-toast + 自定义）。