aural-ui 4.0.1 → 4.1.0

package/dist/components/aspect-ratio/AspectRatio.stories.tsx

@@ -1,546 +1,37 @@
 import React from "react"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import { AspectRatio } from "."
 
 const meta: Meta<typeof AspectRatio> = {
   title: "Components/UI/AspectRatio",
   component: AspectRatio,
   parameters: {
-    layout: "fullscreen",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "darker", value: "#000000" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
+    layout: "centered",
     docs: {
+      description: {
+        component:
+          "A utility component for maintaining consistent aspect ratios across different content types and screen sizes. Built on Radix UI primitives for reliability.",
+      },
       page: () => (
-        <>
-          {/* Override default docs styling */}
-          <style>
-            {`
-              .sbdocs-wrapper {
-                padding: 0 !important;
-                max-width: none !important;
-                background: transparent !important;
-              }
-              .sbdocs-content {
-                max-width: none !important;
-                padding: 0 !important;
-                margin: 0 !important;
-                background: transparent !important;
-              }
-              .docs-story {
-                background: transparent !important;
-              }
-              .sbdocs {
-                background: transparent !important;
-              }
-              body {
-                background: var(--color-fm-surface-primary) !important;
-              }
-              #storybook-docs {
-                background: var(--color-fm-surface-primary) !important;
-              }
-              .sbdocs-preview {
-                background: transparent !important;
-                border: none !important;
-              }
-              .sbdocs-h1, .sbdocs-h2, .sbdocs-h3, .sbdocs-h4, .sbdocs-h5, .sbdocs-h6 {
-                color: var(--color-fm-icon-active) !important;
-              }
-              .sbdocs-p, .sbdocs-li {
-                color: var(--color-fm-secondary) !important;
-              }
-              .sbdocs-code {
-                background: var(--color-fm-surface-secondary) !important;
-                color: var(--color-fm-secondary-500) !important;
-                border: 1px solid var(--color-fm-divider-secondary) !important;
-              }
-              .sbdocs-pre {
-                background: var(--color-fm-surface-secondary) !important;
-                border: 1px solid var(--color-fm-divider-secondary) !important;
-              }
-              .sbdocs-table {
-                background: var(--color-fm-surface-secondary) !important;
-                border: 1px solid var(--color-fm-divider-secondary) !important;
-              }
-              .sbdocs-table th {
-                background: var(--color-fm-surface-secondary) !important;
-                color: var(--color-fm-icon-active) !important;
-                border-bottom: 1px solid var(--color-fm-divider-secondary) !important;
-              }
-              .sbdocs-table td {
-                color: var(--color-fm-secondary) !important;
-                border-bottom: 1px solid var(--color-fm-divider-tertiary) !important;
-              }
-            `}
-          </style>
-
-          <div className="bg-fm-surface-primary min-h-screen">
-            {/* Header */}
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/50 relative overflow-hidden border-b backdrop-blur-xl">
-              <div className="from-fm-secondary-500/10 to-fm-blue-500/10 absolute inset-0 bg-gradient-to-r via-transparent" />
-              <div className="relative !mx-auto max-w-7xl px-6 py-16">
-                <div className="!space-y-6 text-center">
-                  <h1 className="!text-fm-primary">AspectRatio</h1>
-                  <p className="!text-fm-primary !mx-auto max-w-3xl text-xl leading-relaxed">
-                    A utility component for maintaining consistent aspect ratios
-                    across different content types and screen sizes. Built on
-                    Radix UI primitives for reliability and accessibility.
-                  </p>
-
-                  {/* Stats */}
-                  <div className="flex items-center justify-center gap-8 pt-8">
-                    <div className="text-center">
-                      <div className="text-fm-icon-brand-secondary text-3xl font-bold">
-                        Responsive
-                      </div>
-                      <div className="text-fm-tertiary text-sm">
-                        Adapts to container
-                      </div>
-                    </div>
-                    <div className="bg-fm-surface-tertiary h-8 w-px" />
-                    <div className="text-center">
-                      <div className="text-fm-info text-3xl font-bold">
-                        Flexible
-                      </div>
-                      <div className="text-fm-tertiary text-sm">
-                        Any content type
-                      </div>
-                    </div>
-                    <div className="bg-fm-surface-tertiary h-8 w-px" />
-                    <div className="text-center">
-                      <div className="text-fm-positive text-3xl font-bold">
-                        Consistent
-                      </div>
-                      <div className="text-fm-tertiary text-sm">
-                        Maintains ratio
-                      </div>
-                    </div>
-                  </div>
-                </div>
-              </div>
-            </div>
-
-            {/* Content */}
-            <div className="!mx-auto max-w-7xl !space-y-16 px-6 py-12">
-              {/* Features */}
-              <div className="!space-y-8">
-                <h3 className="!text-fm-primary text-center text-2xl font-bold">
-                  Key Features
-                </h3>
-                <div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
-                  <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-4 rounded-lg border p-6">
-                    <div className="text-3xl">📐</div>
-                    <h4 className="!text-fm-primary text-lg font-semibold">
-                      Consistent Ratios
-                    </h4>
-                    <p className="!text-fm-tertiary text-sm">
-                      Maintains specified aspect ratios regardless of container
-                      size changes
-                    </p>
-                  </div>
-                  <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-4 rounded-lg border p-6">
-                    <div className="text-3xl">📱</div>
-                    <h4 className="!text-fm-primary text-lg font-semibold">
-                      Responsive Design
-                    </h4>
-                    <p className="!text-fm-tertiary text-sm">
-                      Adapts to parent container while preserving aspect ratio
-                    </p>
-                  </div>
-                  <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-4 rounded-lg border p-6">
-                    <div className="text-3xl">🎨</div>
-                    <h4 className="!text-fm-primary text-lg font-semibold">
-                      Flexible Content
-                    </h4>
-                    <p className="!text-fm-tertiary text-sm">
-                      Works with images, videos, iframes, and any custom content
-                    </p>
-                  </div>
-                </div>
-              </div>
-
-              {/* API Reference */}
-              <div className="!space-y-8">
-                <h3 className="!text-fm-primary text-center text-2xl font-bold">
-                  API Reference
-                </h3>
-
-                {/* Component Signature */}
-                <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-6">
-                  <h4 className="!text-fm-icon-brand-secondary mb-4 text-lg font-semibold">
-                    Component Signature
-                  </h4>
-                  <div className="bg-fm-surface-secondary rounded-lg p-4">
-                    <pre className="!text-fm-info text-sm">
-                      {`import { AspectRatio } from "@/components/ui/aspect-ratio"
-
-<AspectRatio ratio={16 / 9}>
-  {/* Your content */}
-</AspectRatio>`}
-                    </pre>
-                  </div>
-                </div>
-
-                {/* Props Table */}
-                <div className="border-fm-divider-secondary bg-fm-surface-secondary overflow-hidden rounded-lg border">
-                  <div className="bg-fm-surface-secondary p-4">
-                    <h4 className="!text-fm-primary text-lg font-semibold">
-                      Props
-                    </h4>
-                  </div>
-                  <table className="!my-0 w-full">
-                    <thead className="bg-fm-surface-secondary">
-                      <tr className="border-fm-divider-secondary border-b">
-                        <th className="!text-fm-primary px-6 py-4 text-left text-sm font-semibold">
-                          Prop
-                        </th>
-                        <th className="!text-fm-primary px-6 py-4 text-left text-sm font-semibold">
-                          Type
-                        </th>
-                        <th className="!text-fm-primary px-6 py-4 text-left text-sm font-semibold">
-                          Default
-                        </th>
-                        <th className="!text-fm-primary px-6 py-4 text-left text-sm font-semibold">
-                          Description
-                        </th>
-                      </tr>
-                    </thead>
-                    <tbody>
-                      <tr className="border-fm-divider-secondary border-b">
-                        <td className="!text-fm-icon-brand-secondary px-6 py-4 font-mono text-sm">
-                          ratio
-                        </td>
-                        <td className="!text-fm-tertiary px-6 py-4 text-sm">
-                          number
-                        </td>
-                        <td className="!text-fm-secondary px-6 py-4 text-sm">
-                          1
-                        </td>
-                        <td className="!text-fm-tertiary px-6 py-4 text-sm">
-                          The desired aspect ratio (width / height)
-                        </td>
-                      </tr>
-                      <tr className="border-fm-divider-secondary border-b !bg-transparent">
-                        <td className="!text-fm-icon-brand-secondary px-6 py-4 font-mono text-sm">
-                          children
-                        </td>
-                        <td className="!text-fm-tertiary px-6 py-4 text-sm">
-                          ReactNode
-                        </td>
-                        <td className="!text-fm-secondary px-6 py-4 text-sm">
-                          -
-                        </td>
-                        <td className="!text-fm-tertiary px-6 py-4 text-sm">
-                          Content to maintain aspect ratio for
-                        </td>
-                      </tr>
-                      <tr>
-                        <td className="!text-fm-icon-brand-secondary px-6 py-4 font-mono text-sm">
-                          className
-                        </td>
-                        <td className="!text-fm-tertiary px-6 py-4 text-sm">
-                          string
-                        </td>
-                        <td className="!text-fm-secondary px-6 py-4 text-sm">
-                          -
-                        </td>
-                        <td className="!text-fm-tertiary px-6 py-4 text-sm">
-                          Additional CSS classes
-                        </td>
-                      </tr>
-                    </tbody>
-                  </table>
-                </div>
-              </div>
-
-              {/* Usage Examples */}
-              <div className="!space-y-8">
-                <h3 className="!text-fm-primary text-center text-2xl font-bold">
-                  Usage Examples
-                </h3>
-
-                <div className="grid grid-cols-1 gap-8 lg:grid-cols-2">
-                  <div className="space-y-4">
-                    <h4 className="!text-fm-icon-brand-secondary text-lg font-semibold">
-                      Basic Image
-                    </h4>
-                    <div className="bg-fm-surface-secondary rounded-lg p-4">
-                      <pre className="!text-fm-positive overflow-x-auto text-sm">
-                        {`<AspectRatio ratio={16 / 9}>
-  <img 
-    src="/image.jpg" 
-    alt="Description"
-    className="h-full w-full object-cover"
-  />
-</AspectRatio>`}
-                      </pre>
-                    </div>
-                  </div>
-
-                  <div className="space-y-4">
-                    <h4 className="!text-fm-icon-brand-secondary text-lg font-semibold">
-                      Video Embed
-                    </h4>
-                    <div className="bg-fm-surface-secondary rounded-lg p-4">
-                      <pre className="!text-fm-info overflow-x-auto text-sm">
-                        {`<AspectRatio ratio={16 / 9}>
-  <iframe 
-    src="https://www.youtube.com/embed/..."
-    className="h-full w-full"
-  />
-</AspectRatio>`}
-                      </pre>
-                    </div>
-                  </div>
-
-                  <div className="space-y-4">
-                    <h4 className="!text-fm-icon-brand-secondary text-lg font-semibold">
-                      Custom Content
-                    </h4>
-                    <div className="bg-fm-surface-secondary rounded-lg p-4">
-                      <pre className="!text-fm-warning overflow-x-auto text-sm">
-                        {`<AspectRatio ratio={1}>
-  <div className="flex h-full w-full items-center 
-                  justify-center bg-gradient-to-br 
-                  from-blue-500 to-purple-600">
-    <h3 className="text-white">Square Content</h3>
-  </div>
-</AspectRatio>`}
-                      </pre>
-                    </div>
-                  </div>
-
-                  <div className="space-y-4">
-                    <h4 className="!text-fm-icon-brand-secondary text-lg font-semibold">
-                      Common Ratios
-                    </h4>
-                    <div className="bg-fm-surface-secondary rounded-lg p-4">
-                      <pre className="!text-fm-secondary overflow-x-auto text-sm">
-                        {`// Common aspect ratios
-16/9   // Widescreen, video
-4/3    // Traditional, photo
-1      // Square, profile pics
-3/2    // Photography
-21/9   // Ultra-wide
-9/16   // Portrait, mobile`}
-                      </pre>
-                    </div>
-                  </div>
-                </div>
-              </div>
-
-              {/* Common Ratios Visual Guide */}
-              <div className="!space-y-8">
-                <h3 className="!text-fm-primary text-center text-2xl font-bold">
-                  Common Aspect Ratios
-                </h3>
-                <div className="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-6">
-                  {[
-                    {
-                      ratio: 1,
-                      label: "1:1",
-                      name: "Square",
-                      color: "from-purple-500 to-pink-500",
-                    },
-                    {
-                      ratio: 16 / 9,
-                      label: "16:9",
-                      name: "Widescreen",
-                      color: "from-blue-500 to-cyan-500",
-                    },
-                    {
-                      ratio: 4 / 3,
-                      label: "4:3",
-                      name: "Traditional",
-                      color: "from-green-500 to-emerald-500",
-                    },
-                    {
-                      ratio: 3 / 2,
-                      label: "3:2",
-                      name: "Photography",
-                      color: "from-orange-500 to-red-500",
-                    },
-                    {
-                      ratio: 21 / 9,
-                      label: "21:9",
-                      name: "Ultra-wide",
-                      color: "from-indigo-500 to-purple-500",
-                    },
-                    {
-                      ratio: 9 / 16,
-                      label: "9:16",
-                      name: "Portrait",
-                      color: "from-pink-500 to-rose-500",
-                    },
-                  ].map((item) => (
-                    <div key={item.label} className="space-y-3">
-                      <AspectRatio ratio={item.ratio}>
-                        <div
-                          className={`flex h-full w-full items-center justify-center rounded-lg bg-gradient-to-br ${item.color} text-fm-primary shadow-lg`}
-                        >
-                          <div className="text-center">
-                            <div className="text-sm font-bold">
-                              {item.label}
-                            </div>
-                          </div>
-                        </div>
-                      </AspectRatio>
-                      <div className="text-center">
-                        <div className="text-fm-primary text-sm font-medium">
-                          {item.name}
-                        </div>
-                        <div className="text-fm-secondary text-xs">
-                          {item.label}
-                        </div>
-                      </div>
-                    </div>
-                  ))}
-                </div>
-              </div>
-
-              {/* Use Cases */}
-              <div className="!space-y-8">
-                <h3 className="!text-fm-primary text-center text-2xl font-bold">
-                  Common Use Cases
-                </h3>
-                <div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
-                  <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-3 rounded-lg border p-6">
-                    <div className="text-2xl">🖼️</div>
-                    <h4 className="!text-fm-primary text-lg font-semibold">
-                      Image Galleries
-                    </h4>
-                    <p className="!text-fm-tertiary text-sm">
-                      Consistent thumbnail sizes across different image
-                      dimensions
-                    </p>
-                  </div>
-                  <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-3 rounded-lg border p-6">
-                    <div className="text-2xl">🎬</div>
-                    <h4 className="!text-fm-primary text-lg font-semibold">
-                      Video Players
-                    </h4>
-                    <p className="!text-fm-tertiary text-sm">
-                      Standard video aspect ratios like 16:9 and 4:3
-                    </p>
-                  </div>
-                  <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-3 rounded-lg border p-6">
-                    <div className="text-2xl">🃏</div>
-                    <h4 className="!text-fm-primary text-lg font-semibold">
-                      Card Layouts
-                    </h4>
-                    <p className="!text-fm-tertiary text-sm">
-                      Uniform card dimensions for consistent grid layouts
-                    </p>
-                  </div>
-                  <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-3 rounded-lg border p-6">
-                    <div className="text-2xl">📺</div>
-                    <h4 className="!text-fm-primary text-lg font-semibold">
-                      Media Embeds
-                    </h4>
-                    <p className="!text-fm-tertiary text-sm">
-                      YouTube, Vimeo, and social media embeds
-                    </p>
-                  </div>
-                  <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-3 rounded-lg border p-6">
-                    <div className="text-2xl">🛍️</div>
-                    <h4 className="!text-fm-primary text-lg font-semibold">
-                      Product Images
-                    </h4>
-                    <p className="!text-fm-tertiary text-sm">
-                      E-commerce product displays with consistent sizing
-                    </p>
-                  </div>
-                  <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-3 rounded-lg border p-6">
-                    <div className="text-2xl">👤</div>
-                    <h4 className="!text-fm-primary text-lg font-semibold">
-                      Profile Pictures
-                    </h4>
-                    <p className="!text-fm-tertiary text-sm">
-                      Square avatar containers for user profiles
-                    </p>
-                  </div>
-                </div>
-              </div>
-
-              {/* Best Practices */}
-              <div className="!space-y-8">
-                <h3 className="!text-fm-primary text-center text-2xl font-bold">
-                  Best Practices
-                </h3>
-                <div className="grid grid-cols-1 gap-6 md:grid-cols-2">
-                  <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-4 rounded-lg border p-6">
-                    <h4 className="!text-fm-positive text-lg font-semibold">
-                      ✅ Do
-                    </h4>
-                    <ul className="!text-fm-tertiary space-y-2 text-sm">
-                      <li className="!text-fm-tertiary">
-                        Use consistent ratios across similar content types
-                      </li>
-                      <li className="!text-fm-tertiary">
-                        Choose ratios that match your content's natural
-                        proportions
-                      </li>
-                      <li className="!text-fm-tertiary">
-                        Apply object-fit: cover for images to maintain quality
-                      </li>
-                      <li className="!text-fm-tertiary">
-                        Test ratios across different screen sizes
-                      </li>
-                      <li className="!text-fm-tertiary">
-                        Use semantic aspect ratios (16:9 for video, 1:1 for
-                        avatars)
-                      </li>
-                    </ul>
-                  </div>
-                  <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-4 rounded-lg border p-6">
-                    <h4 className="!text-fm-negative text-lg font-semibold">
-                      ❌ Don't
-                    </h4>
-                    <ul className="!text-fm-tertiary space-y-2 text-sm">
-                      <li className="!text-fm-tertiary">
-                        Mix different ratios in the same content grid
-                      </li>
-                      <li className="!text-fm-tertiary">
-                        Use extreme ratios that distort content
-                      </li>
-                      <li className="!text-fm-tertiary">
-                        Forget to handle different content types gracefully
-                      </li>
-                      <li className="!text-fm-tertiary">
-                        Ignore responsive behavior on mobile devices
-                      </li>
-                      <li className="!text-fm-tertiary">
-                        Use ratios that don't match platform conventions
-                      </li>
-                    </ul>
-                  </div>
-                </div>
-              </div>
-            </div>
-
-            {/* Footer */}
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary/50 border-t backdrop-blur-xl">
-              <div className="!mx-auto max-w-7xl px-6 py-8">
-                <div className="space-y-4 text-center">
-                  <p className="!text-fm-secondary">
-                    AspectRatio component built on Radix UI primitives for
-                    reliability and accessibility.
-                  </p>
-                  <p className="!text-fm-tertiary text-sm">
-                    Maintains consistent aspect ratios while being fully
-                    responsive and flexible.
-                  </p>
-                </div>
-              </div>
-            </div>
-          </div>
-        </>
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Ratio Flexibility",
+              description: "Any numeric ratio",
+            },
+            {
+              title: "Content-Agnostic",
+              description: "Works with any content",
+            },
+            {
+              title: "Responsive by Design",
+              description: "Scales at any viewport",
+            },
+          ]}
+        />
       ),
     },
   },
@@ -550,216 +41,132 @@ const meta: Meta<typeof AspectRatio> = {
 export default meta
 type Story = StoryObj<typeof AspectRatio>
 
-// All stories should also have dark backgrounds
-const storyParameters = {
-  backgrounds: {
-    default: "dark",
-    values: [
-      { name: "dark", value: "var(--color-fm-surface-primary)" },
-      { name: "darker", value: "var(--color-fm-neutral-0)" },
-    ],
+// ─── 1. Configurations ───────────────────────────────────────────────────────
+
+const COMMON_RATIOS = [
+  {
+    ratio: 1,
+    label: "1:1",
+    name: "Square",
+    desc: "Avatars, social posts",
+    bg: "from-fm-secondary-500 to-fm-hotpink-500",
   },
-}
+  {
+    ratio: 16 / 9,
+    label: "16:9",
+    name: "Widescreen",
+    desc: "Video, presentations",
+    bg: "from-fm-blue-500 to-fm-electricblue-500",
+  },
+  {
+    ratio: 4 / 3,
+    label: "4:3",
+    name: "Traditional",
+    desc: "Classic photos, old TV",
+    bg: "from-fm-green-500 to-fm-emerald-500",
+  },
+  {
+    ratio: 3 / 2,
+    label: "3:2",
+    name: "Photography",
+    desc: "35mm film, DSLR",
+    bg: "from-fm-red-500 to-fm-yellow-500",
+  },
+  {
+    ratio: 21 / 9,
+    label: "21:9",
+    name: "Ultra-wide",
+    desc: "Cinematic, gaming",
+    bg: "from-fm-blue-400 to-fm-secondary-500",
+  },
+  {
+    ratio: 9 / 16,
+    label: "9:16",
+    name: "Portrait",
+    desc: "Mobile, stories, reels",
+    bg: "from-fm-hotpink-500 to-fm-primary-500",
+  },
+]
 
-// 1. Common Aspect Ratios
-export const CommonRatios: Story = {
+export const Configurations: Story = {
   render: () => (
-    <div className="from-fm-surface-primary via-fm-secondary-50/10 to-fm-surface-primary min-h-screen bg-linear-to-br p-8">
-      <div className="mx-auto max-w-7xl space-y-12">
-        <div className="text-center">
-          <h3 className="from-fm-primary via-fm-icon-brand-secondary to-fm-primary mb-4 bg-linear-to-r bg-clip-text text-3xl font-bold text-transparent">
-            Common Aspect Ratios
-          </h3>
-          <p className="text-fm-tertiary mx-auto max-w-2xl text-lg">
-            Standard aspect ratios for different content types, each optimized
-            for specific use cases
-          </p>
-        </div>
-
-        <div className="grid grid-cols-1 gap-8 md:grid-cols-2 lg:grid-cols-3">
-          {/* Square - 1:1 */}
-          <div className="group space-y-4">
-            <div className="mx-auto w-full max-w-sm">
-              <AspectRatio ratio={1}>
-                <div className="text-fm-primary flex h-full w-full items-center justify-center rounded-lg bg-gradient-to-br from-purple-500 to-pink-500 shadow-xl transition-transform duration-300 group-hover:scale-105">
-                  <div className="text-center">
-                    <div className="text-2xl font-bold">1:1</div>
-                    <div className="text-sm opacity-80">Square</div>
-                  </div>
-                </div>
-              </AspectRatio>
-            </div>
-            <div className="text-center">
-              <h4 className="text-fm-primary text-lg font-semibold">
-                Square (1:1)
-              </h4>
-              <p className="text-fm-secondary text-sm">
-                Profile pictures, avatars, social media posts
-              </p>
-            </div>
-          </div>
-
-          {/* Video - 16:9 */}
-          <div className="group space-y-4">
-            <div className="mx-auto w-full max-w-sm">
-              <AspectRatio ratio={16 / 9}>
-                <div className="text-fm-primary flex h-full w-full items-center justify-center rounded-lg bg-gradient-to-br from-blue-500 to-cyan-500 shadow-xl transition-transform duration-300 group-hover:scale-105">
-                  <div className="text-center">
-                    <div className="text-2xl font-bold">16:9</div>
-                    <div className="text-sm opacity-80">Widescreen</div>
-                  </div>
-                </div>
-              </AspectRatio>
-            </div>
-            <div className="text-center">
-              <h4 className="text-fm-primary text-lg font-semibold">
-                Widescreen (16:9)
-              </h4>
-              <p className="text-fm-secondary text-sm">
-                Videos, presentations, modern displays
-              </p>
-            </div>
-          </div>
-
-          {/* Traditional - 4:3 */}
-          <div className="group space-y-4">
-            <div className="mx-auto w-full max-w-sm">
-              <AspectRatio ratio={4 / 3}>
-                <div className="text-fm-primary flex h-full w-full items-center justify-center rounded-lg bg-gradient-to-br from-green-500 to-emerald-500 shadow-xl transition-transform duration-300 group-hover:scale-105">
-                  <div className="text-center">
-                    <div className="text-2xl font-bold">4:3</div>
-                    <div className="text-sm opacity-80">Traditional</div>
-                  </div>
-                </div>
-              </AspectRatio>
-            </div>
-            <div className="text-center">
-              <h4 className="text-fm-primary text-lg font-semibold">
-                Traditional (4:3)
-              </h4>
-              <p className="text-fm-secondary text-sm">
-                Classic photos, old TV format
-              </p>
-            </div>
-          </div>
-
-          {/* Photo - 3:2 */}
-          <div className="group space-y-4">
-            <div className="mx-auto w-full max-w-sm">
-              <AspectRatio ratio={3 / 2}>
-                <div className="text-fm-primary flex h-full w-full items-center justify-center rounded-lg bg-gradient-to-br from-orange-500 to-red-500 shadow-xl transition-transform duration-300 group-hover:scale-105">
-                  <div className="text-center">
-                    <div className="text-2xl font-bold">3:2</div>
-                    <div className="text-sm opacity-80">Photography</div>
-                  </div>
-                </div>
-              </AspectRatio>
-            </div>
-            <div className="text-center">
-              <h4 className="text-fm-primary text-lg font-semibold">
-                Photography (3:2)
-              </h4>
-              <p className="text-fm-secondary text-sm">
-                35mm film, DSLR cameras
-              </p>
-            </div>
-          </div>
-
-          {/* Ultra-wide - 21:9 */}
-          <div className="group space-y-4">
-            <div className="mx-auto w-full max-w-sm">
-              <AspectRatio ratio={21 / 9}>
-                <div className="text-fm-primary flex h-full w-full items-center justify-center rounded-lg bg-gradient-to-br from-indigo-500 to-purple-500 shadow-xl transition-transform duration-300 group-hover:scale-105">
-                  <div className="text-center">
-                    <div className="text-2xl font-bold">21:9</div>
-                    <div className="text-sm opacity-80">Ultra-wide</div>
-                  </div>
-                </div>
-              </AspectRatio>
-            </div>
-            <div className="text-center">
-              <h4 className="text-fm-primary text-lg font-semibold">
-                Ultra-wide (21:9)
-              </h4>
-              <p className="text-fm-secondary text-sm">
-                Cinematic, gaming monitors
-              </p>
-            </div>
+    <div className="space-y-8">
+      <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+        Common Aspect Ratios
+      </h4>
+      <div className="flex flex-wrap justify-center gap-6">
+        {COMMON_RATIOS.map((item) => (
+          <div key={item.label} className="w-28 space-y-2 text-center">
+            <AspectRatio ratio={item.ratio}>
+              <div
+                className={`flex h-full w-full items-center justify-center rounded-lg bg-linear-to-br ${item.bg}`}
+              >
+                <span className="bg-fm-surface-primary/80 text-fm-primary rounded px-1.5 py-0.5 text-xs font-bold backdrop-blur-sm">
+                  {item.label}
+                </span>
+              </div>
+            </AspectRatio>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              {item.name}
+            </p>
           </div>
+        ))}
+      </div>
 
-          {/* Portrait - 9:16 */}
-          <div className="group space-y-4">
-            <div className="mx-auto w-full max-w-sm">
-              <AspectRatio ratio={9 / 16}>
-                <div className="text-fm-primary flex h-full w-full items-center justify-center rounded-lg bg-gradient-to-br from-pink-500 to-rose-500 shadow-xl transition-transform duration-300 group-hover:scale-105">
-                  <div className="text-center">
-                    <div className="text-2xl font-bold">9:16</div>
-                    <div className="text-sm opacity-80">Portrait</div>
-                  </div>
-                </div>
-              </AspectRatio>
-            </div>
-            <div className="text-center">
-              <h4 className="text-fm-primary text-lg font-semibold">
-                Portrait (9:16)
-              </h4>
-              <p className="text-fm-secondary text-sm">
-                Mobile screens, stories, reels
-              </p>
-            </div>
-          </div>
-        </div>
+      <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+        <ul className="grid grid-cols-2 gap-x-6 gap-y-3 sm:grid-cols-3">
+          {COMMON_RATIOS.map((item) => (
+            <li key={item.label} className="flex flex-col gap-0.5">
+              <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-semibold">
+                {item.label} — {item.name}
+              </span>
+              <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                {item.desc}
+              </span>
+            </li>
+          ))}
+        </ul>
       </div>
     </div>
   ),
   parameters: {
-    ...storyParameters,
     docs: {
       description: {
         story:
-          "Common aspect ratios used across different media types and platforms.",
+          "All common aspect ratios with their visual shape and typical use case.",
       },
     },
   },
 }
 
-// 2. Image Gallery Example
-export const ImageGallery: Story = {
-  render: () => (
-    <div className="from-fm-surface-primary via-fm-secondary-50/10 to-fm-surface-primary min-h-screen bg-linear-to-br p-8">
-      <div className="mx-auto max-w-7xl space-y-8">
-        <div className="text-center">
-          <h3 className="from-fm-primary via-fm-icon-brand-secondary to-fm-primary mb-4 bg-linear-to-r bg-clip-text text-3xl font-bold text-transparent">
-            Image Gallery
-          </h3>
-          <p className="text-fm-tertiary mx-auto max-w-2xl text-lg">
-            Consistent image thumbnails using AspectRatio for a clean gallery
-            layout
-          </p>
-        </div>
+// ─── 2. Use Cases ────────────────────────────────────────────────────────────
 
-        <div className="grid grid-cols-2 gap-4 md:grid-cols-3 lg:grid-cols-4">
-          {Array.from({ length: 12 }).map((_, i) => (
+export const UseCases: Story = {
+  render: () => (
+    <div className="mx-auto max-w-3xl space-y-8 p-8">
+      {/* Image Gallery */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Image Gallery (1:1)
+        </h4>
+        <div className="grid grid-cols-3 gap-3 sm:grid-cols-4">
+          {Array.from({ length: 8 }).map((_, i) => (
             <div key={i} className="group cursor-pointer">
               <AspectRatio ratio={1}>
-                <div className="from-fm-surface-secondary to-fm-surface-primary relative h-full w-full overflow-hidden rounded-lg bg-linear-to-br transition-transform duration-300 group-hover:scale-105">
-                  <div
-                    className={`absolute inset-0 bg-gradient-to-br ${
-                      [
-                        "from-red-500 to-pink-500",
-                        "from-blue-500 to-cyan-500",
-                        "from-green-500 to-emerald-500",
-                        "from-purple-500 to-violet-500",
-                        "from-orange-500 to-yellow-500",
-                        "from-indigo-500 to-blue-500",
-                      ][i % 6]
-                    } opacity-80`}
-                  />
-                  <div className="text-fm-primary absolute inset-0 flex items-center justify-center">
-                    <div className="text-center">
-                      <div className="text-lg font-semibold">Image {i + 1}</div>
-                      <div className="text-sm opacity-75">1:1 Ratio</div>
-                    </div>
+                <div
+                  className={`relative h-full w-full overflow-hidden rounded-lg bg-linear-to-br ${
+                    [
+                      "from-fm-hotpink-500 to-fm-primary-500",
+                      "from-fm-blue-500 to-fm-electricblue-500",
+                      "from-fm-green-500 to-fm-emerald-500",
+                      "from-fm-secondary-500 to-fm-hotpink-500",
+                    ][i % 4]
+                  }`}
+                >
+                  <div className="absolute inset-0 flex items-end justify-start p-1.5">
+                    <span className="bg-fm-surface-primary/80 text-fm-primary rounded px-1 py-0.5 text-xs font-medium backdrop-blur-sm">
+                      Image {i + 1}
+                    </span>
                   </div>
                   <div className="absolute inset-0 bg-black/20 opacity-0 transition-opacity group-hover:opacity-100" />
                 </div>
@@ -768,236 +175,124 @@ export const ImageGallery: Story = {
           ))}
         </div>
       </div>
-    </div>
-  ),
-  parameters: {
-    ...storyParameters,
-    docs: {
-      description: {
-        story:
-          "Example of using AspectRatio for consistent image gallery thumbnails.",
-      },
-    },
-  },
-}
-
-// 3. Video Players
-export const VideoPlayers: Story = {
-  render: () => (
-    <div className="from-fm-surface-primary via-fm-secondary-50/10 to-fm-surface-primary min-h-screen bg-linear-to-br p-8">
-      <div className="mx-auto max-w-7xl space-y-12">
-        <div className="text-center">
-          <h3 className="from-fm-primary via-fm-icon-brand-secondary to-fm-primary mb-4 bg-linear-to-r bg-clip-text text-3xl font-bold text-transparent">
-            Video Players
-          </h3>
-          <p className="text-fm-tertiary mx-auto max-w-2xl text-lg">
-            Standard video aspect ratios for different video content types
-          </p>
-        </div>
 
-        <div className="space-y-8">
-          {/* Widescreen Video */}
-          <div className="space-y-4">
-            <h4 className="text-fm-primary text-xl font-semibold">
-              Widescreen Video (16:9)
-            </h4>
-            <div className="mx-auto max-w-4xl">
-              <AspectRatio ratio={16 / 9}>
-                <div className="bg-fm-surface-primary relative h-full w-full overflow-hidden rounded-lg shadow-2xl">
-                  <div className="from-fm-surface-secondary to-fm-surface-primary absolute inset-0 bg-linear-to-br" />
-                  <div className="absolute inset-0 flex items-center justify-center">
-                    <div className="text-fm-primary text-center">
-                      <div className="mb-4 text-6xl">▶️</div>
-                      <div className="text-xl font-semibold">Video Player</div>
-                      <div className="text-sm opacity-75">
-                        16:9 Aspect Ratio
-                      </div>
-                    </div>
-                  </div>
-                  {/* Mock video controls */}
-                  <div className="absolute right-0 bottom-0 left-0 bg-gradient-to-t from-black/80 to-transparent p-4">
-                    <div className="flex items-center gap-4">
-                      <button className="text-fm-primary">⏸️</button>
-                      <div className="bg-fm-surface-tertiary h-1 flex-1 rounded-full">
-                        <div className="h-full w-1/3 rounded-full bg-red-500" />
-                      </div>
-                      <span className="text-fm-secondary text-sm">
-                        1:23 / 4:56
-                      </span>
-                    </div>
+      {/* Video Player */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Video Player (16:9)
+        </h4>
+        <div className="mx-auto max-w-md">
+          <AspectRatio ratio={16 / 9}>
+            <div className="bg-fm-surface-secondary relative h-full w-full overflow-hidden rounded-lg">
+              <div className="from-fm-surface-secondary to-fm-surface-primary absolute inset-0 bg-linear-to-br" />
+              <div className="absolute inset-0 flex items-center justify-center">
+                <div className="text-center">
+                  <div className="text-fm-tertiary mb-2 text-4xl">▶</div>
+                  <div className="text-fm-primary text-sm font-semibold">
+                    Widescreen 16:9
                   </div>
                 </div>
-              </AspectRatio>
-            </div>
-          </div>
-
-          {/* Traditional Video */}
-          <div className="space-y-4">
-            <h4 className="text-fm-primary text-xl font-semibold">
-              Traditional Video (4:3)
-            </h4>
-            <div className="mx-auto max-w-2xl">
-              <AspectRatio ratio={4 / 3}>
-                <div className="bg-fm-surface-primary relative h-full w-full overflow-hidden rounded-lg shadow-2xl">
-                  <div className="from-fm-surface-secondary to-fm-surface-primary absolute inset-0 bg-linear-to-br" />
-                  <div className="absolute inset-0 flex items-center justify-center">
-                    <div className="text-fm-primary text-center">
-                      <div className="mb-4 text-5xl">📺</div>
-                      <div className="text-lg font-semibold">
-                        Classic TV Format
-                      </div>
-                      <div className="text-sm opacity-75">4:3 Aspect Ratio</div>
-                    </div>
+              </div>
+              <div className="absolute right-0 bottom-0 left-0 bg-linear-to-t from-black/60 to-transparent p-3">
+                <div className="flex items-center gap-3">
+                  <div className="bg-fm-surface-tertiary h-1 flex-1 rounded-full">
+                    <div className="bg-fm-primary-500 h-full w-1/3 rounded-full" />
                   </div>
+                  <span className="text-xs text-white">1:23 / 4:56</span>
                 </div>
-              </AspectRatio>
+              </div>
             </div>
-          </div>
+          </AspectRatio>
+        </div>
+      </div>
 
-          {/* Mobile Video */}
-          <div className="space-y-4">
-            <h4 className="text-fm-primary text-xl font-semibold">
-              Mobile Video (9:16)
-            </h4>
-            <div className="mx-auto max-w-sm">
-              <AspectRatio ratio={9 / 16}>
-                <div className="bg-fm-surface-primary relative h-full w-full overflow-hidden rounded-lg shadow-2xl">
-                  <div className="from-fm-surface-secondary to-fm-surface-primary absolute inset-0 bg-linear-to-br" />
-                  <div className="absolute inset-0 flex items-center justify-center">
-                    <div className="text-fm-primary text-center">
-                      <div className="mb-4 text-4xl">📱</div>
-                      <div className="text-lg font-semibold">
-                        Stories & Reels
-                      </div>
-                      <div className="text-sm opacity-75">
-                        9:16 Aspect Ratio
-                      </div>
-                    </div>
+      {/* Product Cards */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Product Cards (4:3)
+        </h4>
+        <div className="grid grid-cols-3 gap-4">
+          {[
+            { icon: "👟", title: "Sneakers", price: "$89" },
+            { icon: "🎧", title: "Headphones", price: "$149" },
+            { icon: "⌚", title: "Watch", price: "$299" },
+          ].map((product, i) => (
+            <div
+              key={i}
+              className="border-fm-divider-secondary bg-fm-surface-secondary overflow-hidden rounded-xl border"
+            >
+              <AspectRatio ratio={4 / 3}>
+                <div className="bg-fm-surface-primary relative h-full w-full">
+                  <div className="text-fm-primary absolute inset-0 flex items-center justify-center text-3xl">
+                    {product.icon}
                   </div>
                 </div>
               </AspectRatio>
+              <div className="p-3">
+                <p className="text-fm-primary text-sm font-medium">
+                  {product.title}
+                </p>
+                <p className="text-fm-secondary text-sm">{product.price}</p>
+              </div>
             </div>
-          </div>
+          ))}
         </div>
       </div>
-    </div>
-  ),
-  parameters: {
-    ...storyParameters,
-    docs: {
-      description: {
-        story:
-          "Video player examples with different aspect ratios for various content types.",
-      },
-    },
-  },
-}
 
-// 4. Card Layouts
-export const CardLayouts: Story = {
-  render: () => (
-    <div className="from-fm-surface-primary via-fm-secondary-50/10 to-fm-surface-primary min-h-screen bg-linear-to-br p-8">
-      <div className="mx-auto max-w-7xl space-y-8">
-        <div className="text-center">
-          <h3 className="from-fm-primary via-fm-icon-brand-secondary to-fm-primary mb-4 bg-linear-to-r bg-clip-text text-3xl font-bold text-transparent">
-            Card Layouts
-          </h3>
-          <p className="text-fm-tertiary mx-auto max-w-2xl text-lg">
-            Consistent card designs using AspectRatio for uniform layouts
-          </p>
-        </div>
-
-        <div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
-          {[
-            {
-              title: "Product Card",
-              ratio: 4 / 3,
-              icon: "🛍️",
-              desc: "E-commerce product",
-            },
-            {
-              title: "Blog Card",
-              ratio: 16 / 9,
-              icon: "📝",
-              desc: "Article preview",
-            },
-            {
-              title: "Profile Card",
-              ratio: 1,
-              icon: "👤",
-              desc: "User profile",
-            },
-            {
-              title: "Recipe Card",
-              ratio: 3 / 2,
-              icon: "🍳",
-              desc: "Food & cooking",
-            },
-            {
-              title: "Event Card",
-              ratio: 16 / 9,
-              icon: "🎉",
-              desc: "Event listing",
-            },
-            {
-              title: "Portfolio Card",
-              ratio: 4 / 3,
-              icon: "🎨",
-              desc: "Creative work",
-            },
-          ].map((card, i) => (
-            <div
-              key={i}
-              className="group border-fm-divider-secondary bg-fm-surface-secondary hover:border-fm-divider-contrast hover:bg-fm-surface-frosted/15 cursor-pointer overflow-hidden rounded-xl border transition-all duration-300 hover:scale-105"
-            >
-              <AspectRatio ratio={card.ratio}>
+      {/* Portrait Stories */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Stories & Reels (9:16)
+        </h4>
+        <div className="flex gap-3">
+          {Array.from({ length: 4 }).map((_, i) => (
+            <div key={i} className="w-24 shrink-0">
+              <AspectRatio ratio={9 / 16}>
                 <div
-                  className={`relative h-full w-full bg-gradient-to-br ${
+                  className={`flex h-full w-full flex-col justify-end overflow-hidden rounded-xl bg-linear-to-b p-1.5 ${
                     [
-                      "from-fm-blue-500 to-fm-secondary-600",
-                      "from-fm-green-500 to-fm-emerald-600",
-                      "from-fm-red-500 to-fm-red-600",
-                      "from-fm-secondary-500 to-fm-hotpink-600",
-                      "from-fm-electricblue-500 to-fm-blue-600",
-                      "from-fm-hotpink-500 to-fm-red-600",
-                    ][i % 6]
+                      "from-fm-secondary-500 to-fm-blue-500",
+                      "from-fm-hotpink-500 to-fm-red-500",
+                      "from-fm-green-500 to-fm-blue-500",
+                      "from-fm-red-500 to-fm-secondary-500",
+                    ][i % 4]
                   }`}
                 >
-                  <div className="text-fm-primary absolute inset-0 flex items-center justify-center">
-                    <div className="text-center">
-                      <div className="mb-2 text-4xl">{card.icon}</div>
-                      <div className="text-lg font-semibold">{card.title}</div>
-                    </div>
-                  </div>
-                  <div className="absolute inset-0 bg-black/20 opacity-0 transition-opacity group-hover:opacity-100" />
+                  <span className="bg-fm-surface-primary/80 text-fm-primary self-start rounded px-1 py-0.5 text-xs font-medium backdrop-blur-sm">
+                    @user{i + 1}
+                  </span>
                 </div>
               </AspectRatio>
-              <div className="p-4">
-                <h4 className="text-fm-primary font-semibold">{card.title}</h4>
-                <p className="text-fm-secondary text-sm">{card.desc}</p>
-                <div className="text-fm-icon-brand-secondary mt-2 text-xs">
-                  Ratio: {card.ratio.toFixed(2)}
-                </div>
-              </div>
             </div>
           ))}
         </div>
       </div>
+
+      {/* Usage note */}
+      <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">
+          AspectRatio wraps any content and maintains its ratio as the container
+          resizes. Use <code>ratio={"{width / height}"}</code> to specify the
+          desired proportion. Children must fill 100% width and height using{" "}
+          <code>className="h-full w-full"</code>.
+        </p>
+      </div>
     </div>
   ),
   parameters: {
-    ...storyParameters,
+    layout: "fullscreen",
     docs: {
       description: {
         story:
-          "Card layout examples showing how AspectRatio creates consistent designs.",
+          "Practical usage examples: image galleries, video players, product cards, and portrait stories.",
       },
     },
   },
 }
 
-// 5. Interactive Playground
-export const InteractivePlayground: Story = {
+// ─── 3. Interactive ──────────────────────────────────────────────────────────
+
+export const Interactive: Story = {
   render: () => {
     const [selectedRatio, setSelectedRatio] = React.useState<number | "custom">(
       16 / 9
@@ -1017,158 +312,93 @@ export const InteractivePlayground: Story = {
     const currentRatio =
       selectedRatio === "custom" ? customWidth / customHeight : selectedRatio
 
-    return (
-      <div className="from-fm-surface-primary via-fm-secondary-50/10 to-fm-surface-primary min-h-screen bg-linear-to-br p-8">
-        <div className="mx-auto max-w-7xl space-y-8">
-          <div className="text-center">
-            <h3 className="from-fm-primary via-fm-icon-brand-secondary to-fm-primary mb-4 bg-linear-to-r bg-clip-text text-3xl font-bold text-transparent">
-              Interactive Playground
-            </h3>
-            <p className="text-fm-tertiary mx-auto max-w-2xl text-lg">
-              Experiment with different aspect ratios and see how they affect
-              content layout
-            </p>
-          </div>
-
-          <div className="grid grid-cols-1 gap-8 lg:grid-cols-3">
-            {/* Controls */}
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-6 rounded-xl border p-6">
-              <h4 className="text-fm-primary text-lg font-semibold">
-                Controls
-              </h4>
+    const currentLabel =
+      selectedRatio === "custom"
+        ? `${customWidth}:${customHeight}`
+        : (presetRatios.find((p) => p.value === selectedRatio)?.label ??
+          currentRatio.toFixed(2))
 
-              {/* Preset Ratios */}
-              <div className="space-y-3">
-                <label className="text-fm-primary text-sm font-medium">
-                  Preset Ratios
-                </label>
-                <div className="grid grid-cols-2 gap-2">
-                  {presetRatios.map((preset) => (
-                    <button
-                      key={preset.name}
-                      onClick={() => setSelectedRatio(preset.value)}
-                      className={`rounded-lg px-3 py-2 text-sm transition-colors ${
-                        selectedRatio === preset.value
-                          ? "text-fm-primary bg-fm-secondary-500"
-                          : "bg-fm-surface-secondary text-fm-tertiary hover:bg-fm-surface-tertiary"
-                      }`}
-                    >
-                      {preset.label}
-                    </button>
-                  ))}
-                </div>
+    return (
+      <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">
+                Presets
+              </p>
+              <div className="grid grid-cols-2 gap-2">
+                {presetRatios.map((preset) => (
+                  <button
+                    key={preset.name}
+                    onClick={() => setSelectedRatio(preset.value)}
+                    className={`text-fm-sm rounded-lg px-3 py-2 transition-colors ${
+                      selectedRatio === preset.value
+                        ? "bg-fm-secondary-500 text-white"
+                        : "bg-fm-surface-primary text-fm-primary hover:bg-fm-surface-tertiary"
+                    }`}
+                  >
+                    {preset.label}
+                  </button>
+                ))}
               </div>
 
-              {/* Custom Ratio */}
-              <div className="space-y-3">
-                <label className="text-fm-primary text-sm font-medium">
-                  Custom Ratio
-                </label>
-                <div className="flex items-center gap-2">
-                  <input
-                    type="number"
-                    min="1"
-                    max="50"
-                    value={customWidth}
-                    onChange={(e) => {
-                      setCustomWidth(Number(e.target.value))
-                      setSelectedRatio("custom")
-                    }}
-                    className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary placeholder-fm-tertiary w-20 rounded-lg border px-3 py-2 text-sm"
-                  />
-                  <span className="text-fm-primary">:</span>
-                  <input
-                    type="number"
-                    min="1"
-                    max="50"
-                    value={customHeight}
-                    onChange={(e) => {
-                      setCustomHeight(Number(e.target.value))
-                      setSelectedRatio("custom")
-                    }}
-                    className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary placeholder-fm-tertiary w-20 rounded-lg border px-3 py-2 text-sm"
-                  />
-                </div>
-                <button
-                  onClick={() => setSelectedRatio(customWidth / customHeight)}
-                  className="bg-fm-secondary-500/20 hover:bg-fm-secondary-500/30 text-fm-icon-brand-secondary w-full rounded-lg px-3 py-2 text-sm transition-colors"
-                >
-                  Apply Custom ({customWidth}:{customHeight})
-                </button>
-              </div>
+              <div className="border-fm-divider-secondary border-t pt-4" />
 
-              {/* Current Info */}
-              <div className="bg-fm-surface-secondary space-y-2 rounded-lg p-4">
-                <div className="text-fm-primary text-sm font-medium">
-                  Current Ratio
-                </div>
-                <div className="text-fm-icon-brand-secondary text-lg font-bold">
-                  {currentRatio.toFixed(3)}
-                </div>
-                <div className="text-fm-secondary text-xs">
-                  {selectedRatio === "custom"
-                    ? `${customWidth}:${customHeight}`
-                    : presetRatios.find((p) => p.value === selectedRatio)
-                        ?.label || "Custom"}
-                </div>
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                Custom
+              </p>
+              <div className="flex items-center gap-2">
+                <input
+                  type="number"
+                  min="1"
+                  max="50"
+                  value={customWidth}
+                  onChange={(e) => {
+                    setCustomWidth(Number(e.target.value))
+                    setSelectedRatio("custom")
+                  }}
+                  className="text-fm-sm border-fm-divider-secondary bg-fm-surface-primary text-fm-primary w-16 rounded-lg border px-2 py-2"
+                />
+                <span className="text-fm-secondary font-medium">:</span>
+                <input
+                  type="number"
+                  min="1"
+                  max="50"
+                  value={customHeight}
+                  onChange={(e) => {
+                    setCustomHeight(Number(e.target.value))
+                    setSelectedRatio("custom")
+                  }}
+                  className="text-fm-sm border-fm-divider-secondary bg-fm-surface-primary text-fm-primary w-16 rounded-lg border px-2 py-2"
+                />
               </div>
             </div>
 
-            {/* Preview */}
-            <div className="lg:col-span-2">
-              <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-4 rounded-xl border p-6">
-                <h4 className="text-fm-primary text-lg font-semibold">
-                  Preview
-                </h4>
-                <div className="mx-auto max-w-lg">
-                  <AspectRatio ratio={currentRatio}>
-                    <div className="relative h-full w-full overflow-hidden rounded-lg bg-gradient-to-br from-blue-500 via-purple-500 to-pink-500 shadow-xl">
-                      <div className="text-fm-primary absolute inset-0 flex items-center justify-center">
-                        <div className="text-center">
-                          <div className="text-2xl font-bold">
-                            {selectedRatio === "custom"
-                              ? `${customWidth}:${customHeight}`
-                              : presetRatios.find(
-                                  (p) => p.value === selectedRatio
-                                )?.label || currentRatio.toFixed(2)}
-                          </div>
-                          <div className="text-sm opacity-80">Aspect Ratio</div>
-                          <div className="mt-2 text-xs opacity-60">
-                            Decimal: {currentRatio.toFixed(3)}
-                          </div>
-                        </div>
+            {/* Preview stage */}
+            <div className="flex flex-col gap-3 lg:col-span-2">
+              <div className="mx-auto w-full max-w-sm">
+                <AspectRatio ratio={currentRatio}>
+                  <div className="border-fm-divider-secondary bg-fm-surface-secondary flex h-full w-full items-center justify-center rounded-lg border">
+                    <div className="text-center">
+                      <div className="text-fm-primary text-lg font-bold">
+                        {currentLabel}
                       </div>
-                      {/* Grid overlay */}
-                      <div className="absolute inset-0 opacity-20">
-                        <div className="grid h-full w-full grid-cols-3 grid-rows-3 gap-px">
-                          {Array.from({ length: 9 }).map((_, i) => (
-                            <div
-                              key={i}
-                              className="border-fm-divider-secondary border"
-                            />
-                          ))}
-                        </div>
+                      <div className="text-fm-tertiary text-xs">
+                        {currentRatio.toFixed(3)}
                       </div>
                     </div>
-                  </AspectRatio>
-                </div>
-
-                {/* Code Example */}
-                <div className="space-y-2">
-                  <label className="text-fm-primary text-sm font-medium">
-                    Code
-                  </label>
-                  <div className="bg-fm-surface-secondary rounded-lg p-4">
-                    <pre className="text-fm-positive text-sm">
-                      {`<AspectRatio ratio={${currentRatio.toFixed(3)}}>
-  <div className="h-full w-full bg-gradient-to-br 
-                  from-blue-500 to-purple-500">
-    Your content here
-  </div>
-</AspectRatio>`}
-                    </pre>
                   </div>
-                </div>
+                </AspectRatio>
+              </div>
+              <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+                <code className="text-fm-md leading-fm-md text-fm-secondary font-[var(--font-fm-mono)]">
+                  {`<AspectRatio ratio={${currentRatio.toFixed(3)}}>`}
+                  <br />
+                  {"  {/* your content */}"}
+                  <br />
+                  {"</AspectRatio>"}
+                </code>
               </div>
             </div>
           </div>
@@ -1177,179 +407,11 @@ export const InteractivePlayground: Story = {
     )
   },
   parameters: {
-    ...storyParameters,
-    docs: {
-      description: {
-        story:
-          "Interactive playground to experiment with different aspect ratios.",
-      },
-    },
-  },
-}
-
-// 6. Real World Examples
-export const RealWorldExamples: Story = {
-  render: () => (
-    <div className="from-fm-surface-primary via-fm-secondary-50/10 to-fm-surface-primary min-h-screen bg-linear-to-br p-8">
-      <div className="mx-auto max-w-7xl space-y-12">
-        <div className="text-center">
-          <h3 className="from-fm-primary via-fm-icon-brand-secondary to-fm-primary mb-4 bg-linear-to-r bg-clip-text text-3xl font-bold text-transparent">
-            Real World Examples
-          </h3>
-          <p className="text-fm-tertiary mx-auto max-w-2xl text-lg">
-            Practical implementations of AspectRatio in common UI patterns
-          </p>
-        </div>
-
-        {/* Social Media Feed */}
-        <div className="space-y-6">
-          <h4 className="text-fm-primary text-xl font-semibold">
-            Social Media Feed
-          </h4>
-          <div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
-            {Array.from({ length: 6 }).map((_, i) => (
-              <div
-                key={i}
-                className="border-fm-divider-secondary bg-fm-surface-secondary overflow-hidden rounded-xl border"
-              >
-                <AspectRatio ratio={1}>
-                  <div
-                    className={`relative h-full w-full bg-gradient-to-br ${
-                      [
-                        "from-fm-hotpink-500 to-fm-primary-500",
-                        "from-fm-blue-500 to-fm-electricblue-500",
-                        "from-fm-green-500 to-fm-emerald-500",
-                        "from-fm-secondary-500 to-fm-hotpink-500",
-                        "from-fm-red-500 to-fm-yellow-500",
-                        "from-fm-blue-400 to-fm-blue-500",
-                      ][i % 6]
-                    }`}
-                  >
-                    <div className="text-fm-primary absolute inset-0 flex items-center justify-center">
-                      <div className="text-4xl">
-                        {["🌟", "🎨", "🚀", "💎", "🔥", "⚡"][i % 6]}
-                      </div>
-                    </div>
-                  </div>
-                </AspectRatio>
-                <div className="p-4">
-                  <div className="flex items-center gap-3">
-                    <div className="from-fm-surface-tertiary to-fm-surface-secondary h-8 w-8 rounded-full bg-linear-to-br" />
-                    <div>
-                      <div className="text-fm-primary text-sm font-medium">
-                        @user{i + 1}
-                      </div>
-                      <div className="text-fm-secondary text-xs">
-                        2 hours ago
-                      </div>
-                    </div>
-                  </div>
-                  <p className="text-fm-tertiary mt-2 text-sm">
-                    Beautiful post content with perfect aspect ratio!
-                    #photography
-                  </p>
-                </div>
-              </div>
-            ))}
-          </div>
-        </div>
-
-        {/* E-commerce Grid */}
-        <div className="space-y-6">
-          <h4 className="text-fm-primary text-xl font-semibold">
-            E-commerce Product Grid
-          </h4>
-          <div className="grid grid-cols-2 gap-4 md:grid-cols-3 lg:grid-cols-4">
-            {Array.from({ length: 8 }).map((_, i) => (
-              <div
-                key={i}
-                className="group border-fm-divider-secondary bg-fm-surface-secondary cursor-pointer overflow-hidden rounded-lg border transition-transform duration-200 hover:scale-105"
-              >
-                <AspectRatio ratio={1}>
-                  <div className="from-fm-surface-secondary to-fm-surface-primary relative h-full w-full bg-linear-to-br">
-                    <div className="text-fm-primary absolute inset-0 flex items-center justify-center">
-                      <div className="text-center">
-                        <div className="mb-2 text-2xl">
-                          {["👟", "👕", "⌚", "🎧", "📱", "💻", "🎒", "📷"][i]}
-                        </div>
-                        <div className="text-xs opacity-75">
-                          Product {i + 1}
-                        </div>
-                      </div>
-                    </div>
-                    <div className="absolute top-2 right-2">
-                      <div className="text-fm-primary rounded-full bg-red-500 px-2 py-1 text-xs">
-                        Sale
-                      </div>
-                    </div>
-                  </div>
-                </AspectRatio>
-                <div className="p-3">
-                  <h5 className="text-fm-primary text-sm font-medium">
-                    Product Name
-                  </h5>
-                  <p className="text-fm-icon-brand-secondary text-lg font-bold">
-                    $99.99
-                  </p>
-                </div>
-              </div>
-            ))}
-          </div>
-        </div>
-
-        {/* Video Thumbnails */}
-        <div className="space-y-6">
-          <h4 className="text-fm-primary text-xl font-semibold">
-            Video Thumbnails
-          </h4>
-          <div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
-            {Array.from({ length: 6 }).map((_, i) => (
-              <div key={i} className="group cursor-pointer space-y-3">
-                <AspectRatio ratio={16 / 9}>
-                  <div className="from-fm-surface-secondary to-fm-surface-primary relative h-full w-full overflow-hidden rounded-lg bg-linear-to-br">
-                    <div className="absolute inset-0 flex items-center justify-center">
-                      <div className="bg-fm-surface-tertiary text-fm-primary flex h-16 w-16 items-center justify-center rounded-full backdrop-blur-sm transition-transform group-hover:scale-110">
-                        <div className="text-2xl">▶️</div>
-                      </div>
-                    </div>
-                    <div className="bg-fm-surface-primary/80 text-fm-primary absolute right-2 bottom-2 rounded px-2 py-1 text-xs">
-                      {["12:34", "8:45", "15:22", "6:18", "20:15", "4:32"][i]}
-                    </div>
-                    <div
-                      className={`absolute inset-0 bg-gradient-to-br opacity-60 ${
-                        [
-                          "from-fm-red-500 to-fm-hotpink-500",
-                          "from-fm-blue-500 to-fm-blue-400",
-                          "from-fm-green-500 to-fm-emerald-500",
-                          "from-fm-secondary-500 to-fm-electricblue-500",
-                          "from-fm-red-500 to-fm-yellow-500",
-                          "from-fm-electricblue-500 to-fm-secondary-500",
-                        ][i % 6]
-                      }`}
-                    />
-                  </div>
-                </AspectRatio>
-                <div>
-                  <h5 className="text-fm-primary text-sm font-medium">
-                    Video Title: Amazing Content #{i + 1}
-                  </h5>
-                  <p className="text-fm-secondary text-xs">
-                    Channel Name • 1.2M views • 2 days ago
-                  </p>
-                </div>
-              </div>
-            ))}
-          </div>
-        </div>
-      </div>
-    </div>
-  ),
-  parameters: {
-    ...storyParameters,
+    layout: "fullscreen",
     docs: {
       description: {
         story:
-          "Real-world examples showing AspectRatio in common UI patterns like social feeds, e-commerce, and video platforms.",
+          "Interactive playground to experiment with preset and custom aspect ratios.",
       },
     },
   },