@fr0mpy/component-system 2.0.0

package/templates/component-recipes/skeleton.md

@@ -0,0 +1,186 @@
+# Skeleton Component Recipe
+
+## Structure
+- Placeholder shapes that mimic content layout
+- Subtle animation (pulse or shimmer)
+- Various preset shapes (text, circle, rectangle)
+- Composable for complex layouts
+
+## Tailwind Classes
+
+### Base
+```
+animate-pulse rounded-md bg-muted
+```
+
+### Shapes
+```
+text:      h-4 w-full rounded
+heading:   h-6 w-3/4 rounded
+paragraph: h-4 w-full rounded (multiple with varying widths)
+circle:    rounded-full aspect-square
+rectangle: rounded-md
+avatar:    h-10 w-10 rounded-full
+button:    h-10 w-24 rounded-lg
+card:      h-48 w-full rounded-lg
+image:     aspect-video w-full rounded-lg
+```
+
+### Animation Variants
+```
+pulse:   animate-pulse (default, uses opacity)
+shimmer: animate-shimmer (gradient sweep)
+
+@keyframes shimmer {
+  0% { background-position: -200% 0; }
+  100% { background-position: 200% 0; }
+}
+
+shimmer class:
+  bg-gradient-to-r from-muted via-muted/50 to-muted
+  bg-[length:200%_100%] animate-shimmer
+```
+
+### Sizes
+```
+sm: Scale down by 75%
+md: Default size
+lg: Scale up by 125%
+```
+
+## Props Interface
+```typescript
+interface SkeletonProps {
+  className?: string
+  variant?: 'pulse' | 'shimmer'
+}
+
+interface SkeletonTextProps extends SkeletonProps {
+  lines?: number
+}
+
+interface SkeletonAvatarProps extends SkeletonProps {
+  size?: 'sm' | 'md' | 'lg'
+}
+
+interface SkeletonCardProps extends SkeletonProps {
+  hasImage?: boolean
+  hasTitle?: boolean
+  hasDescription?: boolean
+}
+```
+
+## Do
+- Match skeleton shapes to actual content layout
+- Use consistent animation across page
+- Provide presets for common patterns
+- Keep animations subtle (not distracting)
+
+## Don't
+- Hardcode colors
+- Use jarring animations
+- Show skeleton indefinitely (add timeout)
+- Mix different animation styles
+
+## Example
+```tsx
+import { cn } from '@/lib/utils'
+
+const Skeleton = ({ className, ...props }) => (
+  <div
+    className={cn('animate-pulse rounded-md bg-muted', className)}
+    {...props}
+  />
+)
+
+// Shimmer variant
+const SkeletonShimmer = ({ className, ...props }) => (
+  <div
+    className={cn(
+      'rounded-md bg-gradient-to-r from-muted via-muted/50 to-muted',
+      'bg-[length:200%_100%] animate-shimmer',
+      className
+    )}
+    {...props}
+  />
+)
+
+// Text skeleton (multiple lines)
+const SkeletonText = ({ lines = 3, className }) => (
+  <div className={cn('space-y-2', className)}>
+    {Array.from({ length: lines }).map((_, i) => (
+      <Skeleton
+        key={i}
+        className={cn(
+          'h-4',
+          i === lines - 1 ? 'w-4/5' : 'w-full' // Last line shorter
+        )}
+      />
+    ))}
+  </div>
+)
+
+// Avatar skeleton
+const SkeletonAvatar = ({ size = 'md', className }) => {
+  const sizes = {
+    sm: 'h-8 w-8',
+    md: 'h-10 w-10',
+    lg: 'h-12 w-12',
+  }
+  return <Skeleton className={cn('rounded-full', sizes[size], className)} />
+}
+
+// Card skeleton
+const SkeletonCard = ({ hasImage = true, className }) => (
+  <div className={cn('rounded-lg border border-border p-4 space-y-4', className)}>
+    {hasImage && <Skeleton className="aspect-video w-full rounded-lg" />}
+    <div className="space-y-2">
+      <Skeleton className="h-5 w-2/3" />
+      <Skeleton className="h-4 w-full" />
+      <Skeleton className="h-4 w-4/5" />
+    </div>
+  </div>
+)
+
+// Table row skeleton
+const SkeletonTableRow = ({ columns = 4 }) => (
+  <div className="flex items-center space-x-4 py-3">
+    {Array.from({ length: columns }).map((_, i) => (
+      <Skeleton
+        key={i}
+        className={cn(
+          'h-4',
+          i === 0 ? 'w-8' : 'flex-1'
+        )}
+      />
+    ))}
+  </div>
+)
+
+// Full page skeleton (dashboard example)
+const SkeletonDashboard = () => (
+  <div className="space-y-6 p-6">
+    {/* Header */}
+    <div className="flex items-center justify-between">
+      <Skeleton className="h-8 w-48" />
+      <Skeleton className="h-10 w-32" />
+    </div>
+
+    {/* Stats row */}
+    <div className="grid grid-cols-4 gap-4">
+      {Array.from({ length: 4 }).map((_, i) => (
+        <div key={i} className="rounded-lg border border-border p-4 space-y-2">
+          <Skeleton className="h-4 w-20" />
+          <Skeleton className="h-8 w-16" />
+        </div>
+      ))}
+    </div>
+
+    {/* Content area */}
+    <div className="grid grid-cols-2 gap-6">
+      <SkeletonCard />
+      <SkeletonCard />
+    </div>
+  </div>
+)
+```

package/templates/component-recipes/slider.md

@@ -0,0 +1,114 @@
+# Slider Component Recipe
+
+## Structure
+- Track with filled range indicator
+- Draggable thumb(s)
+- Support single value or range (two thumbs)
+- Optional step markers and value display
+
+## Tailwind Classes
+
+### Root Container
+```
+relative flex w-full touch-none select-none items-center
+```
+
+### Track
+```
+relative h-1.5 w-full grow overflow-hidden rounded-full bg-muted
+```
+
+### Range (filled portion)
+```
+absolute h-full bg-primary
+```
+
+### Thumb
+```
+block h-4 w-4 rounded-full border border-primary/50 bg-background shadow
+transition-colors
+focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary
+disabled:pointer-events-none disabled:opacity-50
+hover:border-primary
+```
+
+### Sizes
+```
+sm: Track h-1, Thumb h-3 w-3
+md: Track h-1.5, Thumb h-4 w-4 (default)
+lg: Track h-2, Thumb h-5 w-5
+```
+
+### With Value Display
+```
+Value label: absolute -top-7 left-1/2 -translate-x-1/2 text-xs font-medium
+```
+
+## Props Interface
+```typescript
+interface SliderProps {
+  value?: number[]
+  defaultValue?: number[]
+  onValueChange?: (value: number[]) => void
+  min?: number
+  max?: number
+  step?: number
+  disabled?: boolean
+  orientation?: 'horizontal' | 'vertical'
+  inverted?: boolean
+  minStepsBetweenThumbs?: number
+}
+```
+
+## Do
+- Use Radix Slider for accessibility
+- Support keyboard navigation (arrows, Home, End)
+- Show current value on drag (tooltip or label)
+- Support both single and range modes
+
+## Don't
+- Hardcode colors
+- Forget touch support
+- Skip min/max/step configuration
+- Use for non-numeric values
+
+## Example
+```tsx
+import * as SliderPrimitive from '@radix-ui/react-slider'
+import { cn } from '@/lib/utils'
+
+const Slider = ({ className, ...props }) => (
+  <SliderPrimitive.Root
+    className={cn(
+      'relative flex w-full touch-none select-none items-center',
+      className
+    )}
+    {...props}
+  >
+    <SliderPrimitive.Track className="relative h-1.5 w-full grow overflow-hidden rounded-full bg-muted">
+      <SliderPrimitive.Range className="absolute h-full bg-primary" />
+    </SliderPrimitive.Track>
+    <SliderPrimitive.Thumb
+      className={cn(
+        'block h-4 w-4 rounded-full border border-primary/50 bg-background shadow',
+        'transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary',
+        'disabled:pointer-events-none disabled:opacity-50 hover:border-primary'
+      )}
+    />
+  </SliderPrimitive.Root>
+)
+
+// With value display
+const SliderWithValue = ({ value, onValueChange, ...props }) => (
+  <div className="space-y-2">
+    <div className="flex justify-between text-sm">
+      <span className="text-muted-foreground">Value</span>
+      <span className="font-medium">{value?.[0] ?? 0}</span>
+    </div>
+    <Slider value={value} onValueChange={onValueChange} {...props} />
+  </div>
+)
+
+// Range slider (two thumbs)
+<Slider defaultValue={[25, 75]} max={100} step={1} />
+```

package/templates/component-recipes/spinner.md

@@ -0,0 +1,225 @@
+# Spinner Component Recipe
+
+## Structure
+- Animated loading indicator
+- SVG-based for crisp rendering
+- Support for multiple sizes
+- Optional label text
+- Accessible with aria-label
+
+## Tailwind Classes
+
+### Base
+```
+animate-spin text-primary
+```
+
+### SVG Structure
+```
+<svg className="animate-spin" viewBox="0 0 24 24" fill="none">
+  <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+  <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
+</svg>
+```
+
+### Sizes
+```
+xs: h-3 w-3
+sm: h-4 w-4
+md: h-6 w-6 (default)
+lg: h-8 w-8
+xl: h-12 w-12
+```
+
+### With Label
+```
+Container: inline-flex items-center gap-2
+Label: text-sm text-muted-foreground
+```
+
+### Overlay Spinner
+```
+Container: fixed inset-0 z-50 flex items-center justify-center bg-background/80 backdrop-blur-sm
+```
+
+### Button Spinner (inline)
+```
+mr-2 h-4 w-4 animate-spin
+```
+
+### Colors
+```
+default: text-primary
+muted: text-muted-foreground
+white: text-white
+current: text-current (inherits)
+```
+
+## Props Interface
+```typescript
+interface SpinnerProps {
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+  color?: 'default' | 'muted' | 'white' | 'current'
+  className?: string
+  label?: string
+  'aria-label'?: string
+}
+
+interface LoadingOverlayProps {
+  visible: boolean
+  label?: string
+  blur?: boolean
+}
+```
+
+## Do
+- Always include aria-label for screen readers
+- Use currentColor for flexible coloring
+- Match spinner size to context (button, page, etc.)
+- Consider reduced motion preferences
+
+## Don't
+- Hardcode colors
+- Use CSS-only spinners (less control)
+- Forget loading state announcements
+- Make spinners too large or distracting
+
+## Example
+```tsx
+import { cn } from '@/lib/utils'
+
+const spinnerSizes = {
+  xs: 'h-3 w-3',
+  sm: 'h-4 w-4',
+  md: 'h-6 w-6',
+  lg: 'h-8 w-8',
+  xl: 'h-12 w-12',
+}
+
+const spinnerColors = {
+  default: 'text-primary',
+  muted: 'text-muted-foreground',
+  white: 'text-white',
+  current: 'text-current',
+}
+
+const Spinner = ({
+  size = 'md',
+  color = 'default',
+  className,
+  label,
+  'aria-label': ariaLabel = 'Loading',
+}: SpinnerProps) => {
+  const spinner = (
+    <svg
+      className={cn(
+        'animate-spin',
+        spinnerSizes[size],
+        spinnerColors[color],
+        className
+      )}
+      viewBox="0 0 24 24"
+      fill="none"
+      aria-label={ariaLabel}
+      role="status"
+    >
+      <circle
+        className="opacity-25"
+        cx="12"
+        cy="12"
+        r="10"
+        stroke="currentColor"
+        strokeWidth="4"
+      />
+      <path
+        className="opacity-75"
+        fill="currentColor"
+        d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+      />
+    </svg>
+  )
+
+  if (label) {
+    return (
+      <div className="inline-flex items-center gap-2">
+        {spinner}
+        <span className="text-sm text-muted-foreground">{label}</span>
+      </div>
+    )
+  }
+
+  return spinner
+}
+
+// Dots variant spinner
+const DotsSpinner = ({ size = 'md', className }: SpinnerProps) => (
+  <div className={cn('flex items-center gap-1', className)}>
+    {[0, 1, 2].map((i) => (
+      <div
+        key={i}
+        className={cn(
+          'rounded-full bg-primary animate-bounce',
+          size === 'sm' ? 'h-1.5 w-1.5' : 'h-2 w-2'
+        )}
+        style={{ animationDelay: `${i * 0.1}s` }}
+      />
+    ))}
+  </div>
+)
+
+// Loading overlay
+const LoadingOverlay = ({
+  visible,
+  label = 'Loading...',
+  blur = true,
+}: LoadingOverlayProps) => {
+  if (!visible) return null
+
+  return (
+    <div
+      className={cn(
+        'fixed inset-0 z-50 flex flex-col items-center justify-center',
+        'bg-background/80',
+        blur && 'backdrop-blur-sm'
+      )}
+    >
+      <Spinner size="xl" />
+      {label && (
+        <p className="mt-4 text-sm text-muted-foreground">{label}</p>
+      )}
+    </div>
+  )
+}
+
+// Button with loading state
+const LoadingButton = ({ loading, children, ...props }) => (
+  <Button disabled={loading} {...props}>
+    {loading && <Spinner size="sm" color="current" className="mr-2" />}
+    {children}
+  </Button>
+)
+
+// Usage examples
+<Spinner />
+<Spinner size="lg" color="muted" />
+<Spinner size="sm" label="Loading data..." />
+<DotsSpinner />
+<LoadingOverlay visible={isLoading} label="Saving changes..." />
+
+<LoadingButton loading={isSubmitting}>
+  {isSubmitting ? 'Saving...' : 'Save'}
+</LoadingButton>
+```
+
+## Reduced Motion Support
+```css
+@media (prefers-reduced-motion: reduce) {
+  .animate-spin {
+    animation: none;
+    opacity: 0.5;
+  }
+  .animate-bounce {
+    animation: none;
+  }
+}
+```

package/templates/component-recipes/switch.md

@@ -0,0 +1,100 @@
+# Switch Component Recipe
+
+## Structure
+- Toggle control with sliding thumb
+- On/Off states with visual indication
+- Optional label alongside
+- Accessible with keyboard
+
+## Tailwind Classes
+
+### Root/Track
+```
+peer inline-flex h-5 w-9 shrink-0 cursor-pointer items-center {tokens.radius}
+border-2 border-transparent shadow-sm transition-colors
+focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2
+disabled:cursor-not-allowed disabled:opacity-50
+data-[state=checked]:bg-primary data-[state=unchecked]:bg-muted
+```
+
+### Thumb
+```
+pointer-events-none block h-4 w-4 rounded-full bg-background shadow-lg ring-0
+transition-transform
+data-[state=checked]:translate-x-4 data-[state=unchecked]:translate-x-0
+```
+
+### Sizes
+```
+sm: Track h-4 w-7, Thumb h-3 w-3, translate-x-3
+md: Track h-5 w-9, Thumb h-4 w-4, translate-x-4 (default)
+lg: Track h-6 w-11, Thumb h-5 w-5, translate-x-5
+```
+
+### With Label
+```
+flex items-center space-x-2
+Label: text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70
+```
+
+## Props Interface
+```typescript
+interface SwitchProps {
+  checked?: boolean
+  onCheckedChange?: (checked: boolean) => void
+  disabled?: boolean
+  required?: boolean
+  name?: string
+  value?: string
+  id?: string
+}
+```
+
+## Do
+- Use Radix Switch for accessibility
+- Include focus ring
+- Animate thumb movement smoothly
+- Use semantic colors (primary for checked)
+
+## Don't
+- Hardcode colors
+- Skip keyboard support (Space to toggle)
+- Forget disabled state
+- Use for multiple selections (use checkboxes)
+
+## Example
+```tsx
+import * as SwitchPrimitive from '@radix-ui/react-switch'
+import { cn } from '@/lib/utils'
+
+const Switch = ({ className, ...props }) => (
+  <SwitchPrimitive.Root
+    className={cn(
+      'peer inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full',
+      'border-2 border-transparent shadow-sm transition-colors',
+      'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2',
+      'disabled:cursor-not-allowed disabled:opacity-50',
+      'data-[state=checked]:bg-primary data-[state=unchecked]:bg-muted',
+      className
+    )}
+    {...props}
+  >
+    <SwitchPrimitive.Thumb
+      className={cn(
+        'pointer-events-none block h-4 w-4 rounded-full bg-background shadow-lg ring-0',
+        'transition-transform data-[state=checked]:translate-x-4 data-[state=unchecked]:translate-x-0'
+      )}
+    />
+  </SwitchPrimitive.Root>
+)
+
+// With label
+const SwitchWithLabel = ({ label, id, ...props }) => (
+  <div className="flex items-center space-x-2">
+    <Switch id={id} {...props} />
+    <label htmlFor={id} className="text-sm font-medium leading-none">
+      {label}
+    </label>
+  </div>
+)
+```