moai-library-shadcn by modu-ai/moai-adk
npx skills add https://github.com/modu-ai/moai-adk --skill moai-library-shadcn企业级 shadcn/ui 组件库专家
全面的 shadcn/ui 专业知识,涵盖 shadcn/cli v4、基于预设的设计系统、RTL 支持、统一的 radix-ui 包、OKLCH 主题化以及面向现代 React 应用程序的 AI 集成。
核心能力:
何时使用:
模块组织:
shadcn/ui 是一个使用 Radix UI 和 Tailwind CSS 构建的可重用组件集合。与传统的组件库不同,它不是一个 npm 包,而是一个您复制到项目中的组件集合。
主要优势包括对组件的完全控制和所有权、除 Radix UI 基元外零依赖、使用 Tailwind CSS 完全自定义、具有出色类型安全性的 TypeScript 优先设计,以及符合 WCAG 2.1 AA 标准的内置无障碍功能。
架构理念:shadcn/ui 组件构建在 Radix UI 基元之上,后者提供了无样式的无障碍基元。Tailwind CSS 提供了实用优先的样式。TypeScript 确保整个过程的类型安全。您的自定义层提供了对最终实现的完全控制。
表单组件包括 Input、Select、Checkbox、Radio 和 Textarea。表单验证与 react-hook-form 和 Zod 集成。通过适当的 ARIA 标签确保无障碍性。
展示组件包括 Card、Dialog、Sheet、Drawer 和 Popover。内置响应式设计模式。包含暗色模式支持。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
导航组件包括 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 特性包括服务器组件支持、并发渲染、自动批处理和流式 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。
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,其中包含字段验证,例如 email 使用 z.string().email(),password 使用 z.string().min(8)。从模式推断 FormValues 类型。表单组件使用 useForm,并传入 formSchema 的 zodResolver。表单元素使用 form.handleSubmit 并传入 onSubmit 处理程序。
相关库:
官方文档:
截至 2026 年 3 月的最新版本:
最后更新:2026-03-28 状态:生产就绪
每周安装量
75
仓库
GitHub 星标
906
首次出现
2026年1月22日
安全审计
安装于
codex60
opencode60
gemini-cli59
claude-code58
cursor55
github-copilot53
Enterprise shadcn/ui Component Library Expert
Comprehensive shadcn/ui expertise covering shadcn/cli v4, preset-based design systems, RTL support, unified radix-ui package, OKLCH theming, and AI integration for modern React applications.
Core Capabilities:
When to Use:
Module Organization:
shadcn/ui is a collection of re-usable components built with Radix UI and Tailwind CSS. Unlike traditional component libraries, it is not an npm package but rather a collection of components you copy into your project.
Key Benefits include full control and ownership of components, zero dependencies beyond Radix UI primitives, complete customization with Tailwind CSS, TypeScript-first design with excellent type safety, and built-in accessibility with WCAG 2.1 AA compliance.
Architecture Philosophy: shadcn/ui components are built on top of Radix UI Primitives which provide unstyled accessible primitives. Tailwind CSS provides utility-first styling. TypeScript ensures type safety throughout. Your customization layer provides full control over the final implementation.
Form Components include Input, Select, Checkbox, Radio, and Textarea. Form validation integrates with react-hook-form and Zod. Accessibility is ensured through proper ARIA labels.
Display Components include Card, Dialog, Sheet, Drawer, and Popover. Responsive design patterns are built in. Dark mode support is included.
Navigation Components include Navigation Menu, Breadcrumb, Tabs, and Pagination. Keyboard navigation support is built in. Focus management is handled automatically.
Data Components include Table, Calendar, DatePicker, and Charts. Virtual scrolling is available for large datasets. TanStack Table integration is supported.
Feedback Components include Alert, Toast, Progress, Badge, and Avatar. Loading states and skeletons are available. Error boundaries are supported.
New Components in 2026 include Empty, Field, Item, Button Group, Spinner, Kbd, and Input Group.
Step 1: Initialize project using shadcn/cli v4. Choose a framework template (Next.js, Vite, TanStack Start, React Router, Astro, or Laravel) and optionally apply a preset for bundled design system configuration.
Step 2: The CLI generates a components.json configuration file. It detects the framework, configures Tailwind CSS (v3 or v4), sets up path aliases, and selects the base primitive library (Radix UI or Base UI).
Step 3: Add components individually using the add command. Use --dry-run to preview changes, --diff to see registry updates. The shadcn info command shows installed components and project configuration.
React 19 features include Server Components support, concurrent rendering, automatic batching, and streaming SSR.
TypeScript 5.9 provides full type safety, improved inference, and enhanced developer experience.
Tailwind CSS v4 includes CSS-first configuration, CSS variables, OKLCH color support, and container queries.
Radix UI uses the unified radix-ui package with single imports. Base UI is available as an alternative primitive library.
Integration Stack includes React Hook Form for form state, Zod for schema validation, class-variance-authority for variants, Framer Motion for animations, and Lucide React for icons.
The ShadcnUIArchitectOptimizer class uses Context7 MCP integration to design optimal shadcn/ui architectures. It initializes a Context7 client, component analyzer, and theme optimizer. The design_optimal_shadcn_architecture method takes design system requirements and fetches latest shadcn/ui and React documentation via Context7. It then optimizes component selection based on UI components and user needs, optimizes theme configuration based on brand guidelines and accessibility requirements, and returns a complete ShadcnUIArchitecture including component library, theme system, accessibility compliance, performance optimization, integration patterns, and customization strategy.
Requirements include using CSS variables for theme customization, implementing proper TypeScript types, following accessibility guidelines for WCAG 2.1 AA compliance, using Radix UI primitives for complex interactions, testing components with React Testing Library, optimizing bundle size with tree-shaking, and implementing responsive design patterns.
Critical Implementation Standards:
[HARD] Use CSS variables exclusively for color values. This enables dynamic theming, supports dark mode transitions, and maintains design system consistency across all components. Without CSS variables, theme changes require code modifications, dark mode fails, and brand customization becomes unmaintainable.
[HARD] Include accessibility attributes on all interactive elements. This ensures WCAG 2.1 AA compliance, screen reader compatibility, and inclusive user experience for users with disabilities. Missing accessibility attributes excludes users with disabilities, violates legal compliance requirements, and reduces application usability.
[HARD] Implement keyboard navigation for all interactive components. This provides essential navigation method for keyboard users, supports assistive technologies, and improves overall user experience efficiency. Without keyboard navigation, power users cannot efficiently use the application and accessibility compliance fails.
[SOFT] Provide loading states for asynchronous operations. This communicates operation progress to users, reduces perceived latency, and improves user confidence in application responsiveness.
[HARD] Implement error boundaries around component trees. This prevents entire application crashes from isolated component failures, enables graceful error recovery, and maintains application stability.
[HARD] Apply Tailwind CSS classes instead of inline styles. This maintains consistency with design system, enables JIT compilation benefits, supports responsive design variants, and improves bundle size optimization.
[SOFT] Implement dark mode support across all components. This provides user preference respect, reduces eye strain in low-light environments, and aligns with modern UI expectations.
Bundle Size optimization includes tree-shaking to remove unused components, code splitting for large components, lazy loading with React.lazy, and dynamic imports for heavy dependencies.
Runtime Performance optimization includes React.memo for expensive components, useMemo and useCallback for computations, virtual scrolling for large lists, and debouncing user interactions.
Accessibility includes ARIA attributes for all interactive elements, keyboard navigation support, focus management, and screen reader testing.
The composable pattern involves importing Card, CardHeader, CardTitle, and CardContent from the ui/card components. A DashboardCard component accepts a title and children props, wrapping them in the Card structure with CardHeader containing CardTitle and CardContent containing the children.
The Zod and React Hook Form integration pattern involves importing useForm from react-hook-form, zodResolver from hookform/resolvers/zod, and z from zod. Define a formSchema with z.object containing field validations such as z.string().email() for email and z.string().min(8) for password. Infer the FormValues type from the schema. The form component uses useForm with zodResolver passing the formSchema. The form element uses form.handleSubmit with an onSubmit handler.
Related Libraries:
Official Documentation:
Latest Versions as of March 2026:
Last Updated: 2026-03-28 Status: Production Ready
Weekly Installs
75
Repository
GitHub Stars
906
First Seen
Jan 22, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
codex60
opencode60
gemini-cli59
claude-code58
cursor55
github-copilot53
TanStack Query v5 完全指南:React 数据管理、乐观更新、离线支持
2,500 周安装