aural-ui 4.0.1 → 4.1.0

package/dist/components/button/Button.stories.tsx

@@ -1,23 +1,56 @@
 import React from "react"
+import {
+  CircularPlayIcon,
+  HeartIcon,
+  SettingIcon,
+  SkipBackwardIcon,
+  SkipForwardIcon,
+  StarIcon,
+} from "@icons/index"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import { Button } from "."
-import { Tabs, TabsContent, TabsList, TabsTrigger } from "../tabs"
 
 const meta: Meta<typeof Button> = {
   title: "Components/UI/Button",
   component: Button,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
+    docs: {
+      description: {
+        component:
+          "A versatile button component with six visual variants (primary, secondary, outline, text, chip, chipActive), three sizes, optional noise texture, icon slots, and tooltip support. Built with CVA for composable, type-safe variant management.",
+      },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "6 Visual Variants",
+              description: "From primary to chip",
+            },
+            {
+              title: "Noise Texture",
+              description: "4 levels of grain",
+            },
+            {
+              title: "Icon Slots & Tooltip",
+              description: "Left, right, tooltip",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
+  args: {
+    variant: "primary",
+    size: "md",
+    noise: "medium",
+    isDisabled: false,
+    children: "Click me",
+  },
   argTypes: {
     variant: {
       control: { type: "select" },
@@ -53,262 +86,584 @@ const meta: Meta<typeof Button> = {
 export default meta
 type Story = StoryObj<typeof Button>
 
-export const Primary: Story = {
+// ─── 1. Playground ────────────────────────────────────────────────────────────
+
+export const Playground: Story = {
   args: {
     variant: "primary",
-    children: "Primary Button",
     size: "md",
     noise: "medium",
+    isDisabled: false,
+    children: "Click me",
   },
-}
-
-export const Secondary: Story = {
-  args: {
-    variant: "secondary",
-    children: "Secondary Button",
-    size: "md",
-    noise: "low",
+  render: (args) => (
+    <div className="flex w-full max-w-sm flex-col items-center space-y-4">
+      <Button {...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)">{`<Button variant="${args.variant}" size="${args.size}" noise="${args.noise}"${args.isDisabled ? " isDisabled" : ""}>${args.children}</Button>`}</code>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Use the controls panel in the sidebar to explore all Button props. The code snippet below the button updates live to reflect the current configuration.",
+      },
+    },
   },
 }
 
-export const Outline: Story = {
-  args: {
-    variant: "outline",
-    children: "Outline Button",
-    size: "md",
-    noise: "none",
-  },
-}
+// ─── 2. All Variants ──────────────────────────────────────────────────────────
 
-export const Text: Story = {
-  args: {
-    variant: "text",
-    children: "Text Button",
-    size: "md",
-    noise: "none",
-  },
-}
+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">
+          Variants
+        </h4>
+        <div className="flex flex-wrap items-end gap-4">
+          <div className="space-y-2 text-center">
+            <Button variant="primary" noise="medium">
+              Primary
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Primary
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="secondary">Secondary</Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Secondary
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="outline" noise="none">
+              Outline
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Outline
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="text" noise="none">
+              Text
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Text
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="chip" noise="none">
+              Chip
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Chip
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="chipActive" noise="medium">
+              Chip Active
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Chip Active
+            </p>
+          </div>
+        </div>
+      </div>
 
-export const Disabled: Story = {
-  args: {
-    children: "Disabled Button",
-    isDisabled: true,
-    variant: "primary",
-  },
-}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Sizes
+        </h4>
+        <div className="flex flex-wrap items-end gap-4">
+          <div className="space-y-2 text-center">
+            <Button variant="primary" size="sm" noise="medium">
+              Small
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Small (sm)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="primary" size="md" noise="medium">
+              Medium
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Medium (md)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="primary" size="lg" noise="medium">
+              Large
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Large (lg)
+            </p>
+          </div>
+        </div>
+      </div>
 
-export const NoiseVariations: Story = {
-  render: () => (
-    <div className="flex flex-col gap-6 rounded p-8">
-      <div className="flex gap-4">
-        <Button noise="none">No Noise</Button>
-        <Button noise="low">Low Noise</Button>
-        <Button noise="medium">Medium Noise</Button>
-        <Button noise="strong">Strong Noise</Button>
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Noise Levels (Primary)
+        </h4>
+        <div className="flex flex-wrap items-end gap-4">
+          <div className="space-y-2 text-center">
+            <Button variant="primary" noise="none">
+              None
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              None
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="primary" noise="low">
+              Low
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Low
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="primary" noise="medium">
+              Medium
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Medium
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="primary" noise="strong">
+              Strong
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Strong
+            </p>
+          </div>
+        </div>
       </div>
-      <div className="flex gap-4">
-        <Button variant="secondary" noise="none">
-          No Noise
-        </Button>
-        <Button variant="secondary" noise="low">
-          Low Noise
-        </Button>
-        <Button variant="secondary" noise="medium">
-          Medium Noise
-        </Button>
-        <Button variant="secondary" noise="strong">
-          Strong Noise
-        </Button>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Noise Levels (Secondary)
+        </h4>
+        <div className="flex flex-wrap items-end gap-4">
+          <div className="space-y-2 text-center">
+            <Button variant="secondary" noise="none">
+              None
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              None
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="secondary" noise="low">
+              Low
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Low
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="secondary" noise="medium">
+              Medium
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Medium
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="secondary" noise="strong">
+              Strong
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Strong
+            </p>
+          </div>
+        </div>
       </div>
-    </div>
-  ),
-}
 
-export const ChipVariants: Story = {
-  render: () => (
-    <div className="w-full max-w-4xl rounded p-8">
-      <Tabs defaultValue="chip" className="w-full">
-        <TabsList className="grid w-full grid-cols-2">
-          <TabsTrigger value="chip">Chip</TabsTrigger>
-          <TabsTrigger value="chipActive">Chip Active</TabsTrigger>
-        </TabsList>
-        <TabsContent value="chip" className="mt-6">
-          <div className="flex flex-col gap-6">
-            <div className="flex flex-col gap-4">
-              <h3 className="text-fm-primary text-lg font-semibold">
-                Noise Variations
-              </h3>
-              <div className="flex gap-4">
-                <Button variant="chip" noise="none">
-                  No Noise
-                </Button>
-                <Button variant="chip" noise="low">
-                  Low Noise
-                </Button>
-                <Button variant="chip" noise="medium">
-                  Medium Noise
-                </Button>
-                <Button variant="chip" noise="strong">
-                  Strong Noise
-                </Button>
-              </div>
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Chip — Noise Levels
+        </h4>
+        <div className="flex flex-wrap items-end gap-4">
+          {(["none", "low", "medium", "strong"] as const).map((noise) => (
+            <div key={noise} className="space-y-2 text-center">
+              <Button variant="chip" noise={noise}>
+                {noise.charAt(0).toUpperCase() + noise.slice(1)}
+              </Button>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm capitalize">
+                {noise}
+              </p>
             </div>
-            <div className="flex flex-col gap-4">
-              <h3 className="text-fm-primary text-lg font-semibold">
-                Size Variations
-              </h3>
-              <div className="flex gap-4">
-                <Button variant="chip" size="sm" noise="medium">
-                  Small
-                </Button>
-                <Button variant="chip" size="md" noise="medium">
-                  Medium
-                </Button>
-                <Button variant="chip" size="lg" noise="medium">
-                  Large
-                </Button>
-              </div>
-            </div>
-            <div className="flex flex-col gap-4">
-              <h3 className="text-fm-primary text-lg font-semibold">
-                Disabled State
-              </h3>
-              <div className="flex gap-4">
-                <Button variant="chip" isDisabled>
-                  Disabled Chip
-                </Button>
-              </div>
-            </div>
-          </div>
-        </TabsContent>
-        <TabsContent value="chipActive" className="mt-6">
-          <div className="flex flex-col gap-6">
-            <div className="flex flex-col gap-4">
-              <h3 className="text-fm-primary text-lg font-semibold">
-                Noise Variations
-              </h3>
-              <div className="flex gap-4">
-                <Button variant="chipActive" noise="none">
-                  No Noise
-                </Button>
-                <Button variant="chipActive" noise="low">
-                  Low Noise
-                </Button>
-                <Button variant="chipActive" noise="medium">
-                  Medium Noise
-                </Button>
-                <Button variant="chipActive" noise="strong">
-                  Strong Noise
-                </Button>
-              </div>
+          ))}
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Chip Active — Noise Levels
+        </h4>
+        <div className="flex flex-wrap items-end gap-4">
+          {(["none", "low", "medium", "strong"] as const).map((noise) => (
+            <div key={noise} className="space-y-2 text-center">
+              <Button variant="chipActive" noise={noise}>
+                {noise.charAt(0).toUpperCase() + noise.slice(1)}
+              </Button>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm capitalize">
+                {noise}
+              </p>
             </div>
-            <div className="flex flex-col gap-4">
-              <h3 className="text-fm-primary text-lg font-semibold">
-                Size Variations
-              </h3>
-              <div className="flex gap-4">
-                <Button variant="chipActive" size="sm" noise="medium">
-                  Small
-                </Button>
-                <Button variant="chipActive" size="md" noise="medium">
-                  Medium
-                </Button>
-                <Button variant="chipActive" size="lg" noise="medium">
-                  Large
+          ))}
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Chip vs Chip Active — Sizes
+        </h4>
+        <div className="flex flex-wrap items-end gap-6">
+          {(["sm", "md", "lg"] as const).map((size) => (
+            <div key={size} className="space-y-3">
+              <div className="space-y-2 text-center">
+                <Button variant="chip" size={size} noise="medium">
+                  Chip
                 </Button>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  chip · {size}
+                </p>
               </div>
-            </div>
-            <div className="flex flex-col gap-4">
-              <h3 className="text-fm-primary text-lg font-semibold">
-                Disabled State
-              </h3>
-              <div className="flex gap-4">
-                <Button variant="chipActive" isDisabled>
-                  Disabled Chip Active
+              <div className="space-y-2 text-center">
+                <Button variant="chipActive" size={size} noise="medium">
+                  Chip Active
                 </Button>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  chipActive · {size}
+                </p>
               </div>
             </div>
-          </div>
-        </TabsContent>
-      </Tabs>
+          ))}
+        </div>
+      </div>
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "All six variants, three sizes, all four noise levels on primary and secondary, and a full chip/chipActive noise and size breakdown.",
+      },
+    },
+  },
 }
 
-export const AllVariants: Story = {
+// ─── 3. States ────────────────────────────────────────────────────────────────
+
+export const States: Story = {
   render: () => (
-    <div className="flex flex-col gap-6 rounded p-8">
-      <div className="flex gap-4">
-        <Button variant="primary" noise="medium">
-          Primary
-        </Button>
-        <Button variant="secondary">Secondary</Button>
-        <Button variant="outline" noise="none">
-          Outline
-        </Button>
-        <Button variant="text" noise="none">
-          Text
-        </Button>
-        <Button variant="chip" noise="low">
-          Chip Active Button
-        </Button>
-        <Button variant="chipActive">Chip Active Button</Button>
+    <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">
+          Disabled — All Variants
+        </h4>
+        <div className="flex flex-wrap items-end gap-4">
+          <div className="space-y-2 text-center">
+            <Button variant="primary" isDisabled>
+              Primary
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Primary
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="secondary" isDisabled>
+              Secondary
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Secondary
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="outline" isDisabled>
+              Outline
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Outline
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="text" isDisabled>
+              Text
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Text
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="chip" isDisabled>
+              Chip
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Chip
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="chipActive" isDisabled>
+              Chip Active
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Chip Active
+            </p>
+          </div>
+        </div>
       </div>
-      <div className="flex items-end gap-4">
-        <Button variant="primary" noise="strong" size="sm">
-          Small
-        </Button>
-        <Button variant="primary" noise="medium" size="md">
-          Medium
-        </Button>
-        <Button variant="primary" noise="low" size="lg">
-          Large
-        </Button>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Disabled with Noise
+        </h4>
+        <div className="flex flex-wrap items-end gap-4">
+          <div className="space-y-2 text-center">
+            <Button variant="primary" noise="strong" isDisabled>
+              Primary
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Primary + strong noise
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="secondary" noise="medium" isDisabled>
+              Secondary
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Secondary + medium noise
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="chipActive" noise="low" isDisabled>
+              Chip Active
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Chip Active + low noise
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Enabled vs Disabled
+        </h4>
+        <div className="flex flex-wrap items-end gap-6">
+          <div className="space-y-2 text-center">
+            <Button variant="primary" noise="medium">
+              Enabled
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Enabled
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Button variant="primary" noise="medium" isDisabled>
+              Disabled
+            </Button>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Disabled
+            </p>
+          </div>
+        </div>
       </div>
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Disabled state applied across all six variants, with and without noise. Compare enabled and disabled appearances side-by-side.",
+      },
+    },
+  },
 }
 
-export const WithToolTip: Story = {
+// ─── 4. Use Cases ─────────────────────────────────────────────────────────────
+
+export const UseCases: Story = {
   render: () => (
-    <div className="flex gap-6 rounded p-8">
-      <Button
-        tooltip="Primary Variant with Medium Noise"
-        tooltipContentProps={{
-          align: "center",
-          side: "top",
-          sideOffset: 10,
-        }}
-        noise="medium"
-      >
-        Primary
-      </Button>
-      <Button
-        variant="secondary"
-        tooltip="Secondary (default: low noise)"
-        tooltipContentProps={{
-          align: "center",
-          side: "bottom",
-          sideOffset: 10,
-        }}
-      >
-        Secondary
-      </Button>
-      <Button
-        variant="outline"
-        tooltip="Outline Variant with No Noise"
-        tooltipContentProps={{
-          align: "center",
-          side: "top",
-          sideOffset: 10,
-        }}
-        noise="none"
-      >
-        Outline
-      </Button>
-      <Button variant="text" tooltip="Text Variant" noise="none">
-        Text
-      </Button>
+    <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">
+          Player Controls
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary flex flex-wrap items-center justify-center gap-4 rounded-xl border p-6">
+          <Button variant="secondary" size="sm">
+            <SkipBackwardIcon className="h-4 w-4" />
+          </Button>
+          <Button
+            variant="primary"
+            noise="strong"
+            size="lg"
+            leftIcon={<CircularPlayIcon />}
+          >
+            Play Now
+          </Button>
+          <Button variant="secondary" size="sm">
+            <SkipForwardIcon className="h-4 w-4" />
+          </Button>
+          <Button variant="secondary" size="sm">
+            <HeartIcon className="h-4 w-4" />
+          </Button>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Subscription CTA
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary flex flex-col items-center gap-4 rounded-xl border p-6">
+          <p className="text-fm-primary font-fm-text text-fm-lg leading-fm-xl font-semibold">
+            Unlock Premium Audio
+          </p>
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl max-w-xs text-center">
+            Get lossless streaming, offline downloads, and exclusive content.
+          </p>
+          <div className="flex flex-wrap justify-center gap-3">
+            <Button
+              variant="primary"
+              noise="medium"
+              size="lg"
+              leftIcon={<StarIcon />}
+            >
+              Start Free Trial
+            </Button>
+            <Button variant="outline" noise="none" size="lg">
+              Learn More
+            </Button>
+          </div>
+          <Button variant="text" noise="none" size="sm">
+            Not now
+          </Button>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Settings Actions
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-3 rounded-xl border p-6">
+          <div className="flex items-center justify-between">
+            <p className="text-fm-primary font-fm-text text-fm-md leading-fm-md">
+              Audio quality
+            </p>
+            <Button variant="secondary" size="sm" leftIcon={<SettingIcon />}>
+              Configure
+            </Button>
+          </div>
+          <div className="border-fm-divider-secondary border-t" />
+          <div className="flex items-center justify-between">
+            <p className="text-fm-primary font-fm-text text-fm-md leading-fm-md">
+              Library sync
+            </p>
+            <Button variant="chip" size="sm">
+              Sync now
+            </Button>
+          </div>
+          <div className="border-fm-divider-secondary border-t" />
+          <div className="flex items-center justify-between">
+            <p className="text-fm-primary font-fm-text text-fm-md leading-fm-md">
+              Equalizer
+            </p>
+            <Button variant="chipActive" size="sm" noise="low">
+              Active
+            </Button>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Genre Filter Chips
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary flex flex-wrap gap-2 rounded-xl border p-6">
+          <Button variant="chipActive" size="sm" noise="medium">
+            All
+          </Button>
+          <Button variant="chip" size="sm">
+            Hip-Hop
+          </Button>
+          <Button variant="chip" size="sm">
+            Electronic
+          </Button>
+          <Button variant="chip" size="sm">
+            Jazz
+          </Button>
+          <Button variant="chip" size="sm">
+            Classical
+          </Button>
+          <Button variant="chip" size="sm">
+            Rock
+          </Button>
+          <Button variant="chip" size="sm">
+            Pop
+          </Button>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Tooltip Integration
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary flex flex-wrap items-center justify-center gap-4 rounded-xl border p-6">
+          <Button
+            tooltip="Primary — medium noise, tooltip above"
+            tooltipContentProps={{
+              align: "center",
+              side: "top",
+              sideOffset: 10,
+            }}
+            noise="medium"
+          >
+            Primary
+          </Button>
+          <Button
+            variant="secondary"
+            tooltip="Secondary — tooltip below"
+            tooltipContentProps={{
+              align: "center",
+              side: "bottom",
+              sideOffset: 10,
+            }}
+          >
+            Secondary
+          </Button>
+          <Button
+            variant="outline"
+            tooltip="Outline — no noise, tooltip above"
+            tooltipContentProps={{
+              align: "center",
+              side: "top",
+              sideOffset: 10,
+            }}
+            noise="none"
+          >
+            Outline
+          </Button>
+          <Button variant="text" tooltip="Text — tooltip on hover" noise="none">
+            Text
+          </Button>
+        </div>
+      </div>
     </div>
   ),
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        story:
+          "Realistic audio-app scenarios: player playback controls, subscription upgrade CTA, settings panel actions, and genre filter chip row.",
+      },
+    },
+  },
 }