From 56411be3e6db7771d1da07a6d2365a62273d085b Mon Sep 17 00:00:00 2001
From: Rob Di Marco <robdimarco@circuitandchisel.com>
Date: Mon, 26 Jan 2026 16:31:00 -0500
Subject: [PATCH 1/2] feat: Add fallbackClassName prop to AvatarGroupItem
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add separate fallbackClassName prop for better control over avatar colors.

Problem: AvatarGroupItem was passing the same className to both Avatar
container and AvatarFallback, causing class conflicts. Background colors
intended for the fallback were also being applied to the container, and
vice versa (border classes on fallback).

Solution: Add fallbackClassName prop specifically for AvatarFallback styling.
- className → Avatar container (border, sizing)
- fallbackClassName → AvatarFallback (background, text color)
- Default bg-muted text-foreground remains for when no fallbackClassName provided

Benefits:
- Clear separation of concerns (container vs fallback styling)
- No class conflicts between container and fallback
- Explicit API makes usage intent clear
- Fallback won't be blank when no custom color provided

Breaking change: No - existing usage with className still works, just passes
to container only. Components relying on className for fallback colors should
migrate to fallbackClassName.
---
 src/components/AvatarGroup/AvatarGroup.tsx | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/components/AvatarGroup/AvatarGroup.tsx b/src/components/AvatarGroup/AvatarGroup.tsx
index 68f5abf..791eceb 100644
--- a/src/components/AvatarGroup/AvatarGroup.tsx
+++ b/src/components/AvatarGroup/AvatarGroup.tsx
@@ -75,15 +75,20 @@ export interface AvatarGroupItemProps
    * Whether to show a presence indicator (green dot)
    */
   showPresence?: boolean;
+  /**
+   * Classes for the fallback background/text (e.g., bg-indigo-500 text-white)
+   * Defaults to bg-muted text-foreground if not provided
+   */
+  fallbackClassName?: string;
 }
 
 const AvatarGroupItem = React.forwardRef<HTMLDivElement, AvatarGroupItemProps>(
-  ({ className, src, alt, fallback, showPresence, ...props }, ref) => {
+  ({ className, fallbackClassName, src, alt, fallback, showPresence, ...props }, ref) => {
     return (
       <div ref={ref} className="relative h-[inherit] w-[inherit]" {...props}>
         <Avatar className={cn('h-full w-full border border-input', className)}>
           {src && <AvatarImage src={src} alt={alt} />}
-          <AvatarFallback className={cn('font-semibold', className)}>
+          <AvatarFallback className={cn('font-semibold', fallbackClassName)}>
             {fallback}
           </AvatarFallback>
         </Avatar>

From 55699f3156232c978f17bff456094257ab33bc31 Mon Sep 17 00:00:00 2001
From: Rob Di Marco <robdimarco@circuitandchisel.com>
Date: Mon, 26 Jan 2026 16:32:13 -0500
Subject: [PATCH 2/2] docs: Add Storybook examples for fallbackClassName

Add two new stories demonstrating fallbackClassName prop usage:
- CustomColors: Shows vivid colors with white text contrast
- CustomBordersAndColors: Shows separating container (borders) from fallback (colors)

Also update all existing stories to use fallbackClassName instead of className
for background colors, following the new API pattern.
---
 .../AvatarGroup/AvatarGroup.stories.tsx       | 102 +++++++++++++-----
 1 file changed, 76 insertions(+), 26 deletions(-)

diff --git a/src/components/AvatarGroup/AvatarGroup.stories.tsx b/src/components/AvatarGroup/AvatarGroup.stories.tsx
index 04da1d0..01befd7 100644
--- a/src/components/AvatarGroup/AvatarGroup.stories.tsx
+++ b/src/components/AvatarGroup/AvatarGroup.stories.tsx
@@ -20,7 +20,7 @@ type Story = StoryObj<typeof meta>;
 export const Single: Story = {
   render: () => (
     <AvatarGroup>
-      <AvatarGroupItem fallback="L" className="bg-orange-100" />
+      <AvatarGroupItem fallback="L" fallbackClassName="bg-orange-100" />
     </AvatarGroup>
   ),
 };
@@ -28,8 +28,8 @@ export const Single: Story = {
 export const Two: Story = {
   render: () => (
     <AvatarGroup>
-      <AvatarGroupItem fallback="L" className="bg-orange-100" />
-      <AvatarGroupItem fallback="B" className="bg-green-100" />
+      <AvatarGroupItem fallback="L" fallbackClassName="bg-orange-100" />
+      <AvatarGroupItem fallback="B" fallbackClassName="bg-green-100" />
     </AvatarGroup>
   ),
 };
@@ -37,9 +37,9 @@ export const Two: Story = {
 export const Three: Story = {
   render: () => (
     <AvatarGroup>
-      <AvatarGroupItem fallback="L" className="bg-orange-100" />
-      <AvatarGroupItem fallback="B" className="bg-green-100" />
-      <AvatarGroupItem fallback="R" className="bg-pink-100" />
+      <AvatarGroupItem fallback="L" fallbackClassName="bg-orange-100" />
+      <AvatarGroupItem fallback="B" fallbackClassName="bg-green-100" />
+      <AvatarGroupItem fallback="R" fallbackClassName="bg-pink-100" />
     </AvatarGroup>
   ),
 };
@@ -47,7 +47,7 @@ export const Three: Story = {
 export const WithPresenceIndicator: Story = {
   render: () => (
     <AvatarGroup>
-      <AvatarGroupItem fallback="L" className="bg-orange-100" showPresence />
+      <AvatarGroupItem fallback="L" fallbackClassName="bg-orange-100" showPresence />
     </AvatarGroup>
   ),
 };
@@ -55,8 +55,8 @@ export const WithPresenceIndicator: Story = {
 export const TwoWithPresence: Story = {
   render: () => (
     <AvatarGroup>
-      <AvatarGroupItem fallback="L" className="bg-orange-100" />
-      <AvatarGroupItem fallback="B" className="bg-green-100" showPresence />
+      <AvatarGroupItem fallback="L" fallbackClassName="bg-orange-100" />
+      <AvatarGroupItem fallback="B" fallbackClassName="bg-green-100" showPresence />
     </AvatarGroup>
   ),
 };
@@ -64,9 +64,9 @@ export const TwoWithPresence: Story = {
 export const SmallSize: Story = {
   render: () => (
     <AvatarGroup size="sm">
-      <AvatarGroupItem fallback="L" className="bg-orange-100" />
-      <AvatarGroupItem fallback="B" className="bg-green-100" />
-      <AvatarGroupItem fallback="R" className="bg-pink-100" />
+      <AvatarGroupItem fallback="L" fallbackClassName="bg-orange-100" />
+      <AvatarGroupItem fallback="B" fallbackClassName="bg-green-100" />
+      <AvatarGroupItem fallback="R" fallbackClassName="bg-pink-100" />
     </AvatarGroup>
   ),
 };
@@ -74,9 +74,9 @@ export const SmallSize: Story = {
 export const LargeSize: Story = {
   render: () => (
     <AvatarGroup size="lg">
-      <AvatarGroupItem fallback="L" className="bg-orange-100" />
-      <AvatarGroupItem fallback="B" className="bg-green-100" />
-      <AvatarGroupItem fallback="R" className="bg-pink-100" />
+      <AvatarGroupItem fallback="L" fallbackClassName="bg-orange-100" />
+      <AvatarGroupItem fallback="B" fallbackClassName="bg-green-100" />
+      <AvatarGroupItem fallback="R" fallbackClassName="bg-pink-100" />
     </AvatarGroup>
   ),
 };
@@ -84,10 +84,10 @@ export const LargeSize: Story = {
 export const TightSpacing: Story = {
   render: () => (
     <AvatarGroup spacing="tight">
-      <AvatarGroupItem fallback="L" className="bg-orange-100" />
-      <AvatarGroupItem fallback="B" className="bg-green-100" />
-      <AvatarGroupItem fallback="R" className="bg-pink-100" />
-      <AvatarGroupItem fallback="D" className="bg-sky-100" />
+      <AvatarGroupItem fallback="L" fallbackClassName="bg-orange-100" />
+      <AvatarGroupItem fallback="B" fallbackClassName="bg-green-100" />
+      <AvatarGroupItem fallback="R" fallbackClassName="bg-pink-100" />
+      <AvatarGroupItem fallback="D" fallbackClassName="bg-sky-100" />
     </AvatarGroup>
   ),
 };
@@ -95,10 +95,10 @@ export const TightSpacing: Story = {
 export const LooseSpacing: Story = {
   render: () => (
     <AvatarGroup spacing="loose">
-      <AvatarGroupItem fallback="L" className="bg-orange-100" />
-      <AvatarGroupItem fallback="B" className="bg-green-100" />
-      <AvatarGroupItem fallback="R" className="bg-pink-100" />
-      <AvatarGroupItem fallback="D" className="bg-sky-100" />
+      <AvatarGroupItem fallback="L" fallbackClassName="bg-orange-100" />
+      <AvatarGroupItem fallback="B" fallbackClassName="bg-green-100" />
+      <AvatarGroupItem fallback="R" fallbackClassName="bg-pink-100" />
+      <AvatarGroupItem fallback="D" fallbackClassName="bg-sky-100" />
     </AvatarGroup>
   ),
 };
@@ -110,19 +110,69 @@ export const WithImages: Story = {
         src="https://i.pravatar.cc/150?img=1"
         alt="User 1"
         fallback="L"
-        className="bg-orange-100"
+        fallbackClassName="bg-orange-100"
       />
       <AvatarGroupItem
         src="https://i.pravatar.cc/150?img=2"
         alt="User 2"
         fallback="B"
-        className="bg-green-100"
+        fallbackClassName="bg-green-100"
       />
       <AvatarGroupItem
         src="https://i.pravatar.cc/150?img=3"
         alt="User 3"
         fallback="R"
-        className="bg-pink-100"
+        fallbackClassName="bg-pink-100"
+      />
+    </AvatarGroup>
+  ),
+};
+
+/**
+ * Demonstrates using fallbackClassName for custom colors with text contrast.
+ * Use fallbackClassName for background/text colors on the fallback initials.
+ */
+export const CustomColors: Story = {
+  render: () => (
+    <AvatarGroup>
+      <AvatarGroupItem
+        fallback="RD"
+        fallbackClassName="bg-indigo-500 text-white"
+      />
+      <AvatarGroupItem
+        fallback="JS"
+        fallbackClassName="bg-purple-500 text-white"
+      />
+      <AvatarGroupItem
+        fallback="EM"
+        fallbackClassName="bg-teal-500 text-white"
+        showPresence
+      />
+    </AvatarGroup>
+  ),
+};
+
+/**
+ * Demonstrates separating container styling (borders) from fallback styling (colors).
+ * className applies to Avatar container, fallbackClassName to the fallback initials.
+ */
+export const CustomBordersAndColors: Story = {
+  render: () => (
+    <AvatarGroup>
+      <AvatarGroupItem
+        fallback="A"
+        className="border-2 border-orange-500"
+        fallbackClassName="bg-orange-500 text-white"
+      />
+      <AvatarGroupItem
+        fallback="B"
+        className="border-2 border-green-500"
+        fallbackClassName="bg-green-500 text-white"
+      />
+      <AvatarGroupItem
+        fallback="C"
+        className="border-2 border-pink-500"
+        fallbackClassName="bg-pink-500 text-white"
       />
     </AvatarGroup>
   ),