moai-library-shadcn

name	moai-library-shadcn
description	Moai Lib Shadcn Ui - Professional implementation guide

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:

npx shadcn-ui@latest init

Step 2: Configure components.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:

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

# 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=._design_integration_patterns(
 requirements.framework_stack
 ),
 customization_strategy=._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:

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:

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 - Advanced component patterns and implementation
• shadcn Theming - Theme system and customization strategies
• moai-domain-uiux - Design system architecture and principles
• moai-lang-unified - TypeScript best practices
• code-frontend - Frontend development patterns

---

Context7 Integration

Related Libraries:

• shadcn/ui: Re-usable components built with Radix UI and Tailwind
• Radix UI: Unstyled, accessible component primitives
• Tailwind CSS: Utility-first CSS framework

Official Documentation:

• shadcn/ui Documentation
• API Reference
• Radix UI Documentation
• Tailwind CSS Documentation

Latest Versions (November 2025):

• React 19
• TypeScript 5.5
• Tailwind CSS 3.4
• Radix UI Latest

---

Last Updated: 2025-11-21 Status: Production Ready