aural-ui 4.0.1 → 4.2.0

package/dist/components/circular-loader/CircularLoader.stories.tsx

@@ -1,7 +1,9 @@
-import React, { useState } from "react"
+import React from "react"
 import { Button } from "@components/button"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import CircularLoader from "."
 
 const meta: Meta<typeof CircularLoader> = {
@@ -9,107 +11,32 @@ const meta: Meta<typeof CircularLoader> = {
   component: CircularLoader,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "darker", value: "#000000" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-# CircularLoader Component
-
-An accessible circular loading spinner component with multiple variants, customizable sizing, and comprehensive screen reader support. Built with proper ARIA attributes and semantic HTML.
-
-## Features
-
-- **Multiple Variants**: Three distinct spinner designs (gradient, solid, neutral)
-- **Size Options**: Four predefined sizes (sm, md, lg, xl) for different contexts
-- **Accessibility First**: Full ARIA support with screen reader compatibility
-- **Customizable Text**: Optional visual text with separate screen reader messages
-- **Live Regions**: Configurable aria-live announcements for dynamic updates
-- **Flexible Styling**: Custom classes for root, loader, and text elements
-- **Semantic HTML**: Proper role and status indicators
-
-## Accessibility Features
-
-- **ARIA Labels**: Automatic labeling for screen readers
-- **Live Regions**: Announces loading state changes
-- **Screen Reader Text**: Hidden text for assistive technologies
-- **Keyboard Safe**: Non-focusable decorative elements
-- **Status Role**: Proper semantic meaning for loading states
-
-## Usage Examples
-
-### Basic Loading
-\`\`\`tsx
-import CircularLoader from '@/components/circular-loader'
-
-// Simple loading with visual text
-<CircularLoader text="Loading..." />
-
-// Screen reader only (no visual text)
-<CircularLoader aria-label="Loading user data" />
-\`\`\`
-
-### Different Variants
-\`\`\`tsx
-// Gradient spinner (default)
-<CircularLoader variant="v1" text="Loading..." />
-
-// Solid spinner
-<CircularLoader variant="v2" text="Processing..." />
-
-// Neutral spinner
-<CircularLoader variant="v3" text="Please wait..." />
-\`\`\`
-
-### Size Variations
-\`\`\`tsx
-// Small loader for buttons
-<CircularLoader size="sm" text="Save" />
-
-// Large loader for page loading
-<CircularLoader size="xl" text="Loading application..." />
-\`\`\`
-
-### Advanced Accessibility
-\`\`\`tsx
-// Custom loading message for screen readers
-<CircularLoader 
-  text="Submitting form..."
-  loadingMessage="Your form is being processed, please wait"
-  aria-live="assertive"
-/>
-
-// Programmatic control
-<CircularLoader 
-  id="form-loader"
-  aria-label="Saving changes"
-  aria-live="polite"
-/>
-\`\`\`
-
-### Custom Styling
-\`\`\`tsx
-<CircularLoader 
-  variant="v2"
-  size="lg"
-  text="Loading..."
-  classes={{
-    root: "my-8",
-    loader: "text-blue-500",
-    text: "text-gray-600 font-medium"
-  }}
-/>
-\`\`\`
-        `,
+        component:
+          "An accessible circular loading spinner with three visual variants (gradient, solid, neutral), four sizes (sm/md/lg/xl), optional visible text, and full ARIA support including aria-live regions and screen-reader-only messages.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "3 Visual Variants",
+              description: "Gradient, solid, neutral",
+            },
+            {
+              title: "Size Scale",
+              description: "sm to xl scale",
+            },
+            {
+              title: "ARIA Support",
+              description: "Live regions built in",
+            },
+          ]}
+        />
+      ),
     },
   },
+  tags: ["autodocs"],
   argTypes: {
     variant: {
       control: { type: "select" },
@@ -148,610 +75,268 @@ import CircularLoader from '@/components/circular-loader'
       description: "Custom classes for different parts of the component",
     },
   },
-  tags: ["autodocs"],
 }
 
 export default meta
 type Story = StoryObj<typeof CircularLoader>
 
-// Story parameters for consistent dark theme
-const storyParameters = {
-  backgrounds: {
-    default: "dark",
-    values: [
-      { name: "dark", value: "#0a0a0a" },
-      { name: "darker", value: "#000000" },
-    ],
-  },
+const loaderTextClass = "text-fm-primary"
+
+function StoryCircularLoader(
+  props: React.ComponentProps<typeof CircularLoader>
+) {
+  return (
+    <CircularLoader
+      {...props}
+      classes={{
+        ...props.classes,
+        text: [loaderTextClass, props.classes?.text].filter(Boolean).join(" "),
+      }}
+    />
+  )
 }
 
-// 1. Basic Examples
-export const Default: Story = {
+// ─── 1. Playground ────────────────────────────────────────────────────────────
+
+export const Playground: Story = {
   args: {
-    text: "Loading...",
     variant: "v1",
     size: "md",
+    text: "Loading...",
+    "aria-label": "Loading",
+    "aria-live": "polite",
+    loadingMessage: "",
   },
-  parameters: storyParameters,
   render: (args) => (
-    <div className="bg-fm-surface-primary flex h-32 items-center justify-center rounded-lg p-8">
-      <CircularLoader {...args} />
-    </div>
-  ),
-}
-
-// 2. Variant Showcase
-export const Variants: Story = {
-  parameters: {
-    ...storyParameters,
-    docs: {
-      description: {
-        story:
-          "Different visual variants of the CircularLoader component with consistent accessibility features.",
-      },
-    },
-  },
-  render: () => (
-    <div className="bg-fm-surface-primary space-y-8 rounded-lg p-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-4 text-xl font-bold">
-          Spinner Variants
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Three distinct visual styles with full accessibility support
-        </p>
+    <div className="w-full max-w-sm space-y-4">
+      <div className="flex justify-center py-6">
+        <StoryCircularLoader {...args} />
       </div>
-
-      <div className="grid grid-cols-1 gap-8 md:grid-cols-3">
-        <div className="text-center">
-          <div className="border-fm-divider-secondary bg-fm-surface-secondary mb-4 flex h-32 items-center justify-center rounded-lg border">
-            <CircularLoader variant="v1" text="Gradient" size="lg" />
-          </div>
-          <div className="space-y-1">
-            <div className="text-fm-primary font-medium">Variant V1</div>
-            <div className="text-fm-secondary text-xs">
-              Gradient spinner with smooth transitions
-            </div>
-          </div>
-        </div>
-
-        <div className="text-center">
-          <div className="border-fm-divider-secondary bg-fm-surface-secondary mb-4 flex h-32 items-center justify-center rounded-lg border">
-            <CircularLoader variant="v2" text="Solid" size="lg" />
-          </div>
-          <div className="space-y-1">
-            <div className="text-fm-primary font-medium">Variant V2</div>
-            <div className="text-fm-secondary text-xs">
-              Solid spinner with consistent theming
-            </div>
-          </div>
-        </div>
-
-        <div className="text-center">
-          <div className="border-fm-divider-secondary bg-fm-surface-secondary mb-4 flex h-32 items-center justify-center rounded-lg border">
-            <CircularLoader variant="v3" text="Neutral" size="lg" />
-          </div>
-          <div className="space-y-1">
-            <div className="text-fm-primary font-medium">Variant V3</div>
-            <div className="text-fm-secondary text-xs">
-              Neutral spinner for any theme
-            </div>
-          </div>
-        </div>
+      <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+        <code className="text-fm-secondary text-fm-md leading-fm-md font-(--font-fm-mono)">
+          {`<CircularLoader variant="${args.variant}" size="${args.size}"${args.text ? ` text="${args.text}"` : ""} />`}
+        </code>
       </div>
     </div>
   ),
-}
-
-// 3. Size Variations
-export const Sizes: Story = {
   parameters: {
-    ...storyParameters,
     docs: {
       description: {
         story:
-          "Different sizes of the CircularLoader for various use cases from small inline loaders to large page loaders.",
+          "Adjust variant, size, text, and accessibility props using the controls panel in the sidebar.",
       },
     },
   },
-  render: () => (
-    <div className="bg-fm-surface-primary space-y-8 rounded-lg p-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-4 text-xl font-bold">
-          Size Variations
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Four predefined sizes for different contexts and use cases
-        </p>
-      </div>
-
-      <div className="grid grid-cols-2 gap-6 md:grid-cols-4">
-        <div className="text-center">
-          <div className="border-fm-divider-secondary bg-fm-surface-secondary mb-4 flex h-24 items-center justify-center rounded-lg border">
-            <CircularLoader size="sm" text="Small" />
-          </div>
-          <div className="space-y-1">
-            <div className="text-fm-primary font-medium">Small</div>
-            <div className="text-fm-secondary text-xs">
-              16×16px - Inline elements
-            </div>
-          </div>
-        </div>
-
-        <div className="text-center">
-          <div className="border-fm-divider-secondary bg-fm-surface-secondary mb-4 flex h-24 items-center justify-center rounded-lg border">
-            <CircularLoader size="md" text="Medium" />
-          </div>
-          <div className="space-y-1">
-            <div className="text-fm-primary font-medium">Medium</div>
-            <div className="text-fm-secondary text-xs">
-              24×24px - Default size
-            </div>
-          </div>
-        </div>
+}
 
-        <div className="text-center">
-          <div className="border-fm-divider-secondary bg-fm-surface-secondary mb-4 flex h-24 items-center justify-center rounded-lg border">
-            <CircularLoader size="lg" text="Large" />
-          </div>
-          <div className="space-y-1">
-            <div className="text-fm-primary font-medium">Large</div>
-            <div className="text-fm-secondary text-xs">
-              32×32px - Prominent loading
-            </div>
-          </div>
-        </div>
+// ─── 2. AllVariants ───────────────────────────────────────────────────────────
 
-        <div className="text-center">
-          <div className="border-fm-divider-secondary bg-fm-surface-secondary mb-4 flex h-24 items-center justify-center rounded-lg border">
-            <CircularLoader size="xl" text="Extra Large" />
-          </div>
-          <div className="space-y-1">
-            <div className="text-fm-primary font-medium">Extra Large</div>
-            <div className="text-fm-secondary text-xs">
-              48×48px - Page loading
-            </div>
+export const AllVariants: Story = {
+  render: () => (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Spinner Variants
+        </h4>
+        <div className="flex flex-wrap items-end gap-8">
+          <div className="space-y-2 text-center">
+            <StoryCircularLoader variant="v1" size="lg" text="Gradient" />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              V1 — Gradient
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <StoryCircularLoader variant="v2" size="lg" text="Solid" />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              V2 — Solid
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <StoryCircularLoader variant="v3" size="lg" text="Neutral" />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              V3 — Neutral
+            </p>
           </div>
         </div>
       </div>
     </div>
   ),
-}
-
-// 4. Accessibility Features
-export const AccessibilityFeatures: Story = {
   parameters: {
-    ...storyParameters,
     docs: {
       description: {
         story:
-          "Comprehensive accessibility features including ARIA labels, live regions, and screen reader support.",
+          "Three distinct spinner designs — gradient (v1), solid branded (v2), and neutral (v3) — shown at large size for easy comparison.",
       },
     },
   },
-  render: () => (
-    <div className="bg-fm-surface-primary space-y-8 rounded-lg p-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-4 text-xl font-bold">
-          Accessibility Features
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Built with comprehensive screen reader support and ARIA attributes
-        </p>
-      </div>
-
-      <div className="grid grid-cols-1 gap-6 md:grid-cols-2">
-        <div className="space-y-6">
-          <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-6">
-            <h4 className="text-fm-primary mb-4 text-lg font-semibold">
-              Visual + Screen Reader
-            </h4>
-            <div className="mb-4 flex items-center justify-center">
-              <CircularLoader text="Loading data..." size="lg" />
-            </div>
-            <div className="text-fm-secondary text-sm">
-              Shows visible text and provides the same message to screen readers
-            </div>
-          </div>
-
-          <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-6">
-            <h4 className="text-fm-primary mb-4 text-lg font-semibold">
-              Screen Reader Only
-            </h4>
-            <div className="mb-4 flex items-center justify-center">
-              <CircularLoader
-                aria-label="Processing user authentication"
-                size="lg"
-              />
-            </div>
-            <div className="text-fm-secondary text-sm">
-              No visible text but provides descriptive label for screen readers
-            </div>
-          </div>
-        </div>
-
-        <div className="space-y-6">
-          <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-6">
-            <h4 className="text-fm-primary mb-4 text-lg font-semibold">
-              Custom Loading Message
-            </h4>
-            <div className="mb-4 flex items-center justify-center">
-              <CircularLoader
-                text="Saving..."
-                loadingMessage="Your changes are being saved to the server"
-                size="lg"
-              />
-            </div>
-            <div className="text-fm-secondary text-sm">
-              Visual text differs from detailed screen reader message
-            </div>
-          </div>
+}
 
-          <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-6">
-            <h4 className="text-fm-primary mb-4 text-lg font-semibold">
-              Assertive Announcements
-            </h4>
-            <div className="mb-4 flex items-center justify-center">
-              <CircularLoader
-                text="Critical process..."
-                aria-live="assertive"
-                size="lg"
-              />
-            </div>
-            <div className="text-fm-secondary text-sm">
-              Immediately announces changes to screen readers
-            </div>
-          </div>
-        </div>
-      </div>
+// ─── 3. Sizes ─────────────────────────────────────────────────────────────────
 
-      <div className="border-fm-divider-secondary bg-fm-surface-info-sec rounded-lg border p-6">
-        <h4 className="text-fm-info mb-4 text-lg font-semibold">
-          Accessibility Best Practices
+export const Sizes: Story = {
+  render: () => (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Size Scale
         </h4>
-        <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
-          <div>
-            <h5 className="text-fm-info mb-2 font-medium">Built-in Features</h5>
-            <ul className="text-fm-info-sec space-y-1 text-sm">
-              <li>• Role="status" for loading states</li>
-              <li>• ARIA-live regions for dynamic updates</li>
-              <li>• ARIA-hidden on decorative elements</li>
-              <li>• Screen reader optimized text</li>
-              <li>• Keyboard navigation safe</li>
-            </ul>
-          </div>
-          <div>
-            <h5 className="text-fm-info mb-2 font-medium">Usage Guidelines</h5>
-            <ul className="text-fm-info-sec space-y-1 text-sm">
-              <li>• Always provide context about what's loading</li>
-              <li>• Use "polite" for non-critical updates</li>
-              <li>• Use "assertive" for important changes</li>
-              <li>• Test with screen readers</li>
-              <li>• Consider reduced motion preferences</li>
-            </ul>
+        <div className="flex flex-wrap items-end justify-center gap-8">
+          <div className="space-y-2 text-center">
+            <CircularLoader size="sm" aria-label="Loading small" />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Small (16px)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <CircularLoader size="md" aria-label="Loading medium" />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Medium (24px)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <CircularLoader size="lg" aria-label="Loading large" />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Large (32px)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <CircularLoader size="xl" aria-label="Loading extra large" />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Extra Large (48px)
+            </p>
           </div>
         </div>
       </div>
     </div>
   ),
-}
-
-// 5. Real-world Usage Examples
-export const UsageExamples: Story = {
   parameters: {
-    ...storyParameters,
     docs: {
       description: {
         story:
-          "Real-world usage examples showing CircularLoader in different UI contexts and scenarios.",
+          "Four predefined sizes side by side — sm for inline/button use, md as the default, lg for prominent loading areas, xl for full-page loading states.",
       },
     },
   },
-  render: () => {
-    const [buttonLoading, setButtonLoading] = useState(false)
-    const [cardLoading, setCardLoading] = useState(false)
-    const [pageLoading, setPageLoading] = useState(false)
-
-    const handleButtonClick = () => {
-      setButtonLoading(true)
-      setTimeout(() => setButtonLoading(false), 3000)
-    }
-
-    const handleCardRefresh = () => {
-      setCardLoading(true)
-      setTimeout(() => setCardLoading(false), 2000)
-    }
-
-    const handlePageRefresh = () => {
-      setPageLoading(true)
-      setTimeout(() => setPageLoading(false), 4000)
-    }
-
-    return (
-      <div className="bg-fm-surface-primary space-y-8 rounded-lg p-8">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-4 text-xl font-bold">
-            Real-world Usage
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Common UI patterns and contexts where CircularLoader is used
-          </p>
-        </div>
-
-        <div className="grid grid-cols-1 gap-8 lg:grid-cols-3">
-          {/* Button Loading */}
-          <div className="space-y-4">
-            <h4 className="text-fm-primary text-lg font-semibold">
-              Button Loading
-            </h4>
-            <div className="space-y-3">
-              <Button
-                onClick={handleButtonClick}
-                disabled={buttonLoading}
-                className="w-full"
-              >
-                {buttonLoading ? (
-                  <div className="flex items-center gap-2">
-                    <CircularLoader size="sm" aria-label="Saving changes" />
-                    <span>Saving...</span>
-                  </div>
-                ) : (
-                  "Save Changes"
-                )}
-              </Button>
-              <div className="text-fm-secondary text-xs">
-                Inline loader in button with accessible label
-              </div>
-            </div>
-          </div>
+}
 
-          {/* Card Loading */}
-          <div className="space-y-4">
-            <h4 className="text-fm-primary text-lg font-semibold">
-              Card Loading
-            </h4>
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
-              {cardLoading ? (
-                <div className="flex h-32 items-center justify-center">
-                  <CircularLoader
-                    text="Refreshing data..."
-                    loadingMessage="Refreshing chart data from server"
-                    size="lg"
-                  />
-                </div>
-              ) : (
-                <div className="space-y-3">
-                  <div className="bg-fm-surface-tertiary h-4 rounded"></div>
-                  <div className="bg-fm-surface-tertiary h-4 rounded"></div>
-                  <div className="bg-fm-surface-tertiary h-4 w-3/4 rounded"></div>
-                  <Button
-                    onClick={handleCardRefresh}
-                    size="sm"
-                    className="mt-2"
-                  >
-                    Refresh Data
-                  </Button>
-                </div>
-              )}
-            </div>
-            <div className="text-fm-secondary text-xs">
-              Content area with detailed loading message
-            </div>
-          </div>
+// ─── 4. Accessibility ─────────────────────────────────────────────────────────
 
-          {/* Page Loading */}
-          <div className="space-y-4">
-            <h4 className="text-fm-primary text-lg font-semibold">
-              Page Loading
-            </h4>
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
-              {pageLoading ? (
-                <div className="flex h-32 items-center justify-center">
-                  <CircularLoader
-                    text="Loading application..."
-                    aria-live="assertive"
-                    size="xl"
-                    variant="v2"
-                  />
-                </div>
-              ) : (
-                <div className="space-y-3">
-                  <div className="text-center">
-                    <div className="text-fm-primary mb-2 text-sm font-medium">
-                      Application Ready
-                    </div>
-                    <Button
-                      onClick={handlePageRefresh}
-                      variant="outline"
-                      size="sm"
-                    >
-                      Simulate Loading
-                    </Button>
-                  </div>
-                </div>
-              )}
-            </div>
-            <div className="text-fm-secondary text-xs">
-              Full page loading with assertive announcements
-            </div>
+export const Accessibility: Story = {
+  render: () => (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          ARIA Patterns
+        </h4>
+        <div className="flex flex-wrap items-start gap-8">
+          <div className="space-y-2 text-center">
+            <StoryCircularLoader
+              size="lg"
+              text="Loading data..."
+              aria-live="polite"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Visual text (polite)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <CircularLoader
+              size="lg"
+              aria-label="Processing your authentication"
+              aria-live="polite"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              SR label only
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <StoryCircularLoader
+              size="lg"
+              text="Saving..."
+              loadingMessage="Your changes are being saved to the server"
+              aria-live="polite"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Custom SR message
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <StoryCircularLoader
+              size="lg"
+              text="Critical update..."
+              aria-live="assertive"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Assertive announce
+            </p>
           </div>
         </div>
+      </div>
 
-        {/* Form Submission Example */}
-        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-6">
-          <h4 className="text-fm-primary mb-4 text-lg font-semibold">
-            Form Submission
-          </h4>
-          <div className="space-y-4">
-            <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
-              <input
-                type="text"
-                placeholder="Name"
-                className="border-fm-divider-secondary bg-fm-surface-tertiary text-fm-primary placeholder:text-fm-tertiary rounded-lg border p-3"
-              />
-              <input
-                type="email"
-                placeholder="Email"
-                className="border-fm-divider-secondary bg-fm-surface-tertiary text-fm-primary placeholder:text-fm-tertiary rounded-lg border p-3"
-              />
-            </div>
-            <textarea
-              placeholder="Message"
-              rows={3}
-              className="border-fm-divider-secondary bg-fm-surface-tertiary text-fm-primary placeholder:text-fm-tertiary w-full rounded-lg border p-3"
-            />
-            <div className="flex items-center justify-between">
-              <div className="flex items-center gap-2">
-                <CircularLoader size="sm" aria-label="Submitting form" />
-                <span className="text-fm-secondary text-sm">
-                  Submitting your message...
-                </span>
-              </div>
-              <Button disabled>Submit</Button>
-            </div>
-          </div>
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          In-context Usage
+        </h4>
+        <div className="flex flex-wrap gap-6">
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center gap-3 rounded-lg border px-4 py-3">
+            <CircularLoader size="sm" aria-label="Saving changes" />
+            <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Saving changes...
+            </span>
+          </div>
+          <Button disabled>
+            <CircularLoader size="sm" aria-label="Submitting form" />
+            Submitting
+          </Button>
         </div>
       </div>
-    )
-  },
-}
 
-// 6. Interactive Playground
-export const Playground: Story = {
+      <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">
+          <strong className="text-fm-primary">Best practices:</strong>
+        </p>
+        <ul className="mt-2 space-y-1">
+          <li>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              • Always supply <code>text</code> or <code>aria-label</code> so
+              screen readers know what is loading.
+            </p>
+          </li>
+          <li>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              • Use <code>loadingMessage</code> when the visible text is too
+              brief — the message is read instead by screen readers.
+            </p>
+          </li>
+          <li>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              • Prefer <code>aria-live="polite"</code> for background tasks;
+              reserve <code>"assertive"</code> for critical, time-sensitive
+              updates.
+            </p>
+          </li>
+          <li>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              • The spinner icon carries <code>aria-hidden="true"</code> — it is
+              purely decorative and excluded from the accessibility tree.
+            </p>
+          </li>
+          <li>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              • <code>role="status"</code> is set automatically on the root
+              element, meeting WCAG 4.1.3 (Status Messages).
+            </p>
+          </li>
+        </ul>
+      </div>
+    </div>
+  ),
   parameters: {
-    ...storyParameters,
     docs: {
       description: {
         story:
-          "Interactive playground to experiment with all CircularLoader configurations and accessibility features.",
+          "Accessibility-focused examples covering polite and assertive aria-live regions, screen-reader-only labels, custom loading messages, and inline button integration — with a best-practices reference.",
       },
     },
   },
-  args: {
-    variant: "v1",
-    size: "md",
-    text: "Loading...",
-    "aria-label": "",
-    "aria-live": "polite",
-    loadingMessage: "",
-    className: "",
-    classes: {},
-  },
-  argTypes: {
-    variant: {
-      control: { type: "select" },
-      options: ["v1", "v2", "v3"],
-      description: "Visual variant of the spinner",
-    },
-    size: {
-      control: { type: "select" },
-      options: ["sm", "md", "lg", "xl"],
-      description: "Size of the spinner",
-    },
-    text: {
-      control: "text",
-      description: "Visible text displayed below the spinner",
-    },
-    "aria-label": {
-      control: "text",
-      description:
-        "Accessible label for screen readers when no text is provided",
-    },
-    "aria-live": {
-      control: { type: "select" },
-      options: ["polite", "assertive", "off"],
-      description: "How screen readers announce loading state changes",
-    },
-    loadingMessage: {
-      control: "text",
-      description: "Custom loading message for screen readers",
-    },
-    className: {
-      control: "text",
-      description: "Additional CSS classes for the spinner icon",
-    },
-    classes: {
-      control: "object",
-      description: "Custom classes for different parts of the component",
-    },
-  },
-  render: (args) => (
-    <div className="bg-fm-surface-primary space-y-8 rounded-lg p-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-4 text-xl font-bold">
-          Interactive Playground
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Experiment with all CircularLoader configurations and accessibility
-          features
-        </p>
-      </div>
-
-      <div className="flex items-center justify-center">
-        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-8">
-          <CircularLoader {...args} />
-        </div>
-      </div>
-
-      <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-6">
-        <h4 className="text-fm-primary mb-4 text-lg font-semibold">
-          Current Configuration
-        </h4>
-        <div className="grid grid-cols-2 gap-4 text-sm">
-          <div>
-            <div className="text-fm-primary font-medium">Variant:</div>
-            <div className="text-fm-secondary">{args.variant}</div>
-          </div>
-          <div>
-            <div className="text-fm-primary font-medium">Size:</div>
-            <div className="text-fm-secondary">{args.size}</div>
-          </div>
-          <div>
-            <div className="text-fm-primary font-medium">Visual Text:</div>
-            <div className="text-fm-secondary">{args.text || "None"}</div>
-          </div>
-          <div>
-            <div className="text-fm-primary font-medium">ARIA Label:</div>
-            <div className="text-fm-secondary">
-              {args["aria-label"] || "None"}
-            </div>
-          </div>
-          <div>
-            <div className="text-fm-primary font-medium">ARIA Live:</div>
-            <div className="text-fm-secondary">{args["aria-live"]}</div>
-          </div>
-          <div>
-            <div className="text-fm-primary font-medium">Loading Message:</div>
-            <div className="text-fm-secondary">
-              {args.loadingMessage || "None"}
-            </div>
-          </div>
-        </div>
-      </div>
-
-      <div className="border-fm-divider-positive bg-fm-surface-positive-sec rounded-lg border p-6">
-        <h4 className="text-fm-positive mb-4 text-lg font-semibold">
-          Accessibility Info
-        </h4>
-        <div className="text-fm-positive-sec space-y-2 text-sm">
-          <div>
-            <strong>Screen Reader Message:</strong>{" "}
-            {args.text ||
-              args.loadingMessage ||
-              args["aria-label"] ||
-              "Loading"}
-          </div>
-          <div>
-            <strong>Announcement Type:</strong> {args["aria-live"]}
-          </div>
-          <div>
-            <strong>Role:</strong> status
-          </div>
-          <div>
-            <strong>Focusable:</strong> No (decorative spinner)
-          </div>
-        </div>
-      </div>
-    </div>
-  ),
 }