Initial commit

docs/components/avatar.md

@@ -0,0 +1,77 @@
+# Avatar Component Documentation
+
+## Overview
+
+The Avatar component presents a circular image element designed for representing users, with built-in fallback functionality. It extends Radix UI's Avatar primitive and includes server-side rendering support plus enhanced features for grouping multiple avatars.
+
+## Component Parts
+
+### Avatar (Root)
+The main container for displaying user avatars.
+
+**Props:**
+- `className` (string): Additional CSS classes
+- `children` (ReactNode): AvatarImage and AvatarFallback components
+- Supports all Radix UI Avatar.Root props
+
+### AvatarImage
+Renders the user's profile image with automatic fallback handling.
+
+**Props:**
+- `src` (string): Image source URL
+- `alt` (string): Alternative text for accessibility
+- `className` (string): Custom CSS classes
+- Inherits all Radix UI Avatar.Image props
+
+### AvatarFallback
+Shows fallback content when the image fails to load.
+
+**Props:**
+- `className` (string): Custom styling
+- `children` (ReactNode): Fallback content, typically initials
+- Supports all Radix UI Avatar.Fallback props
+
+### AvatarGroup
+Groups multiple avatars in a stacked arrangement with configurable spacing.
+
+**Props:**
+- `children` (ReactNode): Avatar components to display
+- `className` (string): Custom CSS classes
+- `spacing` ("tight" | "normal" | "loose"): Controls avatar spacing
+- `max` (number): Maximum avatars shown before displaying "+N" indicator
+
+**Spacing Options:**
+- **tight**: Closest together (`-space-x-1.5`)
+- **normal**: Default spacing (`-space-x-1`)
+- **loose**: Most space between (`-space-x-0.45`)
+
+## Usage Examples
+
+### Basic Avatar
+```jsx
+<Avatar>
+  <AvatarImage src="/images/shadcn.png" alt="@shadcn" />
+  <AvatarFallback>CN</AvatarFallback>
+</Avatar>
+```
+
+### Custom Sizes
+```jsx
+<div className="flex items-center gap-4">
+  <Avatar className="size-8">
+    <AvatarImage src="/images/shadcn.png" alt="@shadcn" />
+    <AvatarFallback className="text-xs">CN</AvatarFallback>
+  </Avatar>
+  <Avatar className="size-12">
+    <AvatarImage src="/images/shadcn.png" alt="@shadcn" />
+    <AvatarFallback>CN</AvatarFallback>
+  </Avatar>
+  <Avatar className="size-16">
+    <AvatarImage src="/images/shadcn.png" alt="@shadcn" />
+    <AvatarFallback className="text-lg">CN</AvatarFallback>
+  </Avatar>
+</div>
+```
+
+### Avatar Groups with Spacing Variants
+Groups can implement tight, normal, or loose spacing configurations by adjusting the `spacing` prop on the `AvatarGroup` component.