aural-ui 4.0.1 → 4.2.0

package/dist/components/icon-button/IconButton.stories.tsx

@@ -1,10 +1,22 @@
 import React from "react"
-import { CrossIcon } from "@icons/cross-icon"
-import { FeatureShineIcon } from "@icons/feature-shine-icon"
-import { SearchIcon } from "@icons/search-icon"
-import { type Meta, type StoryObj } from "@storybook/react-vite"
+import {
+  CircularPlayIcon,
+  CrossIcon,
+  HeartIcon,
+  MusicalNoteIcon,
+  PauseIcon,
+  SearchIcon,
+  SettingIcon,
+  ShareIcon,
+  SkipBackwardIcon,
+  SkipForwardIcon,
+  TrashIcon,
+  VerticalMenuIcon,
+  VolumeFullIcon,
+} from "@icons/index"
+import type { Meta, StoryObj } from "@storybook/react-vite"
 
-import { NotepadIcon } from "src/ui/icons"
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
 
 import { IconButton } from "."
 
@@ -13,12 +25,29 @@ const meta: Meta<typeof IconButton> = {
   component: IconButton,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
+    docs: {
+      description: {
+        component:
+          "A compact button that renders a single icon. Supports three variants (background, ghost, outlined), three sizes (small, medium, large), and two shapes (circle, square). Accessible via a required label prop that populates aria-label, with optional tooltip support.",
+      },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "3 Variants",
+              description: "Background, ghost, outlined",
+            },
+            {
+              title: "Circle & Square",
+              description: "Two shape options",
+            },
+            {
+              title: "Accessible",
+              description: "Required label for ARIA",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -48,257 +77,871 @@ const meta: Meta<typeof IconButton> = {
 export default meta
 type Story = StoryObj<typeof IconButton>
 
-export const Default: Story = {
-  args: {
-    label: "Search",
-    icon: <SearchIcon />,
-  },
-}
+// ─── 1. Playground ────────────────────────────────────────────────────────────
 
-export const WithBackground: Story = {
+export const Playground: Story = {
   args: {
-    label: "Search",
-    icon: <SearchIcon />,
     variant: "background",
+    size: "medium",
+    shape: "circle",
+    disabled: false,
+    icon: <SearchIcon />,
+    label: "Search",
   },
   render: (args) => (
-    <div className="bg-fm-neutral-0 flex flex-col space-y-6 rounded p-8">
-      <h2 className="text-fm-yellow-500 text-sm font-bold">WITH BACKGROUND</h2>
+    <div className="flex w-full max-w-sm flex-col items-center space-y-4">
+      <IconButton {...args} />
+      <div className="border-fm-divider-secondary bg-fm-surface-secondary w-full rounded-lg border px-4 py-3">
+        <code className="text-fm-secondary text-fm-md leading-fm-md font-(--font-fm-mono)">{`<IconButton variant="${args.variant}" size="${args.size}" shape="${args.shape}"${args.disabled ? " disabled" : ""} label="${args.label}" />`}</code>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Use the controls panel in the sidebar to explore all IconButton props. The code snippet below updates live to reflect the current configuration.",
+      },
+    },
+  },
+}
 
-      <div className="flex flex-col space-y-4">
-        <div>
-          <h3 className="text-fm-primary mb-2">SMALL</h3>
-          <div className="flex space-x-4">
-            <IconButton {...args} size="small" label="Default" />
-            <IconButton {...args} size="small" disabled label="Disabled" />
-          </div>
-        </div>
+// ─── 2. All Variants ──────────────────────────────────────────────────────────
 
-        <div>
-          <h3 className="text-fm-primary mb-2">MEDIUM</h3>
-          <div className="flex space-x-4">
-            <IconButton {...args} size="medium" label="Default" />
-            <IconButton {...args} size="medium" disabled label="Disabled" />
+export const AllVariants: Story = {
+  render: () => (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Variant × Shape Matrix
+        </h4>
+        <div className="grid grid-cols-3 gap-8">
+          {/* Column headers */}
+          <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm text-center">
+            Background
+          </p>
+          <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm text-center">
+            Ghost
+          </p>
+          <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm text-center">
+            Outlined
+          </p>
+
+          {/* Circle row */}
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="background"
+              shape="circle"
+              icon={<SearchIcon />}
+              label="Search"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Circle
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="ghost"
+              shape="circle"
+              icon={<SearchIcon />}
+              label="Search"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Circle
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="outlined"
+              shape="circle"
+              icon={<SearchIcon />}
+              label="Search"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Circle
+            </p>
           </div>
-        </div>
 
-        <div>
-          <h3 className="text-fm-primary mb-2">LARGE</h3>
-          <div className="flex space-x-4">
-            <IconButton {...args} size="large" label="Default" />
-            <IconButton {...args} size="large" disabled label="Disabled" />
+          {/* Square row */}
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="background"
+              shape="square"
+              icon={<SearchIcon />}
+              label="Search"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Square
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="ghost"
+              shape="square"
+              icon={<SearchIcon />}
+              label="Search"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Square
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="outlined"
+              shape="square"
+              icon={<SearchIcon />}
+              label="Search"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Square
+            </p>
           </div>
         </div>
       </div>
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Full variant × shape matrix: all three variants (background, ghost, outlined) crossed with both shapes (circle, square).",
+      },
+    },
+  },
 }
 
-export const WithoutBackground: Story = {
-  args: {
-    label: "Search",
-    icon: <SearchIcon />,
-    variant: "ghost",
-  },
-  render: (args) => (
-    <div className="bg-fm-neutral-0 flex flex-col space-y-6 rounded p-8">
-      <h2 className="text-fm-yellow-500 text-sm font-bold">
-        WITHOUT BACKGROUND
-      </h2>
+// ─── 3. Sizes ─────────────────────────────────────────────────────────────────
 
-      <div className="flex flex-col space-y-4">
-        <div>
-          <h3 className="text-fm-primary mb-2">SMALL</h3>
-          <div className="flex space-x-4">
-            <IconButton {...args} size="small" label="Default" />
-            <IconButton {...args} size="small" disabled label="Disabled" />
+export const Sizes: Story = {
+  render: () => (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Background Variant
+        </h4>
+        <div className="flex flex-wrap items-end gap-6">
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="background"
+              size="small"
+              icon={<SearchIcon />}
+              label="Search small"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Small (32px)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="background"
+              size="medium"
+              icon={<SearchIcon />}
+              label="Search medium"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Medium (44px)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="background"
+              size="large"
+              icon={<SearchIcon />}
+              label="Search large"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Large (56px)
+            </p>
           </div>
         </div>
+      </div>
 
-        <div>
-          <h3 className="text-fm-primary mb-2">MEDIUM</h3>
-          <div className="flex space-x-4">
-            <IconButton {...args} size="medium" label="Default" />
-            <IconButton {...args} size="medium" disabled label="Disabled" />
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Ghost Variant
+        </h4>
+        <div className="flex flex-wrap items-end gap-6">
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="ghost"
+              size="small"
+              icon={<HeartIcon />}
+              label="Like small"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Small (32px)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="ghost"
+              size="medium"
+              icon={<HeartIcon />}
+              label="Like medium"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Medium (44px)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="ghost"
+              size="large"
+              icon={<HeartIcon />}
+              label="Like large"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Large (56px)
+            </p>
           </div>
         </div>
+      </div>
 
-        <div>
-          <h3 className="text-fm-primary mb-2">LARGE</h3>
-          <div className="flex space-x-4">
-            <IconButton {...args} size="large" label="Default" />
-            <IconButton {...args} size="large" disabled label="Disabled" />
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Outlined Variant
+        </h4>
+        <div className="flex flex-wrap items-end gap-6">
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="outlined"
+              size="small"
+              icon={<ShareIcon />}
+              label="Share small"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Small (32px)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="outlined"
+              size="medium"
+              icon={<ShareIcon />}
+              label="Share medium"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Medium (44px)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="outlined"
+              size="large"
+              icon={<ShareIcon />}
+              label="Share large"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Large (56px)
+            </p>
           </div>
         </div>
       </div>
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Side-by-side size comparison (small 32px, medium 44px, large 56px) for each of the three variants.",
+      },
+    },
+  },
 }
 
-export const WithToolTip: Story = {
-  render: () => (
-    <div className="bg-fm-neutral-0 flex flex-col space-y-6 rounded p-8">
-      <h2 className="text-fm-yellow-500 text-sm font-bold">
-        With ToolTip EXAMPLES
-      </h2>
-
-      <div className="flex space-x-4">
-        <IconButton
-          variant="background"
-          icon={<SearchIcon />}
-          label="Search"
-          onClick={() => alert("Search clicked")}
-          tooltip="Search Items"
-          tooltipContentProps={{
-            align: "center",
-            side: "bottom",
-          }}
-        />
-        <IconButton
-          variant="ghost"
-          icon={<CrossIcon />}
-          label="Close"
-          onClick={() => alert("Close clicked")}
-          tooltip="Cancel"
-          tooltipContentProps={{
-            align: "center",
-            side: "bottom",
-          }}
-        />
-        <IconButton
-          variant="outlined"
-          icon={<NotepadIcon />}
-          label="Add"
-          onClick={() => alert("Add clicked")}
-          tooltip="Notes"
-          tooltipContentProps={{
-            align: "center",
-            side: "bottom",
-          }}
-        />
-      </div>
-    </div>
-  ),
-}
+// ─── 4. States ────────────────────────────────────────────────────────────────
 
-export const Outlined: Story = {
-  args: {
-    label: "Search",
-    icon: <SearchIcon />,
-    variant: "outlined",
-  },
-  render: (args) => (
-    <div className="bg-fm-neutral-0 flex flex-col space-y-6 rounded p-8">
-      <h2 className="text-fm-yellow-500 text-sm font-bold">OUTLINED</h2>
-
-      <div className="flex flex-col space-y-4">
-        <div>
-          <h3 className="text-fm-primary mb-2">SMALL</h3>
-          <div className="flex space-x-4">
-            <IconButton {...args} size="small" label="Default" />
-            <IconButton {...args} size="small" disabled label="Disabled" />
+export const States: Story = {
+  render: () => (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Background — Enabled vs Disabled
+        </h4>
+        <div className="flex flex-wrap items-end gap-6">
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="background"
+              shape="circle"
+              icon={<SearchIcon />}
+              label="Search"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Circle enabled
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="background"
+              shape="circle"
+              icon={<SearchIcon />}
+              label="Search disabled"
+              disabled
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Circle disabled
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="background"
+              shape="square"
+              icon={<SearchIcon />}
+              label="Search"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Square enabled
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="background"
+              shape="square"
+              icon={<SearchIcon />}
+              label="Search disabled"
+              disabled
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Square disabled
+            </p>
           </div>
         </div>
+      </div>
 
-        <div>
-          <h3 className="text-fm-primary mb-2">MEDIUM</h3>
-          <div className="flex space-x-4">
-            <IconButton {...args} size="medium" label="Default" />
-            <IconButton {...args} size="medium" disabled label="Disabled" />
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Ghost — Enabled vs Disabled
+        </h4>
+        <div className="flex flex-wrap items-end gap-6">
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="ghost"
+              shape="circle"
+              icon={<HeartIcon />}
+              label="Like"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Circle enabled
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="ghost"
+              shape="circle"
+              icon={<HeartIcon />}
+              label="Like disabled"
+              disabled
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Circle disabled
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="ghost"
+              shape="square"
+              icon={<HeartIcon />}
+              label="Like"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Square enabled
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="ghost"
+              shape="square"
+              icon={<HeartIcon />}
+              label="Like disabled"
+              disabled
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Square disabled
+            </p>
           </div>
         </div>
+      </div>
 
-        <div>
-          <h3 className="text-fm-primary mb-2">LARGE</h3>
-          <div className="flex space-x-4">
-            <IconButton {...args} size="large" label="Default" />
-            <IconButton {...args} size="large" disabled label="Disabled" />
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Outlined — Enabled vs Disabled
+        </h4>
+        <div className="flex flex-wrap items-end gap-6">
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="outlined"
+              shape="circle"
+              icon={<ShareIcon />}
+              label="Share"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Circle enabled
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="outlined"
+              shape="circle"
+              icon={<ShareIcon />}
+              label="Share disabled"
+              disabled
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Circle disabled
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="outlined"
+              shape="square"
+              icon={<ShareIcon />}
+              label="Share"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Square enabled
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="outlined"
+              shape="square"
+              icon={<ShareIcon />}
+              label="Share disabled"
+              disabled
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Square disabled
+            </p>
           </div>
         </div>
       </div>
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Enabled and disabled states for each variant/shape combination. Disabled buttons apply reduced opacity to the icon and prevent interaction.",
+      },
+    },
+  },
 }
 
-export const DifferentIcons: Story = {
+// ─── 5. Use Cases ─────────────────────────────────────────────────────────────
+
+export const UseCases: Story = {
   render: () => (
-    <div className="bg-fm-neutral-0 flex flex-col space-y-6 rounded p-8">
-      <h2 className="text-fm-yellow-500 text-sm font-bold">ICON VARIATIONS</h2>
+    <div className="mx-auto max-w-3xl space-y-8 p-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Audio Player Controls
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary flex flex-wrap items-center justify-center gap-3 rounded-xl border p-6">
+          <IconButton
+            variant="ghost"
+            size="small"
+            shape="circle"
+            icon={<SkipBackwardIcon />}
+            label="Previous track"
+            tooltip="Previous"
+            tooltipContentProps={{ side: "top", sideOffset: 8 }}
+          />
+          <IconButton
+            variant="background"
+            size="large"
+            shape="circle"
+            icon={<CircularPlayIcon />}
+            label="Play"
+            tooltip="Play"
+            tooltipContentProps={{ side: "top", sideOffset: 8 }}
+          />
+          <IconButton
+            variant="ghost"
+            size="small"
+            shape="circle"
+            icon={<SkipForwardIcon />}
+            label="Next track"
+            tooltip="Next"
+            tooltipContentProps={{ side: "top", sideOffset: 8 }}
+          />
+          <IconButton
+            variant="ghost"
+            size="small"
+            shape="circle"
+            icon={<VolumeFullIcon />}
+            label="Volume"
+            tooltip="Volume"
+            tooltipContentProps={{ side: "top", sideOffset: 8 }}
+          />
+          <IconButton
+            variant="ghost"
+            size="small"
+            shape="circle"
+            icon={<HeartIcon />}
+            label="Add to favourites"
+            tooltip="Favourite"
+            tooltipContentProps={{ side: "top", sideOffset: 8 }}
+          />
+        </div>
+      </div>
 
-      <div className="flex space-x-4">
-        <IconButton variant="background" icon={<SearchIcon />} label="Search" />
-        <IconButton variant="background" icon={<CrossIcon />} label="Close" />
-        <IconButton
-          variant="background"
-          icon={<FeatureShineIcon />}
-          label="Add"
-        />
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Track List Row Actions
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md rounded-xl border">
+          {[
+            { title: "Midnight Dreams", artist: "Lunar Waves" },
+            { title: "Electric Sunrise", artist: "Neon Drift" },
+            { title: "Echoes in Rain", artist: "The Resonants" },
+          ].map(({ title, artist }) => (
+            <div
+              key={title}
+              className="border-fm-divider-secondary flex items-center justify-between border-b p-4 last:border-b-0"
+            >
+              <div className="space-y-0.5">
+                <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                  {title}
+                </p>
+                <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                  {artist}
+                </p>
+              </div>
+              <div className="flex items-center gap-1">
+                <IconButton
+                  variant="ghost"
+                  size="small"
+                  shape="circle"
+                  icon={<HeartIcon />}
+                  label={`Add ${title} to favourites`}
+                />
+                <IconButton
+                  variant="ghost"
+                  size="small"
+                  shape="circle"
+                  icon={<VerticalMenuIcon />}
+                  label={`More options for ${title}`}
+                />
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Panel Header Actions
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md rounded-xl border p-5">
+          <div className="mb-4 flex items-center justify-between">
+            <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+              Now Playing
+            </p>
+            <div className="flex items-center gap-1">
+              <IconButton
+                variant="ghost"
+                size="small"
+                shape="square"
+                icon={<ShareIcon />}
+                label="Share track"
+                tooltip="Share"
+                tooltipContentProps={{ side: "bottom", sideOffset: 8 }}
+              />
+              <IconButton
+                variant="ghost"
+                size="small"
+                shape="square"
+                icon={<SettingIcon />}
+                label="Open settings"
+                tooltip="Settings"
+                tooltipContentProps={{ side: "bottom", sideOffset: 8 }}
+              />
+              <IconButton
+                variant="outlined"
+                size="small"
+                shape="square"
+                icon={<CrossIcon />}
+                label="Close panel"
+                tooltip="Close"
+                tooltipContentProps={{ side: "bottom", sideOffset: 8 }}
+              />
+            </div>
+          </div>
+          <div className="border-fm-divider-secondary flex items-center gap-4 rounded-lg border p-4">
+            <div className="bg-fm-surface-secondary size-12 rounded-lg" />
+            <div className="space-y-0.5">
+              <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                Midnight Dreams
+              </p>
+              <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                Lunar Waves
+              </p>
+            </div>
+            <div className="ml-auto">
+              <IconButton
+                variant="background"
+                size="medium"
+                shape="circle"
+                icon={<PauseIcon />}
+                label="Pause"
+              />
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Library Management
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md rounded-xl border p-5">
+          <div className="flex flex-wrap items-center justify-between gap-3">
+            <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+              My Library
+            </p>
+            <div className="flex items-center gap-2">
+              <IconButton
+                variant="background"
+                size="small"
+                shape="square"
+                icon={<SearchIcon />}
+                label="Search library"
+                tooltip="Search"
+                tooltipContentProps={{ side: "top", sideOffset: 8 }}
+              />
+              <IconButton
+                variant="background"
+                size="small"
+                shape="square"
+                icon={<MusicalNoteIcon />}
+                label="Add track"
+                tooltip="Add track"
+                tooltipContentProps={{ side: "top", sideOffset: 8 }}
+              />
+              <IconButton
+                variant="ghost"
+                size="small"
+                shape="square"
+                icon={<TrashIcon />}
+                label="Delete selected"
+                tooltip="Delete"
+                tooltipContentProps={{ side: "top", sideOffset: 8 }}
+              />
+            </div>
+          </div>
+        </div>
       </div>
     </div>
   ),
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        story:
+          "Real-world audio app scenarios: player playback controls, track list row actions, panel header controls, and library management toolbar.",
+      },
+    },
+  },
 }
 
-export const Shapes: Story = {
-  render: () => (
-    <div className="bg-fm-neutral-0 flex flex-col space-y-6 rounded p-8">
-      <h2 className="text-fm-yellow-500 text-sm font-bold">SHAPES</h2>
+// ─── 6. Accessibility ─────────────────────────────────────────────────────────
 
-      <div className="flex flex-col space-y-4">
-        <div>
-          <h3 className="text-fm-primary mb-2">CIRCLE</h3>
-          <div className="flex space-x-4">
+export const Accessibility: Story = {
+  render: () => (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Required label prop (aria-label)
+        </h4>
+        <div className="flex flex-wrap items-end gap-6">
+          <div className="space-y-2 text-center">
             <IconButton
               variant="background"
               icon={<SearchIcon />}
-              label="Search"
-              shape="circle"
+              label="Search tracks"
             />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              label="Search tracks"
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="background"
+              icon={<HeartIcon />}
+              label="Add to favourites"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              label="Add to favourites"
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="background"
+              icon={<TrashIcon />}
+              label="Delete track"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              label="Delete track"
+            </p>
           </div>
         </div>
+      </div>
 
-        <div>
-          <h3 className="text-fm-primary mb-2">SQUARE</h3>
-          <div className="flex space-x-4">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Tooltip for visible context
+        </h4>
+        <div className="flex flex-wrap items-center gap-6 pb-8">
+          <div className="space-y-2 text-center">
             <IconButton
               variant="background"
-              icon={<SearchIcon />}
-              label="Search"
-              shape="square"
+              icon={<SettingIcon />}
+              label="Open settings"
+              tooltip="Settings"
+              tooltipContentProps={{ side: "bottom", sideOffset: 8 }}
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              With tooltip
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="outlined"
+              icon={<CrossIcon />}
+              label="Close panel"
+              tooltip="Close"
+              tooltipContentProps={{ side: "bottom", sideOffset: 8 }}
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              With tooltip
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <IconButton
+              variant="ghost"
+              icon={<VerticalMenuIcon />}
+              label="More options"
+              tooltip="More options"
+              tooltipContentProps={{ side: "bottom", sideOffset: 8 }}
             />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              With tooltip
+            </p>
           </div>
         </div>
       </div>
-    </div>
-  ),
-}
 
-export const Interactive: Story = {
-  render: () => (
-    <div className="bg-fm-neutral-0 flex flex-col space-y-6 rounded p-8">
-      <h2 className="text-fm-yellow-500 text-sm font-bold">
-        INTERACTIVE EXAMPLES
-      </h2>
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Player controls in context
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary flex flex-wrap items-center justify-center gap-3 rounded-xl border p-6">
+          <IconButton
+            variant="ghost"
+            size="small"
+            shape="circle"
+            icon={<SkipBackwardIcon />}
+            label="Skip backward"
+            tooltip="Previous track"
+            tooltipContentProps={{ side: "top", sideOffset: 8 }}
+          />
+          <IconButton
+            variant="background"
+            size="large"
+            shape="circle"
+            icon={<CircularPlayIcon />}
+            label="Play"
+            tooltip="Play"
+            tooltipContentProps={{ side: "top", sideOffset: 8 }}
+          />
+          <IconButton
+            variant="ghost"
+            size="small"
+            shape="circle"
+            icon={<SkipForwardIcon />}
+            label="Skip forward"
+            tooltip="Next track"
+            tooltipContentProps={{ side: "top", sideOffset: 8 }}
+          />
+          <IconButton
+            variant="ghost"
+            size="small"
+            shape="circle"
+            icon={<VolumeFullIcon />}
+            label="Volume"
+            tooltip="Volume"
+            tooltipContentProps={{ side: "top", sideOffset: 8 }}
+          />
+        </div>
+      </div>
 
-      <div className="flex space-x-4">
-        <IconButton
-          variant="background"
-          icon={<SearchIcon />}
-          label="Search"
-          onClick={() => alert("Search clicked")}
-        />
-        <IconButton
-          variant="ghost"
-          icon={<CrossIcon />}
-          label="Close"
-          onClick={() => alert("Close clicked")}
-        />
-        <IconButton
-          variant="outlined"
-          icon={<FeatureShineIcon />}
-          label="Add"
-          onClick={() => alert("Add clicked")}
-        />
+      <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+        <ul className="space-y-2">
+          <li>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Always provide a descriptive{" "}
+              <code className="text-fm-primary font-fm-text text-fm-sm">
+                label
+              </code>{" "}
+              prop — it populates both{" "}
+              <code className="text-fm-primary font-fm-text text-fm-sm">
+                aria-label
+              </code>{" "}
+              and the inner AccessibleIcon, ensuring screen readers announce the
+              button's purpose.
+            </p>
+          </li>
+          <li>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Use the{" "}
+              <code className="text-fm-primary font-fm-text text-fm-sm">
+                tooltip
+              </code>{" "}
+              prop to surface a visible label on hover — useful when icon
+              meaning is not immediately obvious to sighted users.
+            </p>
+          </li>
+          <li>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Keyboard focus is handled via the native{" "}
+              <code className="text-fm-primary font-fm-text text-fm-sm">
+                button
+              </code>{" "}
+              element and visible ring tokens — no custom focus management
+              required.
+            </p>
+          </li>
+          <li>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Prefer descriptive labels over generic ones: use "Delete track"
+              not "Delete", "Add to favourites" not "Heart", so announcements
+              are unambiguous out of context.
+            </p>
+          </li>
+          <li>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              The{" "}
+              <code className="text-fm-primary font-fm-text text-fm-sm">
+                disabled
+              </code>{" "}
+              prop sets the native{" "}
+              <code className="text-fm-primary font-fm-text text-fm-sm">
+                disabled
+              </code>{" "}
+              attribute — the button is removed from the tab order
+              automatically.
+            </p>
+          </li>
+        </ul>
       </div>
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Accessibility-focused examples covering the required label prop (aria-label), tooltip for visible context, and a realistic player controls composition. Best practices are listed in the info box.",
+      },
+    },
+  },
 }