Back to Details

shadcn

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

shadcn/ui Patterns

shadcn/ui 使用模式

Use shadcn as a composable source-based UI system, not as a black-box dependency.
将 shadcn 作为可组合的源码级 UI 系统使用，而非黑盒依赖。

Use This Skill When

适用场景

  • Setting up shadcn in Next.js or Vite.
  • Building reusable UI primitives and design tokens.
  • Implementing form/dialog/table workflows with shadcn components.
  • 在 Next.js 或 Vite 中搭建 shadcn 环境。
  • 构建可复用的 UI 基础组件与设计令牌。
  • 使用 shadcn 组件实现表单/对话框/表格的业务流程。

Core Contract

核心准则

  1. Install only needed components.
  2. Centralize theme tokens and semantic styles.
  3. Prefer composition patterns over one-off custom wrappers.
  4. Keep accessibility defaults intact.
  5. Keep business logic outside UI primitives.
  1. 仅安装所需组件。
  2. 集中管理主题令牌与语义化样式。
  3. 优先采用组件组合模式，而非一次性自定义包装器。
  4. 保留默认的无障碍访问设置。
  5. 将业务逻辑与 UI 基础组件分离。

Implementation Workflow

实施流程

1) Setup

1) 环境搭建

  • Initialize shadcn for current framework.
  • Confirm alias paths and 
    components.json
    are correct.
  • Add baseline primitives (
    button
    , 
    input
    , 
    dialog
    , etc.).
  • 为当前框架初始化 shadcn。
  • 确认别名路径与 
    components.json
    配置正确。
  • 添加基础组件（
    button
    、
    input
    、
    dialog
    等）。

2) Theme and Tokens

2) 主题与令牌

  • Define CSS variables for colors, spacing, radii.
  • Keep component variants consistent with product semantics.
  • Avoid ad-hoc style drift across screens.
  • 定义颜色、间距、圆角的 CSS 变量。
  • 保持组件变体与产品语义一致。
  • 避免不同页面间出现随意的样式偏差。

3) Composition Patterns

3) 组件组合模式

  • Forms: RHF + Zod + shadcn form primitives.
  • Dialogs: controlled open state + focus management.
  • Tables: server-state aware loading, empty, error states.
  • Toasts: normalize success/error messaging patterns.
  • 表单：RHF + Zod + shadcn 表单基础组件。
  • 对话框：受控打开状态 + 焦点管理。
  • 表格：服务端状态感知的加载、空数据、错误状态。
  • 提示框：统一成功/错误消息的展示模式。

4) Quality Gate

4) 质量校验

  • Keyboard support and focus traps verified.
  • ARIA labels and roles validated.
  • Component API consistency across feature modules.
  • 验证键盘支持与焦点陷阱功能。
  • 校验 ARIA 标签与角色设置。
  • 确保各功能模块间的组件 API 一致性。

Output Requirements for Agent

Agent 输出要求

  • Installation and config steps.
  • Token/theming plan.
  • Component composition pattern.
  • Accessibility and testing checklist.
  • 安装与配置步骤。
  • 令牌/主题设置方案。
  • 组件组合模式示例。
  • 无障碍访问与测试检查表。

References

参考资料

  • Full setup commands, component examples, and advanced snippets: 
    references/guide.md
  • 完整的搭建命令、组件示例与高级代码片段：
    references/guide.md