@fr0mpy/component-system 2.0.0

package/templates/component-recipes/accordion.md

@@ -0,0 +1,153 @@
+# Accordion Component Recipe
+
+## Structure
+- Root container with multiple items
+- Each item has trigger (header) and content
+- Chevron indicator that rotates on open
+- Support single or multiple items open
+
+## Tailwind Classes
+
+### Item
+```
+border-b border-border
+```
+
+### Trigger
+```
+flex flex-1 items-center justify-between py-4 text-sm font-medium
+transition-all hover:underline
+[&[data-state=open]>svg]:rotate-180
+```
+
+### Chevron Icon
+```
+h-4 w-4 shrink-0 text-muted-foreground transition-transform duration-200
+```
+
+### Content
+```
+overflow-hidden text-sm
+data-[state=closed]:animate-accordion-up
+data-[state=open]:animate-accordion-down
+```
+
+### Content Inner
+```
+pb-4 pt-0
+```
+
+## Animations (add to tailwind.config.js)
+```js
+keyframes: {
+  'accordion-down': {
+    from: { height: '0' },
+    to: { height: 'var(--radix-accordion-content-height)' },
+  },
+  'accordion-up': {
+    from: { height: 'var(--radix-accordion-content-height)' },
+    to: { height: '0' },
+  },
+},
+animation: {
+  'accordion-down': 'accordion-down 0.2s ease-out',
+  'accordion-up': 'accordion-up 0.2s ease-out',
+},
+```
+
+## Props Interface
+```typescript
+interface AccordionProps {
+  type?: 'single' | 'multiple'
+  defaultValue?: string | string[]
+  value?: string | string[]
+  onValueChange?: (value: string | string[]) => void
+  collapsible?: boolean // only for type="single"
+  children: React.ReactNode
+}
+
+interface AccordionItemProps {
+  value: string
+  disabled?: boolean
+  children: React.ReactNode
+}
+
+interface AccordionTriggerProps {
+  className?: string
+  children: React.ReactNode
+}
+
+interface AccordionContentProps {
+  className?: string
+  children: React.ReactNode
+}
+```
+
+## Do
+- Use Radix Accordion for accessibility
+- Animate height changes smoothly
+- Rotate chevron on open
+- Support both single and multiple modes
+
+## Don't
+- Hardcode colors
+- Skip keyboard accessibility
+- Use abrupt open/close (animate it)
+- Forget border between items
+
+## Example
+```tsx
+import * as AccordionPrimitive from '@radix-ui/react-accordion'
+import { ChevronDown } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+const Accordion = AccordionPrimitive.Root
+
+const AccordionItem = ({ className, ...props }) => (
+  <AccordionPrimitive.Item
+    className={cn('border-b border-border', className)}
+    {...props}
+  />
+)
+
+const AccordionTrigger = ({ className, children, ...props }) => (
+  <AccordionPrimitive.Header className="flex">
+    <AccordionPrimitive.Trigger
+      className={cn(
+        'flex flex-1 items-center justify-between py-4 text-sm font-medium',
+        'transition-all hover:underline [&[data-state=open]>svg]:rotate-180',
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <ChevronDown className="h-4 w-4 shrink-0 text-muted-foreground transition-transform duration-200" />
+    </AccordionPrimitive.Trigger>
+  </AccordionPrimitive.Header>
+)
+
+const AccordionContent = ({ className, children, ...props }) => (
+  <AccordionPrimitive.Content
+    className="overflow-hidden text-sm data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down"
+    {...props}
+  >
+    <div className={cn('pb-4 pt-0', className)}>{children}</div>
+  </AccordionPrimitive.Content>
+)
+
+// Usage
+<Accordion type="single" collapsible>
+  <AccordionItem value="item-1">
+    <AccordionTrigger>Is it accessible?</AccordionTrigger>
+    <AccordionContent>
+      Yes. It adheres to the WAI-ARIA design pattern.
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="item-2">
+    <AccordionTrigger>Is it styled?</AccordionTrigger>
+    <AccordionContent>
+      Yes. It comes with default styles that match your design system.
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```

package/templates/component-recipes/alert.md

@@ -0,0 +1,145 @@
+# Alert Component Recipe
+
+## Structure
+- Container with icon, title, and description
+- Support variants: info, success, warning, error/destructive
+- Optional dismiss button
+- Optional action buttons
+
+## Tailwind Classes
+
+### Container
+```
+relative w-full {tokens.radius} border p-4
+[&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:h-4 [&>svg]:w-4
+[&>svg+div]:translate-y-[-3px] [&:has(svg)]:pl-11
+```
+
+### Variants
+```
+default:     bg-background border-border text-foreground [&>svg]:text-foreground
+info:        bg-blue-500/10 border-blue-500/20 text-blue-600 [&>svg]:text-blue-600
+success:     bg-green-500/10 border-green-500/20 text-green-600 [&>svg]:text-green-600
+warning:     bg-yellow-500/10 border-yellow-500/20 text-yellow-600 [&>svg]:text-yellow-600
+destructive: bg-destructive/10 border-destructive/20 text-destructive [&>svg]:text-destructive
+```
+
+### Title
+```
+mb-1 font-medium leading-none tracking-tight
+```
+
+### Description
+```
+text-sm [&_p]:leading-relaxed
+```
+
+### Dismiss Button
+```
+absolute right-2 top-2 {tokens.radius} p-1 opacity-70
+hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-primary
+```
+
+## Props Interface
+```typescript
+interface AlertProps {
+  variant?: 'default' | 'info' | 'success' | 'warning' | 'destructive'
+  icon?: React.ReactNode
+  title?: string
+  onDismiss?: () => void
+  children: React.ReactNode
+}
+
+interface AlertTitleProps {
+  className?: string
+  children: React.ReactNode
+}
+
+interface AlertDescriptionProps {
+  className?: string
+  children: React.ReactNode
+}
+```
+
+## Icons per Variant
+```
+info:        <Info /> or <AlertCircle />
+success:     <CheckCircle />
+warning:     <AlertTriangle />
+destructive: <XCircle /> or <AlertOctagon />
+default:     <Info /> or custom
+```
+
+## Do
+- Include appropriate icon for each variant
+- Use semantic colors from tokens where possible
+- Support composable pattern (Alert.Title, Alert.Description)
+- Add dismiss functionality when needed
+
+## Don't
+- Hardcode colors
+- Make alerts too visually heavy
+- Forget to position icon properly
+- Skip the semantic meaning of variants
+
+## Example
+```tsx
+import { cn } from '@/lib/utils'
+import { AlertCircle, CheckCircle, AlertTriangle, XCircle, X, Info } from 'lucide-react'
+
+const alertVariants = {
+  default: 'bg-background border-border text-foreground',
+  info: 'bg-blue-500/10 border-blue-500/20 text-blue-600 [&>svg]:text-blue-600',
+  success: 'bg-green-500/10 border-green-500/20 text-green-600 [&>svg]:text-green-600',
+  warning: 'bg-yellow-500/10 border-yellow-500/20 text-yellow-600 [&>svg]:text-yellow-600',
+  destructive: 'bg-destructive/10 border-destructive/20 text-destructive [&>svg]:text-destructive',
+}
+
+const alertIcons = {
+  default: Info,
+  info: AlertCircle,
+  success: CheckCircle,
+  warning: AlertTriangle,
+  destructive: XCircle,
+}
+
+const Alert = ({ variant = 'default', title, onDismiss, className, children, ...props }) => {
+  const Icon = alertIcons[variant]
+
+  return (
+    <div
+      role="alert"
+      className={cn(
+        'relative w-full rounded-lg border p-4',
+        '[&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:h-4 [&>svg]:w-4',
+        '[&>svg+div]:translate-y-[-3px] [&:has(svg)]:pl-11',
+        alertVariants[variant],
+        className
+      )}
+      {...props}
+    >
+      <Icon className="h-4 w-4" />
+      <div>
+        {title && <AlertTitle>{title}</AlertTitle>}
+        <AlertDescription>{children}</AlertDescription>
+      </div>
+      {onDismiss && (
+        <button
+          onClick={onDismiss}
+          className="absolute right-2 top-2 rounded p-1 opacity-70 hover:opacity-100"
+        >
+          <X className="h-4 w-4" />
+        </button>
+      )}
+    </div>
+  )
+}
+
+const AlertTitle = ({ className, ...props }) => (
+  <h5 className={cn('mb-1 font-medium leading-none tracking-tight', className)} {...props} />
+)
+
+const AlertDescription = ({ className, ...props }) => (
+  <div className={cn('text-sm [&_p]:leading-relaxed', className)} {...props} />
+)
+```

package/templates/component-recipes/avatar.md

@@ -0,0 +1,165 @@
+# Avatar Component Recipe
+
+## Structure
+- Circular container for image or fallback
+- Support image, initials fallback, or icon fallback
+- Multiple sizes
+- Optional status indicator (online/offline)
+- Avatar group for stacking
+
+## Tailwind Classes
+
+### Container
+```
+relative flex shrink-0 overflow-hidden rounded-full
+```
+
+### Sizes
+```
+xs: h-6 w-6 text-xs
+sm: h-8 w-8 text-xs
+md: h-10 w-10 text-sm (default)
+lg: h-12 w-12 text-base
+xl: h-16 w-16 text-lg
+2xl: h-24 w-24 text-xl
+```
+
+### Image
+```
+aspect-square h-full w-full object-cover
+```
+
+### Fallback (initials or icon)
+```
+flex h-full w-full items-center justify-center rounded-full
+bg-muted text-muted-foreground font-medium
+```
+
+### Status Indicator
+```
+absolute bottom-0 right-0 h-3 w-3 rounded-full border-2 border-background
+online:  bg-green-500
+offline: bg-gray-400
+busy:    bg-red-500
+away:    bg-yellow-500
+```
+
+### Avatar Group
+```
+flex -space-x-2
+[&>*]:ring-2 [&>*]:ring-background
+```
+
+## Props Interface
+```typescript
+interface AvatarProps {
+  src?: string
+  alt?: string
+  fallback?: string | React.ReactNode
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+  status?: 'online' | 'offline' | 'busy' | 'away'
+}
+
+interface AvatarGroupProps {
+  max?: number
+  children: React.ReactNode
+}
+```
+
+## Do
+- Use Radix Avatar for image loading states
+- Show fallback immediately while image loads
+- Support both initials and icon fallbacks
+- Use ring for avatar group overlap effect
+
+## Don't
+- Hardcode colors
+- Forget alt text for images
+- Use non-square aspect ratios
+- Skip loading state handling
+
+## Example
+```tsx
+import * as AvatarPrimitive from '@radix-ui/react-avatar'
+import { cn } from '@/lib/utils'
+import { User } from 'lucide-react'
+
+const avatarSizes = {
+  xs: 'h-6 w-6 text-xs',
+  sm: 'h-8 w-8 text-xs',
+  md: 'h-10 w-10 text-sm',
+  lg: 'h-12 w-12 text-base',
+  xl: 'h-16 w-16 text-lg',
+  '2xl': 'h-24 w-24 text-xl',
+}
+
+const statusColors = {
+  online: 'bg-green-500',
+  offline: 'bg-gray-400',
+  busy: 'bg-red-500',
+  away: 'bg-yellow-500',
+}
+
+const Avatar = ({ src, alt, fallback, size = 'md', status, className }) => (
+  <div className="relative inline-block">
+    <AvatarPrimitive.Root
+      className={cn(
+        'relative flex shrink-0 overflow-hidden rounded-full',
+        avatarSizes[size],
+        className
+      )}
+    >
+      <AvatarPrimitive.Image
+        src={src}
+        alt={alt}
+        className="aspect-square h-full w-full object-cover"
+      />
+      <AvatarPrimitive.Fallback
+        className="flex h-full w-full items-center justify-center rounded-full bg-muted text-muted-foreground font-medium"
+      >
+        {fallback || <User className="h-1/2 w-1/2" />}
+      </AvatarPrimitive.Fallback>
+    </AvatarPrimitive.Root>
+    {status && (
+      <span
+        className={cn(
+          'absolute bottom-0 right-0 h-3 w-3 rounded-full border-2 border-background',
+          statusColors[status]
+        )}
+      />
+    )}
+  </div>
+)
+
+// Helper to get initials from name
+const getInitials = (name: string) => {
+  return name
+    .split(' ')
+    .map(n => n[0])
+    .join('')
+    .toUpperCase()
+    .slice(0, 2)
+}
+
+// Avatar group for stacking
+const AvatarGroup = ({ max = 4, children }) => {
+  const avatars = React.Children.toArray(children)
+  const shown = avatars.slice(0, max)
+  const remaining = avatars.length - max
+
+  return (
+    <div className="flex -space-x-2">
+      {shown.map((avatar, i) => (
+        <div key={i} className="ring-2 ring-background rounded-full">
+          {avatar}
+        </div>
+      ))}
+      {remaining > 0 && (
+        <div className="flex h-10 w-10 items-center justify-center rounded-full bg-muted text-muted-foreground text-sm font-medium ring-2 ring-background">
+          +{remaining}
+        </div>
+      )}
+    </div>
+  )
+}
+```

package/templates/component-recipes/badge.md

@@ -0,0 +1,126 @@
+# Badge Component Recipe
+
+## Structure
+- Inline `<span>` or `<div>` element
+- Support variants for different contexts
+- Optional icon or close button
+- Compact sizing
+
+## Tailwind Classes
+
+### Base
+```
+inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium
+transition-colors
+```
+
+### Variants
+```
+default:     bg-primary text-primary-foreground
+secondary:   bg-secondary text-secondary-foreground
+outline:     border border-border text-foreground bg-transparent
+destructive: bg-destructive text-destructive-foreground
+success:     bg-green-500/10 text-green-600 border border-green-500/20
+warning:     bg-yellow-500/10 text-yellow-600 border border-yellow-500/20
+```
+
+### Sizes
+```
+sm: px-2 py-0.5 text-xs
+md: px-2.5 py-0.5 text-xs (default)
+lg: px-3 py-1 text-sm
+```
+
+### With Icon
+```
+gap-1
+Icon: h-3 w-3
+```
+
+### With Close Button
+```
+pr-1
+Close button: ml-1 h-3 w-3 hover:bg-black/10 rounded-full
+```
+
+### Interactive (clickable)
+```
+cursor-pointer hover:opacity-80
+```
+
+## Props Interface
+```typescript
+interface BadgeProps {
+  variant?: 'default' | 'secondary' | 'outline' | 'destructive' | 'success' | 'warning'
+  size?: 'sm' | 'md' | 'lg'
+  icon?: React.ReactNode
+  onClose?: () => void
+  children: React.ReactNode
+}
+```
+
+## Do
+- Use `rounded-full` for pill shape (or `{tokens.radius}` for consistency)
+- Keep text short (1-2 words typically)
+- Use semantic variants (success, warning, destructive)
+- Support icon placement
+
+## Don't
+- Make badges too large
+- Use for long text content
+- Hardcode colors
+- Forget hover state for interactive badges
+
+## Example
+```tsx
+import { cn } from '@/lib/utils'
+import { X } from 'lucide-react'
+
+const badgeVariants = {
+  default: 'bg-primary text-primary-foreground',
+  secondary: 'bg-secondary text-secondary-foreground',
+  outline: 'border border-border text-foreground bg-transparent',
+  destructive: 'bg-destructive text-destructive-foreground',
+  success: 'bg-green-500/10 text-green-600 border border-green-500/20',
+  warning: 'bg-yellow-500/10 text-yellow-600 border border-yellow-500/20',
+}
+
+const badgeSizes = {
+  sm: 'px-2 py-0.5 text-xs',
+  md: 'px-2.5 py-0.5 text-xs',
+  lg: 'px-3 py-1 text-sm',
+}
+
+const Badge = ({
+  variant = 'default',
+  size = 'md',
+  icon,
+  onClose,
+  className,
+  children,
+  ...props
+}) => (
+  <span
+    className={cn(
+      'inline-flex items-center rounded-full font-medium transition-colors',
+      badgeVariants[variant],
+      badgeSizes[size],
+      icon && 'gap-1',
+      onClose && 'pr-1',
+      className
+    )}
+    {...props}
+  >
+    {icon && <span className="h-3 w-3">{icon}</span>}
+    {children}
+    {onClose && (
+      <button
+        onClick={onClose}
+        className="ml-1 rounded-full p-0.5 hover:bg-black/10"
+      >
+        <X className="h-3 w-3" />
+      </button>
+    )}
+  </span>
+)
+```