moai-library-shadcn

Name: moai-library-shadcn
Author: modu-ai

github.com/modu-ai设计与 UI1.2k76 次安装今天更新

代码仓库

关于 moai-library-shadcn

面向配置 React 组件库和设计系统的 shadcn/ui 技能，涵盖 CLI v4、主题、RTL、组件注册表及 AI 架构指导。

主要功能

01shadcn/cli v4 预设与迁移
02Radix UI 和 Base UI 组件
03OKLCH 主题与深色模式
04RTL 布局与逻辑 CSS
05组件注册表与 AI 指导

适用场景

01搭建 shadcn/ui 项目
02配置基于预设的设计系统
03构建或迁移 RTL 布局
04编写组件注册表

MCP 相关

该技能提及供 AI 助手使用的 MCP 服务，以及用于获取 shadcn/ui 和 React 文档的 Context7 MCP 集成；未说明服务操作或提供的工具。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/modu-ai/moai-adk --skill moai-library-shadcn

安装后在 Claude Code 中输入/moai-library-shadcn确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

modules/

advanced-patterns.md

cli-registry.md

optimization.md

shadcn-components.md

shadcn-theming.md

references/

examples.md

reference.md

详细介绍

快速参考

企业级 shadcn/ui 组件库专家

全面掌握 shadcn/ui，涵盖 shadcn/cli v4、基于预设的设计系统、RTL 支持、统一的 radix-ui 包、OKLCH 主题设置，以及面向现代 React 应用的 AI 集成。

核心能力：

CLI v4：预设系统、框架模板、迁移命令、注册表管理
组件：基于 Radix UI 和 Base UI 原语，并采用统一的 radix-ui 包
主题设置：OKLCH 颜色系统、CSS 变量、深色模式、基于预设的配置
RTL：一流的从右向左支持，并使用逻辑 CSS 属性
AI 集成：shadcn/skills 上下文系统、面向 AI 助手的 MCP 服务
注册表：自定义组件分发、字体系统、区块库

适用场景：

shadcn/ui 组件库的设置与自定义
基于预设的设计系统配置
RTL 布局的实现或迁移
用于组件分发的注册表编写
使用 shadcn/skills 辅助 AI 搭建组件

模块组织：

核心概念：本文涵盖 shadcn/ui 概览、架构和生态系统
CLI 和注册表：cli-registry.md 模块涵盖 CLI v4 命令、预设、RTL、迁移和注册表
组件：shadcn-components.md 模块涵盖组件库和模式
主题设置：shadcn-theming.md 模块涵盖 OKLCH 颜色系统和自定义
高级模式：advanced-patterns.md 模块涵盖复杂实现
优化：optimization.md 模块涵盖性能调优

实现指南

shadcn/ui 概览

shadcn/ui 是一个使用 Radix UI 和 Tailwind CSS 构建的可复用组件集合。与传统组件库不同，它并非 npm 包，而是一个可复制到项目中的组件集合。

主要优势包括：完全掌控组件并拥有组件所有权；除 Radix UI 原语外，无其他依赖；可使用 Tailwind CSS 完全自定义；采用 TypeScript 优先的设计，具备出色的类型安全性；内置无障碍功能，符合 WCAG 2.1 AA 标准。

架构理念：shadcn/ui 组件基于 Radix UI Primitives 构建，后者提供无样式且易于访问的原语。Tailwind CSS 提供实用优先的样式。TypeScript 确保全程类型安全。自定义层让你完全掌控最终实现。

核心组件类别

表单组件包括 Input、Select、Checkbox、Radio 和 Textarea。表单验证可与 react-hook-form 和 Zod 集成。通过恰当的 ARIA 标签确保无障碍性。

展示组件包括 Card、Dialog、Sheet、Drawer 和 Popover。内置响应式设计模式，并支持深色模式。

导航组件包括 Navigation Menu、Breadcrumb、Tabs 和 Pagination。内置键盘导航支持，并自动处理焦点管理。

数据组件包括 Table、Calendar、DatePicker 和 Charts。大型数据集可使用虚拟滚动，并支持与 TanStack Table 集成。

反馈组件包括 Alert、Toast、Progress、Badge 和 Avatar。提供加载状态和骨架屏，并支持错误边界。

2026 年新增组件包括 Empty、Field、Item、Button Group、Spinner、Kbd 和 Input Group。

安装与设置

步骤 1：使用 shadcn/cli v4 初始化项目。选择一个框架模板（Next.js、Vite、TanStack Start、React Router、Astro 或 Laravel），并可选择应用预设，以配置打包好的设计系统。

步骤 2：CLI 会生成 components.json 配置文件。它会检测框架、配置 Tailwind CSS（v3 或 v4）、设置路径别名，并选择基础原语库（Radix UI 或 Base UI）。

步骤 3：使用 add 命令逐个添加组件。使用 --dry-run 预览更改，使用 --diff 查看注册表更新。shadcn info 命令会显示已安装的组件和项目配置。

基础技术

React 19 的特性包括支持 Server Components、并发渲染、自动批处理和流式 SSR。

TypeScript 5.9 提供完整的类型安全、改进的类型推断和更出色的开发体验。

Tailwind CSS v4 包含 CSS 优先配置、CSS 变量、OKLCH 颜色支持和容器查询。

Radix UI 使用统一的 radix-ui 包，通过单条导入语句即可使用。Base UI 可作为替代的基础组件库。

集成技术栈包括用于表单状态管理的 React Hook Form、用于模式验证的 Zod、用于变体管理的 class-variance-authority、用于动画的 Framer Motion，以及用于图标的 Lucide React。

AI 驱动的架构设计

ShadcnUIArchitectOptimizer 类使用 Context7 MCP 集成来设计最优的 shadcn/ui 架构。它会初始化 Context7 客户端、组件分析器和主题优化器。design_optimal_shadcn_architecture 方法接收设计系统需求，并通过 Context7 获取最新的 shadcn/ui 和 React 文档。随后，该方法会根据 UI 组件和用户需求优化组件选择，根据品牌指南和无障碍要求优化主题配置，并返回完整的 ShadcnUIArchitecture，其中包括组件库、主题系统、无障碍合规性、性能优化、集成模式和自定义策略。

最佳实践

要求包括：使用 CSS 变量自定义主题、实现适当的 TypeScript 类型、遵循 WCAG 2.1 AA 无障碍指南、使用 Radix UI 基础组件处理复杂交互、使用 React Testing Library 测试组件、通过 tree-shaking 优化打包体积，以及实现响应式设计模式。

关键实现标准：

[HARD] 颜色值只能使用 CSS 变量。这样可以实现动态主题、支持深色模式切换，并确保所有组件的设计系统保持一致。不使用 CSS 变量时，主题更改需要修改代码，深色模式会失效，品牌自定义也会变得难以维护。

[HARD] 为所有交互元素添加无障碍属性。这样可以确保符合 WCAG 2.1 AA 标准、兼容屏幕阅读器，并为残障用户提供包容性的用户体验。缺少无障碍属性会排除残障用户、违反法律合规要求，并降低应用的可用性。

[HARD] 为所有交互组件实现键盘导航。这能为键盘用户提供必要的导航方式、支持辅助技术，并提升整体用户体验效率。缺少键盘导航时，高级用户无法高效使用应用，且无法满足无障碍合规要求。

[SOFT] 为异步操作提供加载状态。这样可以向用户展示操作进度、降低感知延迟，并增强用户对应用响应能力的信心。

[HARD] 在组件树周围实现错误边界。这样可以防止局部组件故障导致整个应用崩溃、支持优雅地恢复错误，并保持应用稳定性。

[HARD] 使用 Tailwind CSS 类，而不是内联样式。这样可以保持设计系统的一致性、发挥 JIT 编译的优势、支持响应式设计变体，并优化打包体积。

[SOFT] 为所有组件实现深色模式支持。这样可以尊重用户偏好、减少低光环境下的眼睛疲劳，并符合现代 UI 的预期。

性能优化

包体积优化包括通过 tree-shaking 移除未使用的组件、对大型组件进行代码拆分、使用 React.lazy 延迟加载，以及为重量级依赖项使用动态导入。

运行时性能优化包括对开销较大的组件使用 React.memo、使用 useMemo 和 useCallback 进行计算、对大型列表进行虚拟滚动，以及对用户交互进行防抖处理。

无障碍功能包括为所有交互元素添加 ARIA 属性、支持键盘导航、管理焦点，以及进行屏幕阅读器测试。

高级模式

组件组合

可组合模式涉及从 ui/card 组件导入 Card、CardHeader、CardTitle 和 CardContent。DashboardCard 组件接收 title 和 children 属性，并将它们包装在 Card 结构中，其中 CardHeader 包含 CardTitle，CardContent 包含 children。

表单验证

Zod 与 React Hook Form 的集成模式涉及从 react-hook-form 导入 useForm、从 hookform/resolvers/zod 导入 zodResolver，以及从 zod 导入 z。使用包含字段验证的 z.object 定义 formSchema，例如，电子邮件使用 z.string().email()，密码使用 z.string().min(8)。根据该 schema 推断 FormValues 类型。表单组件使用 useForm，并将 formSchema 传给 zodResolver。表单元素使用 form.handleSubmit，并传入 onSubmit 处理函数。

配合使用效果良好

modules/cli-registry.md，涵盖 CLI v4 命令、预设、RTL、迁移和 registry
shadcn-components.md 模块，涵盖高级组件模式和实现
shadcn-theming.md 模块，涵盖 OKLCH 主题系统和自定义策略
moai-domain-uiux，涵盖设计系统架构和原则
moai-lang-typescript，涵盖 TypeScript 最佳实践
code-frontend，涵盖前端开发模式