@jini-ai/agent-plugins 0.6.16 → 0.6.19

package/ui-ux-design/skills/shadcn-ui/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: shadcn-ui
+description: Expert guidance for integrating and building applications with shadcn/ui components, including component discovery, installation, customization, and best practices.
+allowed-tools:
+  - "shadcn*:*"
+  - "mcp_shadcn*"
+  - "Read"
+  - "Write"
+  - "Bash"
+  - "web_fetch"
+---
+
+# shadcn/ui Component Integration
+
+Discover the tools available in the current host before using them. Use only
+capabilities that the host provides and permits. The CLI and React examples below
+describe work in an authorized coding checkout; they do not authorize shell commands
+or dependency installation in another environment. If shadcn MCP tools are
+unavailable, explain the limitation. Do not invent tool availability or install
+dependencies to bypass host restrictions.
+
+You are a frontend engineer specialized in building applications with shadcn/ui—a collection of beautifully designed, accessible, and customizable components built with Radix UI or Base UI and Tailwind CSS. You help developers discover, integrate, and customize components following best practices.
+
+## Core Principles
+
+shadcn/ui is **not a component library**—it's a collection of reusable components that you copy into your project. This gives you:
+- **Full ownership**: Components live in your codebase, not node_modules
+- **Complete customization**: Modify styling, behavior, and structure freely, including choosing between Radix UI or Base UI primitives
+- **No version lock-in**: Update components selectively at your own pace
+- **Zero runtime overhead**: No library bundle, just the code you need
+
+## Component Discovery and Installation
+
+### 1. Browse Available Components
+
+Use the shadcn MCP tools to explore the component catalog and Registry Directory:
+- **List all components**: Use `list_components` to see the complete catalog
+- **Get component metadata**: Use `get_component_metadata` to understand props, dependencies, and usage
+- **View component demos**: Use `get_component_demo` to see implementation examples
+
+### 2. Component Installation
+
+There are two approaches to adding components:
+
+**A. Direct Installation (Recommended)**
+```bash
+npx shadcn@latest add [component-name]
+```
+
+This command:
+- Downloads the component source code (adapting to your config: Radix vs Base UI)
+- Installs required dependencies
+- Places files in `components/ui/`
+- Updates your `components.json` config
+
+**B. Manual Integration**
+1. Use `get_component` to retrieve the source code
+2. Create the file in `components/ui/[component-name].tsx`
+3. Install peer dependencies manually
+4. Adjust imports if needed
+
+### 3. Registry and Custom Registries
+
+If working with a custom registry (defined in `components.json`) or exploring the Registry Directory:
+- Use `get_project_registries` to list available registries
+- Use `list_items_in_registries` to see registry-specific components
+- Use `view_items_in_registries` for detailed component information
+- Use `search_items_in_registries` to find specific components
+
+## Project Setup
+
+### Initial Configuration
+
+For **new projects**, use the `create` command to customize everything (style, fonts, component library):
+
+```bash
+npx shadcn@latest create
+```
+
+For **existing projects**, initialize configuration:
+
+```bash
+npx shadcn@latest init
+```
+
+This creates `components.json` with your configuration:
+- **style**: default, new-york (classic) OR choose new visual styles like Vega, Nova, Maia, Lyra, Mira
+- **baseColor**: slate, gray, zinc, neutral, stone
+- **cssVariables**: true/false for CSS variable usage
+- **tailwind config**: paths to Tailwind files
+- **aliases**: import path shortcuts
+- **rsc**: Use React Server Components (yes/no)
+- **rtl**: Enable RTL support (optional)
+
+### Required Dependencies
+
+shadcn/ui components require:
+- **React** (18+)
+- **Tailwind CSS** (3.0+)
+- **Primitives**: Radix UI OR Base UI (depending on your choice)
+- **class-variance-authority** (for variant styling)
+- **clsx** and **tailwind-merge** (for class composition)
+
+## Component Architecture
+
+### File Structure
+```
+src/
+├── components/
+│   ├── ui/              # shadcn components
+│   │   ├── button.tsx
+│   │   ├── card.tsx
+│   │   └── dialog.tsx
+│   └── [custom]/        # your composed components
+│       └── user-card.tsx
+├── lib/
+│   └── utils.ts         # cn() utility
+└── app/
+    └── page.tsx
+```
+
+### The `cn()` Utility
+
+All shadcn components use the `cn()` helper for class merging:
+
+```typescript
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+```
+
+This allows you to:
+- Override default styles without conflicts
+- Conditionally apply classes
+- Merge Tailwind classes intelligently
+
+## Customization Best Practices
+
+### 1. Theme Customization
+
+Edit your Tailwind config and CSS variables in `app/globals.css`:
+
+```css
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 222.2 84% 4.9%;
+    --primary: 221.2 83.2% 53.3%;
+    /* ... more variables */
+  }
+  
+  .dark {
+    --background: 222.2 84% 4.9%;
+    --foreground: 210 40% 98%;
+    /* ... dark mode overrides */
+  }
+}
+```
+
+### 2. Component Variants
+
+Use `class-variance-authority` (cva) for variant logic:
+
+```typescript
+import { cva } from "class-variance-authority"
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center rounded-md",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground",
+        outline: "border border-input",
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+```
+
+### 3. Extending Components
+
+Create wrapper components in `components/` (not `components/ui/`):
+
+```typescript
+// components/custom-button.tsx
+import { Button } from "@/components/ui/button"
+import { Loader2 } from "lucide-react"
+
+export function LoadingButton({ 
+  loading, 
+  children, 
+  ...props 
+}: ButtonProps & { loading?: boolean }) {
+  return (
+    <Button disabled={loading} {...props}>
+      {loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+      {children}
+    </Button>
+  )
+}
+```
+
+## Blocks and Complex Components
+
+shadcn/ui provides complete UI blocks (authentication forms, dashboards, etc.):
+
+1. **List available blocks**: Use `list_blocks` with optional category filter
+2. **Get block source**: Use `get_block` with the block name
+3. **Install blocks**: Many blocks include multiple component files
+
+Blocks are organized by category:
+- **calendar**: Calendar interfaces
+- **dashboard**: Dashboard layouts
+- **login**: Authentication flows
+- **sidebar**: Navigation sidebars
+- **products**: E-commerce components
+
+## Accessibility
+
+All shadcn/ui components are built on Radix UI primitives, ensuring:
+- **Keyboard navigation**: Full keyboard support out of the box
+- **Screen reader support**: Proper ARIA attributes
+- **Focus management**: Logical focus flow
+- **Disabled states**: Proper disabled and aria-disabled handling
+
+When customizing, maintain accessibility:
+- Keep ARIA attributes
+- Preserve keyboard handlers
+- Test with screen readers
+- Maintain focus indicators
+
+## Common Patterns
+
+### Form Building
+```typescript
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+
+// Use with react-hook-form for validation
+import { useForm } from "react-hook-form"
+```
+
+### Dialog/Modal Patterns
+```typescript
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog"
+```
+
+### Data Display
+```typescript
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@/components/ui/table"
+```
+
+## Troubleshooting
+
+### Import Errors
+- Check `components.json` for correct alias configuration
+- Verify `tsconfig.json` includes the `@` path alias:
+  ```json
+  {
+    "compilerOptions": {
+      "paths": {
+        "@/*": ["./src/*"]
+      }
+    }
+  }
+  ```
+
+### Style Conflicts
+- Ensure Tailwind CSS is properly configured
+- Check that `globals.css` is imported in your root layout
+- Verify CSS variable names match between components and theme
+
+### Missing Dependencies
+- Run component installation via CLI to auto-install deps
+- Manually check `package.json` for required Radix UI packages
+- Use `get_component_metadata` to see dependency lists
+
+### Version Compatibility
+- shadcn/ui v4 requires React 18+ and Next.js 13+ (if using Next.js)
+- Some components require specific Radix UI versions
+- Check documentation for breaking changes between versions
+
+## Validation and Quality
+
+Before committing components:
+1. **Type check**: Run `tsc --noEmit` to verify TypeScript
+2. **Lint**: Run your linter to catch style issues
+3. **Test accessibility**: Use tools like axe DevTools
+4. **Visual QA**: Test in light and dark modes
+5. **Responsive check**: Verify behavior at different breakpoints
+
+## Resources
+
+Refer to the following resource files for detailed guidance:
+- `resources/setup-guide.md` - Step-by-step project initialization
+- `resources/component-catalog.md` - Complete component reference
+- `resources/customization-guide.md` - Theming and variant patterns
+- `resources/migration-guide.md` - Upgrading from other UI libraries
+
+## Examples
+
+See the `examples/` directory for:
+- Complete component implementations
+- Form patterns with validation
+- Dashboard layouts
+- Authentication flows
+- Data table implementations

package/ui-ux-design/skills/shadcn-ui/examples/auth-layout.tsx

@@ -0,0 +1,177 @@
+// Example: Authentication Layout with shadcn/ui
+// Demonstrates: Layout composition, card usage, form integration
+
+"use client"
+
+import { Button } from "@/components/ui/button"
+import {
+    Card,
+    CardContent,
+    CardDescription,
+    CardFooter,
+    CardHeader,
+    CardTitle,
+} from "@/components/ui/card"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"
+import { useState } from "react"
+
+export function AuthLayout() {
+  const [isLoading, setIsLoading] = useState<boolean>(false)
+
+  async function onSubmit(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault()
+    setIsLoading(true)
+
+    // Simulate API call
+    setTimeout(() => {
+      setIsLoading(false)
+    }, 2000)
+  }
+
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-muted/40">
+      <Tabs defaultValue="login" className="w-[400px]">
+        <TabsList className="grid w-full grid-cols-2">
+          <TabsTrigger value="login">Login</TabsTrigger>
+          <TabsTrigger value="register">Register</TabsTrigger>
+        </TabsList>
+        
+        <TabsContent value="login">
+          <Card>
+            <CardHeader>
+              <CardTitle>Login</CardTitle>
+              <CardDescription>
+                Enter your credentials to access your account.
+              </CardDescription>
+            </CardHeader>
+            <form onSubmit={onSubmit}>
+              <CardContent className="space-y-4">
+                <div className="space-y-2">
+                  <Label htmlFor="email">Email</Label>
+                  <Input
+                    id="email"
+                    type="email"
+                    placeholder="m@example.com"
+                    required
+                  />
+                </div>
+                <div className="space-y-2">
+                  <Label htmlFor="password">Password</Label>
+                  <Input
+                    id="password"
+                    type="password"
+                    required
+                  />
+                </div>
+              </CardContent>
+              <CardFooter className="flex flex-col space-y-4">
+                <Button 
+                  type="submit" 
+                  className="w-full"
+                  disabled={isLoading}
+                >
+                  {isLoading ? "Signing in..." : "Sign in"}
+                </Button>
+                <Button
+                  type="button"
+                  variant="link"
+                  className="w-full text-sm text-muted-foreground"
+                >
+                  Forgot password?
+                </Button>
+              </CardFooter>
+            </form>
+          </Card>
+        </TabsContent>
+        
+        <TabsContent value="register">
+          <Card>
+            <CardHeader>
+              <CardTitle>Create an account</CardTitle>
+              <CardDescription>
+                Enter your information to create an account.
+              </CardDescription>
+            </CardHeader>
+            <form onSubmit={onSubmit}>
+              <CardContent className="space-y-4">
+                <div className="space-y-2">
+                  <Label htmlFor="name">Name</Label>
+                  <Input
+                    id="name"
+                    placeholder="John Doe"
+                    required
+                  />
+                </div>
+                <div className="space-y-2">
+                  <Label htmlFor="register-email">Email</Label>
+                  <Input
+                    id="register-email"
+                    type="email"
+                    placeholder="m@example.com"
+                    required
+                  />
+                </div>
+                <div className="space-y-2">
+                  <Label htmlFor="register-password">Password</Label>
+                  <Input
+                    id="register-password"
+                    type="password"
+                    required
+                  />
+                </div>
+                <div className="space-y-2">
+                  <Label htmlFor="confirm-password">Confirm Password</Label>
+                  <Input
+                    id="confirm-password"
+                    type="password"
+                    required
+                  />
+                </div>
+              </CardContent>
+              <CardFooter>
+                <Button 
+                  type="submit" 
+                  className="w-full"
+                  disabled={isLoading}
+                >
+                  {isLoading ? "Creating account..." : "Create account"}
+                </Button>
+              </CardFooter>
+            </form>
+          </Card>
+        </TabsContent>
+      </Tabs>
+    </div>
+  )
+}
+
+/**
+ * Key Patterns Demonstrated:
+ * 
+ * 1. Layout Composition: Centered authentication card with full-height viewport
+ * 2. Card Usage: Structured content with header, body, and footer
+ * 3. Tabs: Switch between login and register forms
+ * 4. Form Structure: Proper labeling and input grouping
+ * 5. Loading States: Button disabled state during form submission
+ * 6. Responsive Design: Mobile-friendly with max-width constraint
+ * 7. Tailwind Utilities: Using spacing, flexbox, and grid utilities
+ * 
+ * Design Choices:
+ * - Minimal, clean interface focusing on the task at hand
+ * - Proper semantic HTML with form elements
+ * - Accessible labels and inputs
+ * - Clear visual hierarchy with card components
+ * - Loading feedback for better UX
+ * 
+ * Required Dependencies:
+ * None beyond React and shadcn/ui components
+ * 
+ * Installation:
+ * npx shadcn@latest add card
+ * npx shadcn@latest add input
+ * npx shadcn@latest add label
+ * npx shadcn@latest add button
+ * npx shadcn@latest add tabs
+ */