moai-adk 0.25.4__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-library-shadcn/SKILL.md

@@ -0,0 +1,373 @@
+---
+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: 2026-01-08
+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 (
+ <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-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