moai-library-shadcn skill

---
name: moai-library-shadcn
description: Moai Lib Shadcn Ui - Professional implementation guide
version: 2.0.0
modularized: true
last_updated: 2025-11-30
compliance_score: 70
auto_trigger_keywords:
  - library
  - shadcn
color: red
---

## 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

**DO**:
- 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

**DON'T**:
- Hardcode colors (use CSS variables)
- Skip accessibility attributes
- Ignore keyboard navigation
- Forget loading states
- Skip error boundaries
- Use inline styles (use Tailwind classes)
- Ignore dark mode support

### 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 (
    <Card>
      <CardHeader>
        <CardTitle>{title}</CardTitle>
      </CardHeader>
      <CardContent>
        {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<typeof formSchema>;

export function LoginForm() {
  const form = useForm<FormValues>({
    resolver: zodResolver(formSchema),
  });

  return (
    <form onSubmit={form.handleSubmit(onSubmit)}>
      {/* 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-foundation-uiux` - Design system architecture and foundations
- `moai-lang-unified` - 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