aural-ui 4.0.1 → 4.2.0

package/dist/components/dialog/Dialog.stories.tsx

@@ -1,17 +1,10 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import React, { useState } from "react"
 import { Button } from "@components/button"
-import { Checkbox } from "@components/checkbox"
-import Input from "@components/input"
-import { Label } from "@components/label"
-import Textarea from "@components/textarea"
-import { AlertIcon } from "@icons/alert-icon"
-import { EditBigIcon } from "@icons/edit-big-icon"
-import { LightBulbSimpleIcon } from "@icons/light-bulb-simple-icon"
-import { TickIcon } from "@icons/tick-icon"
-import { TrashIcon } from "@icons/trash-icon"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import {
   Dialog,
   DialogClose,
@@ -29,90 +22,41 @@ const meta: Meta<typeof DialogContent> = {
   component: Dialog,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-# Dialog Component
-
-A modal dialog component built on Radix UI primitives with customizable overlays, animations, variant styling, and configurable border sides. Includes React 18 compatibility fixes for pointer-events issues.
-
-## Features
-
-- **Multiple Variants**: Neutral, positive, negative, warning, and info styles
-- **Configurable Borders**: Support for all sides, specific sides, or no borders
-- **Custom Overlays**: Configurable opacity, glass effect, and noise texture
-- **Smooth Animations**: Zoom in/out animations with duration control
-- **Accessible**: Full keyboard navigation and screen reader support
-- **Flexible Content**: Header, footer, and body sections with custom styling
-- **Close Button**: Positioned close button with icon
-- **Portal Rendering**: Renders outside normal DOM hierarchy
-- **Focus Management**: Automatic focus trapping and restoration
-- **React 18 Fix**: Includes \`useDialogCleanup\` hook for pointer-events issues
-
-## Border Configuration
-
-The \`borderConfig\` prop allows you to control which sides of the dialog have gradient borders:
-
-- \`"none"\` - No borders
-- \`"all"\` - All four sides
-- \`"top"\` - Top border only (default)
-- \`["top", "bottom"]\` - Top and bottom borders
-- \`["left", "right"]\` - Left and right borders
-- \`["top", "left", "right"]\` - Top, left, and right borders
-
-## Usage Examples
-
-### Basic Dialog with Border Configuration
-\`\`\`tsx
-import { Dialog, DialogContent, DialogTrigger } from '@/components/dialog'
-
-// All borders
-<DialogContent borderConfig="all" variant="positive">
-  Content with borders on all sides
-</DialogContent>
-
-// Specific sides
-<DialogContent borderConfig={["top", "bottom"]} variant="warning">
-  Content with top and bottom borders
-</DialogContent>
-
-// No borders
-<DialogContent borderConfig="none" variant="neutral">
-  Content without any borders
-</DialogContent>
-\`\`\`
-        `,
+        component:
+          "A modal dialog built on Radix UI primitives with configurable variant borders, glass/noise overlays, and zoom animations. Includes useDialogCleanup for React 18 pointer-events compatibility.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "5 Variant Borders",
+              description: "Neutral to negative",
+            },
+            {
+              title: "Glass & Noise Overlay",
+              description: "Blur and grain levels",
+            },
+            {
+              title: "Focus Trap",
+              description: "Keyboard & ARIA safe",
+            },
+          ]}
+        />
+      ),
     },
   },
   argTypes: {
     variant: {
       control: { type: "select" },
       options: ["neutral", "positive", "negative", "warning", "info"],
-      description: "Dialog variant for different use cases",
+      description: "Dialog border-shadow variant",
     },
     borderConfig: {
       control: { type: "select" },
-      options: [
-        "none",
-        "all",
-        "top",
-        "bottom",
-        "left",
-        "right",
-        ["top", "bottom"],
-        ["left", "right"],
-        ["top", "left", "right"],
-        ["bottom", "left", "right"],
-      ],
-      description: "Border configuration - which sides to show borders on",
+      options: ["none", "all", "top", "bottom", "left", "right"],
+      description: "Which sides display gradient border accents",
     },
     opacity: {
       control: { type: "select" },
@@ -122,7 +66,7 @@ import { Dialog, DialogContent, DialogTrigger } from '@/components/dialog'
     glass: {
       control: { type: "select" },
       options: ["high", "medium", "low", "none"],
-      description: "Glass blur effect intensity",
+      description: "Backdrop blur intensity",
     },
     noise: {
       control: { type: "select" },
@@ -131,7 +75,7 @@ import { Dialog, DialogContent, DialogTrigger } from '@/components/dialog'
     },
     showCloseButton: {
       control: "boolean",
-      description: "Show/hide the close button",
+      description: "Show the floating close button above the dialog",
     },
   },
   tags: ["autodocs"],
@@ -140,964 +84,541 @@ import { Dialog, DialogContent, DialogTrigger } from '@/components/dialog'
 export default meta
 type Story = StoryObj<typeof Dialog>
 
-// 1. Border Configuration Examples
-export const BorderConfigurations: Story = {
-  render: () => {
-    const BorderConfigDialog = ({
-      borderConfig,
-      variant,
-      title,
-      description,
-    }: any) => {
-      const { handleDialogClose } = useDialogCleanup({ threshold: 100 })
-
-      return (
-        <Dialog>
-          <DialogTrigger asChild>
-            <Button variant="outline" size="sm">
-              {title}
-            </Button>
-          </DialogTrigger>
-          <DialogContent
-            variant={variant}
-            borderConfig={borderConfig}
-            //@ts-expect-error onEscapeKeyDown available in Radix v2.0.0
-            onEscapeKeyDown={handleDialogClose}
-            onPointerDownOutside={handleDialogClose}
-          >
-            <DialogHeader>
-              <DialogTitle>{title}</DialogTitle>
-              <DialogDescription>{description}</DialogDescription>
-            </DialogHeader>
-            <div className="py-4">
-              <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-3">
-                <div className="text-fm-secondary space-y-1 text-xs">
-                  <div>
-                    Variant: <span className="text-fm-primary">{variant}</span>
-                  </div>
-                  <div>
-                    Border Config:{" "}
-                    <span className="text-fm-primary">
-                      {Array.isArray(borderConfig)
-                        ? `[${borderConfig.join(", ")}]`
-                        : borderConfig}
-                    </span>
-                  </div>
-                </div>
-              </div>
-            </div>
-            <DialogFooter>
-              <DialogClose asChild>
-                <Button onClick={handleDialogClose}>Close</Button>
-              </DialogClose>
-            </DialogFooter>
-          </DialogContent>
-        </Dialog>
-      )
-    }
-
-    return (
-      <div className="space-y-8">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 font-medium">
-            Border Configurations
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Explore different border configurations for dialog variants
-          </p>
-        </div>
-
-        <div className="space-y-6">
-          {/* All Borders */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">
-              All Borders
-            </h4>
-            <div className="flex flex-wrap gap-2">
-              <BorderConfigDialog
-                borderConfig="all"
-                variant="neutral"
-                title="All - Neutral"
-                description="Dialog with borders on all four sides"
-              />
-              <BorderConfigDialog
-                borderConfig="all"
-                variant="positive"
-                title="All - Success"
-                description="Success dialog with complete border frame"
-              />
-              <BorderConfigDialog
-                borderConfig="all"
-                variant="negative"
-                title="All - Error"
-                description="Error dialog with full border emphasis"
-              />
-            </div>
-          </div>
-
-          {/* Single Sides */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">
-              Single Side Borders
-            </h4>
-            <div className="flex flex-wrap gap-2">
-              <BorderConfigDialog
-                borderConfig="top"
-                variant="info"
-                title="Top Only"
-                description="Dialog with top border accent"
-              />
-              <BorderConfigDialog
-                borderConfig="bottom"
-                variant="warning"
-                title="Bottom Only"
-                description="Dialog with bottom border accent"
-              />
-              <BorderConfigDialog
-                borderConfig="left"
-                variant="positive"
-                title="Left Only"
-                description="Dialog with left border accent"
-              />
-              <BorderConfigDialog
-                borderConfig="right"
-                variant="negative"
-                title="Right Only"
-                description="Dialog with right border accent"
-              />
-            </div>
-          </div>
-
-          {/* Two Sides */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">
-              Two Side Borders
-            </h4>
-            <div className="flex flex-wrap gap-2">
-              <BorderConfigDialog
-                borderConfig={["top", "bottom"]}
-                variant="neutral"
-                title="Top + Bottom"
-                description="Horizontal border emphasis"
-              />
-              <BorderConfigDialog
-                borderConfig={["left", "right"]}
-                variant="info"
-                title="Left + Right"
-                description="Vertical border emphasis"
-              />
-              <BorderConfigDialog
-                borderConfig={["top", "left"]}
-                variant="warning"
-                title="Top + Left"
-                description="Corner border accent"
-              />
-              <BorderConfigDialog
-                borderConfig={["bottom", "right"]}
-                variant="positive"
-                title="Bottom + Right"
-                description="Opposite corner accent"
-              />
-            </div>
-          </div>
-
-          {/* Three Sides */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">
-              Three Side Borders
-            </h4>
-            <div className="flex flex-wrap gap-2">
-              <BorderConfigDialog
-                borderConfig={["top", "left", "right"]}
-                variant="negative"
-                title="Top + Left + Right"
-                description="Open bottom design"
-              />
-              <BorderConfigDialog
-                borderConfig={["bottom", "left", "right"]}
-                variant="warning"
-                title="Bottom + Left + Right"
-                description="Open top design"
-              />
-            </div>
-          </div>
-
-          {/* No Border */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">
-              No Borders
-            </h4>
-            <div className="flex flex-wrap gap-2">
-              <BorderConfigDialog
-                borderConfig="none"
-                variant="neutral"
-                title="No Borders"
-                description="Clean minimal design without border accents"
-              />
-            </div>
-          </div>
+// ─── Configurations ────────────────────────────────────────────────────────────
+
+const ConfigDialog = ({
+  borderConfig,
+  variant,
+  opacity,
+  glass,
+  noise,
+  showCloseButton,
+  triggerLabel,
+  title,
+  description,
+}: any) => {
+  const { handleDialogClose } = useDialogCleanup({ threshold: 100 })
+  return (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button variant="outline" size="sm">
+          {triggerLabel}
+        </Button>
+      </DialogTrigger>
+      <DialogContent
+        variant={variant}
+        borderConfig={borderConfig}
+        opacity={opacity}
+        glass={glass}
+        noise={noise}
+        showCloseButton={showCloseButton}
+      >
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+          <DialogDescription>{description}</DialogDescription>
+        </DialogHeader>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+          <code className="text-fm-secondary text-fm-sm leading-fm-sm font-(--font-fm-mono)">
+            {`variant="${variant}" borderConfig="${Array.isArray(borderConfig) ? `[${borderConfig.join(", ")}]` : borderConfig}"`}
+          </code>
         </div>
-      </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Comprehensive showcase of all border configuration options across different variants.",
-      },
-    },
-  },
+        <DialogFooter>
+          <DialogClose asChild>
+            <Button onClick={handleDialogClose}>Close</Button>
+          </DialogClose>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
 }
 
-// 2. Dialog Cleanup Example - React 18 Compatibility
-export const DialogCleanupExample: Story = {
-  render: () => {
-    const DialogWithCleanup = () => {
-      const { handleDialogClose } = useDialogCleanup({ threshold: 100 })
-      const [isOpen, setIsOpen] = useState(false)
-
-      const handleClose = () => {
-        handleDialogClose()
-        setIsOpen(false)
-      }
-
-      return (
-        <Dialog open={isOpen} onOpenChange={setIsOpen}>
-          <DialogTrigger asChild>
-            <Button>Open Dialog with Cleanup</Button>
-          </DialogTrigger>
-          <DialogContent
-            variant="info"
-            //@ts-expect-error onEscapeKeyDown available in Radix v2.0.0
-            onEscapeKeyDown={handleClose}
-            onPointerDownOutside={handleClose}
-          >
-            <DialogHeader>
-              <DialogTitle>Dialog with React 18 Fix</DialogTitle>
-              <DialogDescription>
-                This dialog uses useDialogCleanup to prevent pointer-events
-                issues in React 18.
-              </DialogDescription>
-            </DialogHeader>
-            <div className="py-4">
-              <div className="border-fm-info bg-fm-surface-info-sec rounded-lg border p-3">
-                <p className="text-fm-info text-sm">
-                  The useDialogCleanup hook ensures that pointer-events: none
-                  doesn't get stuck on the body element when the dialog closes,
-                  which was a common issue in React 18.
-                </p>
-              </div>
-            </div>
-            <DialogFooter>
-              <DialogClose asChild>
-                <Button variant="outline" onClick={handleClose}>
-                  Cancel
-                </Button>
-              </DialogClose>
-              <Button onClick={handleClose}>Confirm</Button>
-            </DialogFooter>
-          </DialogContent>
-        </Dialog>
-      )
-    }
-
-    return (
-      <div className="space-y-8">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 font-medium">
-            Dialog Cleanup Hook
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Demonstrates useDialogCleanup hook for React 18 compatibility
-          </p>
-        </div>
-        <div className="flex justify-center">
-          <DialogWithCleanup />
+export const Configurations: Story = {
+  render: () => (
+    <div className="space-y-8">
+      {/* Variant types */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Variant Types
+        </h4>
+        <div className="flex flex-wrap gap-2">
+          {(
+            ["neutral", "positive", "negative", "warning", "info"] as const
+          ).map((v) => (
+            <ConfigDialog
+              key={v}
+              variant={v}
+              borderConfig={["top"]}
+              triggerLabel={v.charAt(0).toUpperCase() + v.slice(1)}
+              title={`${v.charAt(0).toUpperCase() + v.slice(1)} Dialog`}
+              description={`Top border accent with ${v} variant shadow.`}
+            />
+          ))}
         </div>
       </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Example showing how to use useDialogCleanup hook to fix React 18 pointer-events issues.",
-      },
-    },
-  },
-}
 
-// 3. Basic Dialog Variants with Border Styles
-export const BasicVariants: Story = {
-  render: () => {
-    const DialogWithCleanupVariant = ({
-      variant,
-      borderConfig,
-      title,
-      description,
-      children,
-    }: any) => {
-      const { handleDialogClose } = useDialogCleanup({ threshold: 100 })
-
-      return (
-        <Dialog>
-          <DialogTrigger asChild>
-            <Button variant="outline">{title}</Button>
-          </DialogTrigger>
-          <DialogContent
-            variant={variant}
-            borderConfig={borderConfig}
-            //@ts-expect-error onEscapeKeyDown available in Radix v2.0.0
-            onEscapeKeyDown={handleDialogClose}
-            onPointerDownOutside={handleDialogClose}
-          >
-            <DialogHeader>
-              <DialogTitle>{title}</DialogTitle>
-              <DialogDescription>{description}</DialogDescription>
-            </DialogHeader>
-            <div className="py-4">{children}</div>
-            <DialogFooter>
-              <DialogClose asChild>
-                <Button variant="outline" onClick={handleDialogClose}>
-                  Cancel
-                </Button>
-              </DialogClose>
-              <Button onClick={handleDialogClose}>Continue</Button>
-            </DialogFooter>
-          </DialogContent>
-        </Dialog>
-      )
-    }
-
-    return (
-      <div className="space-y-8">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 font-medium">
-            Dialog Variants with Border Styles
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Different dialog variants with customized border configurations
-          </p>
-        </div>
-
-        <div className="flex flex-wrap justify-center gap-4">
-          <DialogWithCleanupVariant
+      {/* Border configurations */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Border Configurations
+        </h4>
+        <div className="flex flex-wrap gap-2">
+          <ConfigDialog
             variant="neutral"
-            title="Neutral Dialog"
-            description="This is a neutral dialog with top border."
-          >
-            <p className="text-fm-secondary text-sm">
-              Neutral dialogs with minimal top border accent are perfect for
-              general information and settings.
-            </p>
-          </DialogWithCleanupVariant>
-
-          <DialogWithCleanupVariant
+            borderConfig="none"
+            triggerLabel="No border"
+            title="No Borders"
+            description="Clean dialog with no accent borders."
+          />
+          <ConfigDialog
+            variant="info"
+            borderConfig={["top"]}
+            triggerLabel="Top only"
+            title="Top Border"
+            description="Single top accent — the default configuration."
+          />
+          <ConfigDialog
             variant="positive"
-            title="Success Dialog"
-            description="Operation completed successfully!"
-          >
-            <div className="mb-2 flex items-center gap-2">
-              <TickIcon className="text-fm-positive h-5 w-5" />
-              <span className="text-fm-positive font-medium">Success!</span>
-            </div>
-            <p className="text-fm-secondary text-sm">
-              Success dialogs with full border frame provide strong positive
-              feedback.
-            </p>
-          </DialogWithCleanupVariant>
-
-          <DialogWithCleanupVariant
+            borderConfig="all"
+            triggerLabel="All sides"
+            title="All Borders"
+            description="Full border frame on all four sides."
+          />
+          <ConfigDialog
             variant="warning"
-            title="Warning Dialog"
-            description="Please review the following before proceeding."
-          >
-            <div className="border-fm-divider-warning bg-fm-surface-warning-alpha-15 rounded-lg border p-3">
-              <div className="mb-2 flex items-center gap-2">
-                <AlertIcon className="text-fm-warning h-4 w-4" />
-                <span className="text-fm-warning font-medium">Warning</span>
-              </div>
-              <p className="text-fm-warning-sec text-sm">
-                Warning dialogs with horizontal borders create focused
-                attention.
-              </p>
-            </div>
-          </DialogWithCleanupVariant>
-
-          <DialogWithCleanupVariant
+            borderConfig={["top", "bottom"]}
+            triggerLabel="Top + Bottom"
+            title="Horizontal Borders"
+            description="Top and bottom accent borders."
+          />
+          <ConfigDialog
             variant="negative"
-            title="Error Dialog"
-            description="An error occurred that requires your attention."
-          >
-            <div className="border-fm-divider-negative bg-fm-surface-negative-alpha-15 rounded-lg border p-3">
-              <div className="mb-2 flex items-center gap-2">
-                <AlertIcon className="text-fm-negative h-4 w-4" />
-                <span className="text-fm-negative font-medium">Error</span>
-              </div>
-              <p className="text-fm-negative-sec text-sm">
-                Error dialogs with vertical borders provide urgent visual cues.
-              </p>
-            </div>
-          </DialogWithCleanupVariant>
-
-          <DialogWithCleanupVariant
+            borderConfig={["left", "right"]}
+            triggerLabel="Left + Right"
+            title="Vertical Borders"
+            description="Left and right accent borders."
+          />
+          <ConfigDialog
             variant="info"
-            title="Information Dialog"
-            description="Here's some important information for you."
-          >
-            <div className="border-fm-info bg-fm-surface-info-alpha-15 rounded-lg border p-3">
-              <div className="mb-2 flex items-center gap-2">
-                <LightBulbSimpleIcon className="text-fm-info h-4 w-4" />
-                <span className="text-fm-info font-medium">Information</span>
-              </div>
-              <p className="text-fm-info-sec text-sm">
-                Clean info dialogs without borders for minimal, focused content
-                presentation.
-              </p>
-            </div>
-          </DialogWithCleanupVariant>
+            borderConfig={["top", "left", "right"]}
+            triggerLabel="Three sides"
+            title="Three-Side Borders"
+            description="Open-bottom border configuration."
+          />
         </div>
       </div>
-    )
-  },
+
+      {/* Glass / noise overlay */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Glass &amp; Noise Overlay Options
+        </h4>
+        <div className="flex flex-wrap gap-2">
+          <ConfigDialog
+            variant="neutral"
+            borderConfig={["top"]}
+            opacity="low"
+            triggerLabel="Low opacity"
+            title="Low Opacity Overlay"
+            description="Subtle background dimming, more of the page remains visible."
+          />
+          <ConfigDialog
+            variant="neutral"
+            borderConfig={["top"]}
+            opacity="high"
+            triggerLabel="High opacity"
+            title="High Opacity Overlay"
+            description="Strong background dimming that focuses attention on the dialog."
+          />
+          <ConfigDialog
+            variant="neutral"
+            borderConfig={["top"]}
+            glass="high"
+            triggerLabel="High glass"
+            title="Glass Blur Overlay"
+            description="Frosted-glass backdrop blur effect at high intensity."
+          />
+          <ConfigDialog
+            variant="neutral"
+            borderConfig={["top"]}
+            noise="medium"
+            triggerLabel="Noise texture"
+            title="Noise Texture Overlay"
+            description="Adds a subtle grain texture to the background overlay."
+          />
+          <ConfigDialog
+            variant="neutral"
+            borderConfig={["top"]}
+            showCloseButton={false}
+            triggerLabel="No close btn"
+            title="No Close Button"
+            description="Dialog without the floating circular close button — close via footer."
+          />
+        </div>
+      </div>
+    </div>
+  ),
   parameters: {
     docs: {
       description: {
         story:
-          "Different dialog variants showcasing various border configurations for enhanced visual hierarchy.",
+          "Comparison of all variant types, border configurations, and overlay options (glass, noise, opacity) available on the Dialog component.",
       },
     },
   },
 }
 
-// 4. Nested Modal with Cleanup
-export const NestedModalWithCleanup: Story = {
+// ─── Interactive ───────────────────────────────────────────────────────────────
+
+export const Interactive: Story = {
   render: () => {
-    const NestedDialogComponent = () => {
-      const { handleDialogClose } = useDialogCleanup({ threshold: 150 })
-      const [isEditOpen, setIsEditOpen] = useState(false)
-      const [isDeleteOpen, setIsDeleteOpen] = useState(false)
+    const InteractiveDemo = () => {
+      const { handleDialogClose } = useDialogCleanup({ threshold: 100 })
+      const [isOpen, setIsOpen] = useState(false)
+      const [variant, setVariant] = useState<
+        "neutral" | "positive" | "negative" | "warning" | "info"
+      >("neutral")
+      const [borderConfig, setBorderConfig] = useState<
+        "none" | "all" | "top" | "bottom" | "left" | "right"
+      >("top")
+      const [glass, setGlass] = useState<"high" | "medium" | "low" | "none">(
+        "none"
+      )
+      const [noise, setNoise] = useState<"high" | "medium" | "low" | "none">(
+        "none"
+      )
+      const [opacity, setOpacity] = useState<
+        "high" | "medium" | "low" | "none"
+      >("medium")
+      const [lastAction, setLastAction] = useState<string | null>(null)
 
-      const handleEditClose = () => {
+      const handleConfirm = () => {
+        setLastAction("confirmed")
         handleDialogClose()
-        setIsEditOpen(false)
+        setIsOpen(false)
       }
 
-      const handleDeleteClose = () => {
+      const handleCancel = () => {
+        setLastAction("cancelled")
         handleDialogClose()
-        setIsDeleteOpen(false)
+        setIsOpen(false)
       }
 
-      const handleDelete = () => {
-        console.log("User deleted")
-        handleDeleteClose()
-        handleEditClose()
-      }
+      const variantOptions = [
+        "neutral",
+        "positive",
+        "negative",
+        "warning",
+        "info",
+      ] as const
+      const borderOptions = [
+        "none",
+        "top",
+        "bottom",
+        "left",
+        "right",
+        "all",
+      ] as const
+      const levelOptions = ["none", "low", "medium", "high"] as const
+
+      const btnCls = (active: boolean) =>
+        `font-fm-text text-fm-sm leading-fm-sm rounded px-2 py-1 outline-none transition-colors ${
+          active
+            ? "bg-fm-surface-contrast text-fm-contrast"
+            : "bg-fm-surface-secondary text-fm-secondary hover:text-fm-primary"
+        }`
+
+      // borderConfig state is a single string key; map to actual BorderConfig when passing to component
+      const resolvedBorderConfig: any =
+        borderConfig === "all" || borderConfig === "none"
+          ? borderConfig
+          : borderConfig
 
       return (
-        <>
-          <Dialog open={isEditOpen} onOpenChange={setIsEditOpen}>
-            <DialogTrigger asChild>
-              <Button className="gap-2">
-                <EditBigIcon className="h-4 w-4" />
-                Edit with Cleanup
-              </Button>
-            </DialogTrigger>
-            <DialogContent
-              className="max-w-md"
-              variant="neutral"
-              //@ts-expect-error onEscapeKeyDown available in Radix v2.0.0
-              onEscapeKeyDown={handleEditClose}
-              onPointerDownOutside={handleEditClose}
-            >
-              <DialogHeader>
-                <DialogTitle>Edit User Profile</DialogTitle>
-                <DialogDescription>
-                  Update user information or delete the account.
-                </DialogDescription>
-              </DialogHeader>
-
-              <div className="space-y-4">
-                <Input placeholder="User name" />
-                <Input placeholder="Email address" type="email" />
-                <Textarea placeholder="Bio" rows={3} />
-              </div>
+        <div className="w-full p-8">
+          <div className="mx-auto max-w-3xl space-y-6">
+            <div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
+              {/* Controls panel */}
+              <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-5 rounded-xl border p-5">
+                <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                  Configuration
+                </p>
 
-              <DialogFooter className="flex-col space-y-2 sm:flex-col sm:space-y-2 sm:space-x-0">
-                <div className="flex gap-2 sm:order-2">
-                  <Button
-                    variant="outline"
-                    onClick={handleEditClose}
-                    className="flex-1"
-                  >
-                    Cancel
-                  </Button>
-                  <Button className="flex-1">Save Changes</Button>
-                </div>
-                <div className="sm:order-1">
-                  <Button
-                    size="sm"
-                    className="mb-4 w-full gap-2"
-                    onClick={() => setIsDeleteOpen(true)}
-                  >
-                    <TrashIcon className="h-4 w-4" />
-                    Delete Account
-                  </Button>
+                <div className="space-y-2">
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Variant
+                  </p>
+                  <div className="flex flex-wrap gap-1">
+                    {variantOptions.map((v) => (
+                      <button
+                        key={v}
+                        onClick={() => setVariant(v)}
+                        className={btnCls(variant === v)}
+                      >
+                        {v}
+                      </button>
+                    ))}
+                  </div>
                 </div>
-              </DialogFooter>
-            </DialogContent>
-          </Dialog>
 
-          <Dialog open={isDeleteOpen} onOpenChange={setIsDeleteOpen}>
-            <DialogContent
-              variant="negative"
-              classes={{
-                root: "max-w-sm",
-                overlay: "z-60",
-                content: "z-70",
-              }}
-              //@ts-expect-error onEscapeKeyDown available in Radix v2.0.0
-              onEscapeKeyDown={handleDeleteClose}
-              onPointerDownOutside={handleDeleteClose}
-            >
-              <DialogHeader>
-                <DialogTitle className="flex items-center gap-2">
-                  <AlertIcon className="text-fm-negative h-5 w-5" />
-                  Delete Account
-                </DialogTitle>
-                <DialogDescription>
-                  This action cannot be undone.
-                </DialogDescription>
-              </DialogHeader>
+                <div className="border-fm-divider-secondary border-t pt-4" />
 
-              <div className="py-4">
-                <div className="border-fm-divider-negative bg-fm-surface-negative-alpha-15 rounded-lg border p-3">
-                  <p className="text-fm-negative-sec text-sm">
-                    Are you absolutely sure you want to delete this account?
-                    This will permanently remove all associated data.
+                <div className="space-y-2">
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Border Config
                   </p>
+                  <div className="flex flex-wrap gap-1">
+                    {borderOptions.map((b) => (
+                      <button
+                        key={b}
+                        onClick={() => setBorderConfig(b)}
+                        className={btnCls(borderConfig === b)}
+                      >
+                        {b}
+                      </button>
+                    ))}
+                  </div>
                 </div>
-              </div>
 
-              <DialogFooter>
-                <Button variant="outline" onClick={handleDeleteClose}>
-                  Cancel
-                </Button>
-                <Button onClick={handleDelete} className="gap-2">
-                  <TrashIcon className="h-4 w-4" />
-                  Delete Forever
-                </Button>
-              </DialogFooter>
-            </DialogContent>
-          </Dialog>
-        </>
-      )
-    }
+                <div className="border-fm-divider-secondary border-t pt-4" />
 
-    return (
-      <div className="space-y-8">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 font-medium">
-            Nested Modal with Custom Borders
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Modal-on-modal with different border configurations
-          </p>
-        </div>
-        <div className="flex justify-center">
-          <NestedDialogComponent />
-        </div>
-      </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Nested modal example showcasing different border configurations for modal hierarchy.",
-      },
-    },
-  },
-}
-
-// 5. Form Dialog with Cleanup
-export const FormDialog: Story = {
-  render: () => {
-    const FormDialogComponent = () => {
-      const { handleDialogClose } = useDialogCleanup({ threshold: 100 })
-      const [formData, setFormData] = useState({
-        name: "",
-        email: "",
-        message: "",
-        newsletter: false,
-      })
-
-      const handleClose = () => {
-        handleDialogClose()
-        // Reset form data on close
-        setFormData({
-          name: "",
-          email: "",
-          message: "",
-          newsletter: false,
-        })
-      }
-
-      return (
-        <Dialog>
-          <DialogTrigger asChild>
-            <Button className="gap-2">
-              <EditBigIcon className="h-4 w-4" />
-              Contact Form
-            </Button>
-          </DialogTrigger>
-          <DialogContent
-            className="max-w-md"
-            variant="info"
-            //@ts-expect-error onEscapeKeyDown available in Radix v2.0.0
-            onEscapeKeyDown={handleClose}
-            onPointerDownOutside={handleClose}
-          >
-            <DialogHeader>
-              <DialogTitle>Contact Us</DialogTitle>
-              <DialogDescription>
-                Send us a message and we'll get back to you soon.
-              </DialogDescription>
-            </DialogHeader>
-
-            <div className="space-y-4">
-              <div className="space-y-2">
-                <Label htmlFor="name">Name</Label>
-                <Input
-                  id="name"
-                  placeholder="Your name"
-                  value={formData.name}
-                  onChange={(e) =>
-                    setFormData((prev) => ({ ...prev, name: e.target.value }))
-                  }
-                />
-              </div>
-
-              <div className="space-y-2">
-                <Label htmlFor="email">Email</Label>
-                <Input
-                  id="email"
-                  type="email"
-                  placeholder="your.email@example.com"
-                  value={formData.email}
-                  onChange={(e) =>
-                    setFormData((prev) => ({
-                      ...prev,
-                      email: e.target.value,
-                    }))
-                  }
-                />
-              </div>
+                <div className="space-y-2">
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Opacity
+                  </p>
+                  <div className="flex flex-wrap gap-1">
+                    {levelOptions.map((o) => (
+                      <button
+                        key={o}
+                        onClick={() => setOpacity(o)}
+                        className={btnCls(opacity === o)}
+                      >
+                        {o}
+                      </button>
+                    ))}
+                  </div>
+                </div>
 
-              <div className="space-y-2">
-                <Label htmlFor="message">Message</Label>
-                <Textarea
-                  id="message"
-                  placeholder="Your message..."
-                  rows={4}
-                  value={formData.message}
-                  onChange={(e) =>
-                    setFormData((prev) => ({
-                      ...prev,
-                      message: e.target.value,
-                    }))
-                  }
-                />
-              </div>
+                <div className="space-y-2">
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Glass
+                  </p>
+                  <div className="flex flex-wrap gap-1">
+                    {levelOptions.map((g) => (
+                      <button
+                        key={g}
+                        onClick={() => setGlass(g)}
+                        className={btnCls(glass === g)}
+                      >
+                        {g}
+                      </button>
+                    ))}
+                  </div>
+                </div>
 
-              <div className="flex items-center space-x-2">
-                <Checkbox
-                  id="newsletter"
-                  checked={formData.newsletter}
-                  onCheckedChange={(checked) =>
-                    setFormData((prev) => ({
-                      ...prev,
-                      newsletter: !!checked,
-                    }))
-                  }
-                />
-                <Label htmlFor="newsletter" className="text-sm">
-                  Subscribe to newsletter
-                </Label>
+                <div className="space-y-2">
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Noise
+                  </p>
+                  <div className="flex flex-wrap gap-1">
+                    {levelOptions.map((n) => (
+                      <button
+                        key={n}
+                        onClick={() => setNoise(n)}
+                        className={btnCls(noise === n)}
+                      >
+                        {n}
+                      </button>
+                    ))}
+                  </div>
+                </div>
               </div>
-            </div>
-
-            <DialogFooter>
-              <DialogClose asChild>
-                <Button variant="outline" onClick={handleClose}>
-                  Cancel
-                </Button>
-              </DialogClose>
-              <Button
-                disabled={
-                  !formData.name || !formData.email || !formData.message
-                }
-                onClick={() => {
-                  console.log("Form submitted:", formData)
-                  handleClose()
-                }}
-              >
-                Send Message
-              </Button>
-            </DialogFooter>
-          </DialogContent>
-        </Dialog>
-      )
-    }
-
-    return (
-      <div className="space-y-8">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 font-medium">Form Dialog</h3>
-          <p className="text-fm-secondary text-sm">
-            Dialog containing form elements with horizontal border accent
-          </p>
-        </div>
-        <div className="flex justify-center">
-          <FormDialogComponent />
-        </div>
-      </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Form dialog with validation and horizontal border configuration for focused data entry.",
-      },
-    },
-  },
-}
 
-// 6. Overlay Variations
-export const OverlayVariations: Story = {
-  render: () => {
-    const OverlayDialog = ({
-      opacity,
-      glass,
-      noise,
-      borderConfig,
-      title,
-      description,
-    }: any) => {
-      const { handleDialogClose } = useDialogCleanup({ threshold: 100 })
-
-      return (
-        <Dialog>
-          <DialogTrigger asChild>
-            <Button variant="outline" size="sm">
-              {title}
-            </Button>
-          </DialogTrigger>
-          <DialogContent
-            opacity={opacity}
-            glass={glass}
-            noise={noise}
-            borderConfig={borderConfig}
-            variant="neutral"
-          >
-            <DialogHeader>
-              <DialogTitle>{title}</DialogTitle>
-              <DialogDescription>{description}</DialogDescription>
-            </DialogHeader>
-            <div className="py-4">
-              <div className="text-fm-secondary grid grid-cols-2 gap-2 text-xs">
-                <div>
-                  Opacity:{" "}
-                  <span className="text-fm-primary">
-                    {opacity || "default"}
-                  </span>
-                </div>
-                <div>
-                  Glass:{" "}
-                  <span className="text-fm-primary">{glass || "default"}</span>
+              {/* Preview stage */}
+              <div className="flex flex-col gap-3 lg:col-span-2">
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary flex min-h-48 flex-col items-center justify-center gap-4 rounded-xl border p-8">
+                  {lastAction && (
+                    <div
+                      className={`rounded-lg border px-4 py-2 ${
+                        lastAction === "confirmed"
+                          ? "border-fm-divider-positive bg-fm-surface-positive-sec"
+                          : "border-fm-divider-secondary bg-fm-surface-secondary"
+                      }`}
+                    >
+                      <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                        Last action:{" "}
+                        <span className="text-fm-primary font-medium">
+                          {lastAction}
+                        </span>
+                      </p>
+                    </div>
+                  )}
+
+                  <Dialog open={isOpen} onOpenChange={setIsOpen}>
+                    <DialogTrigger asChild>
+                      <Button onClick={() => setLastAction(null)}>
+                        Open Dialog
+                      </Button>
+                    </DialogTrigger>
+                    <DialogContent
+                      variant={variant}
+                      borderConfig={resolvedBorderConfig}
+                      opacity={opacity}
+                      glass={glass}
+                      noise={noise}
+                    >
+                      <DialogHeader>
+                        <DialogTitle>Confirm Action</DialogTitle>
+                        <DialogDescription>
+                          Review the current configuration then confirm or
+                          cancel to see live state feedback below.
+                        </DialogDescription>
+                      </DialogHeader>
+
+                      <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+                        <code className="text-fm-secondary text-fm-sm leading-fm-sm font-(--font-fm-mono)">
+                          {`variant="${variant}" border="${borderConfig}" opacity="${opacity}" glass="${glass}" noise="${noise}"`}
+                        </code>
+                      </div>
+
+                      <DialogFooter>
+                        <Button variant="outline" onClick={handleCancel}>
+                          Cancel
+                        </Button>
+                        <Button onClick={handleConfirm}>Confirm</Button>
+                      </DialogFooter>
+                    </DialogContent>
+                  </Dialog>
                 </div>
-                <div>
-                  Noise:{" "}
-                  <span className="text-fm-primary">{noise || "none"}</span>
-                </div>
-                <div>
-                  Border:{" "}
-                  <span className="text-fm-primary">
-                    {Array.isArray(borderConfig)
-                      ? `[${borderConfig.join(", ")}]`
-                      : borderConfig || "top"}
-                  </span>
+
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+                  <code className="text-fm-secondary text-fm-sm leading-fm-sm font-(--font-fm-mono)">
+                    {`<DialogContent variant="${variant}" borderConfig="${borderConfig}" opacity="${opacity}" glass="${glass}" noise="${noise}" />`}
+                  </code>
                 </div>
               </div>
             </div>
-            <DialogFooter>
-              <DialogClose asChild>
-                <Button onClick={handleDialogClose}>Close</Button>
-              </DialogClose>
-            </DialogFooter>
-          </DialogContent>
-        </Dialog>
+          </div>
+        </div>
       )
     }
 
-    return (
-      <div className="space-y-8">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 font-medium">
-            Overlay Variations with Borders
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Different overlay effects combined with border configurations
-          </p>
-        </div>
-
-        <div className="grid grid-cols-2 gap-4 md:grid-cols-3 lg:grid-cols-4">
-          <OverlayDialog
-            opacity="low"
-            title="Low Opacity"
-            description="Subtle background dimming (40%)"
-          />
-          <OverlayDialog
-            opacity="medium"
-            title="Medium Opacity"
-            description="Balanced background dimming (60%)"
-          />
-          <OverlayDialog
-            opacity="high"
-            title="High Opacity"
-            description="Strong background dimming (80%)"
-          />
-          <OverlayDialog
-            opacity="none"
-            title="Full Opacity"
-            description="Complete background coverage (100%)"
-          />
-          <OverlayDialog
-            glass="low"
-            title="Low Glass"
-            description="Subtle backdrop blur effect"
-          />
-          <OverlayDialog
-            glass="medium"
-            title="Medium Glass"
-            description="Balanced backdrop blur effect"
-          />
-          <OverlayDialog
-            glass="high"
-            title="High Glass"
-            description="Strong backdrop blur effect"
-          />
-          <OverlayDialog
-            noise="low"
-            title="Low Noise"
-            description="Subtle texture pattern"
-          />
-        </div>
-      </div>
-    )
+    return <InteractiveDemo />
   },
   parameters: {
     docs: {
       description: {
         story:
-          "Showcase of different overlay configurations combined with various border styles.",
+          "Live configurator — pick variant, borderConfig, opacity, glass, and noise, then open the dialog and confirm or cancel to see state feedback reflected below the trigger.",
       },
     },
   },
 }
 
-// 7. Accessibility Example
-export const AccessibilityExample: Story = {
+// ─── Accessibility ─────────────────────────────────────────────────────────────
+
+export const Accessibility: Story = {
   render: () => {
-    const AccessibleDialog = () => {
+    const A11yDialog = () => {
       const { handleDialogClose } = useDialogCleanup({ threshold: 100 })
 
       return (
         <Dialog>
           <DialogTrigger asChild>
-            <Button>Accessible Dialog Demo</Button>
+            <Button aria-label="Open accessibility demo dialog">
+              Open accessible dialog
+            </Button>
           </DialogTrigger>
           <DialogContent
             variant="info"
-            //@ts-expect-error onEscapeKeyDown available in Radix v2.0.0
-            onEscapeKeyDown={handleDialogClose}
-            onPointerDownOutside={handleDialogClose}
+            borderConfig={["top"]}
+            aria-describedby="dialog-a11y-description"
           >
             <DialogHeader>
-              <DialogTitle>Accessibility Features</DialogTitle>
-              <DialogDescription>
-                This dialog demonstrates proper accessibility implementation
-                with border configuration.
+              <DialogTitle>Keyboard &amp; Screen Reader Support</DialogTitle>
+              <DialogDescription id="dialog-a11y-description">
+                This dialog follows ARIA dialog best practices with role, label,
+                and focus management handled by Radix UI.
               </DialogDescription>
             </DialogHeader>
 
-            <div className="space-y-4">
-              <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
-                <h4 className="text-fm-primary mb-2 font-medium">
-                  Border Configuration
-                </h4>
-                <ul className="text-fm-secondary space-y-1 text-sm">
-                  <li>• Complete border frame for maximum visual emphasis</li>
-                  <li>• Customizable per dialog context and importance</li>
-                  <li>• Maintains accessibility contrast ratios</li>
-                  <li>• Works with all variant color schemes</li>
-                </ul>
-              </div>
-
+            <div className="space-y-3">
               <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
-                <h4 className="text-fm-primary mb-2 font-medium">
-                  Keyboard Navigation
+                <h4 className="text-fm-primary font-fm-text text-fm-md leading-fm-md font-medium">
+                  Keyboard navigation
                 </h4>
-                <ul className="text-fm-secondary space-y-1 text-sm">
+                <ul className="text-fm-secondary font-fm-text text-fm-sm leading-fm-xl mt-2 space-y-1">
                   <li>
-                    {"• "}
-                    <kbd className="bg-fm-surface-tertiary rounded px-1">
+                    <kbd className="bg-fm-surface-tertiary text-fm-xs rounded px-1 py-0.5 font-(--font-fm-mono)">
                       Tab
                     </kbd>{" "}
-                    - Navigate between elements
+                    — move focus forward through interactive elements
                   </li>
                   <li>
-                    {"• "}
-                    <kbd className="bg-fm-surface-tertiary rounded px-1">
-                      Escape
+                    <kbd className="bg-fm-surface-tertiary text-fm-xs rounded px-1 py-0.5 font-(--font-fm-mono)">
+                      Shift+Tab
                     </kbd>{" "}
-                    - Close dialog
+                    — move focus backward
                   </li>
                   <li>
-                    {"• "}
-                    <kbd className="bg-fm-surface-tertiary rounded px-1">
-                      Enter
+                    <kbd className="bg-fm-surface-tertiary text-fm-xs rounded px-1 py-0.5 font-(--font-fm-mono)">
+                      Escape
                     </kbd>{" "}
-                    - Activate buttons
+                    — close the dialog and restore focus to the trigger
                   </li>
                   <li>
-                    {"• "}
-                    <kbd className="bg-fm-surface-tertiary rounded px-1">
-                      Space
+                    <kbd className="bg-fm-surface-tertiary text-fm-xs rounded px-1 py-0.5 font-(--font-fm-mono)">
+                      Enter / Space
                     </kbd>{" "}
-                    - Activate buttons
+                    — activate focused button
                   </li>
                 </ul>
               </div>
 
               <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
-                <h4 className="text-fm-primary mb-2 font-medium">
-                  React 18 Compatibility
+                <h4 className="text-fm-primary font-fm-text text-fm-md leading-fm-md font-medium">
+                  ARIA roles &amp; attributes
                 </h4>
-                <ul className="text-fm-secondary space-y-1 text-sm">
-                  <li>• Cleanup hook prevents pointer-events issues</li>
-                  <li>• Proper modal stacking support</li>
-                  <li>• Body scroll restoration</li>
-                  <li>• Focus restoration on close</li>
+                <ul className="text-fm-secondary font-fm-text text-fm-sm leading-fm-xl mt-2 space-y-1">
+                  <li>
+                    <code className="text-fm-secondary text-fm-sm font-(--font-fm-mono)">
+                      role="dialog"
+                    </code>{" "}
+                    is applied automatically by Radix
+                  </li>
+                  <li>
+                    <code className="text-fm-secondary text-fm-sm font-(--font-fm-mono)">
+                      aria-labelledby
+                    </code>{" "}
+                    links to{" "}
+                    <code className="text-fm-secondary text-fm-sm font-(--font-fm-mono)">
+                      DialogTitle
+                    </code>
+                  </li>
+                  <li>
+                    <code className="text-fm-secondary text-fm-sm font-(--font-fm-mono)">
+                      aria-describedby
+                    </code>{" "}
+                    links to{" "}
+                    <code className="text-fm-secondary text-fm-sm font-(--font-fm-mono)">
+                      DialogDescription
+                    </code>
+                  </li>
+                  <li>Focus is trapped inside the dialog while it is open</li>
+                  <li>
+                    Focus returns to the trigger element when the dialog closes
+                  </li>
                 </ul>
               </div>
             </div>
 
             <DialogFooter>
               <DialogClose asChild>
-                <Button onClick={handleDialogClose}>Close Dialog</Button>
+                <Button
+                  onClick={handleDialogClose}
+                  aria-label="Close accessibility demo dialog"
+                >
+                  Close dialog
+                </Button>
               </DialogClose>
             </DialogFooter>
           </DialogContent>
@@ -1107,16 +628,46 @@ export const AccessibilityExample: Story = {
 
     return (
       <div className="space-y-8">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 font-medium">
-            Accessibility Features
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Dialog with comprehensive accessibility and border configuration
-          </p>
-        </div>
         <div className="flex justify-center">
-          <AccessibleDialog />
+          <A11yDialog />
+        </div>
+
+        <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">
+            Accessibility best practices for Dialog:
+          </p>
+          <ul className="text-fm-secondary font-fm-text text-fm-sm leading-fm-xl mt-2 space-y-1">
+            <li>
+              Always provide a visible{" "}
+              <code className="font-(--font-fm-mono)">DialogTitle</code> — it is
+              announced by screen readers when the dialog opens.
+            </li>
+            <li>
+              Use{" "}
+              <code className="font-(--font-fm-mono)">DialogDescription</code>{" "}
+              to give users context before they interact with dialog controls.
+            </li>
+            <li>
+              Pair{" "}
+              <code className="font-(--font-fm-mono)">useDialogCleanup</code> to
+              prevent React 18 leaving{" "}
+              <code className="font-(--font-fm-mono)">
+                pointer-events: none
+              </code>{" "}
+              on the body after close.
+            </li>
+            <li>
+              Ensure trigger buttons have descriptive labels via{" "}
+              <code className="font-(--font-fm-mono)">aria-label</code> or
+              visible text.
+            </li>
+            <li>
+              Never remove{" "}
+              <code className="font-(--font-fm-mono)">DialogTitle</code> — use{" "}
+              <code className="font-(--font-fm-mono)">sr-only</code> if it must
+              be visually hidden.
+            </li>
+          </ul>
         </div>
       </div>
     )
@@ -1125,7 +676,7 @@ export const AccessibilityExample: Story = {
     docs: {
       description: {
         story:
-          "Comprehensive accessibility example with border configuration and React 18 compatibility features.",
+          "Demonstrates proper ARIA roles, keyboard navigation, and focus management for Dialog. Includes a best-practices reference box.",
       },
     },
   },