aural-ui 4.0.1 → 4.2.0

package/dist/components/card/Card.stories.tsx

@@ -1,8 +1,18 @@
 import React from "react"
 import { Badge } from "@components/badge"
 import { Button } from "@components/button"
+import {
+  HeartIcon,
+  MusicalNoteIcon,
+  PauseIcon,
+  SkipForwardIcon,
+  StarIcon,
+  VolumeFullIcon,
+} from "@icons/index"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import {
   Card,
   CardAction,
@@ -18,107 +28,36 @@ const meta: Meta<typeof Card> = {
   component: Card,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "light", value: "#ffffff" },
-        { name: "dark", value: "#0a0a0a" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-  # Card Component
-  
-  A flexible and interactive card component that serves as a container for related content. Features hover effects and clean styling perfect for displaying information in an organized, visually appealing way.
-  
-  ## Features
-  
-  - **Interactive Design**: Hover gradient effects for better user engagement
-  - **Flexible Layout**: Column-based flex layout with customizable gap spacing
-  - **Clean Styling**: Neutral color scheme with subtle shadows
-  - **Responsive**: Works well across different screen sizes
-  - **Accessible**: Proper cursor states and semantic structure
-  - **Customizable**: Easy to extend with additional CSS classes
-  - **Bordered Design**: Clean borders with rounded corners
-  
-  ## Usage Examples
-  
-  ### Basic Card
-  \`\`\`tsx
-  <Card>
-    <p>Simple card content</p>
-  </Card>
-  \`\`\`
-  
-  ### Card with Header and Content
-  \`\`\`tsx
-  <Card className="w-96">
-    <CardHeader>
-      <CardTitle>Card Title</CardTitle>
-      <CardDescription>Card description</CardDescription>
-    </CardHeader>
-    <CardContent>Content goes here</CardContent>
-  </Card>
-  \`\`\`
-  
-  ### Card with Custom Width
-  \`\`\`tsx
-  <Card className="w-80 max-w-sm">
-    <div className="space-y-2">
-      <h3 className="font-semibold">Custom Card</h3>
-      <p className="text-sm text-gray-600">
-        This card has custom width styling
-      </p>
-    </div>
-  </Card>
-  \`\`\`
-  
-  ### Clickable Card
-  \`\`\`tsx
-  <Card 
-    className="w-72 transition-transform hover:scale-105" 
-    onClick={() => console.log('Card clicked')}
-  >
-    <div className="p-2">
-      <h4 className="font-medium">Clickable Card</h4>
-      <p className="text-sm mt-1">Click me for interaction</p>
-    </div>
-  </Card>
-  \`\`\`
-  
-  ### Card Grid Layout
-  \`\`\`tsx
-  <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-    <Card>
-      <CardHeader>
-        <CardTitle>Feature 1</CardTitle>
-      </CardHeader>
-      <CardContent>Description of feature 1</CardContent>
-    </Card>
-    <Card>
-      <CardHeader>
-        <CardTitle>Feature 2</CardTitle>
-      </CardHeader>
-      <CardContent>Description of feature 2</CardContent>
-    </Card>
-    <Card>
-      <CardHeader>
-        <CardTitle>Feature 3</CardTitle>
-      </CardHeader>
-      <CardContent>Description of feature 3</CardContent>
-    </Card>
-  </div>
-  \`\`\`
-          `,
+        component:
+          "A flexible compound-component card for grouping related content. Composed of CardHeader, CardTitle, CardDescription, CardAction, CardContent, and CardFooter — each a distinct slot that can be used independently or combined. Designed for audio app contexts: track listings, artist profiles, playlist previews, and more.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "6 Composable Parts",
+              description: "Mix and match slots",
+            },
+            {
+              title: "Action Slot",
+              description: "Badge or button in header",
+            },
+            {
+              title: "Flexible Layout",
+              description: "Header, content, footer",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
   argTypes: {
     className: {
       control: "text",
-      description: "Additional CSS classes to apply to the card",
+      description: "Additional CSS classes applied to the card root",
     },
   },
 }
@@ -126,252 +65,631 @@ const meta: Meta<typeof Card> = {
 export default meta
 type Story = StoryObj<typeof meta>
 
-// Basic card examples
-export const Simple: Story = {
-  render: () => (
-    <Card>
-      <CardHeader>
-        <CardTitle>Simple Card</CardTitle>
-        <CardDescription>
-          This is a basic card with header and content.
-        </CardDescription>
-      </CardHeader>
-      <CardContent>
-        <p>
-          This is the main content area of the card. You can put any content
-          here.
-        </p>
-      </CardContent>
-    </Card>
-  ),
-}
+// ─── 1. Parts ─────────────────────────────────────────────────────────────────
 
-export const WithFooter: Story = {
+export const Parts: Story = {
   render: () => (
-    <Card>
-      <CardHeader>
-        <CardTitle>Card with Footer</CardTitle>
-        <CardDescription>
-          A card that includes a footer section.
-        </CardDescription>
-      </CardHeader>
-      <CardContent>
-        <p>Main content goes here. The footer below contains action buttons.</p>
-      </CardContent>
-      <CardFooter className="gap-2">
-        <Button>Cancel</Button>
-        <Button>Save</Button>
-      </CardFooter>
-    </Card>
-  ),
-}
+    <div className="mx-auto w-full max-w-2xl space-y-10">
+      {/* CardHeader */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          CardHeader
+        </h4>
+        <Card className="w-80">
+          <CardHeader>
+            <CardTitle>Track Title</CardTitle>
+            <CardDescription>Artist · Album · 2024</CardDescription>
+          </CardHeader>
+        </Card>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            <strong className="text-fm-primary">CardHeader</strong> is the top
+            zone of the card. It uses a CSS grid that reserves a right column
+            when a <code>CardAction</code> is present. Contains{" "}
+            <code>CardTitle</code> and <code>CardDescription</code> by
+            convention.
+          </p>
+        </div>
+      </div>
 
-export const WithAction: Story = {
-  render: () => (
-    <Card>
-      <CardHeader>
-        <CardTitle>Project Alpha</CardTitle>
-        <CardDescription>A revolutionary new project</CardDescription>
-        <CardAction>
-          <Badge>Active</Badge>
-        </CardAction>
-      </CardHeader>
-      <CardContent>
-        <p>
-          This card demonstrates the action slot in the header, which is
-          positioned to the right.
-        </p>
-      </CardContent>
-    </Card>
-  ),
-}
+      {/* CardTitle */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          CardTitle
+        </h4>
+        <Card className="w-80">
+          <CardHeader>
+            <CardTitle>Midnight Dreams</CardTitle>
+          </CardHeader>
+        </Card>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            <strong className="text-fm-primary">CardTitle</strong> renders a
+            semibold heading with <code>leading-none</code>. It spans the full
+            first column of the header grid.
+          </p>
+        </div>
+      </div>
 
-export const WithActionButton: Story = {
-  render: () => (
-    <Card>
-      <CardHeader>
-        <CardTitle>Settings</CardTitle>
-        <CardDescription>Manage your account preferences</CardDescription>
-        <CardAction>
-          <Button variant="outline" size="sm">
-            Edit
-          </Button>
-        </CardAction>
-      </CardHeader>
-      <CardContent>
-        <div className="space-y-2">
-          <div className="flex justify-between">
-            <span>Notifications</span>
-            <span className="text-muted-foreground">Enabled</span>
-          </div>
-          <div className="flex justify-between">
-            <span>Theme</span>
-            <span className="text-muted-foreground">Dark</span>
-          </div>
+      {/* CardDescription */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          CardDescription
+        </h4>
+        <Card className="w-80">
+          <CardHeader>
+            <CardTitle>Electric Sunrise</CardTitle>
+            <CardDescription>
+              Neon Collective · Wavelength · 2024
+            </CardDescription>
+          </CardHeader>
+        </Card>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            <strong className="text-fm-primary">CardDescription</strong> sits
+            beneath the title in the header grid. Uses <code>text-sm</code> —
+            inherits the card's primary text color at reduced contrast.
+          </p>
         </div>
-      </CardContent>
-    </Card>
-  ),
-}
+      </div>
 
-export const BorderVariants: Story = {
-  render: () => (
-    <div className="flex gap-4">
-      <Card className="w-80">
-        <CardHeader className="border-b">
-          <CardTitle>Header with Border</CardTitle>
-          <CardDescription>The header has a bottom border</CardDescription>
-        </CardHeader>
-        <CardContent>
-          <p>Content section with bordered header above.</p>
-        </CardContent>
-      </Card>
+      {/* CardAction */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          CardAction
+        </h4>
+        <Card className="w-80">
+          <CardHeader>
+            <CardTitle>Echoes in Rain</CardTitle>
+            <CardDescription>Ambient · 3:42</CardDescription>
+            <CardAction>
+              <Badge
+                color="positive"
+                className="bg-fm-surface-positive-sec text-fm-positive-sec"
+              >
+                LIVE
+              </Badge>
+            </CardAction>
+          </CardHeader>
+        </Card>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            <strong className="text-fm-primary">CardAction</strong> occupies the
+            right column of the header grid, spanning both title and description
+            rows. Use it for badges, icon buttons, or status indicators.
+          </p>
+        </div>
+      </div>
 
-      <Card className="w-80">
-        <CardHeader>
-          <CardTitle>Footer with Border</CardTitle>
-          <CardDescription>The footer has a top border</CardDescription>
-        </CardHeader>
-        <CardContent>
-          <p>Content section with bordered footer below.</p>
-        </CardContent>
-        <CardFooter className="border-t">
-          <Button>Action</Button>
-        </CardFooter>
-      </Card>
+      {/* CardContent */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          CardContent
+        </h4>
+        <Card className="w-80">
+          <CardContent>
+            <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+              CardContent is a free-form slot. Place any child content here —
+              metadata rows, waveform visualisers, track lists, or stat
+              summaries.
+            </p>
+          </CardContent>
+        </Card>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            <strong className="text-fm-primary">CardContent</strong> is an
+            unstyled passthrough slot. It adds no padding of its own — the
+            parent <code>Card</code> gap handles spacing between parts.
+          </p>
+        </div>
+      </div>
+
+      {/* CardFooter */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          CardFooter
+        </h4>
+        <Card className="w-80">
+          <CardHeader>
+            <CardTitle>Neon Horizon</CardTitle>
+            <CardDescription>Synthwave · 4:15</CardDescription>
+          </CardHeader>
+          <CardFooter className="gap-2">
+            <Button variant="outline" size="sm" className="flex-1">
+              Add to Queue
+            </Button>
+            <Button size="sm" className="flex-1">
+              Play Now
+            </Button>
+          </CardFooter>
+        </Card>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            <strong className="text-fm-primary">CardFooter</strong> is a flex
+            row at the bottom of the card. Use it for action buttons, metadata,
+            or secondary controls. Supports optional <code>border-t</code>{" "}
+            separator via class.
+          </p>
+        </div>
+      </div>
     </div>
   ),
   parameters: {
     layout: "padded",
+    docs: {
+      description: {
+        story:
+          "Each sub-component of the Card compound displayed individually with a role explanation. Use this as a reference when composing card layouts.",
+      },
+    },
   },
 }
 
-export const ComplexExample: Story = {
+// ─── 2. Configurations ────────────────────────────────────────────────────────
+
+export const Configurations: Story = {
   render: () => (
-    <Card>
-      <CardHeader className="border-b">
-        <CardTitle>User Profile</CardTitle>
-        <CardDescription>Manage user information and settings</CardDescription>
-        <CardAction>
-          <div className="flex gap-2">
-            <Badge>Pro</Badge>
-            <Button variant="outline" size="sm">
-              •••
-            </Button>
+    <div className="mx-auto w-full max-w-4xl space-y-8">
+      {/* Minimal */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Minimal — content only
+        </h4>
+        <div className="flex flex-wrap justify-center gap-4">
+          <div className="space-y-2 text-center">
+            <Card className="w-72">
+              <CardContent>
+                <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+                  A minimal card with no header or footer — just freeform
+                  content inside.
+                </p>
+              </CardContent>
+            </Card>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Content only
+            </p>
           </div>
-        </CardAction>
-      </CardHeader>
-      <CardContent className="space-y-4">
-        <div className="flex items-center space-x-4">
-          <div className="bg-muted flex h-12 w-12 items-center justify-center rounded-full">
-            <span className="text-lg font-semibold">JD</span>
+        </div>
+      </div>
+
+      {/* Header only */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Header only
+        </h4>
+        <div className="flex flex-wrap justify-center gap-4">
+          <div className="space-y-2 text-center">
+            <Card className="w-72">
+              <CardHeader>
+                <CardTitle>Track Title</CardTitle>
+                <CardDescription>Artist · 3:24</CardDescription>
+              </CardHeader>
+            </Card>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Title + description
+            </p>
           </div>
-          <div>
-            <p className="font-medium">John Doe</p>
-            <p className="text-muted-foreground text-sm">
-              john.doe@example.com
+        </div>
+      </div>
+
+      {/* With footer */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          With footer
+        </h4>
+        <div className="flex flex-wrap justify-center gap-4">
+          <div className="space-y-2 text-center">
+            <Card className="w-72">
+              <CardHeader>
+                <CardTitle>Wavelength EP</CardTitle>
+                <CardDescription>Neon Collective · 6 tracks</CardDescription>
+              </CardHeader>
+              <CardContent>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-xl">
+                  An ambient electronic project exploring texture and space.
+                </p>
+              </CardContent>
+              <CardFooter className="gap-2 border-t">
+                <Button variant="outline" size="sm" className="flex-1">
+                  Save
+                </Button>
+                <Button size="sm" className="flex-1">
+                  Play
+                </Button>
+              </CardFooter>
+            </Card>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Header + content + footer
             </p>
           </div>
         </div>
-        <div className="space-y-2">
-          <div className="flex justify-between text-sm">
-            <span>Member since</span>
-            <span className="text-muted-foreground">Jan 2024</span>
+      </div>
+
+      {/* With action */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          With action slot
+        </h4>
+        <div className="flex flex-wrap justify-center gap-4">
+          <div className="space-y-2 text-center">
+            <Card className="w-72">
+              <CardHeader>
+                <CardTitle>Electric Sunrise</CardTitle>
+                <CardDescription>Synthwave · 5:01</CardDescription>
+                <CardAction>
+                  <Badge color="negative">EXPLICIT</Badge>
+                </CardAction>
+              </CardHeader>
+              <CardContent>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-xl">
+                  High-energy track from the Horizon album.
+                </p>
+              </CardContent>
+            </Card>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Header with action badge
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Card className="w-72">
+              <CardHeader>
+                <CardTitle>Playlist Settings</CardTitle>
+                <CardDescription>Manage your queue</CardDescription>
+                <CardAction>
+                  <Button variant="outline" size="sm">
+                    Edit
+                  </Button>
+                </CardAction>
+              </CardHeader>
+              <CardContent>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-xl">
+                  24 tracks · 1h 32m total duration
+                </p>
+              </CardContent>
+            </Card>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Header with action button
+            </p>
           </div>
-          <div className="flex justify-between text-sm">
-            <span>Last login</span>
-            <span className="text-muted-foreground">2 hours ago</span>
+        </div>
+      </div>
+
+      {/* Full card */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Full card — all parts combined
+        </h4>
+        <div className="flex flex-wrap justify-center gap-4">
+          <div className="space-y-2 text-center">
+            <Card className="w-72">
+              <CardHeader className="border-b">
+                <CardTitle>Midnight Dreams</CardTitle>
+                <CardDescription>
+                  Aura Band · Dark Frequencies · 2024
+                </CardDescription>
+                <CardAction>
+                  <Badge
+                    color="info"
+                    className="bg-fm-surface-info-sec text-fm-info-sec"
+                  >
+                    NEW
+                  </Badge>
+                </CardAction>
+              </CardHeader>
+              <CardContent className="space-y-2">
+                <div className="flex items-center justify-between">
+                  <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Duration
+                  </span>
+                  <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                    4:17
+                  </span>
+                </div>
+                <div className="flex items-center justify-between">
+                  <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Plays
+                  </span>
+                  <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                    1.2M
+                  </span>
+                </div>
+                <div className="flex items-center justify-between">
+                  <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Genre
+                  </span>
+                  <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                    Electronic
+                  </span>
+                </div>
+              </CardContent>
+              <CardFooter className="gap-2 border-t">
+                <Button variant="outline" size="sm" className="flex-1">
+                  Add to Queue
+                </Button>
+                <Button size="sm" className="flex-1">
+                  Play
+                </Button>
+              </CardFooter>
+            </Card>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              All parts · border separators
+            </p>
           </div>
         </div>
-      </CardContent>
-      <CardFooter className="gap-2 border-t">
-        <Button variant="outline" className="flex-1">
-          Edit Profile
-        </Button>
-        <Button className="flex-1">View Details</Button>
-      </CardFooter>
-    </Card>
+      </div>
+    </div>
   ),
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        story:
+          "Five card layout configurations: minimal content-only, header-only, with footer, with action slot, and the full compound using all parts together.",
+      },
+    },
+  },
 }
 
-export const ContentVariations: Story = {
-  render: () => (
-    <div className="grid w-full max-w-4xl grid-cols-1 gap-4 md:grid-cols-2">
-      <Card>
-        <CardHeader>
-          <CardTitle>Minimal Card</CardTitle>
-        </CardHeader>
-        <CardContent>
-          <p>Just a title and content.</p>
-        </CardContent>
-      </Card>
+// ─── 3. Use Cases ─────────────────────────────────────────────────────────────
 
-      <Card>
-        <CardContent>
-          <p>Content only - no header or footer.</p>
-        </CardContent>
-      </Card>
+export const UseCases: Story = {
+  render: () => (
+    <div className="mx-auto max-w-3xl space-y-8 p-8">
+      {/* Track Card */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Track Card
+        </h4>
+        <div className="mx-auto max-w-md">
+          <Card>
+            <CardHeader>
+              <CardTitle className="text-fm-primary font-fm-text text-fm-lg leading-fm-lg flex items-center gap-2 font-semibold">
+                <MusicalNoteIcon className="text-fm-secondary size-4 shrink-0" />
+                Midnight Dreams
+              </CardTitle>
+              <CardDescription className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                Aura Band · Dark Frequencies · 4:17
+              </CardDescription>
+              <CardAction>
+                <Badge
+                  color="positive"
+                  className="bg-fm-surface-positive-sec text-fm-positive-sec"
+                >
+                  LIVE
+                </Badge>
+              </CardAction>
+            </CardHeader>
+            <CardContent>
+              {/* Waveform placeholder */}
+              <div className="bg-fm-surface-secondary rounded-fm-s flex h-10 items-center justify-between gap-1 px-2">
+                {Array.from({ length: 32 }).map((_, i) => (
+                  <div
+                    key={i}
+                    className="bg-fm-surface-frosted/40 w-1 rounded-full"
+                    style={{ height: `${20 + Math.sin(i * 0.8) * 14}px` }}
+                  />
+                ))}
+              </div>
+            </CardContent>
+            <CardFooter className="gap-2 border-t">
+              <Button variant="text" size="sm">
+                <HeartIcon className="size-4" />
+              </Button>
+              <div className="flex flex-1 items-center justify-center gap-3">
+                <Button variant="text" size="sm">
+                  <SkipForwardIcon className="size-4 rotate-180" />
+                </Button>
+                <Button size="sm">
+                  <PauseIcon className="size-4" />
+                </Button>
+                <Button variant="text" size="sm">
+                  <SkipForwardIcon className="size-4" />
+                </Button>
+              </div>
+              <Button variant="text" size="sm">
+                <VolumeFullIcon className="size-4" />
+              </Button>
+            </CardFooter>
+          </Card>
+        </div>
+      </div>
 
-      <Card>
-        <CardHeader>
-          <CardTitle>Header Only</CardTitle>
-          <CardDescription>No content section</CardDescription>
-        </CardHeader>
-      </Card>
+      {/* Artist Profile Card */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Artist Profile Card
+        </h4>
+        <div className="mx-auto max-w-md">
+          <Card>
+            <CardHeader className="border-b">
+              <CardTitle className="text-fm-primary font-fm-brand text-fm-xl leading-fm-xl flex items-center gap-3 font-semibold">
+                <div className="bg-fm-surface-secondary text-fm-primary flex size-10 shrink-0 items-center justify-center rounded-full font-semibold">
+                  NC
+                </div>
+                Neon Collective
+              </CardTitle>
+              <CardDescription className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                Ambient Electronic · Berlin, DE
+              </CardDescription>
+              <CardAction>
+                <div className="flex items-center gap-1">
+                  <StarIcon className="text-fm-label-primary size-4" />
+                  <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                    4.9
+                  </span>
+                </div>
+              </CardAction>
+            </CardHeader>
+            <CardContent className="grid grid-cols-3 gap-4 text-center">
+              <div className="space-y-1">
+                <p className="text-fm-primary font-fm-brand text-fm-lg leading-fm-lg font-semibold">
+                  2.4M
+                </p>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  Monthly Listeners
+                </p>
+              </div>
+              <div className="space-y-1">
+                <p className="text-fm-primary font-fm-brand text-fm-lg leading-fm-lg font-semibold">
+                  18
+                </p>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  Albums
+                </p>
+              </div>
+              <div className="space-y-1">
+                <p className="text-fm-primary font-fm-brand text-fm-lg leading-fm-lg font-semibold">
+                  142
+                </p>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  Tracks
+                </p>
+              </div>
+            </CardContent>
+            <CardFooter className="gap-2 border-t">
+              <Button variant="outline" size="sm" className="flex-1">
+                Follow
+              </Button>
+              <Button size="sm" className="flex-1">
+                Play Artist Radio
+              </Button>
+            </CardFooter>
+          </Card>
+        </div>
+      </div>
 
-      <Card>
-        <CardHeader>
-          <CardTitle>List Content</CardTitle>
-        </CardHeader>
-        <CardContent>
-          <ul className="space-y-2">
-            <li className="flex items-center gap-2">
-              <div className="bg-fm-surface-positive h-2 w-2 rounded-full"></div>
-              <span>Task completed</span>
-            </li>
-            <li className="flex items-center gap-2">
-              <div className="bg-fm-surface-warning h-2 w-2 rounded-full"></div>
-              <span>In progress</span>
-            </li>
-            <li className="flex items-center gap-2">
-              <div className="bg-fm-surface-negative h-2 w-2 rounded-full"></div>
-              <span>Blocked</span>
-            </li>
-          </ul>
-        </CardContent>
-      </Card>
+      {/* Playlist Card */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Playlist Card
+        </h4>
+        <div className="mx-auto max-w-md">
+          <Card>
+            <CardHeader>
+              <CardTitle className="text-fm-primary font-fm-brand text-fm-lg leading-fm-lg font-semibold">
+                Late Night Sessions
+              </CardTitle>
+              <CardDescription className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                Curated by you · 24 tracks · 1h 32m
+              </CardDescription>
+              <CardAction>
+                <Badge color="neutral">PRIVATE</Badge>
+              </CardAction>
+            </CardHeader>
+            <CardContent className="space-y-2">
+              {[
+                {
+                  title: "Midnight Dreams",
+                  artist: "Aura Band",
+                  duration: "4:17",
+                },
+                {
+                  title: "Electric Sunrise",
+                  artist: "Neon Collective",
+                  duration: "5:01",
+                },
+                {
+                  title: "Echoes in Rain",
+                  artist: "The Drifters",
+                  duration: "3:42",
+                },
+              ].map((track) => (
+                <div
+                  key={track.title}
+                  className="border-fm-divider-secondary flex items-center justify-between rounded border px-3 py-2"
+                >
+                  <div className="flex items-center gap-2">
+                    <MusicalNoteIcon className="text-fm-tertiary size-3.5 shrink-0" />
+                    <div>
+                      <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                        {track.title}
+                      </p>
+                      <p className="text-fm-secondary font-fm-text text-fm-xs leading-fm-xs">
+                        {track.artist}
+                      </p>
+                    </div>
+                  </div>
+                  <span className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                    {track.duration}
+                  </span>
+                </div>
+              ))}
+            </CardContent>
+            <CardFooter className="gap-2 border-t">
+              <Button variant="outline" size="sm" className="flex-1">
+                Shuffle
+              </Button>
+              <Button size="sm" className="flex-1">
+                Play All
+              </Button>
+            </CardFooter>
+          </Card>
+        </div>
+      </div>
     </div>
   ),
   parameters: {
-    layout: "padded",
+    layout: "fullscreen",
+    docs: {
+      description: {
+        story:
+          "Realistic audio app card compositions: a playback-ready track card with waveform, an artist profile card with stats, and a playlist card with an inline track listing.",
+      },
+    },
   },
 }
 
-// Interactive playground
+// ─── 4. Playground ────────────────────────────────────────────────────────────
+
 export const Playground: Story = {
   args: {
-    className: "w-96",
+    className: "w-80",
   },
-  render: (args: Record<string, unknown>) => (
-    <Card {...args}>
-      <CardHeader>
-        <CardTitle>Playground Card</CardTitle>
-        <CardDescription>
-          Customize this card using the controls below
-        </CardDescription>
-        <CardAction>
-          <Badge>New</Badge>
-        </CardAction>
-      </CardHeader>
-      <CardContent>
-        <p>
-          Use the Storybook controls to modify the card's appearance and
-          behavior.
-        </p>
-      </CardContent>
-      <CardFooter>
-        <Button>Primary Action</Button>
-      </CardFooter>
-    </Card>
+  render: (args) => (
+    <div className="mx-auto w-full max-w-sm space-y-4">
+      <Card {...args}>
+        <CardHeader>
+          <CardTitle>Playground Card</CardTitle>
+          <CardDescription>
+            Adjust this card using the controls panel
+          </CardDescription>
+          <CardAction>
+            <Badge
+              color="info"
+              className="bg-fm-surface-info-sec text-fm-info-sec"
+            >
+              NEW
+            </Badge>
+          </CardAction>
+        </CardHeader>
+        <CardContent>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-xl">
+            Use the Storybook controls panel to modify the card's className and
+            observe layout changes.
+          </p>
+        </CardContent>
+        <CardFooter className="gap-2">
+          <Button variant="outline" size="sm" className="flex-1">
+            Cancel
+          </Button>
+          <Button size="sm" className="flex-1">
+            Confirm
+          </Button>
+        </CardFooter>
+      </Card>
+      <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+        <code className="text-fm-secondary text-fm-md leading-fm-md font-(--font-fm-mono)">
+          {`<Card className="${(args as { className?: string }).className ?? ""}">`}
+        </code>
+      </div>
+    </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Controls-driven story. Use the Storybook sidebar to adjust the className prop and experiment with card widths and overrides.",
+      },
+    },
+  },
 }