aural-ui 4.0.1 → 4.2.0

package/dist/components/divider/Divider.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 { Divider } from "."
 
 const meta: Meta<typeof Divider> = {
@@ -8,93 +10,29 @@ const meta: Meta<typeof Divider> = {
   component: Divider,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-A versatile divider component built on Radix UI Divider with dark theme optimization and multiple visual styles.
-
-## Overview
-
-The Divider component provides clear visual separation between content sections, improving layout organization and readability. It supports multiple variants including solid, stylized, and dashed styles with flexible sizing and orientation options.
-
-## Features
-- **Multiple Variants**: Primary, secondary, stylised, and dashed styles
-- **Flexible Sizing**: Four size options from thin to large
-- **Dual Orientation**: Horizontal and vertical layouts
-- **Dark Theme Optimized**: Designed for dark interfaces
-- **Accessibility Ready**: Built on Radix UI Divider primitive
-- **Stylised Option**: Includes decorative audio bar icon
-- **Dashed Style**: Perfect for subtle separations and grouped content
-
-## Design Tokens
-- Uses \`--fm-divider-primary\`, \`--fm-divider-secondary\`, \`--fm-divider-tertiary\` color tokens
-- Responsive sizing with consistent visual hierarchy
-- Semantic color mapping for different use cases
-
-## Usage
-
-### Basic Divider
-\`\`\`tsx
-import { Divider } from '@/ui/components/divider'
-
-export default function Example() {
-  return (
-    <div className="space-y-4">
-      <p>Content above</p>
-      <Divider />
-      <p>Content below</p>
-    </div>
-  )
-}
-\`\`\`
-
-### Dashed Divider
-\`\`\`tsx
-export default function DashedExample() {
-  return (
-    <div className="space-y-4">
-      <h3>Section Title</h3>
-      <Divider variant="dashed" />
-      <p>Section content with subtle separation</p>
-    </div>
-  )
-}
-\`\`\`
-
-### Vertical Divider
-\`\`\`tsx
-export default function VerticalExample() {
-  return (
-    <div className="flex items-center gap-4">
-      <span>Item 1</span>
-      <Divider orientation="vertical" className="h-6" />
-      <span>Item 2</span>
-    </div>
-  )
-}
-\`\`\`
-
-### Stylised Divider
-\`\`\`tsx
-export default function StylisedExample() {
-  return (
-    <div className="space-y-6">
-      <section>Main content section</section>
-      <Divider variant="stylised" />
-      <section>Next content section</section>
-    </div>
-  )
-}
-\`\`\`
-        `,
+        component:
+          "A versatile divider built on Radix UI Separator with four visual variants (primary, secondary, stylised, dashed), four size steps, and horizontal/vertical orientation. The stylised variant renders a decorative audio-bar icon, making it ideal for section breaks in audio streaming interfaces.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "4 Visual Variants",
+              description: "Primary to stylised",
+            },
+            {
+              title: "Orientations",
+              description: "Horizontal or vertical",
+            },
+            {
+              title: "Size Steps",
+              description: "Hairline to bold",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -102,7 +40,7 @@ export default function StylisedExample() {
     variant: {
       control: "select",
       options: ["primary", "secondary", "stylised", "dashed"],
-      description: "The visual style of the divider",
+      description: "Visual style of the divider.",
       table: {
         type: { summary: "string" },
         defaultValue: { summary: "primary" },
@@ -111,7 +49,7 @@ export default function StylisedExample() {
     size: {
       control: "select",
       options: ["half_default", "full_default", "full_medium", "full_large"],
-      description: "The size/thickness of the divider",
+      description: "Thickness / extent of the divider line.",
       table: {
         type: { summary: "string" },
         defaultValue: { summary: "full_default" },
@@ -120,7 +58,7 @@ export default function StylisedExample() {
     orientation: {
       control: "select",
       options: ["horizontal", "vertical"],
-      description: "The orientation of the divider",
+      description: "Direction of the divider.",
       table: {
         type: { summary: "string" },
         defaultValue: { summary: "horizontal" },
@@ -129,7 +67,7 @@ export default function StylisedExample() {
     decorative: {
       control: "boolean",
       description:
-        "Whether the Divider is decorative (hidden from screen readers)",
+        "When true the element is hidden from the accessibility tree.",
       table: {
         type: { summary: "boolean" },
         defaultValue: { summary: "true" },
@@ -137,18 +75,12 @@ export default function StylisedExample() {
     },
     className: {
       control: "text",
-      description: "Additional CSS classes for custom styling",
-      table: {
-        type: { summary: "string" },
-      },
+      description: "Extra classes applied to the separator element.",
     },
     wrapperClassName: {
       control: "text",
       description:
-        "CSS classes for the wrapper element (used with stylised variant)",
-      table: {
-        type: { summary: "string" },
-      },
+        "Extra classes applied to the outer wrapper (used by the stylised variant to position the audio-bar icon).",
     },
   },
 }
@@ -156,477 +88,299 @@ export default function StylisedExample() {
 export default meta
 type Story = StoryObj<typeof Divider>
 
-export const Primary: Story = {
-  args: {
-    variant: "primary",
-    size: "full_default",
-    className: "my-4 min-w-96",
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "The default primary divider with medium opacity, perfect for standard content separation.",
-      },
-    },
-  },
-}
+// ─── 1. AllVariants ──────────────────────────────────────────────────────────
 
-export const Secondary: Story = {
-  args: {
-    variant: "secondary",
-    size: "full_default",
-    className: "my-4 min-w-96",
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "A lighter secondary divider for subtle separations within grouped content.",
+export const AllVariants: Story = {
+  render: () => {
+    const variants = [
+      {
+        key: "primary",
+        label: "Primary",
+        desc: "Standard line for main content separation",
       },
-    },
-  },
-}
-
-export const Dashed: Story = {
-  args: {
-    variant: "dashed",
-    size: "full_default",
-    className: "my-4 min-w-96",
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "A dashed divider style perfect for indicating temporary or conditional separations.",
+      {
+        key: "secondary",
+        label: "Secondary",
+        desc: "Subtler line for related-content groups",
       },
-    },
-  },
-}
-
-export const Stylised: Story = {
-  args: {
-    variant: "stylised",
-    size: "full_default",
-    className: "my-4 min-w-96",
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "A decorative divider with an audio bar icon, ideal for section breaks in audio/media interfaces.",
-      },
-    },
-  },
-}
-
-export const SizeVariations: Story = {
-  render: () => (
-    <div className="bg-fm-surface-primary w-full max-w-2xl space-y-8 rounded-lg p-6">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 text-lg font-medium">
-          Size Variations
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Different thickness options for various use cases
-        </p>
-      </div>
-
-      <div className="space-y-6">
-        {(
-          [
-            {
-              size: "half_default",
-              label: "Half Default",
-              description: "50% width, minimal thickness",
-            },
-            {
-              size: "full_default",
-              label: "Full Default",
-              description: "Standard thickness for most use cases",
-            },
-            {
-              size: "full_medium",
-              label: "Full Medium",
-              description: "Medium thickness for emphasis",
-            },
-            {
-              size: "full_large",
-              label: "Full Large",
-              description: "Bold thickness for strong separation",
-            },
-          ] as const
-        ).map((item) => (
-          <div key={item.size} className="space-y-3">
-            <div className="flex items-center justify-between">
-              <h4 className="text-fm-primary text-sm font-medium">
-                {item.label}
-              </h4>
-              <span className="text-fm-tertiary text-xs">
-                {item.description}
-              </span>
-            </div>
-            <Divider variant="primary" size={item.size} />
-          </div>
-        ))}
-      </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Comparison of all available size options for dividers, from subtle to prominent separations.",
+      {
+        key: "stylised",
+        label: "Stylised",
+        desc: "Decorative audio-bar accent for section breaks",
       },
-    },
-  },
-}
-
-export const VariantComparison: Story = {
-  render: () => (
-    <div className="bg-fm-surface-primary w-full max-w-2xl space-y-8 rounded-lg p-6">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 text-lg font-medium">
-          Variant Comparison
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Different visual styles for various design needs
-        </p>
-      </div>
-
-      <div className="space-y-8">
-        {(
-          [
-            {
-              variant: "primary",
-              label: "Primary",
-              description: "Standard divider for main content separation",
-              useCase: "Main sections, page content",
-            },
-            {
-              variant: "secondary",
-              label: "Secondary",
-              description: "Subtle divider for related content groups",
-              useCase: "Subsections, related items",
-            },
-            {
-              variant: "dashed",
-              label: "Dashed",
-              description:
-                "Dotted line for temporary or conditional separations",
-              useCase: "Grouped items, optional content",
-            },
-            {
-              variant: "stylised",
-              label: "Stylised",
-              description: "Decorative divider with audio bar icon",
-              useCase: "Section breaks, audio interfaces",
-            },
-          ] as const
-        ).map((item) => (
-          <div key={item.variant} className="space-y-3">
-            <div className="space-y-1">
-              <h4 className="text-fm-primary text-sm font-medium">
-                {item.label}
-              </h4>
-              <p className="text-fm-secondary text-xs">{item.description}</p>
-              <p className="text-fm-tertiary text-xs">
-                Use case: {item.useCase}
-              </p>
-            </div>
-            <Divider variant={item.variant} size="full_default" />
-          </div>
-        ))}
-      </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Side-by-side comparison of all divider variants with their recommended use cases.",
+      {
+        key: "dashed",
+        label: "Dashed",
+        desc: "Soft dashed line for optional or conditional breaks",
       },
-    },
-  },
-}
+    ] as const
 
-export const DashedVariations: Story = {
-  render: () => (
-    <div className="bg-fm-surface-primary w-full max-w-2xl space-y-8 rounded-lg p-6">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 text-lg font-medium">
-          Dashed Divider Variations
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Different sizes and orientations of dashed dividers
-        </p>
-      </div>
-
-      <div className="space-y-6">
+    return (
+      <div className="space-y-8" style={{ width: 560 }}>
+        {/* Horizontal */}
         <div>
-          <h4 className="text-fm-primary mb-4 text-sm font-medium">
-            Horizontal Dashed
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+            Horizontal
           </h4>
-          <div className="space-y-4">
-            {(
-              [
-                { size: "half_default", label: "Half Width" },
-                { size: "full_default", label: "Full Width" },
-                { size: "full_medium", label: "Medium Thickness" },
-                { size: "full_large", label: "Large Thickness" },
-              ] as const
-            ).map((item) => (
-              <div key={item.size} className="space-y-2">
-                <span className="text-fm-secondary text-xs">{item.label}</span>
-                <Divider variant="dashed" size={item.size} />
+          <div className="space-y-6">
+            {variants.map(({ key, label, desc }) => (
+              <div key={key} className="space-y-2 text-center">
+                <Divider
+                  variant={key}
+                  size="full_default"
+                  orientation="horizontal"
+                />
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  {label} — {desc}
+                </p>
               </div>
             ))}
           </div>
         </div>
 
+        {/* Vertical */}
         <div>
-          <h4 className="text-fm-primary mb-4 text-sm font-medium">
-            Vertical Dashed
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+            Vertical
           </h4>
-          <div className="flex h-16 items-center gap-6">
-            {(
-              [
-                { size: "half_default", label: "Half" },
-                { size: "full_default", label: "Full" },
-                { size: "full_medium", label: "Medium" },
-                { size: "full_large", label: "Large" },
-              ] as const
-            ).map((item) => (
-              <div key={item.size} className="flex flex-col items-center gap-2">
-                <span className="text-fm-secondary text-xs">{item.label}</span>
-                <Divider
-                  variant="dashed"
-                  size={item.size}
-                  orientation="vertical"
-                  className="h-12"
-                />
+          <div className="flex flex-wrap items-center justify-center gap-10">
+            {variants.map(({ key, label }) => (
+              <div key={key} className="space-y-2 text-center">
+                <div className="flex h-16 items-center justify-center">
+                  <Divider
+                    variant={key}
+                    size="full_default"
+                    orientation="vertical"
+                    className="h-12"
+                  />
+                </div>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  {label}
+                </p>
               </div>
             ))}
           </div>
         </div>
       </div>
-    </div>
-  ),
+    )
+  },
   parameters: {
     docs: {
       description: {
         story:
-          "Comprehensive showcase of dashed divider options in both horizontal and vertical orientations.",
+          "Full matrix of all four variants in both horizontal and vertical orientations, each with a short label describing its intended use.",
       },
     },
   },
 }
 
-export const OrientationExample: Story = {
-  render: () => (
-    <div className="bg-fm-surface-primary w-full max-w-2xl space-y-8 rounded-lg p-6">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 text-lg font-medium">
-          Orientation Examples
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Horizontal and vertical divider usage in layouts
-        </p>
-      </div>
+// ─── 2. Sizes ────────────────────────────────────────────────────────────────
 
-      <div className="space-y-8">
-        {/* Horizontal Example */}
-        <div className="space-y-4">
-          <h4 className="text-fm-primary text-sm font-medium">
-            Horizontal Dividers
+export const Sizes: Story = {
+  render: () => {
+    const sizes = [
+      {
+        key: "half_default",
+        label: "Half Default",
+        sub: "50% width · hairline",
+      },
+      {
+        key: "full_default",
+        label: "Full Default",
+        sub: "100% width · hairline",
+      },
+      {
+        key: "full_medium",
+        label: "Full Medium",
+        sub: "100% width · 4 px",
+      },
+      {
+        key: "full_large",
+        label: "Full Large",
+        sub: "100% width · 8 px",
+      },
+    ] as const
+
+    return (
+      <div className="space-y-8" style={{ width: 520 }}>
+        {/* Horizontal sizes */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+            Horizontal — primary variant
           </h4>
-          <div className="bg-fm-surface-secondary space-y-4 rounded-lg p-4">
-            <div className="text-fm-tertiary text-sm">
-              Section A: User Profile
-            </div>
-            <Divider variant="primary" />
-            <div className="text-fm-tertiary text-sm">
-              Section B: Account Settings
-            </div>
-            <Divider variant="dashed" />
-            <div className="text-fm-tertiary text-sm">
-              Section C: Privacy Options
-            </div>
+          <div className="space-y-6">
+            {sizes.map(({ key, label, sub }) => (
+              <div key={key} className="space-y-2 text-center">
+                <Divider
+                  variant="primary"
+                  size={key}
+                  orientation="horizontal"
+                />
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  {label}
+                  <span className="text-fm-tertiary"> — {sub}</span>
+                </p>
+              </div>
+            ))}
           </div>
         </div>
 
-        {/* Vertical Example */}
-        <div className="space-y-4">
-          <h4 className="text-fm-primary text-sm font-medium">
-            Vertical Dividers
+        {/* Vertical sizes */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+            Vertical — primary variant
           </h4>
-          <div className="bg-fm-surface-secondary flex items-center gap-6 rounded-lg p-4">
-            <div className="text-fm-tertiary text-sm">Profile</div>
-            <Divider variant="primary" orientation="vertical" className="h-8" />
-            <div className="text-fm-tertiary text-sm">Settings</div>
-            <Divider variant="dashed" orientation="vertical" className="h-8" />
-            <div className="text-fm-tertiary text-sm">Help</div>
-            <Divider
-              variant="secondary"
-              orientation="vertical"
-              className="h-8"
-            />
-            <div className="text-fm-tertiary text-sm">Logout</div>
+          <div className="flex flex-wrap items-end justify-center gap-8">
+            {sizes.map(({ key, label }) => (
+              <div key={key} className="space-y-2 text-center">
+                <div className="flex h-20 items-center justify-center">
+                  <Divider
+                    variant="primary"
+                    size={key}
+                    orientation="vertical"
+                    className="h-full"
+                  />
+                </div>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  {label}
+                </p>
+              </div>
+            ))}
           </div>
         </div>
       </div>
-    </div>
-  ),
+    )
+  },
   parameters: {
     docs: {
       description: {
         story:
-          "Real-world examples showing how to use dividers in both horizontal and vertical layouts.",
+          "Side-by-side size comparison for both orientations, from the hairline default to the bold large variant.",
       },
     },
   },
 }
 
-export const RealWorldUsage: Story = {
-  render: () => (
-    <div className="bg-fm-surface-primary w-full max-w-4xl space-y-8 rounded-lg p-6">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 text-lg font-medium">
-          Real World Usage
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Practical examples in common UI patterns
-        </p>
-      </div>
+// ─── 3. UseCases ─────────────────────────────────────────────────────────────
 
-      <div className="grid grid-cols-1 gap-8 md:grid-cols-2">
-        {/* Card Layout */}
-        <div className="space-y-4">
-          <h4 className="text-fm-primary text-sm font-medium">Card Layout</h4>
-          <div className="bg-fm-surface-secondary space-y-4 rounded-lg p-4">
-            <div className="flex items-center gap-3">
-              <div className="h-10 w-10 rounded-full bg-blue-600"></div>
-              <div>
-                <div className="text-fm-primary text-sm font-medium">
-                  John Doe
-                </div>
-                <div className="text-fm-secondary text-xs">
-                  Product Designer
-                </div>
-              </div>
-            </div>
-            <Divider variant="dashed" />
-            <div className="text-fm-tertiary text-sm">
-              Passionate about creating intuitive user experiences and
-              innovative design solutions.
-            </div>
-            <Divider variant="secondary" />
-            <div className="text-fm-secondary flex gap-4 text-xs">
-              <span>Joined: Jan 2024</span>
-              <span>Projects: 12</span>
+export const UseCases: Story = {
+  render: () => (
+    <div className="mx-auto max-w-3xl space-y-8 p-8">
+      {/* Podcast episode card */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          Podcast episode card
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md space-y-4 rounded-xl border p-5">
+          <div className="flex items-center gap-3">
+            <div className="bg-fm-surface-tertiary h-12 w-12 shrink-0 rounded-lg" />
+            <div>
+              <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+                The Sound Lab · Ep. 42
+              </p>
+              <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                45 min · Anya Reeves
+              </p>
             </div>
           </div>
+          <Divider variant="secondary" size="full_default" />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Mixing live orchestral recordings, spatial audio formats, and the
+            future of independent streaming.
+          </p>
+          <Divider variant="dashed" size="full_default" />
+          <div className="flex items-center justify-between">
+            <span className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              2.4k plays
+            </span>
+            <span className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              ★ 4.9
+            </span>
+          </div>
         </div>
+      </div>
 
-        {/* Navigation Layout */}
-        <div className="space-y-4">
-          <h4 className="text-fm-primary text-sm font-medium">
-            Navigation Menu
-          </h4>
-          <div className="bg-fm-surface-secondary space-y-3 rounded-lg p-4">
-            <div className="text-fm-primary cursor-pointer text-sm hover:text-blue-400">
-              Dashboard
-            </div>
-            <Divider variant="secondary" />
-            <div className="text-fm-primary cursor-pointer text-sm hover:text-blue-400">
-              Projects
-            </div>
-            <Divider variant="secondary" />
-            <div className="text-fm-primary cursor-pointer text-sm hover:text-blue-400">
-              Team
-            </div>
-            <Divider variant="dashed" />
-            <div className="text-fm-primary cursor-pointer text-sm hover:text-blue-400">
-              Settings
-            </div>
-            <Divider variant="primary" />
-            <div className="cursor-pointer text-sm text-red-400 hover:text-red-300">
-              Logout
-            </div>
+      {/* Section break with stylised divider */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          Section break — stylised
+        </h4>
+        <div className="mx-auto max-w-md space-y-4">
+          <div className="space-y-2">
+            <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+              Featured Releases
+            </p>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              New albums curated by Aural editors this week.
+            </p>
+          </div>
+          <Divider variant="stylised" size="full_default" />
+          <div className="space-y-2">
+            <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+              Trending Now
+            </p>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Tracks climbing the charts across all genres.
+            </p>
           </div>
         </div>
+      </div>
 
-        {/* Timeline Layout */}
-        <div className="space-y-4">
-          <h4 className="text-fm-primary text-sm font-medium">
-            Content Timeline
-          </h4>
-          <div className="bg-fm-surface-secondary space-y-4 rounded-lg p-4">
-            <div className="space-y-2">
-              <div className="text-fm-primary text-sm font-medium">
-                Project Started
-              </div>
-              <div className="text-fm-secondary text-xs">
-                Initial setup and planning phase
-              </div>
-            </div>
-            <Divider variant="stylised" />
-            <div className="space-y-2">
-              <div className="text-fm-primary text-sm font-medium">
-                Development Phase
-              </div>
-              <div className="text-fm-secondary text-xs">
-                Core features implementation
-              </div>
-            </div>
-            <Divider variant="dashed" />
-            <div className="space-y-2">
-              <div className="text-fm-primary text-sm font-medium">
-                Testing & QA
-              </div>
-              <div className="text-fm-secondary text-xs">
-                Quality assurance and bug fixes
-              </div>
-            </div>
+      {/* Inline toolbar with vertical dividers */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          Player toolbar — vertical dividers
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md rounded-xl border px-5 py-3">
+          <div className="flex items-center gap-4">
+            <button className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm hover:text-fm-primary cursor-pointer outline-none">
+              Queue
+            </button>
+            <Divider
+              variant="secondary"
+              orientation="vertical"
+              className="h-5"
+            />
+            <button className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm hover:text-fm-primary cursor-pointer outline-none">
+              Lyrics
+            </button>
+            <Divider variant="dashed" orientation="vertical" className="h-5" />
+            <button className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm hover:text-fm-primary cursor-pointer outline-none">
+              Related
+            </button>
+            <Divider variant="primary" orientation="vertical" className="h-5" />
+            <button className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm hover:text-fm-primary cursor-pointer outline-none">
+              Share
+            </button>
           </div>
         </div>
+      </div>
 
-        {/* Toolbar Layout */}
-        <div className="space-y-4">
-          <h4 className="text-fm-primary text-sm font-medium">
-            Toolbar Actions
-          </h4>
-          <div className="bg-fm-surface-secondary rounded-lg p-4">
-            <div className="flex items-center gap-4">
-              <button className="text-fm-tertiary hover:text-fm-primary text-sm">
-                Edit
-              </button>
-              <Divider
-                variant="secondary"
-                orientation="vertical"
-                className="h-6"
-              />
-              <button className="text-fm-tertiary hover:text-fm-primary text-sm">
-                Share
-              </button>
-              <Divider
-                variant="dashed"
-                orientation="vertical"
-                className="h-6"
-              />
-              <button className="text-fm-tertiary hover:text-fm-primary text-sm">
-                Export
-              </button>
-              <Divider
-                variant="primary"
-                orientation="vertical"
-                className="h-6"
-              />
-              <button className="text-sm text-red-400 hover:text-red-300">
-                Delete
-              </button>
-            </div>
-          </div>
+      {/* Artist profile settings panel */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          Settings panel — grouped sections
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md space-y-3 rounded-xl border p-5">
+          <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+            Account
+          </p>
+          <Divider variant="primary" size="full_default" />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Profile · Subscription · Billing
+          </p>
+          <Divider variant="secondary" size="full_default" />
+          <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+            Playback
+          </p>
+          <Divider variant="primary" size="full_default" />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Audio quality · Downloads · Crossfade
+          </p>
+          <Divider variant="dashed" size="full_default" />
+          <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+            Advanced settings
+          </p>
         </div>
       </div>
     </div>
@@ -635,24 +389,7 @@ export const RealWorldUsage: Story = {
     docs: {
       description: {
         story:
-          "Real-world UI patterns showing effective use of different divider variants in common interface layouts.",
-      },
-    },
-  },
-}
-
-export const InteractivePlayground: Story = {
-  args: {
-    variant: "primary",
-    size: "full_default",
-    orientation: "horizontal",
-    className: "my-4 min-w-96",
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Interactive playground to experiment with all divider properties and see live changes.",
+          "Real-world scenarios from an audio streaming context: episode cards, stylised section breaks, inline player toolbars with vertical dividers, and a settings panel with grouped sections.",
       },
     },
   },