diff options
Diffstat (limited to 'ui/shadcn/README.md')
| -rw-r--r-- | ui/shadcn/README.md | 448 |
1 files changed, 448 insertions, 0 deletions
diff --git a/ui/shadcn/README.md b/ui/shadcn/README.md new file mode 100644 index 0000000..c82d1f1 --- /dev/null +++ b/ui/shadcn/README.md @@ -0,0 +1,448 @@ +# shadcn/ui Claude Code Configuration 🎨 + +A comprehensive Claude Code configuration for building beautiful, accessible, and customizable UI components with shadcn/ui. This configuration transforms Claude into an expert shadcn/ui developer with deep knowledge of React patterns, Tailwind CSS, Radix UI, and modern accessibility standards. + +## ✨ Features + +This configuration provides comprehensive shadcn/ui development support: + +- **10 Specialized AI Agents** for different aspects of UI development +- **8 Powerful Commands** for component scaffolding and optimization +- **Intelligent Hooks** for automated validation and formatting +- **Optimized Settings** for shadcn/ui workflows +- **Comprehensive Memory** with component patterns and best practices +- **Framework-agnostic** support (Next.js, Vite, Remix, Astro, etc.) + +## 📦 Installation + +1. Copy the configuration to your shadcn/ui project: + +```bash +# Copy the entire configuration +cp -r shadcn/.claude your-project/ +cp shadcn/CLAUDE.md your-project/ + +# Make hook scripts executable (if any) +chmod +x your-project/.claude/hooks/*.sh +``` + +2. Initialize shadcn/ui in your project (if not already done): + +```bash +npx shadcn@latest init +``` + +3. The configuration will be automatically loaded when you start Claude Code. + +## 📁 Configuration Structure + +```text +.claude/ +├── settings.json # Main configuration with permissions and hooks +├── agents/ # Specialized AI subagents +│ ├── component-builder.md # Component creation specialist +│ ├── accessibility-auditor.md # A11y compliance expert +│ ├── tailwind-optimizer.md # Tailwind CSS optimization +│ ├── radix-expert.md # Radix UI primitives specialist +│ ├── form-specialist.md # Form and validation expert +│ ├── data-display-expert.md # Tables and charts specialist +│ ├── theme-designer.md # Theming and styling expert +│ ├── animation-specialist.md # Animations and transitions +│ ├── migration-expert.md # Component migration specialist +│ └── performance-optimizer.md # Performance optimization +├── commands/ # Custom slash commands +│ ├── add-component.md # Scaffold new component +│ ├── create-variant.md # Add component variant +│ ├── setup-form.md # Set up form with validation +│ ├── create-data-table.md # Create data table +│ ├── setup-dark-mode.md # Configure dark mode +│ ├── analyze-accessibility.md # A11y audit +│ ├── optimize-bundle.md # Bundle optimization +│ └── migrate-component.md # Migrate existing components +└── hooks/ # Automation scripts + ├── validate-components.sh # Component validation + ├── format-tailwind.sh # Tailwind class sorting + ├── check-accessibility.sh # A11y checks + └── optimize-imports.sh # Import optimization + +CLAUDE.md # Main expertise instructions +README.md # This file +``` + +## 🤖 Specialized Agents (10 Expert Agents) + +### Core Development Agents + +| Agent | Description | Use Cases | +|-------|-------------|-----------| +| `component-builder` | Component creation specialist | Building new shadcn/ui components, proper TypeScript types, variant systems | +| `accessibility-auditor` | Accessibility compliance expert | ARIA attributes, keyboard navigation, screen reader support | +| `tailwind-optimizer` | Tailwind CSS specialist | Utility classes, custom CSS properties, responsive design | +| `radix-expert` | Radix UI primitives specialist | Behavior implementation, primitive composition, portal usage | +| `form-specialist` | Form and validation expert | React Hook Form integration, Zod schemas, error handling | + +### Advanced Feature Agents + +| Agent | Description | Use Cases | +|-------|-------------|-----------| +| `data-display-expert` | Tables and charts specialist | TanStack Table, Recharts, data visualization | +| `theme-designer` | Theming and styling expert | CSS variables, color systems, dark mode | +| `animation-specialist` | Animation and transitions expert | Framer Motion, CSS transitions, gesture handling | +| `migration-expert` | Component migration specialist | Converting existing components to shadcn/ui patterns | +| `performance-optimizer` | Performance optimization expert | Bundle size, code splitting, lazy loading | + +## 🛠️ Commands (8 Powerful Commands) + +| Command | Description | Usage | +|---------|-------------|-------| +| `/add-component` | Scaffold new shadcn/ui component | `/add-component button dialog card` | +| `/create-variant` | Add variant to existing component | `/create-variant button size=xl` | +| `/setup-form` | Set up form with validation | `/setup-form contact-form` | +| `/create-data-table` | Create advanced data table | `/create-data-table users` | +| `/setup-dark-mode` | Configure dark mode | `/setup-dark-mode [next\|vite\|remix]` | +| `/analyze-accessibility` | Run accessibility audit | `/analyze-accessibility` | +| `/optimize-bundle` | Optimize bundle size | `/optimize-bundle` | +| `/migrate-component` | Migrate to shadcn/ui patterns | `/migrate-component Button.jsx` | + +## 🪝 Automation Hooks + +### Pre-commit Validation + +- **Component Structure Validator** (`validate-components.sh`) + - Validates proper component structure + - Checks for required TypeScript types + - Ensures proper forwardRef usage + - Validates variant system implementation + +### Auto-formatting + +- **Tailwind Class Sorter** (`format-tailwind.sh`) + - Sorts Tailwind classes automatically + - Merges duplicate classes + - Orders responsive modifiers + - Groups related utilities + +### Accessibility Checks + +- **A11y Validator** (`check-accessibility.sh`) + - Validates ARIA attributes + - Checks keyboard navigation support + - Ensures proper focus management + - Validates color contrast + +### Import Optimization + +- **Import Optimizer** (`optimize-imports.sh`) + - Removes unused imports + - Orders imports consistently + - Groups related imports + - Validates component exports + +## ⚙️ Configuration Details + +### Security Permissions + +**Allowed Operations:** +- All file operations in components/ui directory +- NPM commands for component installation +- shadcn CLI commands +- Development server commands +- Testing and linting commands +- Git operations for version control + +**Denied Operations:** +- Modifying node_modules +- Deleting core configuration files +- Publishing to npm without review +- Modifying system files + +### Environment Variables + +Pre-configured for shadcn/ui development: + +```env +# Component configuration +SHADCN_STYLE=new-york +SHADCN_RSC=true +SHADCN_TSX=true +SHADCN_CSS_VARIABLES=true +SHADCN_TAILWIND_CONFIG=tailwind.config.js +SHADCN_COMPONENTS_PATH=@/components +SHADCN_UTILS_PATH=@/lib/utils +SHADCN_BASE_COLOR=zinc +``` + +## 🚀 Usage Examples + +### Creating a New Component + +```bash +# Add official shadcn/ui component +> /add-component sheet + +# Create custom component following shadcn patterns +> Use the component-builder agent to create a custom DateRangePicker component +``` + +### Setting Up Forms + +```bash +# Create a complete form with validation +> /setup-form user-registration + +# The command will: +# - Create form component structure +# - Set up React Hook Form +# - Add Zod validation schema +# - Create all form fields +# - Add error handling +``` + +### Implementing Data Tables + +```bash +# Create an advanced data table +> /create-data-table products + +# Features included: +# - Sorting and filtering +# - Pagination +# - Row selection +# - Column visibility +# - Export functionality +``` + +### Dark Mode Setup + +```bash +# Configure dark mode for your framework +> /setup-dark-mode next + +# Sets up: +# - Theme provider +# - CSS variables +# - Toggle component +# - System preference detection +# - Cookie persistence +``` + +## 📊 Component Categories + +### Form Controls +```tsx +// Comprehensive form component support +<Form> + <FormField + control={form.control} + name="email" + render={({ field }) => ( + <FormItem> + <FormLabel>Email</FormLabel> + <FormControl> + <Input {...field} /> + </FormControl> + <FormDescription>Your email address</FormDescription> + <FormMessage /> + </FormItem> + )} + /> +</Form> +``` + +### Overlay Components +```tsx +// Accessible modal patterns +<Dialog> + <DialogTrigger asChild> + <Button>Open Dialog</Button> + </DialogTrigger> + <DialogContent> + <DialogHeader> + <DialogTitle>Title</DialogTitle> + <DialogDescription>Description</DialogDescription> + </DialogHeader> + </DialogContent> +</Dialog> +``` + +### Data Display +```tsx +// Advanced table with TanStack Table +<DataTable + columns={columns} + data={data} + searchKey="email" + pagination + sorting + filtering +/> +``` + +## 🎨 Theming System + +### CSS Variables +```css +/* Automatic theme switching */ +:root { + --background: 0 0% 100%; + --foreground: 222.2 84% 4.9%; + --primary: 222.2 47.4% 11.2%; + --primary-foreground: 210 40% 98%; +} + +.dark { + --background: 222.2 84% 4.9%; + --foreground: 210 40% 98%; + --primary: 210 40% 98%; + --primary-foreground: 222.2 84% 4.9%; +} +``` + +### Component Variants +```tsx +// CVA-powered variant system +const buttonVariants = cva( + "base-classes", + { + variants: { + variant: { + default: "...", + destructive: "...", + outline: "...", + }, + size: { + default: "...", + sm: "...", + lg: "...", + } + } + } +) +``` + +## 📝 Best Practices Enforced + +1. **Accessibility First** - WCAG 2.1 AA compliance +2. **Type Safety** - Full TypeScript support +3. **Component Composition** - Flexible, reusable patterns +4. **Performance** - Optimized bundle size and runtime +5. **Customization** - Easy to modify and extend +6. **Framework Agnostic** - Works with any React framework +7. **Dark Mode** - Built-in theme support +8. **Mobile First** - Responsive by default + +## 🔧 Framework-Specific Support + +### Next.js (13-15) +- App Router support +- Server Components compatibility +- Streaming and Suspense +- Metadata API integration + +### Vite +- Fast HMR +- Optimized builds +- Tailwind v4 support + +### Remix +- Progressive enhancement +- Action/Loader patterns +- Session-based theming + +### Astro +- Island architecture +- Partial hydration +- Multi-framework support + +## 🐛 Troubleshooting + +### Common Issues + +**Components not styling correctly:** +```bash +# Verify Tailwind configuration +npx shadcn@latest init + +# Check CSS import +# Ensure globals.css is imported in your app +``` + +**TypeScript errors:** +```bash +# Update TypeScript config +# Ensure paths are configured correctly +{ + "compilerOptions": { + "paths": { + "@/*": ["./*"] + } + } +} +``` + +**Dark mode not working:** +```bash +# Verify theme provider setup +# Check CSS variables are defined +# Ensure class/data attribute is applied to html +``` + +## 🚀 Quick Start Example + +```bash +# 1. Initialize a new Next.js project +npx create-next-app@latest my-app --typescript --tailwind + +# 2. Initialize shadcn/ui +cd my-app +npx shadcn@latest init + +# 3. Copy Claude configuration +cp -r path/to/shadcn/.claude . +cp path/to/shadcn/CLAUDE.md . + +# 4. Add your first components +npx shadcn@latest add button card form + +# 5. Start developing with Claude Code +# Claude now has full shadcn/ui expertise! +``` + +## 📚 Resources + +- [shadcn/ui Documentation](https://ui.shadcn.com) +- [Component Examples](https://ui.shadcn.com/examples) +- [Radix UI Primitives](https://radix-ui.com) +- [Tailwind CSS](https://tailwindcss.com) +- [React Hook Form](https://react-hook-form.com) +- [Zod Validation](https://zod.dev) + +## 🎯 What Makes This Configuration Special + +### Complete Development Environment +- **10 Expert Agents** - Specialized AI assistants for every aspect of UI development +- **8 Power Commands** - From component creation to optimization +- **4 Smart Hooks** - Automatic validation, formatting, and optimization +- **Comprehensive Settings** - Pre-configured for shadcn/ui best practices + +### Key Capabilities +1. **Component Generation** - Create components following shadcn/ui patterns +2. **Accessibility Compliance** - Built-in WCAG 2.1 AA validation +3. **Performance Optimization** - Automatic bundle and runtime optimization +4. **Framework Support** - Works with Next.js, Vite, Remix, Astro, and more +5. **Theme Management** - Complete dark mode and theming system + +### Perfect For +- Building modern React applications with shadcn/ui +- Creating accessible, performant UI components +- Implementing design systems with Tailwind CSS +- Migrating existing components to shadcn/ui patterns +- Learning React component best practices + +--- + +**Built for the modern web** 🚀 + +*Create beautiful, accessible, and customizable UI components with shadcn/ui and Claude Code.* + +**Configuration Version:** 1.0.0 | **Compatible with:** shadcn/ui 0.8+, React 18+, Tailwind CSS 3.4+
\ No newline at end of file |