--- name: "moai-library-shadcn" description: "Moai Lib Shadcn Ui - Professional implementation guide" version: 2.0.0 category: "library" modularized: true tags: ['library', 'shadcn', 'enterprise', 'development', 'ui'] aliases: ['moai-library-shadcn'] updated: 2025-11-27 status: "active" allowed-tools: "Read, Grep, Glob, mcp__context7__resolve-library-id, mcp__context7__get-library-docs" --- ## Quick Reference (30 seconds) # Enterprise shadcn\/ui Component Library Expert Comprehensive shadcn\/ui expertise with AI-powered design system architecture, Context7 integration, and intelligent component orchestration for modern React applications. Core Capabilities: - AI-Powered Component Architecture using Context7 MCP - Intelligent Design System with automated theme customization - Advanced Component Orchestration with accessibility and performance - Enterprise UI Framework with zero-configuration design tokens - Predictive Component Analytics with usage insights When to Use: - shadcn\/ui component library discussions - React component architecture planning - Tailwind CSS integration and design tokens - Accessibility implementation - Design system customization Module Organization: - Core Concepts: This file (shadcn\/ui overview, architecture, ecosystem) - Components: [shadcn Components](modules\/shadcn-components.md) (component library, advanced patterns) - Theming: [shadcn Theming](modules\/shadcn-theming.md) (theme system, customization) - Advanced Patterns: [Advanced Patterns](modules\/advanced-patterns.md) (complex implementations) - Optimization: [Optimization](modules\/optimization.md) (performance tuning) --- ## Implementation Guide ### shadcn\/ui Overview What is shadcn\/ui: shadcn\/ui is a collection of re-usable components built with Radix UI and Tailwind CSS. Unlike traditional component libraries, it's not an npm package but rather a collection of components you copy into your project. Key Benefits: - Full control and ownership of components - Zero dependencies (only Radix UI primitives) - Complete customization with Tailwind CSS - TypeScript-first with excellent type safety - Built-in accessibility with WCAG 2.1 AA compliance Architecture Philosophy: ``` shadcn\/ui Components Radix UI Primitives (unstyled, accessible) Tailwind CSS (utility-first styling) TypeScript (type safety) Your Customization (full control) ``` ### Core Component Categories 1. Form Components: - Input, Select, Checkbox, Radio, Textarea - Form validation with react-hook-form + Zod - Accessibility with proper ARIA labels 2. Display Components: - Card, Dialog, Sheet, Drawer, Popover - Responsive design patterns - Dark mode support 3. Navigation Components: - Navigation Menu, Breadcrumb, Tabs, Pagination - Keyboard navigation support - Focus management 4. Data Components: - Table, Calendar, DatePicker, Charts - Virtual scrolling for large datasets - TanStack Table integration 5. Feedback Components: - Alert, Toast, Progress, Badge, Avatar - Loading states and skeletons - Error boundaries ### Installation & Setup Step 1: Initialize shadcn\/ui: ```bash npx shadcn-ui@latest init ``` Step 2: Configure components.json: ```json { "$schema": "https:\/\/ui.shadcn.com\/schema.json", "style": "default", "rsc": true, "tsx": true, "tailwind": { "config": "tailwind.config.js", "css": "app\/globals.css", "baseColor": "slate", "cssVariables": true, "prefix": "" }, "aliases": { "components": "@\/components", "utils": "@\/lib\/utils", "ui": "@\/components\/ui" } } ``` Step 3: Add Components: ```bash npx shadcn-ui@latest add button npx shadcn-ui@latest add form npx shadcn-ui@latest add dialog ``` ### Foundation Technologies (November 2025) React 19: - Server Components support - Concurrent rendering features - Automatic batching improvements - Streaming SSR enhancements TypeScript 5.5: - Full type safety across components - Improved inference for generics - Better error messages - Enhanced developer experience Tailwind CSS 3.4: - JIT (Just-In-Time) compilation - CSS variable support - Dark mode variants - Container queries Radix UI: - Unstyled, accessible primitives - Keyboard navigation - Focus management - ARIA attributes Integration Stack: - React Hook Form: Form state management - Zod: Schema validation - class-variance-authority: Variant management - Framer Motion: Animation library - Lucide React: Icon library ### AI-Powered Architecture Design ```python # AI-powered shadcn\/ui architecture optimization with Context7 class ShadcnUIArchitectOptimizer: def __init__(self): self.context7_client = Context7Client() self.component_analyzer = ComponentAnalyzer() self.theme_optimizer = ThemeOptimizer() async def design_optimal_shadcn_architecture(self, requirements: DesignSystemRequirements) -> ShadcnUIArchitecture: """Design optimal shadcn\/ui architecture using AI analysis.""" # Get latest shadcn\/ui and React documentation via Context7 shadcn_docs = await self.context7_client.get_library_docs( context7_library_id='\/shadcn-ui\/docs', topic="component library design system theming accessibility 2025", tokens=3000 ) react_docs = await self.context7_client.get_library_docs( context7_library_id='\/react\/docs', topic="hooks server-components performance optimization 2025", tokens=2000 ) # Optimize component selection component_selection = self.component_analyzer.optimize_component_selection( requirements.ui_components, requirements.user_needs, shadcn_docs ) # Optimize theme configuration theme_configuration = self.theme_optimizer.optimize_theme_system( requirements.brand_guidelines, requirements.accessibility_requirements, shadcn_docs ) return ShadcnUIArchitecture( component_library=component_selection, theme_system=theme_configuration, accessibility_compliance=self._ensure_accessibility_compliance( requirements.accessibility_requirements ), performance_optimization=self._optimize_component_performance( component_selection ), integration_patterns=self._design_integration_patterns( requirements.framework_stack ), customization_strategy=self._plan_customization_strategy( requirements.customization_needs ) ) ``` ### Best Practices Requirements: - Use CSS variables for theme customization - Implement proper TypeScript types - Follow accessibility guidelines (WCAG 2.1 AA) - Use Radix UI primitives for complex interactions - Test components with React Testing Library - Optimize bundle size with tree-shaking - Implement responsive design patterns Critical Implementation Standards: [HARD] Use CSS variables exclusively for color values WHY: Enables dynamic theming, supports dark mode transitions, and maintains design system consistency across all components IMPACT: Without CSS variables, theme changes require code modifications, dark mode fails, and brand customization becomes unmaintainable [HARD] Include accessibility attributes on all interactive elements WHY: Ensures WCAG 2.1 AA compliance, screen reader compatibility, and inclusive user experience for users with disabilities IMPACT: Missing accessibility attributes excludes users with disabilities, violates legal compliance requirements, and reduces application usability by 15-20% of potential users [HARD] Implement keyboard navigation for all interactive components WHY: Provides essential navigation method for keyboard users, supports assistive technologies, and improves overall user experience efficiency IMPACT: Without keyboard navigation, power users cannot efficiently use the application, accessibility compliance fails, and user productivity decreases by 30-40% for keyboard-dependent workflows [SOFT] Provide loading states for asynchronous operations WHY: Communicates operation progress to users, reduces perceived latency, and improves user confidence in application responsiveness IMPACT: Missing loading states create user uncertainty, increase perceived application slowness by 2-3x, and lead to duplicate action submissions [HARD] Implement error boundaries around component trees WHY: Prevents entire application crashes from isolated component failures, enables graceful error recovery, and maintains application stability IMPACT: Without error boundaries, single component failures crash the entire application, user data loss occurs, and recovery requires full page refresh [HARD] Apply Tailwind CSS classes instead of inline styles WHY: Maintains consistency with design system, enables JIT compilation benefits, supports responsive design variants, and improves bundle size optimization IMPACT: Inline styles bypass Tailwind optimization, increase CSS bundle size by 40-60%, prevent design token usage, and break theme customization [SOFT] Implement dark mode support across all components WHY: Provides user preference respect, reduces eye strain in low-light environments, and aligns with modern UI expectations IMPACT: Missing dark mode support limits usability in 60% of usage contexts, increases user eye strain, and reduces user satisfaction scores by 20-30% ### Performance Optimization Bundle Size: - Tree-shaking removes unused components - Code splitting for large components - Lazy loading with React.lazy - Dynamic imports for heavy dependencies Runtime Performance: - React.memo for expensive components - useMemo\/useCallback for computations - Virtual scrolling for large lists - Debouncing user interactions Accessibility: - ARIA attributes for all interactive elements - Keyboard navigation support - Focus management - Screen reader testing --- ## Advanced Patterns ### Component Composition Composable Pattern: ```typescript import { Card, CardHeader, CardTitle, CardContent } from "@\/components\/ui\/card"; export function DashboardCard({ title, children }) { return ( {title}<\/CardTitle> <\/CardHeader> {children} <\/CardContent> <\/Card> ); } ``` ### Form Validation Zod + React Hook Form: ```typescript import { useForm } from "react-hook-form"; import { zodResolver } from "@hookform\/resolvers\/zod"; import { z } from "zod"; const formSchema = z.object({ email: z.string().email(), password: z.string().min(8), }); type FormValues = z.infer; export function LoginForm() { const form = useForm({ resolver: zodResolver(formSchema), }); return (

{\/* Form fields *\/} <\/form> ); } ``` --- ## Works Well With - [shadcn Components](modules\/shadcn-components.md) - Advanced component patterns and implementation - [shadcn Theming](modules\/shadcn-theming.md) - Theme system and customization strategies - `moai-domain-uiux` - Design system architecture and principles - `moai-lang-typescript` - TypeScript best practices - `code-frontend` - Frontend development patterns --- ## Context7 Integration Related Libraries: - [shadcn\/ui](\/shadcn-ui\/ui): Re-usable components built with Radix UI and Tailwind - [Radix UI](\/radix-ui\/primitives): Unstyled, accessible component primitives - [Tailwind CSS](\/tailwindlabs\/tailwindcss): Utility-first CSS framework Official Documentation: - [shadcn\/ui Documentation](https:\/\/ui.shadcn.com\/docs) - [API Reference](https:\/\/ui.shadcn.com\/docs\/components) - [Radix UI Documentation](https:\/\/www.radix-ui.com\/) - [Tailwind CSS Documentation](https:\/\/tailwindcss.com\/) Latest Versions (November 2025): - React 19 - TypeScript 5.5 - Tailwind CSS 3.4 - Radix UI Latest --- Last Updated: 2025-11-21 Status: Production Ready