aural-ui 4.0.1 → 4.1.0

package/dist/components/avatar/Avatar.stories.tsx

@@ -1,6 +1,8 @@
 import React from "react"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import { Avatar, AvatarFallback, AvatarImage } from "."
 
 const meta: Meta<typeof Avatar> = {
@@ -8,61 +10,29 @@ const meta: Meta<typeof Avatar> = {
   component: Avatar,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-# Avatar Component
-
-A versatile avatar component built on Radix UI primitives for displaying user profile images with automatic fallback handling.
-
-## Features
-
-- **Automatic Fallback**: Graceful fallback to initials or placeholder when image fails to load
-- **Responsive Design**: Flexible sizing with consistent aspect ratio
-- **Accessibility**: Built-in accessibility features from Radix UI
-- **Custom Styling**: Easy customization via className prop
-- **Image Optimization**: Proper image handling with loading states
-- **Circular Design**: Rounded avatar design optimized for profile pictures
-
-## Component Structure
-
-- **Avatar**: Root container that manages the avatar display
-- **AvatarImage**: The actual image element with proper sizing and aspect ratio
-- **AvatarFallback**: Fallback content displayed when image fails to load or is loading
-
-## Usage Examples
-
-### Basic Avatar
-\`\`\`tsx
-<Avatar>
-  <AvatarImage src="/user-avatar.jpg" alt="User Name" />
-  <AvatarFallback>UN</AvatarFallback>
-</Avatar>
-\`\`\`
-
-### Custom Sizing
-\`\`\`tsx
-<Avatar className="size-16">
-  <AvatarImage src="/user-avatar.jpg" alt="User Name" />
-  <AvatarFallback>UN</AvatarFallback>
-</Avatar>
-\`\`\`
-
-### Fallback Only
-\`\`\`tsx
-<Avatar>
-  <AvatarFallback>AB</AvatarFallback>
-</Avatar>
-\`\`\`
-        `,
+        component:
+          "A versatile avatar component built on Radix UI primitives for displaying user profile images with automatic fallback handling.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Image & Fallback",
+              description: "Auto-handles load errors",
+            },
+            {
+              title: "Flexible Sizing",
+              description: "Any size via className",
+            },
+            {
+              title: "Composable Parts",
+              description: "Image, Fallback sub-parts",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -71,19 +41,15 @@ A versatile avatar component built on Radix UI primitives for displaying user pr
 export default meta
 type Story = StoryObj<typeof Avatar>
 
-// 1. Basic Avatar Examples
-export const BasicAvatars: Story = {
+// ─── 1. All Variants ─────────────────────────────────────────────────────────
+
+export const AllVariants: Story = {
   render: () => (
     <div className="space-y-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">Basic Avatars</h3>
-        <p className="text-fm-secondary text-sm">
-          Standard avatar components with images and fallbacks
-        </p>
-      </div>
-
+      <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+        Image &amp; Fallback
+      </h4>
       <div className="flex flex-wrap items-center justify-center gap-4">
-        {/* Avatar with Image */}
         <div className="space-y-2 text-center">
           <Avatar>
             <AvatarImage
@@ -92,32 +58,37 @@ export const BasicAvatars: Story = {
             />
             <AvatarFallback>JD</AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">With Image</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            With Image
+          </p>
         </div>
 
-        {/* Avatar with Fallback Only */}
         <div className="space-y-2 text-center">
-          <Avatar className="text-fm-primary [font-size:var(--text-fm-sm)]">
+          <Avatar>
             <AvatarFallback>AB</AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Fallback Only</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Fallback Only
+          </p>
         </div>
 
-        {/* Avatar with Broken Image (shows fallback) */}
         <div className="space-y-2 text-center">
-          <Avatar className="text-fm-primary [font-size:var(--text-fm-sm)]">
+          <Avatar>
             <AvatarImage src="/broken-image.jpg" alt="Broken" />
             <AvatarFallback>BR</AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Broken Image</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Broken Image
+          </p>
         </div>
 
-        {/* Different Initials */}
         <div className="space-y-2 text-center">
-          <Avatar className="text-fm-primary [font-size:var(--text-fm-sm)]">
+          <Avatar>
             <AvatarFallback>SM</AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Initials</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Initials
+          </p>
         </div>
       </div>
     </div>
@@ -132,43 +103,38 @@ export const BasicAvatars: Story = {
   },
 }
 
-// 2. Size Variations
-export const SizeVariations: Story = {
+// ─── 2. Sizes ─────────────────────────────────────────────────────────────────
+
+export const Sizes: Story = {
   render: () => (
     <div className="space-y-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">Size Variations</h3>
-        <p className="text-fm-secondary text-sm">
-          Different avatar sizes for various use cases
-        </p>
-      </div>
-
       <div className="flex flex-wrap items-end justify-center gap-6">
-        {/* Extra Small */}
         <div className="space-y-2 text-center">
-          <Avatar className="text-fm-primary size-6 [font-size:var(--text-fm-sm)]">
+          <Avatar className="size-6">
             <AvatarImage
               src="https://images.unsplash.com/photo-1494790108755-2616b612b47c?w=100&h=100&fit=crop&crop=face"
               alt="User"
             />
-            <AvatarFallback className="text-xs">XS</AvatarFallback>
+            <AvatarFallback>XS</AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Extra Small (24px)</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Extra Small (24px)
+          </p>
         </div>
 
-        {/* Small */}
         <div className="space-y-2 text-center">
           <Avatar className="size-7">
             <AvatarImage
               src="https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=100&h=100&fit=crop&crop=face"
               alt="User"
             />
-            <AvatarFallback className="text-xs">S</AvatarFallback>
+            <AvatarFallback>S</AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Small (28px)</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Small (28px)
+          </p>
         </div>
 
-        {/* Default */}
         <div className="space-y-2 text-center">
           <Avatar>
             <AvatarImage
@@ -177,10 +143,11 @@ export const SizeVariations: Story = {
             />
             <AvatarFallback>M</AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Default (32px)</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Default (32px)
+          </p>
         </div>
 
-        {/* Large */}
         <div className="space-y-2 text-center">
           <Avatar className="size-12">
             <AvatarImage
@@ -189,31 +156,35 @@ export const SizeVariations: Story = {
             />
             <AvatarFallback>L</AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Large (48px)</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Large (48px)
+          </p>
         </div>
 
-        {/* Extra Large */}
         <div className="space-y-2 text-center">
           <Avatar className="size-16">
             <AvatarImage
               src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=100&h=100&fit=crop&crop=face"
               alt="User"
             />
-            <AvatarFallback className="text-lg">XL</AvatarFallback>
+            <AvatarFallback>XL</AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Extra Large (64px)</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Extra Large (64px)
+          </p>
         </div>
 
-        {/* XXL */}
         <div className="space-y-2 text-center">
-          <Avatar className="text-fm-primary size-20 [font-size:var(--text-fm-sm)]">
+          <Avatar className="size-20">
             <AvatarImage
               src="https://images.unsplash.com/photo-1494790108755-2616b612b47c?w=100&h=100&fit=crop&crop=face"
               alt="User"
             />
-            <AvatarFallback className="text-xl">XXL</AvatarFallback>
+            <AvatarFallback>XXL</AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">XXL (80px)</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            XXL (80px)
+          </p>
         </div>
       </div>
     </div>
@@ -222,98 +193,102 @@ export const SizeVariations: Story = {
     docs: {
       description: {
         story:
-          "Various avatar sizes from extra small (24px) to extra large (80px) for different UI contexts.",
+          "Various avatar sizes from extra small (24px) to XXL (80px) for different UI contexts.",
       },
     },
   },
 }
 
-// 3. Fallback Variations
-export const FallbackVariations: Story = {
+// ─── 3. Configurations ───────────────────────────────────────────────────────
+
+export const Configurations: Story = {
   render: () => (
     <div className="space-y-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">
-          Fallback Variations
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Different fallback content styles and approaches
-        </p>
-      </div>
-
+      <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+        Fallback Styles
+      </h4>
       <div className="mx-auto grid max-w-lg grid-cols-2 gap-6 md:grid-cols-4">
-        {/* Standard Initials */}
         <div className="space-y-2 text-center">
-          <Avatar className="text-fm-primary size-12">
+          <Avatar className="size-12">
             <AvatarFallback>JD</AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Standard Initials</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Standard Initials
+          </p>
         </div>
 
-        {/* Single Initial */}
         <div className="space-y-2 text-center">
-          <Avatar className="text-fm-primary size-12">
+          <Avatar className="size-12">
             <AvatarFallback>A</AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Single Initial</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Single Initial
+          </p>
         </div>
 
-        {/* Numbers */}
         <div className="space-y-2 text-center">
-          <Avatar className="text-fm-primary size-12">
+          <Avatar className="size-12">
             <AvatarFallback>42</AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Numbers</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Numbers
+          </p>
         </div>
 
-        {/* Custom Background */}
         <div className="space-y-2 text-center">
           <Avatar className="size-12">
-            <AvatarFallback className="bg-blue-500 text-white">
+            <AvatarFallback className="bg-fm-surface-info-sec text-fm-primary">
               BG
             </AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Custom Background</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Info
+          </p>
         </div>
 
-        {/* Gradient Background */}
+        {/* text-white ensures contrast on vivid bg in both light and dark mode */}
         <div className="space-y-2 text-center">
           <Avatar className="size-12">
-            <AvatarFallback className="bg-gradient-to-br from-purple-500 to-pink-500 text-white">
-              GR
+            <AvatarFallback className="bg-fm-secondary-500 text-white">
+              AC
             </AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Gradient</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Accent
+          </p>
         </div>
 
-        {/* Different Color */}
         <div className="space-y-2 text-center">
           <Avatar className="size-12">
-            <AvatarFallback className="bg-green-500 text-white">
+            <AvatarFallback className="bg-fm-surface-positive-sec text-fm-primary">
               GN
             </AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Green Theme</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Positive
+          </p>
         </div>
 
-        {/* Orange Theme */}
         <div className="space-y-2 text-center">
           <Avatar className="size-12">
-            <AvatarFallback className="bg-orange-500 text-white">
-              OR
+            <AvatarFallback className="bg-fm-surface-warning-sec text-fm-primary">
+              WA
             </AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Orange Theme</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Warning
+          </p>
         </div>
 
-        {/* Dark Theme */}
         <div className="space-y-2 text-center">
           <Avatar className="size-12">
-            <AvatarFallback className="bg-gray-800 text-gray-200">
+            <AvatarFallback className="bg-fm-surface-secondary text-fm-primary">
               DK
             </AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Dark Theme</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Surface
+          </p>
         </div>
       </div>
     </div>
@@ -322,28 +297,22 @@ export const FallbackVariations: Story = {
     docs: {
       description: {
         story:
-          "Various fallback content styles including initials, numbers, and custom backgrounds with different color themes.",
+          "Various fallback content configurations including initials, numbers, and semantic background color themes from the design system.",
       },
     },
   },
 }
 
-// 4. Real World Examples
-export const RealWorldExamples: Story = {
-  render: () => (
-    <div className="space-y-12">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">
-          Real World Examples
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Common avatar usage patterns in UI components
-        </p>
-      </div>
+// ─── 4. Use Cases ─────────────────────────────────────────────────────────────
 
+export const UseCases: Story = {
+  render: () => (
+    <div className="mx-auto max-w-3xl space-y-8 p-8">
       {/* User List */}
       <div className="space-y-4">
-        <h4 className="text-fm-tertiary text-sm font-medium">User List</h4>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          User List
+        </h4>
         <div className="mx-auto max-w-md space-y-3">
           <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center gap-3 rounded-lg border p-3">
             <Avatar>
@@ -354,8 +323,12 @@ export const RealWorldExamples: Story = {
               <AvatarFallback>JD</AvatarFallback>
             </Avatar>
             <div>
-              <p className="text-fm-primary text-sm font-medium">John Doe</p>
-              <p className="text-fm-secondary text-xs">john.doe@example.com</p>
+              <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                John Doe
+              </p>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                john.doe@example.com
+              </p>
             </div>
           </div>
           <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center gap-3 rounded-lg border p-3">
@@ -367,25 +340,27 @@ export const RealWorldExamples: Story = {
               <AvatarFallback>SW</AvatarFallback>
             </Avatar>
             <div>
-              <p className="text-fm-primary text-sm font-medium">
+              <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
                 Sarah Wilson
               </p>
-              <p className="text-fm-secondary text-xs">
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
                 sarah.wilson@example.com
               </p>
             </div>
           </div>
           <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center gap-3 rounded-lg border p-3">
             <Avatar>
-              <AvatarFallback className="bg-blue-500 text-white">
+              <AvatarFallback className="bg-fm-surface-info-sec text-fm-primary">
                 MJ
               </AvatarFallback>
             </Avatar>
             <div>
-              <p className="text-fm-primary text-sm font-medium">
+              <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
                 Michael Johnson
               </p>
-              <p className="text-fm-secondary text-xs">michael.j@example.com</p>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                michael.j@example.com
+              </p>
             </div>
           </div>
         </div>
@@ -393,7 +368,9 @@ export const RealWorldExamples: Story = {
 
       {/* Comment Thread */}
       <div className="space-y-4">
-        <h4 className="text-fm-tertiary text-sm font-medium">Comment Thread</h4>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Comment Thread
+        </h4>
         <div className="mx-auto max-w-md space-y-4">
           <div className="flex gap-3">
             <Avatar className="size-8">
@@ -401,36 +378,41 @@ export const RealWorldExamples: Story = {
                 src="https://images.unsplash.com/photo-1500648767791-00dcc994a43e?w=100&h=100&fit=crop&crop=face"
                 alt="Alex"
               />
-              <AvatarFallback className="text-xs">AL</AvatarFallback>
+              <AvatarFallback>AL</AvatarFallback>
             </Avatar>
             <div className="flex-1">
               <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-3">
-                <p className="text-fm-primary mb-1 text-xs font-medium">
+                <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm mb-1 font-medium">
                   Alex Thompson
                 </p>
-                <p className="text-fm-tertiary text-sm">
+                <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
                   This looks great! Really like the new design direction.
                 </p>
               </div>
-              <p className="text-fm-secondary mt-1 text-xs">2 hours ago</p>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm mt-1">
+                2 hours ago
+              </p>
             </div>
           </div>
           <div className="flex gap-3">
+            {/* text-white ensures contrast on vivid bg in both light and dark mode */}
             <Avatar className="size-8">
-              <AvatarFallback className="bg-purple-500 text-xs text-white">
+              <AvatarFallback className="bg-fm-secondary-500 text-white">
                 EM
               </AvatarFallback>
             </Avatar>
             <div className="flex-1">
               <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-3">
-                <p className="text-fm-primary mb-1 text-xs font-medium">
+                <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm mb-1 font-medium">
                   Emma Davis
                 </p>
-                <p className="text-fm-tertiary text-sm">
+                <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
                   Agreed! The frosted glass effect is perfect.
                 </p>
               </div>
-              <p className="text-fm-secondary mt-1 text-xs">1 hour ago</p>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm mt-1">
+                1 hour ago
+              </p>
             </div>
           </div>
         </div>
@@ -438,7 +420,9 @@ export const RealWorldExamples: Story = {
 
       {/* Team Members */}
       <div className="space-y-4">
-        <h4 className="text-fm-tertiary text-sm font-medium">Team Members</h4>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Team Members
+        </h4>
         <div className="flex items-center justify-center gap-2">
           <Avatar className="size-10">
             <AvatarImage
@@ -455,17 +439,17 @@ export const RealWorldExamples: Story = {
             <AvatarFallback>DS</AvatarFallback>
           </Avatar>
           <Avatar className="size-10">
-            <AvatarFallback className="bg-green-500 text-white">
+            <AvatarFallback className="bg-fm-surface-positive-sec text-fm-primary">
               DE
             </AvatarFallback>
           </Avatar>
           <Avatar className="size-10">
-            <AvatarFallback className="bg-orange-500 text-white">
+            <AvatarFallback className="bg-fm-surface-warning-sec text-fm-primary">
               PM
             </AvatarFallback>
           </Avatar>
           <Avatar className="size-10">
-            <AvatarFallback className="bg-gray-600 text-xs text-white">
+            <AvatarFallback className="bg-fm-surface-secondary text-fm-primary">
               +3
             </AvatarFallback>
           </Avatar>
@@ -474,6 +458,7 @@ export const RealWorldExamples: Story = {
     </div>
   ),
   parameters: {
+    layout: "fullscreen",
     docs: {
       description: {
         story:
@@ -483,52 +468,48 @@ export const RealWorldExamples: Story = {
   },
 }
 
-// 5. Loading States
-export const LoadingStates: Story = {
+// ─── 5. States ────────────────────────────────────────────────────────────────
+
+export const States: Story = {
   render: () => (
     <div className="space-y-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">Loading States</h3>
-        <p className="text-fm-secondary text-sm">
-          How avatars handle loading and error states
-        </p>
-      </div>
-
       <div className="flex flex-wrap items-center justify-center gap-6">
-        {/* Loading State Simulation */}
         <div className="space-y-2 text-center">
           <Avatar>
             <AvatarImage
               src="https://httpstat.us/200?sleep=5000"
               alt="Loading"
             />
-            <AvatarFallback className="animate-pulse bg-gray-600">
-              <div className="h-4 w-4 rounded bg-gray-400"></div>
+            <AvatarFallback className="bg-fm-surface-tertiary animate-pulse">
+              <div className="bg-fm-surface-secondary h-4 w-4 rounded"></div>
             </AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Loading...</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Loading
+          </p>
         </div>
 
-        {/* Error State */}
         <div className="space-y-2 text-center">
           <Avatar>
             <AvatarImage src="/non-existent-image.jpg" alt="Error" />
-            <AvatarFallback className="border border-red-500/30 bg-red-500/20 text-red-400">
+            <AvatarFallback className="bg-fm-surface-negative-sec text-fm-primary">
               !
             </AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Error State</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Error
+          </p>
         </div>
 
-        {/* Skeleton State */}
         <div className="space-y-2 text-center">
-          <Avatar className="animate-pulse bg-gray-700">
-            <AvatarFallback className="bg-gray-600"></AvatarFallback>
+          <Avatar className="bg-fm-surface-secondary animate-pulse">
+            <AvatarFallback className="bg-fm-surface-tertiary"></AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Skeleton</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Skeleton
+          </p>
         </div>
 
-        {/* Success State */}
         <div className="space-y-2 text-center">
           <Avatar>
             <AvatarImage
@@ -537,19 +518,18 @@ export const LoadingStates: Story = {
             />
             <AvatarFallback>OK</AvatarFallback>
           </Avatar>
-          <p className="text-fm-secondary text-xs">Loaded</p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Loaded
+          </p>
         </div>
       </div>
 
-      <div className="text-center">
-        <div className="border-fm-divider-secondary bg-fm-surface-secondary inline-block max-w-lg rounded-lg border p-4">
-          <h4 className="text-fm-primary mb-2 text-sm font-medium">
-            Loading Behavior
-          </h4>
-          <p className="text-fm-secondary text-xs leading-relaxed">
+      <div className="flex justify-center">
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary max-w-lg rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
             Avatars automatically show fallback content while images are loading
-            or if they fail to load. You can customize the fallback appearance
-            to match your design system or show loading indicators.
+            or if they fail to load. Customize the fallback appearance to match
+            your design system or show loading indicators.
           </p>
         </div>
       </div>
@@ -559,27 +539,18 @@ export const LoadingStates: Story = {
     docs: {
       description: {
         story:
-          "Examples of different loading states including loading indicators, error states, skeleton loading, and successful image loading.",
+          "Loading, error, skeleton, and success states demonstrating how avatars handle image lifecycle events.",
       },
     },
   },
 }
 
-// 6. Accessibility Example
-export const AccessibilityExample: Story = {
+// ─── 6. Accessibility ────────────────────────────────────────────────────────
+
+export const Accessibility: Story = {
   render: () => (
     <div className="space-y-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">
-          Accessibility Features
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Proper accessibility implementation with alt text and descriptions
-        </p>
-      </div>
-
       <div className="mx-auto max-w-md space-y-6">
-        {/* Profile with proper alt text */}
         <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center gap-3 rounded-lg border p-4">
           <Avatar>
             <AvatarImage
@@ -589,12 +560,15 @@ export const AccessibilityExample: Story = {
             <AvatarFallback>JD</AvatarFallback>
           </Avatar>
           <div>
-            <p className="text-fm-primary text-sm font-medium">John Doe</p>
-            <p className="text-fm-secondary text-xs">Software Engineer</p>
+            <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+              John Doe
+            </p>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Software Engineer
+            </p>
           </div>
         </div>
 
-        {/* Fallback with descriptive content */}
         <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center gap-3 rounded-lg border p-4">
           <Avatar title="User avatar for Sarah Wilson">
             <AvatarFallback aria-label="Sarah Wilson's initials">
@@ -602,12 +576,15 @@ export const AccessibilityExample: Story = {
             </AvatarFallback>
           </Avatar>
           <div>
-            <p className="text-fm-primary text-sm font-medium">Sarah Wilson</p>
-            <p className="text-fm-secondary text-xs">UX Designer</p>
+            <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+              Sarah Wilson
+            </p>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              UX Designer
+            </p>
           </div>
         </div>
 
-        {/* Online status indicator */}
         <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center gap-3 rounded-lg border p-4">
           <div className="relative">
             <Avatar>
@@ -624,26 +601,33 @@ export const AccessibilityExample: Story = {
             ></div>
           </div>
           <div>
-            <p className="text-fm-primary text-sm font-medium">Emma Davis</p>
-            <p className="text-fm-secondary text-xs">
-              Product Manager • Online
+            <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+              Emma Davis
+            </p>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Product Manager · Online
             </p>
           </div>
         </div>
       </div>
 
-      <div className="text-center">
-        <div className="border-fm-divider-secondary bg-fm-surface-secondary inline-block max-w-lg rounded-lg border p-4">
-          <h4 className="text-fm-primary mb-2 text-sm font-medium">
-            Accessibility Best Practices
-          </h4>
-          <div className="text-fm-secondary space-y-2 text-left text-xs">
-            <p>• Use descriptive alt text for images</p>
-            <p>• Provide aria-label for fallback content</p>
-            <p>• Include title attributes for additional context</p>
-            <p>• Ensure sufficient color contrast for text</p>
-            <p>• Add status indicators with proper labels</p>
-          </div>
+      <div className="flex justify-center">
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary max-w-lg space-y-1 rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Use descriptive alt text for avatar images
+          </p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Provide aria-label on fallback content
+          </p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Include title attributes for additional context
+          </p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Ensure sufficient color contrast for fallback text
+          </p>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Add status indicators with proper aria labels
+          </p>
         </div>
       </div>
     </div>