aural-ui 4.0.1 → 4.2.0

package/dist/components/overlay/Overlay.stories.tsx

@@ -1,13 +1,11 @@
 import React, { useState } from "react"
 import { Button } from "@components/button"
-import { AlertIcon } from "@icons/alert-icon"
-import { ChevronRightIcon } from "@icons/chevron-right-icon"
 import { CrossIcon } from "@icons/cross-icon"
-import { MaintenanceIcon } from "@icons/maintenance-icon"
 import { SearchIcon } from "@icons/search-icon"
-import { TickCircleIcon } from "@icons/tick-circle-icon"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import { Overlay } from "."
 
 const meta: Meta<typeof Overlay> = {
@@ -15,74 +13,29 @@ const meta: Meta<typeof Overlay> = {
   component: Overlay,
   parameters: {
     layout: "fullscreen",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-# Overlay Component
-
-A flexible overlay component for creating modal backgrounds, loading states, and layered content with customizable opacity, glass effects, and noise textures.
-
-## Features
-
-- **Multiple Opacity Levels**: High (80%), medium (60%), low (40%), or none
-- **Glass Effect**: Backdrop blur with high, medium, low, or no blur
-- **Noise Texture**: Visual noise patterns for enhanced aesthetics
-- **Animation Support**: Built-in fade in/out animations
-- **Z-Index Management**: Proper layering with configurable z-index
-- **Content Positioning**: Automatic centering of overlay content
-- **Event Handling**: Pointer events management for interactive overlays
-
-## Variant Options
-
-### Opacity Variants
-- **high**: 80% black background - Maximum dimming
-- **medium**: 60% black background - Balanced dimming (default)
-- **low**: 40% black background - Subtle dimming
-- **none**: Solid black background - Complete coverage
-
-### Glass Effect Variants
-- **high**: Strong backdrop blur - Heavy glass effect
-- **medium**: Medium backdrop blur - Moderate glass effect
-- **low**: Light backdrop blur - Subtle glass effect (default)
-- **none**: No backdrop blur - No glass effect
-
-### Noise Variants
-- **high**: Strong noise texture - Pronounced texture
-- **medium**: Medium noise texture - Balanced texture
-- **low**: Light noise texture - Subtle texture (default)
-- **none**: No noise texture - Clean overlay
-
-## Usage Examples
-
-### Basic Overlay
-\`\`\`tsx
-<Overlay>
-  <div>Overlay content</div>
-</Overlay>
-\`\`\`
-
-### Custom Configuration
-\`\`\`tsx
-<Overlay opacity="high" glass="medium" noise="low">
-  <div className="bg-white/10 p-4 rounded-lg">Modal content</div>
-</Overlay>
-\`\`\`
-
-### Loading State
-\`\`\`tsx
-<Overlay opacity="medium" glass="high">
-  <div className="text-fm-primary">Loading...</div>
-</Overlay>
-\`\`\`
-        `,
+        component:
+          "A flexible full-screen overlay for modal backgrounds, loading states, and layered UI. Offers independent control over opacity (low/medium/high/none), glass blur (none/low/medium/high), and noise texture (none/low/medium/high). Renders children in a centered z-50 container above the scrim.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Opacity Control",
+              description: "Low to high scrim",
+            },
+            {
+              title: "Glass Blur",
+              description: "None to high backdrop",
+            },
+            {
+              title: "Noise Texture",
+              description: "Grain overlay level",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -91,48 +44,48 @@ A flexible overlay component for creating modal backgrounds, loading states, and
 export default meta
 type Story = StoryObj<typeof Overlay>
 
-// Demo background content component
-const BackgroundContent = () => (
-  <div className="min-h-screen bg-gradient-to-br from-blue-900 via-purple-900 to-pink-900 p-8">
+// ─── shared backing content ───────────────────────────────────────────────────
+
+/**
+ * A content card background built entirely from design tokens.
+ * No hardcoded gradient colors.
+ */
+const BackingContent = () => (
+  <div className="bg-fm-surface-primary min-h-screen w-full p-8">
     <div className="mx-auto max-w-4xl space-y-8">
-      <header className="text-center">
-        <h1 className="mb-4 text-4xl font-bold text-white">
-          Background Content
+      <header className="space-y-2">
+        <p className="text-fm-tertiary font-fm-brand text-fm-sm leading-fm-sm tracking-widest uppercase">
+          PocketFM
+        </p>
+        <h1 className="text-fm-primary font-fm-brand text-fm-4xl leading-fm-4xl font-semibold">
+          Your music, everywhere
         </h1>
-        <p className="text-fm-tertiary">
-          This content sits behind the overlay to demonstrate the effects
+        <p className="text-fm-secondary font-fm-text text-fm-lg leading-fm-xl">
+          Discover curated playlists, follow your favourite artists, and listen
+          offline — all in one place.
         </p>
       </header>
 
       <div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
-        {Array.from({ length: 6 }, (_, i) => (
+        {[
+          { label: "New Releases", meta: "Updated today" },
+          { label: "Top Charts", meta: "Global & local" },
+          { label: "Your Mixes", meta: "Personalised for you" },
+          { label: "Artist Radio", meta: "Endless discovery" },
+          { label: "Podcasts", meta: "500 k+ shows" },
+          { label: "Audiobooks", meta: "10 k+ titles" },
+        ].map((card) => (
           <div
-            key={i}
-            className="border-fm-divider-secondary bg-fm-surface-secondary/80 rounded-lg border p-6"
+            key={card.label}
+            className="border-fm-divider-secondary bg-fm-surface-secondary rounded-xl border p-6"
           >
-            <div className="mb-4">
-              <h3 className="text-lg font-semibold text-white">Card {i + 1}</h3>
-              <p className="text-fm-secondary text-sm">
-                Sample card content with some description text
-              </p>
-            </div>
-            <div className="space-y-3">
-              <div className="flex h-32 items-center justify-center rounded-lg bg-gradient-to-r from-cyan-500 to-blue-600">
-                <span className="font-medium text-white">
-                  Image Placeholder
-                </span>
-              </div>
-              <p className="text-fm-tertiary text-sm">
-                This is some sample content that demonstrates how the overlay
-                affects background visibility and readability.
-              </p>
-              <div className="flex gap-2">
-                <Button size="sm" variant="outline">
-                  Action
-                </Button>
-                <Button size="sm">Primary</Button>
-              </div>
-            </div>
+            <div className="bg-fm-surface-contrast mb-4 h-24 w-full rounded-lg" />
+            <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+              {card.label}
+            </p>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              {card.meta}
+            </p>
           </div>
         ))}
       </div>
@@ -140,666 +93,203 @@ const BackgroundContent = () => (
   </div>
 )
 
-// 1. Opacity Variants
-export const OpacityVariants: Story = {
-  render: () => {
-    const [activeOverlay, setActiveOverlay] = useState<string | null>(null)
+// ─── 1. Configurations ────────────────────────────────────────────────────────
 
-    return (
-      <div className="relative">
-        <BackgroundContent />
-
-        {/* Control Panel */}
-        <div className="fixed top-4 left-4 z-50 space-y-2">
-          <div className="bg-fm-surface-primary border-fm-divider-secondary space-y-2 rounded-lg border p-4 backdrop-blur-sm">
-            <h3 className="text-fm-primary text-sm font-medium">
-              Opacity Variants
-            </h3>
-            <div className="space-y-2">
-              <Button
-                size="sm"
-                variant={activeOverlay === "low" ? "primary" : "outline"}
-                onClick={() =>
-                  setActiveOverlay(activeOverlay === "low" ? null : "low")
-                }
-                className="w-full"
-              >
-                Low (40%)
-              </Button>
-              <Button
-                size="sm"
-                variant={activeOverlay === "medium" ? "primary" : "outline"}
-                onClick={() =>
-                  setActiveOverlay(activeOverlay === "medium" ? null : "medium")
-                }
-                className="w-full"
-              >
-                Medium (60%)
-              </Button>
-              <Button
-                size="sm"
-                variant={activeOverlay === "high" ? "primary" : "outline"}
-                onClick={() =>
-                  setActiveOverlay(activeOverlay === "high" ? null : "high")
-                }
-                className="w-full"
-              >
-                High (80%)
-              </Button>
-              <Button
-                size="sm"
-                variant={activeOverlay === "none" ? "primary" : "outline"}
-                onClick={() =>
-                  setActiveOverlay(activeOverlay === "none" ? null : "none")
-                }
-                className="w-full"
-              >
-                None (100%)
-              </Button>
-            </div>
-            {activeOverlay && (
-              <Button
-                size="sm"
-                variant="secondary"
-                onClick={() => setActiveOverlay(null)}
-                className="w-full"
-              >
-                Clear Overlay
-              </Button>
-            )}
-          </div>
-        </div>
+export const Configurations: Story = {
+  render: () => {
+    const [activeOpacity, setActiveOpacity] = useState<
+      "low" | "medium" | "high" | "none" | null
+    >(null)
+    const [activeGlass, setActiveGlass] = useState<
+      "none" | "low" | "medium" | "high" | null
+    >(null)
+    const [activeNoise, setActiveNoise] = useState<
+      "none" | "low" | "medium" | "high" | null
+    >(null)
+
+    const clearAll = () => {
+      setActiveOpacity(null)
+      setActiveGlass(null)
+      setActiveNoise(null)
+    }
 
-        {/* Overlays */}
-        {activeOverlay === "low" && (
-          <Overlay opacity="low">
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 max-w-md rounded-lg border p-6 backdrop-blur-sm">
-              <h3 className="text-fm-primary mb-2 text-lg font-semibold">
-                Low Opacity Overlay
-              </h3>
-              <p className="text-fm-secondary text-sm">
-                40% background dimming - Background remains quite visible
-              </p>
-            </div>
-          </Overlay>
-        )}
+    const hasActive = activeOpacity || activeGlass || activeNoise
 
-        {activeOverlay === "medium" && (
-          <Overlay opacity="medium">
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 max-w-md rounded-lg border p-6 backdrop-blur-sm">
-              <h3 className="text-fm-primary mb-2 text-lg font-semibold">
-                Medium Opacity Overlay
-              </h3>
-              <p className="text-fm-secondary text-sm">
-                60% background dimming - Balanced visibility
-              </p>
-            </div>
-          </Overlay>
-        )}
-
-        {activeOverlay === "high" && (
-          <Overlay opacity="high">
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 max-w-md rounded-lg border p-6 backdrop-blur-sm">
-              <h3 className="text-fm-primary mb-2 text-lg font-semibold">
-                High Opacity Overlay
-              </h3>
-              <p className="text-fm-secondary text-sm">
-                80% background dimming - Strong focus on overlay content
-              </p>
-            </div>
-          </Overlay>
-        )}
+    const opacityOptions = [
+      { value: "low", label: "Low · 40%" },
+      { value: "medium", label: "Medium · 60%" },
+      { value: "high", label: "High · 80%" },
+      { value: "none", label: "Solid · 100%" },
+    ] as const
 
-        {activeOverlay === "none" && (
-          <Overlay opacity="none">
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 max-w-md rounded-lg border p-6 backdrop-blur-sm">
-              <h3 className="text-fm-primary mb-2 text-lg font-semibold">
-                No Opacity Overlay
-              </h3>
-              <p className="text-fm-secondary text-sm">
-                100% background coverage - Complete background blocking
-              </p>
-            </div>
-          </Overlay>
-        )}
-      </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Interactive demonstration of different opacity levels showing how background visibility changes from 40% to 100% coverage.",
-      },
-    },
-  },
-}
+    const glassOptions = [
+      { value: "none", label: "No blur" },
+      { value: "low", label: "Low blur" },
+      { value: "medium", label: "Medium blur" },
+      { value: "high", label: "High blur" },
+    ] as const
 
-// 2. Glass Effect Variants
-export const GlassEffectVariants: Story = {
-  render: () => {
-    const [activeGlass, setActiveGlass] = useState<string | null>(null)
+    const noiseOptions = [
+      { value: "none", label: "No texture" },
+      { value: "low", label: "Low texture" },
+      { value: "medium", label: "Medium texture" },
+      { value: "high", label: "Strong texture" },
+    ] as const
 
     return (
-      <div className="relative">
-        <BackgroundContent />
-
-        {/* Control Panel */}
-        <div className="fixed top-4 right-4 z-50 space-y-2">
-          <div className="bg-fm-surface-primary border-fm-divider-secondary space-y-2 rounded-lg border p-4 backdrop-blur-sm">
-            <h3 className="text-fm-primary text-sm font-medium">
-              Glass Effect Variants
-            </h3>
-            <div className="space-y-2">
-              <Button
-                size="sm"
-                variant={activeGlass === "none" ? "primary" : "outline"}
-                onClick={() =>
-                  setActiveGlass(activeGlass === "none" ? null : "none")
-                }
-                className="w-full"
-              >
-                No Glass
-              </Button>
-              <Button
-                size="sm"
-                variant={activeGlass === "low" ? "primary" : "outline"}
-                onClick={() =>
-                  setActiveGlass(activeGlass === "low" ? null : "low")
-                }
-                className="w-full"
-              >
-                Low Blur
-              </Button>
-              <Button
-                size="sm"
-                variant={activeGlass === "medium" ? "primary" : "outline"}
-                onClick={() =>
-                  setActiveGlass(activeGlass === "medium" ? null : "medium")
-                }
-                className="w-full"
-              >
-                Medium Blur
-              </Button>
-              <Button
-                size="sm"
-                variant={activeGlass === "high" ? "primary" : "outline"}
-                onClick={() =>
-                  setActiveGlass(activeGlass === "high" ? null : "high")
-                }
-                className="w-full"
-              >
-                High Blur
-              </Button>
-            </div>
-            {activeGlass && (
-              <Button
-                size="sm"
-                variant="secondary"
-                onClick={() => setActiveGlass(null)}
-                className="w-full"
-              >
-                Clear Overlay
-              </Button>
-            )}
-          </div>
-        </div>
-
-        {/* Glass Effect Overlays */}
-        {activeGlass === "none" && (
-          <Overlay opacity="medium" glass="none">
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 max-w-md rounded-lg border p-6">
-              <h3 className="text-fm-primary mb-2 text-lg font-semibold">
-                No Glass Effect
-              </h3>
-              <p className="text-fm-secondary text-sm">
-                Clean overlay without backdrop blur
+      <div className="w-full p-8">
+        <div className="mx-auto grid max-w-5xl grid-cols-1 gap-6 lg:grid-cols-[280px_minmax(0,1fr)]">
+          {/* ── Control panel ── */}
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary h-[32rem] overflow-y-auto rounded-xl border p-5 shadow-lg">
+            <div className="space-y-5">
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                Opacity
               </p>
-            </div>
-          </Overlay>
-        )}
-
-        {activeGlass === "low" && (
-          <Overlay opacity="medium" glass="low">
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 max-w-md rounded-lg border p-6">
-              <h3 className="text-fm-primary mb-2 text-lg font-semibold">
-                Low Glass Effect
-              </h3>
-              <p className="text-fm-secondary text-sm">
-                Subtle backdrop blur for gentle glass effect
-              </p>
-            </div>
-          </Overlay>
-        )}
+              <div className="space-y-2">
+                {opacityOptions.map((o) => (
+                  <Button
+                    key={o.value}
+                    size="sm"
+                    variant={activeOpacity === o.value ? "primary" : "outline"}
+                    onClick={() =>
+                      setActiveOpacity(
+                        activeOpacity === o.value ? null : o.value
+                      )
+                    }
+                    className="w-full justify-start"
+                  >
+                    {o.label}
+                  </Button>
+                ))}
+              </div>
 
-        {activeGlass === "medium" && (
-          <Overlay opacity="medium" glass="medium">
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 max-w-md rounded-lg border p-6">
-              <h3 className="text-fm-primary mb-2 text-lg font-semibold">
-                Medium Glass Effect
-              </h3>
-              <p className="text-fm-secondary text-sm">
-                Balanced backdrop blur for modern glass aesthetics
-              </p>
-            </div>
-          </Overlay>
-        )}
+              <div className="border-fm-divider-secondary border-t pt-4" />
 
-        {activeGlass === "high" && (
-          <Overlay opacity="medium" glass="high">
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 max-w-md rounded-lg border p-6">
-              <h3 className="text-fm-primary mb-2 text-lg font-semibold">
-                High Glass Effect
-              </h3>
-              <p className="text-fm-secondary text-sm">
-                Strong backdrop blur for premium frosted glass look
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                Glass
               </p>
-            </div>
-          </Overlay>
-        )}
-      </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Interactive demonstration of glass effect variants showing different levels of backdrop blur from none to high intensity.",
-      },
-    },
-  },
-}
-
-// 3. Loading States
-export const LoadingStates: Story = {
-  render: () => {
-    const [loadingType, setLoadingType] = useState<string | null>(null)
-
-    const startLoading = (type: string) => {
-      setLoadingType(type)
-      setTimeout(() => setLoadingType(null), 3000)
-    }
+              <div className="space-y-2">
+                {glassOptions.map((g) => (
+                  <Button
+                    key={g.value}
+                    size="sm"
+                    variant={activeGlass === g.value ? "primary" : "outline"}
+                    onClick={() =>
+                      setActiveGlass(activeGlass === g.value ? null : g.value)
+                    }
+                    className="w-full justify-start"
+                  >
+                    {g.label}
+                  </Button>
+                ))}
+              </div>
 
-    return (
-      <div className="relative">
-        <BackgroundContent />
-
-        {/* Control Panel */}
-        <div className="fixed top-4 left-1/2 z-50 -translate-x-1/2 transform">
-          <div className="bg-fm-surface-primary border-fm-divider-secondary space-y-2 rounded-lg border p-4 backdrop-blur-sm">
-            <h3 className="text-fm-primary text-center text-sm font-medium">
-              Loading States
-            </h3>
-            <div className="flex gap-2">
-              <Button
-                size="sm"
-                onClick={() => startLoading("spinner")}
-                disabled={!!loadingType}
-              >
-                Spinner Loading
-              </Button>
-              <Button
-                size="sm"
-                onClick={() => startLoading("progress")}
-                disabled={!!loadingType}
-              >
-                Progress Loading
-              </Button>
-              <Button
-                size="sm"
-                onClick={() => startLoading("dots")}
-                disabled={!!loadingType}
-              >
-                Dots Loading
-              </Button>
-            </div>
-          </div>
-        </div>
+              <div className="border-fm-divider-secondary border-t pt-4" />
 
-        {/* Loading Overlays */}
-        {loadingType === "spinner" && (
-          <Overlay opacity="high" glass="medium">
-            <div className="text-fm-primary text-center">
-              <div className="border-fm-primary mx-auto mb-4 h-12 w-12 animate-spin rounded-full border-b-2"></div>
-              <h3 className="mb-2 text-lg font-medium">Loading...</h3>
-              <p className="text-fm-secondary">
-                Please wait while we process your request
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                Noise
               </p>
-            </div>
-          </Overlay>
-        )}
-
-        {loadingType === "progress" && (
-          <Overlay opacity="high" glass="low">
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 min-w-80 rounded-lg border p-6 backdrop-blur-sm">
-              <div className="text-fm-primary text-center">
-                <h3 className="mb-4 text-lg font-medium">Uploading Files</h3>
-                <div className="bg-fm-surface-tertiary mb-4 h-2 w-full rounded-full">
-                  <div
-                    className="bg-fm-info h-2 animate-pulse rounded-full"
-                    style={{ width: "65%" }}
-                  ></div>
-                </div>
-                <p className="text-fm-secondary">
-                  65% complete - 3 of 5 files uploaded
-                </p>
+              <div className="space-y-2">
+                {noiseOptions.map((n) => (
+                  <Button
+                    key={n.value}
+                    size="sm"
+                    variant={activeNoise === n.value ? "primary" : "outline"}
+                    onClick={() =>
+                      setActiveNoise(activeNoise === n.value ? null : n.value)
+                    }
+                    className="w-full justify-start"
+                  >
+                    {n.label}
+                  </Button>
+                ))}
               </div>
-            </div>
-          </Overlay>
-        )}
 
-        {loadingType === "dots" && (
-          <Overlay opacity="medium" glass="high">
-            <div className="text-fm-primary text-center">
-              <div className="mb-4 flex items-center justify-center space-x-2">
-                <div className="bg-fm-primary h-3 w-3 animate-bounce rounded-full"></div>
-                <div
-                  className="bg-fm-primary h-3 w-3 animate-bounce rounded-full"
-                  style={{ animationDelay: "0.1s" }}
-                ></div>
-                <div
-                  className="bg-fm-primary h-3 w-3 animate-bounce rounded-full"
-                  style={{ animationDelay: "0.2s" }}
-                ></div>
-              </div>
-              <h3 className="mb-2 text-lg font-medium">Processing</h3>
-              <p className="text-fm-secondary">Analyzing your data...</p>
+              {hasActive && (
+                <>
+                  <div className="border-fm-divider-secondary border-t pt-4" />
+                  <Button
+                    size="sm"
+                    variant="secondary"
+                    onClick={clearAll}
+                    className="w-full"
+                  >
+                    Clear overlay
+                  </Button>
+                </>
+              )}
             </div>
-          </Overlay>
-        )}
-      </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Common loading state patterns using overlays with different animations and progress indicators.",
-      },
-    },
-  },
-}
-
-// 4. Interactive Examples
-export const InteractiveExamples: Story = {
-  render: () => {
-    const [showSearch, setShowSearch] = useState(false)
-    const [showSettings, setShowSettings] = useState(false)
-    const [showConfirm, setShowConfirm] = useState(false)
+          </div>
 
-    return (
-      <div className="relative">
-        <BackgroundContent />
-
-        {/* Control Panel */}
-        <div className="fixed top-4 left-1/2 z-50 -translate-x-1/2 transform">
-          <div className="bg-fm-surface-primary border-fm-divider-secondary space-y-2 rounded-lg border p-4 backdrop-blur-sm">
-            <h3 className="text-fm-primary text-center text-sm font-medium">
-              Interactive Examples
-            </h3>
-            <div className="flex gap-2">
-              <Button size="sm" onClick={() => setShowSearch(true)}>
-                Search Modal
-              </Button>
-              <Button size="sm" onClick={() => setShowSettings(true)}>
-                Settings
-              </Button>
-              <Button
-                size="sm"
-                variant="primary"
-                onClick={() => setShowConfirm(true)}
-              >
-                Confirm Action
-              </Button>
+          {/* ── Preview stage ── */}
+          <div className="relative overflow-hidden rounded-2xl">
+            <div className="h-[32rem] overflow-hidden rounded-2xl">
+              <BackingContent />
             </div>
-          </div>
-        </div>
 
-        {/* Search Modal */}
-        {showSearch && (
-          <Overlay opacity="medium" glass="medium">
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 w-full max-w-lg rounded-lg border p-6 backdrop-blur-sm">
-              <div className="mb-4 flex items-center justify-between">
-                <h3 className="text-fm-primary text-lg font-semibold">
-                  Search
-                </h3>
-                <button
-                  onClick={() => setShowSearch(false)}
-                  className="text-fm-primary hover:bg-fm-surface-secondary rounded-full p-2"
-                >
-                  <CrossIcon className="h-4 w-4" />
-                </button>
-              </div>
-              <div className="space-y-4">
-                <div className="relative">
-                  <SearchIcon className="text-fm-secondary absolute top-1/2 left-3 h-4 w-4 -translate-y-1/2" />
-                  <input
-                    type="text"
-                    placeholder="Search anything..."
-                    className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary placeholder:text-fm-tertiary focus:border-fm-divider-primary w-full rounded-lg border py-3 pr-4 pl-10 focus:outline-none"
-                  />
-                </div>
-                <div className="space-y-2">
-                  {["Recent searches", "Popular items", "Suggestions"].map(
-                    (item, i) => (
-                      <div
-                        key={i}
-                        className="hover:bg-fm-surface-secondary flex items-center gap-3 rounded-lg p-3"
-                      >
-                        <SearchIcon className="text-fm-secondary h-4 w-4" />
-                        <span className="text-fm-primary">{item}</span>
-                      </div>
-                    )
-                  )}
+            {!hasActive && (
+              <div className="pointer-events-none absolute inset-x-6 bottom-6 z-20">
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary/90 ml-auto max-w-sm rounded-xl border p-4 backdrop-blur-sm">
+                  <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md mb-1 font-semibold">
+                    Overlay Preview
+                  </p>
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-xl">
+                    Choose opacity, glass, and noise options from the left to
+                    preview the overlay over this bounded content stage.
+                  </p>
                 </div>
               </div>
-            </div>
-          </Overlay>
-        )}
+            )}
 
-        {/* Settings Modal */}
-        {showSettings && (
-          <Overlay opacity="high" glass="low">
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 w-full max-w-md rounded-lg border p-6 backdrop-blur-sm">
-              <div className="mb-4 flex items-center justify-between">
-                <h3 className="text-fm-primary text-lg font-semibold">
-                  Settings
-                </h3>
-                <button
-                  onClick={() => setShowSettings(false)}
-                  className="text-fm-primary hover:bg-fm-surface-secondary rounded-full p-2"
-                >
-                  <CrossIcon className="h-4 w-4" />
-                </button>
-              </div>
-              <div className="space-y-4">
-                {[
-                  { label: "Notifications", icon: AlertIcon },
-                  { label: "Privacy", icon: MaintenanceIcon },
-                  { label: "Account", icon: TickCircleIcon },
-                ].map((item, i) => (
-                  <div
-                    key={i}
-                    className="hover:bg-fm-surface-secondary flex items-center justify-between rounded-lg p-3"
-                  >
-                    <div className="flex items-center gap-3">
-                      <item.icon className="text-fm-secondary h-5 w-5" />
-                      <span className="text-fm-primary">{item.label}</span>
-                    </div>
-                    <ChevronRightIcon className="text-fm-secondary h-4 w-4" />
+            {/* ── Active overlay ── */}
+            {hasActive && (
+              <Overlay
+                opacity={activeOpacity ?? "medium"}
+                glass={activeGlass ?? "none"}
+                noise={activeNoise ?? "none"}
+                className="absolute inset-0 z-10"
+                classes={{
+                  wrapper: "absolute inset-0",
+                  content: "px-6",
+                }}
+              >
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary max-w-sm rounded-xl border p-6">
+                  <p className="text-fm-primary font-fm-brand text-fm-lg leading-fm-lg mb-1 font-semibold">
+                    Active overlay
+                  </p>
+                  <div className="text-fm-secondary font-fm-text text-fm-sm leading-fm-xl space-y-0.5">
+                    <p>
+                      Opacity:{" "}
+                      <span className="text-fm-primary">
+                        {activeOpacity ?? "medium"}
+                      </span>
+                    </p>
+                    <p>
+                      Glass:{" "}
+                      <span className="text-fm-primary">
+                        {activeGlass ?? "none"}
+                      </span>
+                    </p>
+                    <p>
+                      Noise:{" "}
+                      <span className="text-fm-primary">
+                        {activeNoise ?? "none"}
+                      </span>
+                    </p>
                   </div>
-                ))}
-              </div>
-            </div>
-          </Overlay>
-        )}
-
-        {/* Confirmation Modal */}
-        {showConfirm && (
-          <Overlay opacity="high" glass="high">
-            <div className="border-fm-divider-negative bg-fm-surface-negative-sec w-full max-w-sm rounded-lg border p-6 backdrop-blur-sm">
-              <div className="text-center">
-                <AlertIcon className="text-fm-negative mx-auto mb-4 h-12 w-12" />
-                <h3 className="text-fm-primary mb-2 text-lg font-semibold">
-                  Confirm Action
-                </h3>
-                <p className="text-fm-secondary mb-6 text-sm">
-                  This action cannot be undone. Are you sure you want to
-                  continue?
-                </p>
-                <div className="flex gap-3">
                   <Button
-                    variant="outline"
-                    size="sm"
-                    onClick={() => setShowConfirm(false)}
-                    className="flex-1"
-                  >
-                    Cancel
-                  </Button>
-                  <Button
-                    variant="secondary"
                     size="sm"
-                    onClick={() => setShowConfirm(false)}
-                    className="flex-1"
+                    variant="outline"
+                    onClick={clearAll}
+                    className="mt-4 w-full"
                   >
-                    Confirm
+                    Dismiss
                   </Button>
                 </div>
-              </div>
-            </div>
-          </Overlay>
-        )}
-      </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Interactive overlay examples including search modals, settings panels, and confirmation dialogs demonstrating real-world usage patterns.",
-      },
-    },
-  },
-}
-
-// 5. Noise Texture Variants
-export const NoiseTextureVariants: Story = {
-  render: () => {
-    const [activeNoise, setActiveNoise] = useState<string | null>(null)
-
-    return (
-      <div className="relative">
-        <BackgroundContent />
-
-        {/* Control Panel */}
-        <div className="fixed bottom-4 left-1/2 z-50 -translate-x-1/2 transform">
-          <div className="bg-fm-surface-primary border-fm-divider-secondary space-y-2 rounded-lg border p-4 backdrop-blur-sm">
-            <h3 className="text-fm-primary text-center text-sm font-medium">
-              Noise Texture Variants
-            </h3>
-            <div className="flex gap-2">
-              <Button
-                size="sm"
-                variant={activeNoise === "none" ? "primary" : "outline"}
-                onClick={() =>
-                  setActiveNoise(activeNoise === "none" ? null : "none")
-                }
-              >
-                No Noise
-              </Button>
-              <Button
-                size="sm"
-                variant={activeNoise === "low" ? "primary" : "outline"}
-                onClick={() =>
-                  setActiveNoise(activeNoise === "low" ? null : "low")
-                }
-              >
-                Low Noise
-              </Button>
-              <Button
-                size="sm"
-                variant={activeNoise === "medium" ? "primary" : "outline"}
-                onClick={() =>
-                  setActiveNoise(activeNoise === "medium" ? null : "medium")
-                }
-              >
-                Medium Noise
-              </Button>
-              <Button
-                size="sm"
-                variant={activeNoise === "high" ? "primary" : "outline"}
-                onClick={() =>
-                  setActiveNoise(activeNoise === "high" ? null : "high")
-                }
-              >
-                High Noise
-              </Button>
-            </div>
-            {activeNoise && (
-              <Button
-                size="sm"
-                variant="secondary"
-                onClick={() => setActiveNoise(null)}
-                className="w-full"
-              >
-                Clear Overlay
-              </Button>
+              </Overlay>
             )}
           </div>
         </div>
-
-        {/* Noise Overlays */}
-        {activeNoise === "none" && (
-          <Overlay opacity="medium" glass="low" noise="none">
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 max-w-md rounded-lg border p-6 backdrop-blur-sm">
-              <h3 className="text-fm-primary mb-2 text-lg font-semibold">
-                No Noise Texture
-              </h3>
-              <p className="text-fm-secondary text-sm">
-                Clean overlay without any texture patterns
-              </p>
-            </div>
-          </Overlay>
-        )}
-
-        {activeNoise === "low" && (
-          <Overlay opacity="medium" glass="low" noise="low">
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 max-w-md rounded-lg border p-6 backdrop-blur-sm">
-              <h3 className="text-fm-primary mb-2 text-lg font-semibold">
-                Low Noise Texture
-              </h3>
-              <p className="text-fm-secondary text-sm">
-                Subtle noise pattern for added visual interest
-              </p>
-            </div>
-          </Overlay>
-        )}
-
-        {activeNoise === "medium" && (
-          <Overlay opacity="medium" glass="low" noise="medium">
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 max-w-md rounded-lg border p-6 backdrop-blur-sm">
-              <h3 className="text-fm-primary mb-2 text-lg font-semibold">
-                Medium Noise Texture
-              </h3>
-              <p className="text-fm-secondary text-sm">
-                Balanced noise pattern for enhanced texture
-              </p>
-            </div>
-          </Overlay>
-        )}
-
-        {activeNoise === "high" && (
-          <Overlay opacity="medium" glass="low" noise="high">
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 max-w-md rounded-lg border p-6 backdrop-blur-sm">
-              <h3 className="text-fm-primary mb-2 text-lg font-semibold">
-                High Noise Texture
-              </h3>
-              <p className="text-fm-secondary text-sm">
-                Prominent noise pattern for dramatic effect
-              </p>
-            </div>
-          </Overlay>
-        )}
       </div>
     )
   },
@@ -807,144 +297,282 @@ export const NoiseTextureVariants: Story = {
     docs: {
       description: {
         story:
-          "Demonstration of noise texture variants that add visual interest and depth to overlays with different intensity levels.",
+          "Interactive panel to explore every configuration axis independently: opacity levels (40 % / 60 % / 80 % / solid), glass blur (none → high), and noise texture (none → strong). Mix and match any combination to preview the live effect over real backing content.",
       },
     },
   },
 }
 
-// 6. Combined Effects Showcase
-export const CombinedEffectsShowcase: Story = {
-  render: () => {
-    const [currentCombo, setCurrentCombo] = useState<string | null>(null)
+// ─── 2. Showcase ──────────────────────────────────────────────────────────────
 
-    const combinations = [
+export const Showcase: Story = {
+  render: () => {
+    /**
+     * Each card shows the Overlay rendered inside a bounded relative container
+     * (position: relative on the wrapper, not fixed on the overlay) so the
+     * gallery fits on-canvas. We override `className` to switch from
+     * `fixed inset-0` to `absolute inset-0` for in-card previews.
+     */
+    const combos = [
       {
-        id: "minimal",
         name: "Minimal",
+        meta: "opacity: low · glass: none · noise: none",
         opacity: "low",
         glass: "none",
         noise: "none",
+        backing: "bg-fm-surface-primary",
       },
       {
-        id: "subtle",
         name: "Subtle",
+        meta: "opacity: medium · glass: low · noise: low",
         opacity: "medium",
         glass: "low",
         noise: "low",
+        backing: "bg-fm-surface-secondary",
+      },
+      {
+        name: "Frosted",
+        meta: "opacity: medium · glass: high · noise: none",
+        opacity: "medium",
+        glass: "high",
+        noise: "none",
+        backing: "bg-fm-surface-contrast",
       },
       {
-        id: "balanced",
         name: "Balanced",
+        meta: "opacity: medium · glass: medium · noise: medium",
         opacity: "medium",
         glass: "medium",
         noise: "medium",
+        backing: "bg-fm-surface-secondary",
       },
       {
-        id: "dramatic",
         name: "Dramatic",
+        meta: "opacity: high · glass: high · noise: low",
         opacity: "high",
         glass: "high",
         noise: "low",
+        backing: "bg-fm-surface-primary",
       },
       {
-        id: "premium",
-        name: "Premium",
+        name: "Textured",
+        meta: "opacity: high · glass: medium · noise: high",
         opacity: "high",
-        glass: "high",
+        glass: "medium",
         noise: "high",
+        backing: "bg-fm-surface-contrast",
       },
     ] as const
 
     return (
-      <div className="relative">
-        <BackgroundContent />
-
-        {/* Control Panel */}
-        <div className="fixed top-1/2 left-4 z-50 -translate-y-1/2 transform">
-          <div className="bg-fm-surface-primary border-fm-divider-secondary space-y-2 rounded-lg border p-4 backdrop-blur-sm">
-            <h3 className="text-fm-primary text-sm font-medium">
-              Effect Combinations
-            </h3>
-            <div className="space-y-2">
-              {combinations.map((combo) => (
-                <Button
-                  key={combo.id}
-                  size="sm"
-                  variant={currentCombo === combo.id ? "primary" : "outline"}
-                  onClick={() =>
-                    setCurrentCombo(currentCombo === combo.id ? null : combo.id)
-                  }
-                  className="w-full justify-start"
+      <div className="w-full p-8">
+        <div className="mx-auto max-w-4xl space-y-10">
+          <div className="grid grid-cols-2 gap-6 sm:grid-cols-3">
+            {combos.map((combo) => (
+              <div key={combo.name} className="group space-y-3">
+                {/* Bounded preview card */}
+                <div
+                  className={`relative h-40 w-full overflow-hidden rounded-xl ${combo.backing}`}
                 >
-                  {combo.name}
-                </Button>
-              ))}
-            </div>
-            {currentCombo && (
-              <Button
-                size="sm"
-                variant="secondary"
-                onClick={() => setCurrentCombo(null)}
-                className="w-full"
-              >
-                Clear Overlay
-              </Button>
-            )}
-          </div>
-        </div>
+                  {/* Mock content in the "background" */}
+                  <div className="absolute inset-0 flex flex-col gap-2 p-4">
+                    <div className="border-fm-divider-secondary bg-fm-surface-secondary h-6 w-3/4 rounded" />
+                    <div className="border-fm-divider-secondary bg-fm-surface-secondary h-4 w-full rounded" />
+                    <div className="border-fm-divider-secondary bg-fm-surface-secondary h-4 w-5/6 rounded" />
+                    <div className="border-fm-divider-secondary bg-fm-surface-secondary mt-auto flex gap-2">
+                      <div className="h-7 w-16 rounded" />
+                      <div className="h-7 w-20 rounded" />
+                    </div>
+                  </div>
 
-        {/* Effect Information Panel */}
-        {currentCombo && (
-          <div className="fixed top-1/2 right-4 z-50 -translate-y-1/2 transform">
-            <div className="bg-fm-surface-primary border-fm-divider-secondary max-w-xs space-y-2 rounded-lg border p-4 backdrop-blur-sm">
-              <h4 className="text-fm-primary text-sm font-medium">
-                {combinations.find((c) => c.id === currentCombo)?.name} Effect
-              </h4>
-              <div className="text-fm-secondary space-y-1 text-xs">
-                <div>
-                  Opacity:{" "}
-                  {combinations.find((c) => c.id === currentCombo)?.opacity}
-                </div>
-                <div>
-                  Glass:{" "}
-                  {combinations.find((c) => c.id === currentCombo)?.glass}
+                  {/* Overlay — absolute instead of fixed for bounded card display */}
+                  <Overlay
+                    opacity={combo.opacity}
+                    glass={combo.glass}
+                    noise={combo.noise}
+                    className="absolute inset-0 z-10"
+                  />
                 </div>
-                <div>
-                  Noise:{" "}
-                  {combinations.find((c) => c.id === currentCombo)?.noise}
+
+                {/* Item metadata */}
+                <div className="space-y-0.5 text-center">
+                  <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+                    {combo.name}
+                  </p>
+                  <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                    {combo.meta}
+                  </p>
                 </div>
               </div>
-            </div>
+            ))}
           </div>
-        )}
 
-        {/* Combined Effect Overlays */}
-        {combinations.map(
-          (combo) =>
-            currentCombo === combo.id && (
-              <Overlay
-                key={combo.id}
-                opacity={combo.opacity}
-                glass={combo.glass}
-                noise={combo.noise}
-              >
-                <div className="border-fm-divider-secondary bg-fm-surface-secondary/80 max-w-md rounded-lg border p-6 backdrop-blur-sm">
-                  <h3 className="text-fm-primary mb-2 text-lg font-semibold">
-                    {combo.name} Overlay
-                  </h3>
-                  <p className="text-fm-secondary mb-4 text-sm">
-                    Combination of {combo.opacity} opacity, {combo.glass} glass
-                    effect, and {combo.noise} noise texture
-                  </p>
-                  <p className="text-fm-tertiary text-sm">
-                    This combination creates a {combo.name.toLowerCase()}{" "}
-                    overlay effect suitable for different design contexts and
-                    user interface needs.
+          {/* Info box */}
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+            <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+              Each card above uses a design-token background (
+              <code className="text-fm-primary font-(--font-fm-mono)">
+                bg-fm-surface-primary
+              </code>
+              ,{" "}
+              <code className="text-fm-primary font-(--font-fm-mono)">
+                bg-fm-surface-secondary
+              </code>
+              ,{" "}
+              <code className="text-fm-primary font-(--font-fm-mono)">
+                bg-fm-surface-contrast
+              </code>
+              ) — no hardcoded gradient colors. The{" "}
+              <code className="text-fm-primary font-(--font-fm-mono)">
+                className
+              </code>{" "}
+              prop switches the overlay from{" "}
+              <code className="text-fm-primary">fixed</code> to{" "}
+              <code className="text-fm-primary">absolute</code> for bounded
+              in-card previews.
+            </p>
+          </div>
+        </div>
+      </div>
+    )
+  },
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        story:
+          "Curated gallery of six overlay combinations — from minimal (low opacity, no glass) to textured (high opacity, medium glass, strong noise). Each card uses design-token backgrounds (bg-fm-surface-primary, bg-fm-surface-secondary, bg-fm-surface-contrast) with no hardcoded Tailwind gradient colors.",
+      },
+    },
+  },
+}
+
+// ─── 3. Interactive ───────────────────────────────────────────────────────────
+
+export const Interactive: Story = {
+  render: () => {
+    const [showSearch, setShowSearch] = useState(false)
+    const [showConfirm, setShowConfirm] = useState(false)
+    const [searchQuery, setSearchQuery] = useState("")
+
+    return (
+      <div className="relative">
+        <BackingContent />
+
+        {/* Trigger buttons */}
+        <div className="fixed top-4 left-1/2 z-50 -translate-x-1/2">
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary flex gap-3 rounded-xl border p-4">
+            <Button size="sm" onClick={() => setShowSearch(true)}>
+              Search
+            </Button>
+            <Button
+              size="sm"
+              variant="secondary"
+              onClick={() => setShowConfirm(true)}
+            >
+              Confirm action
+            </Button>
+          </div>
+        </div>
+
+        {/* Search modal */}
+        {showSearch && (
+          <Overlay opacity="medium" glass="medium" noise="none">
+            <div className="border-fm-divider-secondary bg-fm-surface-secondary w-full max-w-lg rounded-xl border p-6">
+              <div className="mb-4 flex items-center justify-between">
+                <p className="text-fm-primary font-fm-brand text-fm-lg leading-fm-lg font-semibold">
+                  Search
+                </p>
+                <button
+                  onClick={() => {
+                    setShowSearch(false)
+                    setSearchQuery("")
+                  }}
+                  className="text-fm-secondary hover:text-fm-primary rounded-full p-1 transition-colors"
+                  aria-label="Close search"
+                >
+                  <CrossIcon className="h-4 w-4" />
+                </button>
+              </div>
+
+              <div className="relative mb-4">
+                <SearchIcon className="text-fm-tertiary absolute top-1/2 left-3 h-4 w-4 -translate-y-1/2" />
+                <input
+                  type="text"
+                  placeholder="Search artists, albums, tracks…"
+                  value={searchQuery}
+                  onChange={(e) => setSearchQuery(e.target.value)}
+                  className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary placeholder:text-fm-tertiary focus:border-fm-divider-primary font-fm-text text-fm-sm leading-fm-sm w-full rounded-lg border py-3 pr-4 pl-10 focus:outline-none"
+                  autoFocus
+                />
+              </div>
+
+              {searchQuery.length === 0 && (
+                <div className="space-y-1">
+                  <p className="text-fm-secondary font-fm-brand text-fm-sm leading-fm-sm mb-2 font-semibold tracking-widest uppercase">
+                    Recent
                   </p>
+                  {["Bicep", "Four Tet", "Floating Points"].map((item) => (
+                    <button
+                      key={item}
+                      onClick={() => setSearchQuery(item)}
+                      className="hover:bg-fm-surface-tertiary flex w-full items-center gap-3 rounded-lg px-3 py-2 text-left transition-colors"
+                    >
+                      <SearchIcon className="text-fm-tertiary h-4 w-4 shrink-0" />
+                      <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                        {item}
+                      </span>
+                    </button>
+                  ))}
                 </div>
-              </Overlay>
-            )
+              )}
+
+              {searchQuery.length > 0 && (
+                <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                  Showing results for{" "}
+                  <span className="text-fm-primary">"{searchQuery}"</span>…
+                </p>
+              )}
+            </div>
+          </Overlay>
+        )}
+
+        {/* Confirmation dialog */}
+        {showConfirm && (
+          <Overlay opacity="high" glass="high" noise="none">
+            <div className="border-fm-divider-secondary bg-fm-surface-secondary max-w-sm rounded-xl border p-6 text-center">
+              <div className="border-fm-divider-secondary bg-fm-surface-tertiary mx-auto mb-4 flex h-12 w-12 items-center justify-center rounded-full">
+                <span className="text-fm-primary font-fm-brand text-fm-lg leading-fm-lg font-bold">
+                  !
+                </span>
+              </div>
+              <p className="text-fm-primary font-fm-brand text-fm-lg leading-fm-lg mb-2 font-semibold">
+                Remove from library?
+              </p>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-xl mb-6">
+                This will remove the album from your library. You can always add
+                it back later.
+              </p>
+              <div className="flex gap-3">
+                <Button
+                  variant="outline"
+                  size="sm"
+                  onClick={() => setShowConfirm(false)}
+                  className="flex-1"
+                >
+                  Cancel
+                </Button>
+                <Button
+                  variant="secondary"
+                  size="sm"
+                  onClick={() => setShowConfirm(false)}
+                  className="flex-1"
+                >
+                  Remove
+                </Button>
+              </div>
+            </div>
+          </Overlay>
         )}
       </div>
     )
@@ -953,7 +581,7 @@ export const CombinedEffectsShowcase: Story = {
     docs: {
       description: {
         story:
-          "Curated combinations of opacity, glass, and noise effects showing different aesthetic approaches from minimal to premium styling.",
+          "Live interaction examples: a search modal (medium opacity, medium glass) and a confirmation dialog (high opacity, high glass). Demonstrates real-world overlay usage with controlled open/close state and accessible focus management.",
       },
     },
   },