@neynar/ui 0.4.0 → 1.0.0

package/src/components/ui/stories/avatar.stories.tsx

@@ -1,316 +1,542 @@
-import type { Meta, StoryObj } from "@storybook/react-vite";
-import { User } from "lucide-react";
-import { Avatar, AvatarFallback, AvatarImage } from "../avatar";
+import type { Meta, StoryObj } from "@storybook/react";
+import {
+  CheckIcon,
+  MessageCircleIcon,
+  UserIcon,
+  UsersIcon,
+  ZapIcon,
+} from "lucide-react";
 
-const meta = {
-  title: "Data Display/Avatar",
+import {
+  Avatar,
+  AvatarBadge,
+  AvatarFallback,
+  AvatarGroup,
+  AvatarGroupCount,
+  AvatarImage,
+} from "../avatar";
+
+const meta: Meta<typeof Avatar> = {
+  title: "Components/Advanced & Specialized/Avatar",
   component: Avatar,
   parameters: {
     layout: "centered",
-    docs: {
-      description: {
-        component:
-          "A flexible avatar component for displaying user profile pictures with fallback support. Built on Radix UI primitives with automatic loading states and accessibility features.",
-      },
-    },
   },
   argTypes: {
-    className: {
-      control: { type: "text" },
-      description: "Additional CSS classes for styling and sizing",
-      table: {
-        type: { summary: "string" },
-        defaultValue: { summary: "" },
-      },
+    size: {
+      control: "select",
+      options: ["sm", "default", "lg"],
+      description: "Avatar size variant",
     },
   },
-} satisfies Meta<typeof Avatar>;
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof Avatar>;
 
 /**
- * Interactive playground for testing all Avatar props and variants.
- * Use the controls panel to experiment with different sizes, styles, and content.
+ * Farcaster User Profiles - A realistic scenario showing avatars in context
+ * of Farcaster user profiles, team members, and social interactions in the Neynar Dashboard.
  */
-export const Interactive: Story = {
-  args: {
-    className: "size-10",
-  },
-  argTypes: {
-    className: {
-      control: { type: "select" },
-      options: [
-        "size-6",
-        "size-8", 
-        "size-10",
-        "size-12",
-        "size-16",
-        "size-10 rounded-lg",
-        "size-10 rounded-md",
-        "size-10 rounded-none",
-      ],
-      description: "Size and shape variants",
-    },
-  },
-  render: (args) => (
-    <Avatar {...args}>
-      <AvatarImage src="https://github.com/shadcn.png" alt="shadcn" />
-      <AvatarFallback>CN</AvatarFallback>
-    </Avatar>
-  ),
+export const InContext: Story = {
   parameters: {
-    docs: {
-      description: {
-        story: "Experiment with different Avatar sizes and styles using the controls panel.",
-      },
-    },
+    layout: "padded",
+  },
+  render: () => {
+    return (
+      <div className="w-full max-w-xl space-y-6">
+        {/* User Profile Header */}
+        <section className="space-y-4">
+          <div>
+            <h3 className="text-lg font-semibold">User Profile</h3>
+            <p className="text-muted-foreground text-sm">
+              Farcaster user profile with avatar, username, and verification
+              badge.
+            </p>
+          </div>
+          <div className="border-border bg-card rounded-lg border p-6">
+            <div className="flex items-center gap-4">
+              <Avatar size="lg">
+                <AvatarImage
+                  src="https://i.imgur.com/xIe7Wlb.png"
+                  alt="@dwr.eth"
+                />
+                <AvatarFallback>DW</AvatarFallback>
+                <AvatarBadge>
+                  <CheckIcon />
+                </AvatarBadge>
+              </Avatar>
+              <div>
+                <div className="flex items-center gap-2">
+                  <p className="font-semibold">Dan Romero</p>
+                  <span className="bg-primary/10 text-primary rounded-full px-2 py-0.5 text-xs font-medium">
+                    Power User
+                  </span>
+                </div>
+                <p className="text-muted-foreground text-sm">@dwr.eth</p>
+                <p className="text-muted-foreground mt-1 text-sm">
+                  Co-founder of Farcaster. Building the future of decentralized
+                  social.
+                </p>
+              </div>
+            </div>
+          </div>
+        </section>
+
+        {/* Recent Activity */}
+        <section className="space-y-4">
+          <div>
+            <h3 className="text-lg font-semibold">Recent Activity</h3>
+            <p className="text-muted-foreground text-sm">
+              Activity feed showing user avatars with different states and
+              sizes.
+            </p>
+          </div>
+          <div className="space-y-3">
+            <div className="border-border bg-card rounded-lg border p-4">
+              <div className="flex items-start gap-3">
+                <Avatar>
+                  <AvatarImage src="https://i.imgur.com/4jKKHVW.png" alt="@v" />
+                  <AvatarFallback>V</AvatarFallback>
+                  <AvatarBadge className="bg-green-500">
+                    <ZapIcon />
+                  </AvatarBadge>
+                </Avatar>
+                <div className="flex-1">
+                  <p className="text-sm">
+                    <span className="font-medium">@v</span> cast a new post
+                  </p>
+                  <p className="text-muted-foreground text-xs">2 minutes ago</p>
+                </div>
+              </div>
+            </div>
+
+            <div className="border-border bg-card rounded-lg border p-4">
+              <div className="flex items-start gap-3">
+                <Avatar>
+                  <AvatarImage
+                    src="https://i.imgur.com/xIe7Wlb.png"
+                    alt="@dwr.eth"
+                  />
+                  <AvatarFallback>DW</AvatarFallback>
+                  <AvatarBadge>
+                    <MessageCircleIcon />
+                  </AvatarBadge>
+                </Avatar>
+                <div className="flex-1">
+                  <p className="text-sm">
+                    <span className="font-medium">@dwr.eth</span> replied to
+                    your cast
+                  </p>
+                  <p className="text-muted-foreground text-xs">
+                    15 minutes ago
+                  </p>
+                </div>
+              </div>
+            </div>
+          </div>
+        </section>
+
+        {/* Team Members */}
+        <section className="space-y-4">
+          <div>
+            <h3 className="text-lg font-semibold">Team Members</h3>
+            <p className="text-muted-foreground text-sm">
+              Collaborative team view with avatar groups and counts.
+            </p>
+          </div>
+          <div className="border-border bg-card rounded-lg border p-4">
+            <div className="flex items-center justify-between">
+              <div>
+                <p className="font-medium">Neynar Team</p>
+                <p className="text-muted-foreground text-sm">12 members</p>
+              </div>
+              <AvatarGroup>
+                <Avatar>
+                  <AvatarImage
+                    src="https://i.imgur.com/xIe7Wlb.png"
+                    alt="Dan"
+                  />
+                  <AvatarFallback>DW</AvatarFallback>
+                </Avatar>
+                <Avatar>
+                  <AvatarImage src="https://i.imgur.com/4jKKHVW.png" alt="V" />
+                  <AvatarFallback>V</AvatarFallback>
+                </Avatar>
+                <Avatar>
+                  <AvatarFallback>JK</AvatarFallback>
+                </Avatar>
+                <Avatar>
+                  <AvatarFallback>SM</AvatarFallback>
+                </Avatar>
+                <AvatarGroupCount>+8</AvatarGroupCount>
+              </AvatarGroup>
+            </div>
+          </div>
+        </section>
+
+        {/* User Directory */}
+        <section className="space-y-4">
+          <div>
+            <h3 className="text-lg font-semibold">User Directory</h3>
+            <p className="text-muted-foreground text-sm">
+              List of users with fallback states and initials.
+            </p>
+          </div>
+          <div className="space-y-2">
+            <div className="border-border bg-card flex items-center justify-between rounded-lg border p-3">
+              <div className="flex items-center gap-3">
+                <Avatar size="sm">
+                  <AvatarImage
+                    src="https://i.imgur.com/xIe7Wlb.png"
+                    alt="Dan Romero"
+                  />
+                  <AvatarFallback>DR</AvatarFallback>
+                </Avatar>
+                <div>
+                  <p className="text-sm font-medium">Dan Romero</p>
+                  <p className="text-muted-foreground text-xs">@dwr.eth</p>
+                </div>
+              </div>
+              <span className="bg-green-500/10 text-green-500 rounded-full px-2 py-1 text-xs font-medium">
+                Active
+              </span>
+            </div>
+
+            <div className="border-border bg-card flex items-center justify-between rounded-lg border p-3">
+              <div className="flex items-center gap-3">
+                <Avatar size="sm">
+                  <AvatarImage src="https://i.imgur.com/4jKKHVW.png" alt="V" />
+                  <AvatarFallback>V</AvatarFallback>
+                </Avatar>
+                <div>
+                  <p className="text-sm font-medium">V</p>
+                  <p className="text-muted-foreground text-xs">@v</p>
+                </div>
+              </div>
+              <span className="bg-green-500/10 text-green-500 rounded-full px-2 py-1 text-xs font-medium">
+                Active
+              </span>
+            </div>
+
+            <div className="border-border bg-card flex items-center justify-between rounded-lg border p-3">
+              <div className="flex items-center gap-3">
+                <Avatar size="sm">
+                  <AvatarFallback>AB</AvatarFallback>
+                </Avatar>
+                <div>
+                  <p className="text-sm font-medium">Alice Brown</p>
+                  <p className="text-muted-foreground text-xs">@alice</p>
+                </div>
+              </div>
+              <span className="text-muted-foreground rounded-full px-2 py-1 text-xs font-medium">
+                Offline
+              </span>
+            </div>
+          </div>
+        </section>
+      </div>
+    );
   },
 };
 
 /**
- * Comprehensive showcase of all Avatar variants and combinations.
- * Displays different sizes, fallback types, shapes, and grouping patterns.
+ * Complete design system reference showing all avatar sizes, states, and compositions.
  */
 export const Variants: Story = {
+  parameters: {
+    layout: "padded",
+  },
   render: () => (
-    <div className="space-y-8">
-      {/* Size Variants */}
-      <div className="space-y-4">
-        <h3 className="font-semibold">Size Variants</h3>
-        <div className="flex items-end gap-4">
-          <div className="text-center space-y-2">
-            <Avatar className="size-6">
-              <AvatarImage src="https://github.com/shadcn.png" alt="XS" />
-              <AvatarFallback className="text-xs">XS</AvatarFallback>
-            </Avatar>
-            <div className="text-xs text-muted-foreground">size-6</div>
-          </div>
-          <div className="text-center space-y-2">
-            <Avatar className="size-8">
-              <AvatarImage src="https://github.com/shadcn.png" alt="SM" />
-              <AvatarFallback className="text-xs">SM</AvatarFallback>
+    <div className="w-full max-w-4xl space-y-10">
+      {/* Sizes */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Sizes</h3>
+          <p className="text-muted-foreground text-sm">
+            Three size variants for different contexts and density needs.
+          </p>
+        </div>
+        <div className="flex items-end gap-6">
+          <div className="flex flex-col items-center gap-2">
+            <Avatar size="sm">
+              <AvatarImage src="https://i.imgur.com/xIe7Wlb.png" alt="Small" />
+              <AvatarFallback>SM</AvatarFallback>
             </Avatar>
-            <div className="text-xs text-muted-foreground">size-8</div>
+            <span className="text-muted-foreground text-xs">Small (24px)</span>
           </div>
-          <div className="text-center space-y-2">
-            <Avatar className="size-10">
-              <AvatarImage src="https://github.com/shadcn.png" alt="MD" />
+          <div className="flex flex-col items-center gap-2">
+            <Avatar size="default">
+              <AvatarImage
+                src="https://i.imgur.com/xIe7Wlb.png"
+                alt="Default"
+              />
               <AvatarFallback>MD</AvatarFallback>
             </Avatar>
-            <div className="text-xs text-muted-foreground">size-10</div>
+            <span className="text-muted-foreground text-xs">
+              Default (32px)
+            </span>
           </div>
-          <div className="text-center space-y-2">
-            <Avatar className="size-12">
-              <AvatarImage src="https://github.com/shadcn.png" alt="LG" />
+          <div className="flex flex-col items-center gap-2">
+            <Avatar size="lg">
+              <AvatarImage src="https://i.imgur.com/xIe7Wlb.png" alt="Large" />
               <AvatarFallback>LG</AvatarFallback>
             </Avatar>
-            <div className="text-xs text-muted-foreground">size-12</div>
-          </div>
-          <div className="text-center space-y-2">
-            <Avatar className="size-16">
-              <AvatarImage src="https://github.com/shadcn.png" alt="XL" />
-              <AvatarFallback className="text-lg">XL</AvatarFallback>
-            </Avatar>
-            <div className="text-xs text-muted-foreground">size-16</div>
+            <span className="text-muted-foreground text-xs">Large (40px)</span>
           </div>
         </div>
-      </div>
+      </section>
 
-      {/* Fallback Types */}
-      <div className="space-y-4">
-        <h3 className="font-semibold">Fallback Types</h3>
-        <div className="flex items-center gap-4">
-          <div className="text-center space-y-2">
+      {/* States */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">States</h3>
+          <p className="text-muted-foreground text-sm">
+            Image loaded, fallback initials, and icon fallback states.
+          </p>
+        </div>
+        <div className="flex items-center gap-6">
+          <div className="flex flex-col items-center gap-2">
             <Avatar>
-              <AvatarImage src="https://github.com/shadcn.png" alt="With Image" />
-              <AvatarFallback>WI</AvatarFallback>
+              <AvatarImage
+                src="https://i.imgur.com/xIe7Wlb.png"
+                alt="With image"
+              />
+              <AvatarFallback>DW</AvatarFallback>
             </Avatar>
-            <div className="text-xs text-muted-foreground">With Image</div>
+            <span className="text-muted-foreground text-xs">With Image</span>
           </div>
-          <div className="text-center space-y-2">
+          <div className="flex flex-col items-center gap-2">
             <Avatar>
-              <AvatarImage src="" alt="Initials" />
-              <AvatarFallback>JD</AvatarFallback>
+              <AvatarFallback>AB</AvatarFallback>
             </Avatar>
-            <div className="text-xs text-muted-foreground">Initials</div>
+            <span className="text-muted-foreground text-xs">Initials</span>
           </div>
-          <div className="text-center space-y-2">
+          <div className="flex flex-col items-center gap-2">
             <Avatar>
-              <AvatarImage src="" alt="Icon" />
               <AvatarFallback>
-                <User className="size-4" />
+                <UserIcon className="size-4" />
               </AvatarFallback>
             </Avatar>
-            <div className="text-xs text-muted-foreground">Icon</div>
-          </div>
-          <div className="text-center space-y-2">
-            <Avatar>
-              <AvatarImage src="" alt="Colored" />
-              <AvatarFallback className="bg-blue-500 text-white">CB</AvatarFallback>
-            </Avatar>
-            <div className="text-xs text-muted-foreground">Colored</div>
+            <span className="text-muted-foreground text-xs">Icon Fallback</span>
           </div>
         </div>
-      </div>
+      </section>
 
-      {/* Shape Variants */}
-      <div className="space-y-4">
-        <h3 className="font-semibold">Shape Variants</h3>
-        <div className="flex items-center gap-4">
-          <div className="text-center space-y-2">
+      {/* With Badges */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">With Badges</h3>
+          <p className="text-muted-foreground text-sm">
+            Status indicators and notification badges.
+          </p>
+        </div>
+        <div className="flex items-center gap-6">
+          <div className="flex flex-col items-center gap-2">
             <Avatar>
-              <AvatarImage src="https://github.com/shadcn.png" alt="Round" />
-              <AvatarFallback>RO</AvatarFallback>
+              <AvatarImage
+                src="https://i.imgur.com/xIe7Wlb.png"
+                alt="Verified"
+              />
+              <AvatarFallback>DW</AvatarFallback>
+              <AvatarBadge>
+                <CheckIcon />
+              </AvatarBadge>
             </Avatar>
-            <div className="text-xs text-muted-foreground">Default Round</div>
+            <span className="text-muted-foreground text-xs">Verified</span>
           </div>
-          <div className="text-center space-y-2">
-            <Avatar className="rounded-lg">
-              <AvatarImage src="https://github.com/vercel.png" alt="Rounded" />
-              <AvatarFallback>RL</AvatarFallback>
+          <div className="flex flex-col items-center gap-2">
+            <Avatar>
+              <AvatarImage src="https://i.imgur.com/4jKKHVW.png" alt="Active" />
+              <AvatarFallback>V</AvatarFallback>
+              <AvatarBadge className="bg-green-500" />
             </Avatar>
-            <div className="text-xs text-muted-foreground">Rounded Large</div>
+            <span className="text-muted-foreground text-xs">Active</span>
           </div>
-          <div className="text-center space-y-2">
-            <Avatar className="rounded-md">
-              <AvatarImage src="" alt="Medium" />
-              <AvatarFallback>RM</AvatarFallback>
+          <div className="flex flex-col items-center gap-2">
+            <Avatar>
+              <AvatarFallback>SM</AvatarFallback>
+              <AvatarBadge className="bg-yellow-500">
+                <ZapIcon />
+              </AvatarBadge>
             </Avatar>
-            <div className="text-xs text-muted-foreground">Rounded Medium</div>
+            <span className="text-muted-foreground text-xs">Power User</span>
           </div>
-          <div className="text-center space-y-2">
-            <Avatar className="rounded-none">
-              <AvatarImage src="" alt="Square" />
-              <AvatarFallback>SQ</AvatarFallback>
+          <div className="flex flex-col items-center gap-2">
+            <Avatar>
+              <AvatarFallback>JK</AvatarFallback>
+              <AvatarBadge className="bg-red-500" />
             </Avatar>
-            <div className="text-xs text-muted-foreground">Square</div>
+            <span className="text-muted-foreground text-xs">Busy</span>
           </div>
         </div>
-      </div>
+      </section>
 
-      {/* Avatar Group */}
-      <div className="space-y-4">
-        <h3 className="font-semibold">Avatar Group</h3>
-        <div className="flex -space-x-2">
-          <Avatar className="border-2 border-background">
-            <AvatarImage src="https://github.com/shadcn.png" alt="User 1" />
-            <AvatarFallback>U1</AvatarFallback>
-          </Avatar>
-          <Avatar className="border-2 border-background">
-            <AvatarImage src="https://github.com/vercel.png" alt="User 2" />
-            <AvatarFallback>U2</AvatarFallback>
-          </Avatar>
-          <Avatar className="border-2 border-background">
-            <AvatarImage src="" alt="User 3" />
-            <AvatarFallback>U3</AvatarFallback>
-          </Avatar>
-          <Avatar className="border-2 border-background">
-            <AvatarFallback>+5</AvatarFallback>
-          </Avatar>
+      {/* Avatar Groups */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Avatar Groups</h3>
+          <p className="text-muted-foreground text-sm">
+            Stacked avatars for team members and collaborators.
+          </p>
         </div>
-      </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story: "Complete showcase of all Avatar variants including sizes, fallback types, shapes, and grouping patterns.",
-      },
-    },
-  },
-};
+        <div className="space-y-4">
+          <div className="flex items-center gap-3">
+            <AvatarGroup>
+              <Avatar size="sm">
+                <AvatarImage src="https://i.imgur.com/xIe7Wlb.png" alt="Dan" />
+                <AvatarFallback>DW</AvatarFallback>
+              </Avatar>
+              <Avatar size="sm">
+                <AvatarImage src="https://i.imgur.com/4jKKHVW.png" alt="V" />
+                <AvatarFallback>V</AvatarFallback>
+              </Avatar>
+              <Avatar size="sm">
+                <AvatarFallback>JK</AvatarFallback>
+              </Avatar>
+            </AvatarGroup>
+            <span className="text-muted-foreground text-sm">Small group</span>
+          </div>
 
-/**
- * Real-world usage example showing Avatar in a user profile context.
- * Demonstrates how the component integrates with other UI elements in production scenarios.
- */
-export const InContext: Story = {
-  render: () => (
-    <div className="space-y-6 max-w-md">
-      {/* User Profile Header */}
-      <div className="flex items-center gap-4 p-4 border rounded-lg">
-        <Avatar className="size-16">
-          <AvatarImage src="https://github.com/shadcn.png" alt="John Doe" />
-          <AvatarFallback>JD</AvatarFallback>
-        </Avatar>
-        <div className="flex-1">
-          <h3 className="font-semibold text-lg">John Doe</h3>
-          <p className="text-sm text-muted-foreground">Product Designer</p>
-          <p className="text-sm text-muted-foreground">john.doe@company.com</p>
-        </div>
-        <div className="relative">
-          <Avatar className="size-3 absolute -bottom-1 -right-1">
-            <div className="size-3 bg-green-500 rounded-full border-2 border-background" />
-          </Avatar>
-        </div>
-      </div>
+          <div className="flex items-center gap-3">
+            <AvatarGroup>
+              <Avatar>
+                <AvatarImage src="https://i.imgur.com/xIe7Wlb.png" alt="Dan" />
+                <AvatarFallback>DW</AvatarFallback>
+              </Avatar>
+              <Avatar>
+                <AvatarImage src="https://i.imgur.com/4jKKHVW.png" alt="V" />
+                <AvatarFallback>V</AvatarFallback>
+              </Avatar>
+              <Avatar>
+                <AvatarFallback>JK</AvatarFallback>
+              </Avatar>
+              <Avatar>
+                <AvatarFallback>SM</AvatarFallback>
+              </Avatar>
+            </AvatarGroup>
+            <span className="text-muted-foreground text-sm">Default group</span>
+          </div>
 
-      {/* Comment Section */}
-      <div className="space-y-4">
-        <h4 className="font-medium">Recent Comments</h4>
-        <div className="space-y-3">
-          <div className="flex gap-3">
-            <Avatar className="size-8">
-              <AvatarImage src="https://github.com/shadcn.png" alt="Alice" />
-              <AvatarFallback>AL</AvatarFallback>
-            </Avatar>
-            <div className="flex-1">
-              <div className="flex items-center gap-2">
-                <span className="font-medium text-sm">Alice Cooper</span>
-                <span className="text-xs text-muted-foreground">2 hours ago</span>
-              </div>
-              <p className="text-sm text-muted-foreground">Great work on the new design! The user flow is much clearer now.</p>
-            </div>
+          <div className="flex items-center gap-3">
+            <AvatarGroup>
+              <Avatar size="lg">
+                <AvatarImage src="https://i.imgur.com/xIe7Wlb.png" alt="Dan" />
+                <AvatarFallback>DW</AvatarFallback>
+              </Avatar>
+              <Avatar size="lg">
+                <AvatarImage src="https://i.imgur.com/4jKKHVW.png" alt="V" />
+                <AvatarFallback>V</AvatarFallback>
+              </Avatar>
+              <Avatar size="lg">
+                <AvatarFallback>JK</AvatarFallback>
+              </Avatar>
+            </AvatarGroup>
+            <span className="text-muted-foreground text-sm">Large group</span>
           </div>
 
-          <div className="flex gap-3">
-            <Avatar className="size-8">
-              <AvatarImage src="" alt="Bob" />
-              <AvatarFallback>BC</AvatarFallback>
-            </Avatar>
-            <div className="flex-1">
-              <div className="flex items-center gap-2">
-                <span className="font-medium text-sm">Bob Chen</span>
-                <span className="text-xs text-muted-foreground">4 hours ago</span>
-              </div>
-              <p className="text-sm text-muted-foreground">Could we adjust the spacing on mobile? It feels a bit cramped.</p>
-            </div>
+          <div className="flex items-center gap-3">
+            <AvatarGroup>
+              <Avatar>
+                <AvatarImage src="https://i.imgur.com/xIe7Wlb.png" alt="Dan" />
+                <AvatarFallback>DW</AvatarFallback>
+              </Avatar>
+              <Avatar>
+                <AvatarImage src="https://i.imgur.com/4jKKHVW.png" alt="V" />
+                <AvatarFallback>V</AvatarFallback>
+              </Avatar>
+              <Avatar>
+                <AvatarFallback>JK</AvatarFallback>
+              </Avatar>
+              <Avatar>
+                <AvatarFallback>SM</AvatarFallback>
+              </Avatar>
+              <AvatarGroupCount>+12</AvatarGroupCount>
+            </AvatarGroup>
+            <span className="text-muted-foreground text-sm">With count</span>
+          </div>
+
+          <div className="flex items-center gap-3">
+            <AvatarGroup>
+              <Avatar>
+                <AvatarFallback>
+                  <UsersIcon className="size-4" />
+                </AvatarFallback>
+              </Avatar>
+              <AvatarGroupCount>24</AvatarGroupCount>
+            </AvatarGroup>
+            <span className="text-muted-foreground text-sm">
+              Icon with count
+            </span>
           </div>
         </div>
-      </div>
+      </section>
 
-      {/* Team Members */}
-      <div className="space-y-4">
-        <h4 className="font-medium">Team Members</h4>
-        <div className="flex items-center justify-between">
-          <div className="flex -space-x-2">
-            <Avatar className="size-8 border-2 border-background">
-              <AvatarImage src="https://github.com/shadcn.png" alt="Team member" />
-              <AvatarFallback>TM</AvatarFallback>
-            </Avatar>
-            <Avatar className="size-8 border-2 border-background">
-              <AvatarImage src="https://github.com/vercel.png" alt="Team member" />
-              <AvatarFallback>TM</AvatarFallback>
+      {/* Size × Badge Combinations */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Size × Badge Matrix</h3>
+          <p className="text-muted-foreground text-sm">
+            Badge scaling across different avatar sizes.
+          </p>
+        </div>
+        <div className="flex items-end gap-6">
+          <div className="flex flex-col items-center gap-2">
+            <Avatar size="sm">
+              <AvatarImage
+                src="https://i.imgur.com/xIe7Wlb.png"
+                alt="Small with badge"
+              />
+              <AvatarFallback>SM</AvatarFallback>
+              <AvatarBadge>
+                <CheckIcon />
+              </AvatarBadge>
             </Avatar>
-            <Avatar className="size-8 border-2 border-background">
-              <AvatarImage src="" alt="Team member" />
-              <AvatarFallback>TM</AvatarFallback>
+            <span className="text-muted-foreground text-xs">Small</span>
+          </div>
+          <div className="flex flex-col items-center gap-2">
+            <Avatar size="default">
+              <AvatarImage
+                src="https://i.imgur.com/xIe7Wlb.png"
+                alt="Default with badge"
+              />
+              <AvatarFallback>MD</AvatarFallback>
+              <AvatarBadge>
+                <CheckIcon />
+              </AvatarBadge>
             </Avatar>
-            <Avatar className="size-8 border-2 border-background">
-              <AvatarFallback className="text-xs">+12</AvatarFallback>
+            <span className="text-muted-foreground text-xs">Default</span>
+          </div>
+          <div className="flex flex-col items-center gap-2">
+            <Avatar size="lg">
+              <AvatarImage
+                src="https://i.imgur.com/xIe7Wlb.png"
+                alt="Large with badge"
+              />
+              <AvatarFallback>LG</AvatarFallback>
+              <AvatarBadge>
+                <CheckIcon />
+              </AvatarBadge>
             </Avatar>
+            <span className="text-muted-foreground text-xs">Large</span>
           </div>
-          <button className="text-sm text-blue-600 hover:text-blue-500">View all</button>
         </div>
-      </div>
+      </section>
     </div>
   ),
-  parameters: {
-    docs: {
-      description: {
-        story: "Real-world example showing Avatar in user profiles, comment sections, and team member displays with proper spacing and interactions.",
-      },
-    },
+};
+
+/**
+ * Interactive playground for testing avatar props.
+ */
+export const Interactive: Story = {
+  render: (args) => (
+    <Avatar {...args}>
+      <AvatarImage src="https://i.imgur.com/xIe7Wlb.png" alt="User avatar" />
+      <AvatarFallback>DW</AvatarFallback>
+    </Avatar>
+  ),
+  args: {
+    size: "default",
   },
-};
+};