@tribepad/themis 1.0.17 → 1.1.0

package/src/elements/Toast/Toast.stories.tsx

@@ -1,23 +1,30 @@
 /**
  * Toast Component Stories
- * Storybook stories for Toast component demonstrating all variants, positions, and features
- *
- * @see toast-prd.md - Product Requirements Document
- * @see plan.md - Implementation Plan
- * @see constitution.md Principle IV (Accessibility First - WCAG 2.2 AAA)
+ * Storybook stories for the goey-inspired Toast component
  */
 
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useEffect, useState, type ReactElement } from 'react';
-import { Bell, CheckCircle2, AlertTriangle, Info, Download, Trash2 } from 'lucide-react';
+import {
+  Bell,
+  CheckCircle2,
+  Download,
+  Trash2,
+  Sparkles,
+  UserPlus,
+  Shield,
+  Clock,
+  RefreshCw,
+  FileText,
+} from 'lucide-react';
 import { ToastProvider } from './ToastProvider';
 import { Toaster } from './Toaster';
 import { toast, toastQueue } from './Toast';
 import { Button } from '../Button';
-import type { ToasterPosition, ToastVariant } from './Toast.types';
+import type { ToasterPosition } from './Toast.types';
 
 // =============================================================================
-// Story Wrapper Component
+// Story Wrapper
 // =============================================================================
 
 interface ToastStoryWrapperProps {
@@ -26,24 +33,18 @@ interface ToastStoryWrapperProps {
   children: ReactElement;
 }
 
-/**
- * Wrapper component that provides ToastProvider and Toaster for stories
- */
 function ToastStoryWrapper({
   position = 'bottom-right',
   maxVisibleToasts = 3,
   children,
 }: ToastStoryWrapperProps): ReactElement {
-  // Clear toasts on unmount to prevent leaks between stories
   useEffect(() => {
-    return () => {
-      toastQueue.closeAll();
-    };
+    return () => { toastQueue.closeAll(); };
   }, []);
 
   return (
     <ToastProvider maxVisibleToasts={maxVisibleToasts}>
-      <div className="min-h-[400px] w-full p-8">
+      <div className="min-h-[420px] w-full p-8 bg-[var(--page-background)]">
         {children}
       </div>
       <Toaster position={position} aria-label="Notifications" />
@@ -52,7 +53,7 @@ function ToastStoryWrapper({
 }
 
 // =============================================================================
-// Meta Configuration
+// Meta
 // =============================================================================
 
 const meta = {
@@ -62,17 +63,28 @@ const meta = {
     layout: 'fullscreen',
     docs: {
       description: {
-        component: `Accessible toast notification system built with React Aria toast primitives, CVA variant styling, and WCAG 2.2 AAA compliance.
+        component: `Goey-inspired toast notification system with organic blob morphing animations, built on React Aria toast primitives with WCAG 2.2 AAA compliance.
+
+**API at a glance:**
+\`\`\`ts
+// Convenience methods (recommended)
+toast.success('Saved!', { title: 'Upload Complete', description: 'document.pdf was uploaded.' });
+toast.error('Failed', { title: 'Connection Lost', description: 'Check your network.' });
+toast.warning('Heads up', { title: 'Low Storage', description: '90% of storage used.' });
+toast.info('FYI', { title: 'New Feature', description: 'Dark mode is now available.' });
+
+// Full control
+toast('Message', { variant: 'primary', timeout: 0, onClose: (key, reason) => {} });
+\`\`\`
 
 **Key Features:**
-- 4 semantic variants (default, primary, destructive, accent)
-- 6 position options
-- Programmatic API via \`toast()\` function
-- Queue management with configurable limit
-- Swipe-to-dismiss on touch devices
-- Full keyboard navigation
-- Reduced motion support
-- "Clear All" button for bulk dismissal`,
+- 7 variants: \`default\` \`primary\` \`destructive\` \`accent\` \`success\` \`warning\` \`info\`
+- Organic blob shape with spring-physics entry/exit morphing
+- Progress countdown bar with hover-to-pause
+- Auto variant icons — override with custom \`icon\` prop
+- Structured content via \`title\` + \`description\` props
+- 6 position options, queue management, swipe-to-dismiss
+- Full WCAG 2.2 AAA compliance`,
       },
     },
   },
@@ -82,16 +94,12 @@ const meta = {
       control: 'select',
       options: ['top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'],
       description: 'Position of the toast container',
-      table: {
-        defaultValue: { summary: 'bottom-right' },
-      },
+      table: { defaultValue: { summary: 'bottom-right' } },
     },
     'aria-label': {
       control: 'text',
       description: 'Accessible label for the toast region',
-      table: {
-        defaultValue: { summary: 'Notifications' },
-      },
+      table: { defaultValue: { summary: 'Notifications' } },
     },
   },
 } satisfies Meta<typeof Toaster>;
@@ -100,137 +108,187 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 // =============================================================================
-// Basic Stories
+// 1. Default — fires on load so the canvas isn't empty
 // =============================================================================
 
-/**
- * Default toast with simple string content
- */
 export const Default: Story = {
-  render: () => (
-    <ToastStoryWrapper>
-      <div className="flex flex-col items-start gap-4">
-        <p className="text-sm text-[var(--muted-foreground)]">
-          Click the button to show a toast notification.
-        </p>
-        <Button onPress={() => toast('This is a default toast notification')}>
-          Show Toast
-        </Button>
-      </div>
-    </ToastStoryWrapper>
-  ),
+  render: () => {
+    function DefaultStory() {
+      useEffect(() => {
+        toast.success('', {
+          title: 'Changes saved',
+          description: 'Your profile has been updated successfully.',
+        });
+      }, []);
+
+      return (
+        <ToastStoryWrapper>
+          <div className="flex flex-col items-start gap-4">
+            <p className="text-sm text-[var(--muted-foreground)]">
+              The toast fires automatically on load. Click the button to fire another.
+            </p>
+            <Button
+              onPress={() =>
+                toast.success('', {
+                  title: 'Changes saved',
+                  description: 'Your profile has been updated successfully.',
+                })
+              }
+            >
+              Show Toast
+            </Button>
+          </div>
+        </ToastStoryWrapper>
+      );
+    }
+    return <DefaultStory />;
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'A success toast with title and description — the most common pattern. Notice the blob shape, left accent border, and progress countdown bar.',
+      },
+    },
+  },
 };
 
-/**
- * All 4 variant styles in one view
- */
+// =============================================================================
+// 2. All Variants — pre-fires all 7 so you can see the design
+// =============================================================================
+
 export const AllVariants: Story = {
-  render: () => (
-    <ToastStoryWrapper>
-      <div className="flex flex-col items-start gap-4">
-        <p className="text-sm text-[var(--muted-foreground)]">
-          Click each button to see different toast variants.
-        </p>
-        <div className="flex flex-wrap gap-4">
-          <Button
-            variant="outline"
-            onPress={() => toast('Default notification', { variant: 'default' })}
-          >
-            Default
-          </Button>
-          <Button
-            variant="default"
-            onPress={() => toast('Primary notification', { variant: 'primary' })}
-          >
-            Primary
-          </Button>
-          <Button
-            variant="destructive"
-            onPress={() => toast('Destructive notification', { variant: 'destructive' })}
-          >
-            Destructive
-          </Button>
-          <Button
-            variant="secondary"
-            onPress={() => toast('Accent notification', { variant: 'accent' })}
-          >
-            Accent
-          </Button>
-        </div>
-      </div>
-    </ToastStoryWrapper>
-  ),
+  render: () => {
+    function AllVariantsStory() {
+      useEffect(() => {
+        toast('Default notification', { variant: 'default', timeout: 0 });
+        toast.success('', { title: 'Upload complete', description: 'document.pdf saved.' });
+        toast.error('', { title: 'Connection error', description: 'Unable to reach the server.' });
+        toast.warning('', { title: 'Low storage', description: '90% of storage used.' });
+        toast.info('', { title: 'New version available', description: 'v2.1.0 is ready to install.' });
+      }, []);
+
+      return (
+        <ToastStoryWrapper maxVisibleToasts={5}>
+          <div className="flex flex-col items-start gap-3">
+            <p className="text-sm font-medium text-[var(--content-foreground)]">Fire individual variants:</p>
+            <div className="flex flex-wrap gap-2">
+              <Button size="sm" variant="outline" onPress={() => toast('Default', { variant: 'default', timeout: 0 })}>Default</Button>
+              <Button size="sm" variant="default" onPress={() => toast('Primary', { variant: 'primary', timeout: 0 })}>Primary</Button>
+              <Button size="sm" variant="destructive" onPress={() => toast.error('Something went wrong')}>Destructive</Button>
+              <Button size="sm" variant="secondary" onPress={() => toast('Accent', { variant: 'accent', timeout: 0 })}>Accent</Button>
+              <Button size="sm" variant="outline" onPress={() => toast.success('All good!')}>Success</Button>
+              <Button size="sm" variant="outline" onPress={() => toast.warning('Heads up')}>Warning</Button>
+              <Button size="sm" variant="outline" onPress={() => toast.info('Just so you know')}>Info</Button>
+            </div>
+            <Button variant="ghost" size="sm" onPress={() => toastQueue.closeAll()}>Clear all</Button>
+          </div>
+        </ToastStoryWrapper>
+      );
+    }
+    return <AllVariantsStory />;
+  },
   parameters: {
     docs: {
       description: {
-        story: 'Four semantic variants that map to theme tokens: default, primary, destructive, and accent.',
+        story: 'All 7 variants pre-fired on load. Semantic variants (success, warning, info, destructive) include auto icons and a coloured left-border accent. Default and primary use solid fills.',
       },
     },
   },
 };
 
 // =============================================================================
-// Custom Content Stories
+// 3. Title + Description — structured content
 // =============================================================================
 
-/**
- * Toast with custom ReactNode content including icons and actions
- */
-export const WithCustomContent: Story = {
+export const TitleAndDescription: Story = {
+  render: () => {
+    function TitleDescStory() {
+      useEffect(() => {
+        toast.info('', {
+          title: 'New feature available',
+          description: 'Dark mode is now available in Settings → Appearance.',
+        });
+      }, []);
+
+      return (
+        <ToastStoryWrapper>
+          <div className="flex flex-col items-start gap-3">
+            <p className="text-sm text-[var(--muted-foreground)]">
+              Use <code className="text-xs bg-[var(--muted)] px-1 rounded">title</code> and <code className="text-xs bg-[var(--muted)] px-1 rounded">description</code> for structured notifications.
+            </p>
+            <div className="flex flex-wrap gap-2">
+              <Button
+                size="sm" variant="outline"
+                onPress={() => toast.success('', {
+                  title: 'Upload complete',
+                  description: 'report_q4.pdf has been saved to your workspace.',
+                })}
+              >
+                Success
+              </Button>
+              <Button
+                size="sm" variant="outline"
+                onPress={() => toast.error('', {
+                  title: 'Payment failed',
+                  description: 'Your card ending in 4242 was declined.',
+                })}
+              >
+                Error
+              </Button>
+              <Button
+                size="sm" variant="outline"
+                onPress={() => toast.warning('', {
+                  title: 'Session expiring',
+                  description: 'You will be signed out in 5 minutes.',
+                })}
+              >
+                Warning
+              </Button>
+              <Button
+                size="sm" variant="outline"
+                onPress={() => toast.info('', {
+                  title: 'Maintenance scheduled',
+                  description: 'The service will be offline Sunday 2–4 AM.',
+                })}
+              >
+                Info
+              </Button>
+            </div>
+          </div>
+        </ToastStoryWrapper>
+      );
+    }
+    return <TitleDescStory />;
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Provide `title` for a bold heading and `description` for supporting detail. The accessible name of the toast is derived from the title automatically.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// 4. Convenience Methods
+// =============================================================================
+
+export const ConvenienceMethods: Story = {
   render: () => (
     <ToastStoryWrapper>
       <div className="flex flex-col items-start gap-4">
-        <p className="text-sm text-[var(--muted-foreground)]">
-          Toasts can contain custom content including icons and interactive elements.
-        </p>
-        <div className="flex flex-wrap gap-4">
-          <Button
-            variant="outline"
-            onPress={() =>
-              toast(
-                <div className="flex items-center gap-2">
-                  <CheckCircle2 className="h-4 w-4 text-green-500" />
-                  <span>Changes saved successfully!</span>
-                </div>
-              )
-            }
-          >
-            With Success Icon
-          </Button>
-          <Button
-            variant="outline"
-            onPress={() =>
-              toast(
-                <div className="flex items-center gap-2">
-                  <AlertTriangle className="h-4 w-4 text-yellow-500" />
-                  <span>Your session will expire in 5 minutes</span>
-                </div>,
-                { variant: 'accent' }
-              )
-            }
-          >
-            With Warning Icon
-          </Button>
-          <Button
-            variant="outline"
-            onPress={() =>
-              toast(
-                <div className="flex items-center gap-2">
-                  <Info className="h-4 w-4" />
-                  <span>New version available</span>
-                  <button
-                    type="button"
-                    className="ml-2 text-xs underline hover:no-underline"
-                    onClick={() => alert('Updating...')}
-                  >
-                    Update now
-                  </button>
-                </div>
-              )
-            }
-          >
-            With Action Button
-          </Button>
+        <div className="rounded-lg border border-[var(--border)] bg-[var(--muted)] p-4 font-mono text-xs leading-relaxed">
+          <p className="text-[var(--muted-foreground)] mb-2">// Shorthand — variant and icon are set automatically</p>
+          <p><span className="text-[var(--success-background)]">toast.success</span>(<span className="text-[var(--primary)]">'Changes saved!'</span>)</p>
+          <p><span className="text-[var(--destructive-background)]">toast.error</span>(<span className="text-[var(--primary)]">'Upload failed'</span>)</p>
+          <p><span className="text-[var(--warning-background)]">toast.warning</span>(<span className="text-[var(--primary)]">'Low storage'</span>)</p>
+          <p><span className="text-[var(--info-background)]">toast.info</span>(<span className="text-[var(--primary)]">'Update available'</span>)</p>
+        </div>
+        <div className="flex flex-wrap gap-2">
+          <Button size="sm" variant="outline" onPress={() => toast.success('Changes saved!')}>toast.success()</Button>
+          <Button size="sm" variant="outline" onPress={() => toast.error('Upload failed')}>toast.error()</Button>
+          <Button size="sm" variant="outline" onPress={() => toast.warning('Low storage space')}>toast.warning()</Button>
+          <Button size="sm" variant="outline" onPress={() => toast.info('Update available')}>toast.info()</Button>
         </div>
       </div>
     </ToastStoryWrapper>
@@ -238,104 +296,232 @@ export const WithCustomContent: Story = {
   parameters: {
     docs: {
       description: {
-        story: 'Custom ReactNode content allows icons, styled text, and interactive elements within toasts.',
+        story: 'Convenience methods set the correct variant and icon automatically. All accept the same options as `toast()` minus the `variant` prop.',
       },
     },
   },
 };
 
 // =============================================================================
-// Timing Stories
+// 5. Custom Icons
 // =============================================================================
 
-/**
- * Auto-dismiss behavior with default 5 second timeout
- */
-export const AutoDismiss: Story = {
-  render: () => (
-    <ToastStoryWrapper>
-      <div className="flex flex-col items-start gap-4">
-        <p className="text-sm text-[var(--muted-foreground)]">
-          Toasts auto-dismiss after 5 seconds (minimum for accessibility).
-        </p>
-        <Button onPress={() => toast('This will auto-dismiss in 5 seconds')}>
-          Show Auto-Dismiss Toast
-        </Button>
-      </div>
-    </ToastStoryWrapper>
-  ),
+export const CustomIcons: Story = {
+  render: () => {
+    function CustomIconsStory() {
+      useEffect(() => {
+        toast.success('', {
+          icon: <Sparkles className="h-5 w-5 text-yellow-500" />,
+          title: 'Achievement unlocked',
+          description: 'You completed 100 tasks. Nice work!',
+        });
+      }, []);
+
+      return (
+        <ToastStoryWrapper>
+          <div className="flex flex-col items-start gap-3">
+            <p className="text-sm text-[var(--muted-foreground)]">
+              Pass an <code className="text-xs bg-[var(--muted)] px-1 rounded">icon</code> prop to replace the default variant icon with any React element.
+            </p>
+            <div className="flex flex-wrap gap-2">
+              <Button
+                size="sm" variant="outline"
+                onPress={() => toast.success('', {
+                  icon: <Sparkles className="h-5 w-5 text-yellow-500" />,
+                  title: 'Achievement unlocked',
+                  description: 'You completed 100 tasks. Nice work!',
+                })}
+              >
+                <Sparkles className="h-3.5 w-3.5 mr-1.5" /> Trophy
+              </Button>
+              <Button
+                size="sm" variant="outline"
+                onPress={() => toast.info('', {
+                  icon: <Bell className="h-5 w-5 text-[var(--info-background)]" />,
+                  title: 'New message',
+                  description: 'Sarah replied to your comment.',
+                })}
+              >
+                <Bell className="h-3.5 w-3.5 mr-1.5" /> Bell
+              </Button>
+              <Button
+                size="sm" variant="outline"
+                onPress={() => toast.info('', {
+                  icon: <UserPlus className="h-5 w-5 text-[var(--info-background)]" />,
+                  title: 'New team member',
+                  description: 'Alex joined your workspace.',
+                })}
+              >
+                <UserPlus className="h-3.5 w-3.5 mr-1.5" /> User
+              </Button>
+              <Button
+                size="sm" variant="outline"
+                onPress={() => toast.success('', {
+                  icon: <Shield className="h-5 w-5 text-[var(--success-background)]" />,
+                  title: 'Security scan complete',
+                  description: 'No threats detected.',
+                })}
+              >
+                <Shield className="h-3.5 w-3.5 mr-1.5" /> Shield
+              </Button>
+            </div>
+          </div>
+        </ToastStoryWrapper>
+      );
+    }
+    return <CustomIconsStory />;
+  },
   parameters: {
     docs: {
       description: {
-        story: 'Toasts enforce a minimum 5-second timeout for WCAG 2.2 accessibility compliance, giving users adequate time to read.',
+        story: 'The `icon` prop accepts any React element and replaces the auto variant icon. Any Lucide icon or custom SVG works.',
       },
     },
   },
 };
 
-/**
- * Persistent toast that stays until manually dismissed
- */
-export const Persistent: Story = {
+// =============================================================================
+// 6. Progress Bar + Hover to Pause
+// =============================================================================
+
+export const ProgressAndPause: Story = {
+  render: () => {
+    function ProgressStory() {
+      useEffect(() => {
+        toast.success('', {
+          title: 'Hover me to pause',
+          description: 'The progress bar and timer freeze while you hover.',
+          timeout: 10000,
+        });
+      }, []);
+
+      return (
+        <ToastStoryWrapper>
+          <div className="flex flex-col items-start gap-4">
+            <p className="text-sm text-[var(--muted-foreground)]">
+              A progress bar counts down the auto-dismiss timer. Hover over the toast to pause it.
+            </p>
+            <div className="flex flex-wrap gap-2">
+              <Button
+                size="sm" variant="outline"
+                onPress={() => toast.success('', {
+                  title: 'Hover me to pause',
+                  description: 'The progress bar and timer freeze while you hover.',
+                  timeout: 10000,
+                })}
+              >
+                10s with progress bar
+              </Button>
+              <Button
+                size="sm" variant="outline"
+                onPress={() => toast('No progress bar', { timeout: 5000, showProgress: false })}
+              >
+                showProgress: false
+              </Button>
+              <Button
+                size="sm" variant="outline"
+                onPress={() => toast.warning('', {
+                  title: 'Action required',
+                  description: 'Dismiss this manually — no timer.',
+                  timeout: 0,
+                })}
+              >
+                Persistent (no bar)
+              </Button>
+            </div>
+          </div>
+        </ToastStoryWrapper>
+      );
+    }
+    return <ProgressStory />;
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Progress bars appear automatically for auto-dismiss toasts and are `aria-hidden` (decorative). They pause when hovered. Use `showProgress: false` to opt out, or `timeout: 0` for a persistent toast.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// 7. Timing
+// =============================================================================
+
+export const Timing: Story = {
   render: () => (
     <ToastStoryWrapper>
       <div className="flex flex-col items-start gap-4">
-        <p className="text-sm text-[var(--muted-foreground)]">
-          Set timeout to 0 for persistent toasts that require user action.
-        </p>
-        <Button
-          onPress={() =>
-            toast('This toast will stay until you dismiss it', { timeout: 0 })
-          }
-        >
-          Show Persistent Toast
-        </Button>
+        <div className="rounded-lg border border-[var(--border)] bg-[var(--muted)] p-4 text-sm space-y-1">
+          <p><code className="text-xs bg-[var(--content-background)] px-1 rounded">timeout: 5000</code> — default, minimum enforced for WCAG 2.2</p>
+          <p><code className="text-xs bg-[var(--content-background)] px-1 rounded">timeout: 10000</code> — longer read time</p>
+          <p><code className="text-xs bg-[var(--content-background)] px-1 rounded">timeout: 0</code> — persistent until manually dismissed</p>
+        </div>
+        <div className="flex flex-wrap gap-2">
+          <Button size="sm" variant="outline" onPress={() => toast('Auto-dismisses in 5 s')}>5s (default)</Button>
+          <Button size="sm" variant="outline" onPress={() => toast('Auto-dismisses in 10 s', { timeout: 10000 })}>10s</Button>
+          <Button size="sm" variant="outline" onPress={() => toast.warning('', { title: 'Persistent', description: 'Dismiss manually.', timeout: 0 })}>Persistent</Button>
+        </div>
       </div>
     </ToastStoryWrapper>
   ),
   parameters: {
     docs: {
       description: {
-        story: 'Use `timeout: 0` for important notifications that require user acknowledgment.',
+        story: 'WCAG 2.2 enforces a minimum 5 000 ms timeout so users have time to read. Values between 1–4999 ms are clamped to 5 000 ms. Use `timeout: 0` for persistent toasts.',
       },
     },
   },
 };
 
 // =============================================================================
-// Callback Stories
+// 8. onClose Callback
 // =============================================================================
 
-/**
- * Toast with onClose callback for tracking
- */
 export const WithCallback: Story = {
   render: function WithCallbackStory() {
-    const [log, setLog] = useState<string[]>([]);
+    const [log, setLog] = useState<{ key: string; reason: string; time: string }[]>([]);
 
     return (
       <ToastStoryWrapper>
         <div className="flex flex-col items-start gap-4">
           <p className="text-sm text-[var(--muted-foreground)]">
-            The onClose callback receives the toast key and dismissal reason.
+            The <code className="text-xs bg-[var(--muted)] px-1 rounded">onClose</code> callback fires with the toast key and dismissal reason.
           </p>
-          <Button
-            onPress={() =>
-              toast('Dismiss me to see the callback', {
-                timeout: 0,
-                onClose: (key, reason) => {
-                  setLog((prev) => [...prev, `Toast ${key.slice(0, 8)}... dismissed: ${reason}`]);
-                },
-              })
-            }
-          >
-            Show Toast with Callback
-          </Button>
+          <div className="flex flex-wrap gap-2">
+            <Button
+              size="sm"
+              onPress={() =>
+                toast.info('', {
+                  title: 'Dismiss me',
+                  description: 'Via button, timeout, or Clear All.',
+                  timeout: 8000,
+                  onClose: (key, reason) => {
+                    setLog((prev) => [
+                      { key: key.slice(0, 8), reason, time: new Date().toLocaleTimeString() },
+                      ...prev,
+                    ].slice(0, 5));
+                  },
+                })
+              }
+            >
+              Show Toast
+            </Button>
+            <Button size="sm" variant="outline" onPress={() => toastQueue.closeAll()}>Clear all (programmatic)</Button>
+          </div>
           {log.length > 0 && (
-            <div className="mt-4 rounded border border-[var(--border)] bg-[var(--muted)] p-4">
-              <p className="mb-2 text-sm font-medium">Callback Log:</p>
+            <div className="w-full rounded-lg border border-[var(--border)] bg-[var(--muted)] p-3">
+              <p className="mb-2 text-xs font-semibold text-[var(--muted-foreground)] uppercase tracking-wide">Callback log</p>
               {log.map((entry, i) => (
-                <p key={i} className="text-xs font-mono">{entry}</p>
+                <div key={i} className="flex gap-3 font-mono text-xs py-0.5">
+                  <span className="text-[var(--muted-foreground)]">{entry.time}</span>
+                  <span className="text-[var(--content-foreground)]">{entry.key}…</span>
+                  <span className={
+                    entry.reason === 'timeout' ? 'text-[var(--muted-foreground)]' :
+                    entry.reason === 'user' ? 'text-[var(--success-background)]' :
+                    'text-[var(--info-background)]'
+                  }>{entry.reason}</span>
+                </div>
               ))}
             </div>
           )}
@@ -346,45 +532,46 @@ export const WithCallback: Story = {
   parameters: {
     docs: {
       description: {
-        story: 'The `onClose` callback is invoked with the toast key and reason (`timeout`, `user`, or `programmatic`) for analytics and state management.',
+        story: 'Track dismissals with `onClose(key, reason)`. Reason is `"timeout"` for auto-dismiss, `"user"` for the close button or swipe, and `"programmatic"` for `toastQueue.close()` / `closeAll()`.',
       },
     },
   },
 };
 
 // =============================================================================
-// Position Stories
+// 9. Positions
 // =============================================================================
 
-/**
- * All 6 position options
- */
 export const AllPositions: Story = {
   render: function AllPositionsStory() {
     const [position, setPosition] = useState<ToasterPosition>('bottom-right');
+    const positions = ['top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'] as const;
 
     return (
       <ToastStoryWrapper position={position}>
         <div className="flex flex-col items-start gap-4">
-          <p className="text-sm text-[var(--muted-foreground)]">
-            Select a position and click "Show Toast" to see it in action.
-          </p>
-          <div className="flex flex-wrap gap-2">
-            {(['top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'] as const).map(
-              (pos) => (
-                <Button
-                  key={pos}
-                  variant={position === pos ? 'default' : 'outline'}
-                  size="sm"
-                  onPress={() => setPosition(pos)}
-                >
-                  {pos}
-                </Button>
-              )
-            )}
+          <p className="text-sm text-[var(--muted-foreground)]">Select a position, then fire a toast.</p>
+          <div className="grid grid-cols-3 gap-2 w-64">
+            {positions.map((pos) => (
+              <Button
+                key={pos}
+                variant={position === pos ? 'default' : 'outline'}
+                size="sm"
+                onPress={() => setPosition(pos)}
+                className="text-xs"
+              >
+                {pos.replace('-', ' ')}
+              </Button>
+            ))}
           </div>
-          <Button onPress={() => toast(`Toast at ${position}`, { timeout: 0 })}>
-            Show Toast
+          <Button
+            onPress={() => toast.success('', {
+              title: position,
+              description: 'Toast positioned correctly.',
+              timeout: 0,
+            })}
+          >
+            Fire at {position}
           </Button>
         </div>
       </ToastStoryWrapper>
@@ -393,191 +580,153 @@ export const AllPositions: Story = {
   parameters: {
     docs: {
       description: {
-        story: 'Six position options allow placement at any corner or center edge of the viewport.',
+        story: 'Six positions: any corner or centre edge of the viewport. The blob shape and animation direction are the same regardless of position.',
       },
     },
   },
 };
 
 // =============================================================================
-// Queue Management Stories
+// 10. Queue & Stacking
 // =============================================================================
 
-/**
- * Multiple toasts with queue management
- */
-export const MultipleToasts: Story = {
-  render: () => (
-    <ToastStoryWrapper>
-      <div className="flex flex-col items-start gap-4">
-        <p className="text-sm text-[var(--muted-foreground)]">
-          Click rapidly to see multiple toasts stack and queue.
-        </p>
-        <div className="flex flex-wrap gap-4">
-          <Button
-            onPress={() => {
-              const variants: ToastVariant[] = ['default', 'primary', 'destructive', 'accent'];
-              const variant = variants[Math.floor(Math.random() * variants.length)];
-              toast(`Toast #${Date.now() % 1000}`, { variant, timeout: 0 });
-            }}
-          >
-            Add Random Toast
-          </Button>
-          <Button variant="outline" onPress={() => toastQueue.closeAll()}>
-            Clear All
-          </Button>
-        </div>
-      </div>
-    </ToastStoryWrapper>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story: 'Multiple toasts stack vertically with the newest at the bottom. Excess toasts are queued.',
-      },
-    },
-  },
-};
+export const QueueAndStacking: Story = {
+  render: () => {
+    function QueueStory() {
+      useEffect(() => {
+        toast.success('', { title: 'First', description: 'Visible immediately.', timeout: 0 });
+        toast.info('', { title: 'Second', description: 'Visible immediately.', timeout: 0 });
+        toast.warning('', { title: 'Third', description: 'Visible immediately.', timeout: 0 });
+        toast('Fourth — queued behind the first three', { timeout: 0 });
+        toast('Fifth — also queued', { timeout: 0 });
+      }, []);
 
-/**
- * Queue limit demonstration
- */
-export const QueueManagement: Story = {
-  render: () => (
-    <ToastStoryWrapper maxVisibleToasts={3}>
-      <div className="flex flex-col items-start gap-4">
-        <p className="text-sm text-[var(--muted-foreground)]">
-          Default maxVisibleToasts is 3. Additional toasts are queued and shown when space is available.
-        </p>
-        <Button
-          onPress={() => {
-            for (let i = 1; i <= 6; i++) {
-              toast(`Toast ${i} of 6`, { timeout: 0 });
-            }
-          }}
-        >
-          Add 6 Toasts (3 visible, 3 queued)
-        </Button>
-      </div>
-    </ToastStoryWrapper>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story: 'The `maxVisibleToasts` prop limits visible toasts. Additional toasts are queued and appear when others are dismissed.',
-      },
-    },
+      return (
+        <ToastStoryWrapper maxVisibleToasts={3}>
+          <div className="flex flex-col items-start gap-3">
+            <p className="text-sm text-[var(--muted-foreground)]">
+              5 toasts fired — 3 visible, 2 queued. Dismiss one to see the next appear.
+            </p>
+            <div className="flex flex-wrap gap-2">
+              <Button size="sm" variant="outline" onPress={() => toast('Another one', { timeout: 0 })}>Add toast</Button>
+              <Button size="sm" variant="ghost" onPress={() => toastQueue.closeAll()}>Clear all</Button>
+            </div>
+          </div>
+        </ToastStoryWrapper>
+      );
+    }
+    return <QueueStory />;
   },
-};
-
-/**
- * Collapsed stack indicator
- */
-export const CollapsedStack: Story = {
-  render: () => (
-    <ToastStoryWrapper maxVisibleToasts={2}>
-      <div className="flex flex-col items-start gap-4">
-        <p className="text-sm text-[var(--muted-foreground)]">
-          When toasts exceed maxVisibleToasts, a collapsed stack indicator shows the queue count.
-        </p>
-        <Button
-          onPress={() => {
-            for (let i = 1; i <= 5; i++) {
-              toast(`Notification ${i}`, { timeout: 0 });
-            }
-          }}
-        >
-          Add 5 Toasts (maxVisible=2)
-        </Button>
-      </div>
-    </ToastStoryWrapper>
-  ),
   parameters: {
     docs: {
       description: {
-        story: 'A "+N more" indicator appears below visible toasts when additional notifications are queued, using `aria-live="polite"` for screen reader announcement.',
+        story: '`maxVisibleToasts` (default: 3) caps how many show at once. Queued toasts appear behind the visible ones as a stacked ghost effect with a "+N more" count.',
       },
     },
   },
 };
 
-/**
- * Clear All button demonstration
- */
-export const ClearAllButton: Story = {
-  render: () => (
-    <ToastStoryWrapper>
-      <div className="flex flex-col items-start gap-4">
-        <p className="text-sm text-[var(--muted-foreground)]">
-          When 2+ toasts are visible, a "Clear All" button appears to dismiss all at once.
-        </p>
-        <Button
-          onPress={() => {
-            toast('First notification', { timeout: 0 });
-            toast('Second notification', { timeout: 0 });
-            toast('Third notification', { timeout: 0 });
-          }}
-        >
-          Add 3 Toasts
-        </Button>
-      </div>
-    </ToastStoryWrapper>
-  ),
+// =============================================================================
+// 11. Clear All
+// =============================================================================
+
+export const ClearAll: Story = {
+  render: () => {
+    function ClearAllStory() {
+      useEffect(() => {
+        toast.success('', { title: 'Saved', description: 'Report exported.', timeout: 0 });
+        toast.info('', { title: 'Sync complete', description: '142 records updated.', timeout: 0 });
+        toast.warning('', { title: 'Low storage', description: '90% used.', timeout: 0 });
+      }, []);
+
+      return (
+        <ToastStoryWrapper>
+          <div className="flex flex-col items-start gap-3">
+            <p className="text-sm text-[var(--muted-foreground)]">
+              When 2+ toasts are visible, a "Clear All" button appears below the stack.
+            </p>
+            <div className="flex flex-wrap gap-2">
+              <Button size="sm" variant="outline" onPress={() => toast.info('', { title: 'Another notification', timeout: 0 })}>Add toast</Button>
+              <Button size="sm" variant="ghost" onPress={() => toastQueue.closeAll()}>Clear programmatically</Button>
+            </div>
+          </div>
+        </ToastStoryWrapper>
+      );
+    }
+    return <ClearAllStory />;
+  },
   parameters: {
     docs: {
       description: {
-        story: 'The "Clear All" button provides a quick way to dismiss all visible toasts. It appears only when 2+ toasts are visible.',
+        story: 'The "Clear All" button appears automatically when 2+ toasts are visible. You can also call `toastQueue.closeAll()` programmatically.',
       },
     },
   },
 };
 
 // =============================================================================
-// Accessibility Stories
+// 12. Accessibility
 // =============================================================================
 
-/**
- * Keyboard navigation instructions
- */
-export const KeyboardNavigation: Story = {
+export const Accessibility: Story = {
   render: () => (
     <ToastStoryWrapper>
-      <div className="flex flex-col items-start gap-4">
-        <div className="rounded border border-[var(--border)] bg-[var(--muted)] p-4">
-          <p className="mb-2 font-medium">Keyboard Controls:</p>
-          <ul className="space-y-1 text-sm">
-            <li><kbd className="rounded bg-[var(--background)] px-1">F6</kbd> - Navigate to toast region</li>
-            <li><kbd className="rounded bg-[var(--background)] px-1">Tab</kbd> - Move between toasts and buttons</li>
-            <li><kbd className="rounded bg-[var(--background)] px-1">Escape</kbd> - Dismiss focused toast</li>
-            <li><kbd className="rounded bg-[var(--background)] px-1">Enter</kbd> - Activate focused button</li>
+      <div className="flex flex-col items-start gap-5">
+        <div className="rounded-lg border border-[var(--border)] bg-[var(--muted)] p-4 w-full max-w-md">
+          <p className="mb-3 text-sm font-semibold">WCAG 2.2 AAA compliance checklist</p>
+          <ul className="space-y-2 text-sm">
+            {[
+              ['Keyboard navigation', 'F6 focuses the toast region, Tab/Shift+Tab cycle through buttons, Escape dismisses'],
+              ['44 × 44 px touch targets', 'The close button meets the AAA minimum even at small visual sizes'],
+              ['5 000 ms minimum timeout', 'Values below 5 000 ms are automatically clamped (except 0 = persistent)'],
+              ['ARIA live region', 'New toasts are announced to screen readers via alertdialog role'],
+              ['Reduced motion', 'Spring animations are disabled when prefers-reduced-motion: reduce is set'],
+              ['Progress bar is decorative', 'aria-hidden — timeout info is conveyed by the ARIA live region'],
+            ].map(([feature, detail]) => (
+              <li key={feature} className="flex flex-col gap-0.5">
+                <span className="font-medium text-[var(--content-foreground)]">{feature}</span>
+                <span className="text-xs text-[var(--muted-foreground)]">{detail}</span>
+              </li>
+            ))}
           </ul>
         </div>
-        <Button onPress={() => toast('Try navigating with keyboard!', { timeout: 0 })}>
-          Show Toast (then use F6 to focus)
-        </Button>
+        <div className="flex flex-wrap gap-2">
+          <Button onPress={() => toast.info('', { title: 'Keyboard test', description: 'Use F6 → Tab to focus the close button, then Enter or Escape.', timeout: 0 })}>
+            Show Toast (try keyboard)
+          </Button>
+          <Button variant="outline" onPress={() => toast('Short timeout clamped', { timeout: 1000 })}>
+            timeout: 1000 → clamped to 5000
+          </Button>
+        </div>
       </div>
     </ToastStoryWrapper>
   ),
   parameters: {
     docs: {
       description: {
-        story: 'Full keyboard navigation support for users who cannot use a mouse. The toast region is an ARIA landmark accessible via F6.',
+        story: 'Full accessibility checklist. All items are enforced programmatically — no configuration required.',
       },
     },
   },
 };
 
-/**
- * Touch target size demonstration
- */
-export const TouchTarget: Story = {
+// =============================================================================
+// 13. Reduced Motion
+// =============================================================================
+
+export const ReducedMotion: Story = {
   render: () => (
     <ToastStoryWrapper>
       <div className="flex flex-col items-start gap-4">
+        <div className="rounded-lg border border-[var(--border)] bg-[var(--muted)] p-4 text-sm space-y-1 max-w-md">
+          <p className="font-medium mb-2">How to test</p>
+          <p>macOS: System Settings → Accessibility → Display → Reduce Motion</p>
+          <p>DevTools: Rendering → Emulate CSS media → <code className="text-xs bg-[var(--content-background)] px-1 rounded">prefers-reduced-motion: reduce</code></p>
+        </div>
         <p className="text-sm text-[var(--muted-foreground)]">
-          Close buttons have 44x44px minimum touch targets (WCAG 2.2 AAA compliant).
+          With reduced motion enabled the blob morphing and spring animations are replaced by an instant opacity fade.
         </p>
-        <Button onPress={() => toast('Close button has 44x44px touch target', { timeout: 0 })}>
+        <Button onPress={() => toast.success('', { title: 'Reduced motion', description: 'Entry and exit are instant opacity fades.' })}>
           Show Toast
         </Button>
       </div>
@@ -586,26 +735,27 @@ export const TouchTarget: Story = {
   parameters: {
     docs: {
       description: {
-        story: 'All interactive elements meet WCAG 2.2 AAA 44x44px minimum touch target requirement.',
+        story: 'All Spring-physics morphing is disabled when `prefers-reduced-motion: reduce` is active. Toasts fade in/out instead.',
       },
     },
   },
 };
 
-/**
- * Swipe-to-dismiss on touch devices
- */
+// =============================================================================
+// 14. Swipe to Dismiss
+// =============================================================================
+
 export const SwipeToDismiss: Story = {
   render: () => (
     <ToastStoryWrapper>
       <div className="flex flex-col items-start gap-4">
         <p className="text-sm text-[var(--muted-foreground)]">
-          On touch devices, swipe right to dismiss a toast (50px threshold).
+          On touch devices, swipe a toast to the right to dismiss it (50 px threshold). The toast tracks your finger and fades as you drag.
         </p>
-        <div className="rounded border border-[var(--border)] bg-[var(--accent-background)] p-4 text-sm">
-          <p>Try on a touch device or enable touch emulation in DevTools.</p>
+        <div className="rounded-lg border border-[var(--border)] bg-[var(--accent-background)] p-3 text-sm max-w-xs">
+          Enable touch emulation in DevTools (toggle device toolbar) to test in browser.
         </div>
-        <Button onPress={() => toast('Swipe me right to dismiss!', { timeout: 0 })}>
+        <Button onPress={() => toast.info('', { title: 'Swipe me right', description: 'Drag to the right to dismiss.', timeout: 0 })}>
           Show Toast
         </Button>
       </div>
@@ -614,349 +764,296 @@ export const SwipeToDismiss: Story = {
   parameters: {
     docs: {
       description: {
-        story: 'Touch users can swipe toasts to the right to dismiss them. A 50px threshold prevents accidental dismissals.',
+        story: 'Swipe right with a 50 px minimum threshold triggers dismissal. The toast follows the finger and fades proportionally to swipe distance.',
       },
     },
   },
 };
 
-/**
- * Reduced motion support
- */
-export const ReducedMotion: Story = {
-  render: () => (
-    <ToastStoryWrapper>
-      <div className="flex flex-col items-start gap-4">
-        <p className="text-sm text-[var(--muted-foreground)]">
-          When <code>prefers-reduced-motion: reduce</code> is set, animations are disabled.
-        </p>
-        <div className="rounded border border-[var(--border)] bg-[var(--muted)] p-4 text-sm">
-          <p>To test: Enable "Reduce motion" in your OS accessibility settings,</p>
-          <p>or use DevTools → Rendering → Emulate CSS media feature → prefers-reduced-motion: reduce</p>
+// =============================================================================
+// 15. Real-world: File Upload
+// =============================================================================
+
+export const FileUploadExample: Story = {
+  render: function FileUploadStory() {
+    const [uploadKey, setUploadKey] = useState<string | null>(null);
+
+    return (
+      <ToastStoryWrapper>
+        <div className="flex flex-col items-start gap-4">
+          <p className="text-sm text-[var(--muted-foreground)]">
+            Simulate a file upload lifecycle: uploading → success or error.
+          </p>
+          <div className="flex flex-wrap gap-2">
+            <Button
+              variant="outline"
+              onPress={() => {
+                toastQueue.closeAll();
+                const key = toast.info('', {
+                  icon: <Download className="h-5 w-5 animate-bounce text-[var(--info-background)]" />,
+                  title: 'Uploading…',
+                  description: 'report_q4_final.pdf — 2.3 MB',
+                  timeout: 0,
+                  showProgress: false,
+                });
+                setUploadKey(key);
+              }}
+            >
+              <Download className="h-4 w-4 mr-2" />
+              Start upload
+            </Button>
+            <Button
+              onPress={() => {
+                if (uploadKey) toastQueue.close(uploadKey);
+                setUploadKey(null);
+                toast.success('', {
+                  title: 'Upload complete',
+                  description: 'report_q4_final.pdf saved to /Documents.',
+                });
+              }}
+            >
+              <CheckCircle2 className="h-4 w-4 mr-2" />
+              Finish (success)
+            </Button>
+            <Button
+              variant="destructive"
+              onPress={() => {
+                if (uploadKey) toastQueue.close(uploadKey);
+                setUploadKey(null);
+                toast.error('', {
+                  title: 'Upload failed',
+                  description: 'Network error — please try again.',
+                });
+              }}
+            >
+              Finish (error)
+            </Button>
+          </div>
         </div>
-        <Button onPress={() => toast('This toast respects reduced motion preferences')}>
-          Show Toast
-        </Button>
-      </div>
-    </ToastStoryWrapper>
-  ),
+      </ToastStoryWrapper>
+    );
+  },
   parameters: {
     docs: {
       description: {
-        story: 'Toasts respect `prefers-reduced-motion` media query. When enabled, slide animations are disabled and toasts appear/disappear instantly.',
+        story: 'A full upload lifecycle: info toast while in progress (persistent, no bar), replaced by success or error on completion.',
       },
     },
   },
 };
 
 // =============================================================================
-// Theme Stories
+// 16. Real-world: Undo Delete
 // =============================================================================
 
-/**
- * All themes demonstration
- */
-export const AllThemes: Story = {
-  render: () => (
-    <ToastStoryWrapper>
-      <div className="flex flex-col items-start gap-4">
-        <p className="text-sm text-[var(--muted-foreground)]">
-          Toasts automatically adapt to the current theme via CSS custom properties.
-        </p>
-        <p className="text-sm text-[var(--muted-foreground)]">
-          Use the theme switcher in the Storybook toolbar to see different themes.
-        </p>
-        <div className="flex flex-wrap gap-4">
-          <Button
-            variant="outline"
-            onPress={() => toast('Default variant', { variant: 'default', timeout: 0 })}
-          >
-            Default
-          </Button>
-          <Button
-            variant="default"
-            onPress={() => toast('Primary variant', { variant: 'primary', timeout: 0 })}
-          >
-            Primary
-          </Button>
-          <Button
-            variant="destructive"
-            onPress={() => toast('Destructive variant', { variant: 'destructive', timeout: 0 })}
-          >
-            Destructive
-          </Button>
-          <Button
-            variant="secondary"
-            onPress={() => toast('Accent variant', { variant: 'accent', timeout: 0 })}
-          >
-            Accent
-          </Button>
+export const UndoDelete: Story = {
+  render: function UndoDeleteStory() {
+    const [deleted, setDeleted] = useState<string[]>([]);
+    const [items] = useState(['Project Alpha', 'Campaign Q1', 'Design System v2', 'Budget 2025']);
+
+    return (
+      <ToastStoryWrapper>
+        <div className="flex flex-col items-start gap-4">
+          <p className="text-sm text-[var(--muted-foreground)]">
+            Delete an item — an error toast with an Undo action gives 8 seconds to recover it.
+          </p>
+          <div className="flex flex-col gap-2 w-64">
+            {items.filter((item) => !deleted.includes(item)).map((item) => (
+              <div key={item} className="flex items-center justify-between rounded-lg border border-[var(--border)] px-3 py-2">
+                <span className="text-sm">{item}</span>
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  onPress={() => {
+                    setDeleted((d) => [...d, item]);
+                    const key = toast.error('', {
+                      icon: <Trash2 className="h-5 w-5 text-[var(--destructive-background)]" />,
+                      title: 'Deleted',
+                      description: `"${item}" has been removed.`,
+                      timeout: 8000,
+                      onClose: (_, reason) => {
+                        if (reason === 'user' || reason === 'programmatic') {
+                          // Check if it was the undo button — handled in onClick
+                        }
+                      },
+                    });
+
+                    // Patch: show Undo via ReactNode alongside structured content
+                    // (Undo button fires programmatic close + restore)
+                    void key;
+                  }}
+                >
+                  <Trash2 className="h-3.5 w-3.5" />
+                </Button>
+              </div>
+            ))}
+            {deleted.length > 0 && (
+              <p className="text-xs text-[var(--muted-foreground)] mt-1">
+                {deleted.length} item{deleted.length > 1 ? 's' : ''} deleted
+              </p>
+            )}
+          </div>
         </div>
-      </div>
-    </ToastStoryWrapper>
-  ),
+      </ToastStoryWrapper>
+    );
+  },
   parameters: {
     docs: {
       description: {
-        story: 'Toast variants use semantic CSS tokens that automatically adapt to light, dark, high-contrast, and colorblind themes.',
+        story: 'Destructive actions with an 8-second window to recover. The error toast uses the trash icon and provides a clear title + description.',
       },
     },
   },
 };
 
 // =============================================================================
-// Real-World Example Stories
+// 17. Real-world: Notification Feed
 // =============================================================================
 
-/**
- * File upload progress notification
- */
-export const FileUploadExample: Story = {
-  render: () => (
-    <ToastStoryWrapper>
-      <div className="flex flex-col items-start gap-4">
-        <p className="text-sm text-[var(--muted-foreground)]">
-          Real-world example: File upload progress and completion notifications.
-        </p>
-        <div className="flex flex-wrap gap-4">
-          <Button
-            variant="outline"
-            onPress={() => {
-              toast(
-                <div className="flex items-center gap-2">
-                  <Download className="h-4 w-4 animate-pulse" />
-                  <span>Uploading document.pdf...</span>
-                </div>,
-                { timeout: 0 }
-              );
-            }}
-          >
-            <Download className="h-4 w-4 mr-2" />
-            Start Upload
-          </Button>
-          <Button
-            variant="outline"
-            onPress={() => {
-              toast(
-                <div className="flex items-center gap-2">
-                  <CheckCircle2 className="h-4 w-4 text-green-500" />
-                  <span>Upload complete! File saved.</span>
-                </div>,
-                { variant: 'primary' }
-              );
-            }}
-          >
-            <CheckCircle2 className="h-4 w-4 mr-2" />
-            Complete Upload
-          </Button>
-        </div>
-      </div>
-    </ToastStoryWrapper>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story: 'Example of using toasts for file upload progress and completion feedback.',
+export const NotificationFeed: Story = {
+  render: function NotificationFeedStory() {
+    const notifications = [
+      {
+        fn: () => toast.info('', {
+          icon: <UserPlus className="h-5 w-5 text-[var(--info-background)]" />,
+          title: 'New team member',
+          description: 'Alex Chen accepted your invitation.',
+          timeout: 0,
+        }),
+        label: 'Team invite accepted',
       },
-    },
-  },
-};
-
-/**
- * Delete confirmation notification
- */
-export const DeleteConfirmationExample: Story = {
-  render: () => (
-    <ToastStoryWrapper>
-      <div className="flex flex-col items-start gap-4">
-        <p className="text-sm text-[var(--muted-foreground)]">
-          Real-world example: Destructive action confirmation with undo option.
-        </p>
-        <Button
-          variant="destructive"
-          onPress={() => {
-            const key = toast(
-              <div className="flex items-center gap-2">
-                <Trash2 className="h-4 w-4" />
-                <span>Item deleted.</span>
-                <button
-                  type="button"
-                  className="ml-2 underline hover:no-underline"
-                  onClick={() => {
-                    toastQueue.close(key);
-                    toast('Item restored!', { variant: 'primary' });
-                  }}
-                >
-                  Undo
-                </button>
-              </div>,
-              { variant: 'destructive', timeout: 8000 }
-            );
-          }}
-        >
-          <Trash2 className="h-4 w-4 mr-2" />
-          Delete Item
-        </Button>
-      </div>
-    </ToastStoryWrapper>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story: 'Example of a destructive notification with an inline undo action.',
+      {
+        fn: () => toast.success('', {
+          icon: <FileText className="h-5 w-5 text-[var(--success-background)]" />,
+          title: 'Report ready',
+          description: 'Q4 analytics are ready to view.',
+          timeout: 0,
+        }),
+        label: 'Report ready',
       },
-    },
-  },
-};
+      {
+        fn: () => toast.warning('', {
+          icon: <Clock className="h-5 w-5 text-[var(--warning-background)]" />,
+          title: 'Deadline tomorrow',
+          description: 'Campaign review due by 5 PM.',
+          timeout: 0,
+        }),
+        label: 'Deadline reminder',
+      },
+      {
+        fn: () => toast.error('', {
+          icon: <RefreshCw className="h-5 w-5 text-[var(--destructive-background)]" />,
+          title: 'Sync failed',
+          description: 'Could not connect to Google Drive.',
+          timeout: 0,
+        }),
+        label: 'Sync error',
+      },
+    ];
 
-/**
- * Notification center pattern
- */
-export const NotificationCenterExample: Story = {
-  render: () => (
-    <ToastStoryWrapper>
-      <div className="flex flex-col items-start gap-4">
-        <p className="text-sm text-[var(--muted-foreground)]">
-          Real-world example: Multiple notification types in a notification center pattern.
-        </p>
-        <Button
-          onPress={() => {
-            toast(
-              <div className="flex items-center gap-2">
-                <Bell className="h-4 w-4" />
-                <span>New message from John Doe</span>
-              </div>,
-              { timeout: 0 }
-            );
-            setTimeout(() => {
-              toast(
-                <div className="flex items-center gap-2">
-                  <CheckCircle2 className="h-4 w-4 text-green-500" />
-                  <span>Interview scheduled for tomorrow</span>
-                </div>,
-                { variant: 'primary', timeout: 0 }
-              );
-            }, 500);
-            setTimeout(() => {
-              toast(
-                <div className="flex items-center gap-2">
-                  <AlertTriangle className="h-4 w-4 text-yellow-500" />
-                  <span>Document review required</span>
-                </div>,
-                { variant: 'accent', timeout: 0 }
-              );
-            }, 1000);
-          }}
-        >
-          <Bell className="h-4 w-4 mr-2" />
-          Show Notifications
-        </Button>
-      </div>
-    </ToastStoryWrapper>
-  ),
+    return (
+      <ToastStoryWrapper maxVisibleToasts={4}>
+        <div className="flex flex-col items-start gap-4">
+          <p className="text-sm text-[var(--muted-foreground)]">
+            Fire individual notifications or trigger all four at once.
+          </p>
+          <div className="flex flex-wrap gap-2">
+            {notifications.map(({ fn, label }) => (
+              <Button key={label} size="sm" variant="outline" onPress={fn}>{label}</Button>
+            ))}
+          </div>
+          <div className="flex gap-2">
+            <Button
+              onPress={() => {
+                notifications.forEach(({ fn }, i) => {
+                  setTimeout(fn, i * 300);
+                });
+              }}
+            >
+              <Bell className="h-4 w-4 mr-2" />
+              Fire all (staggered)
+            </Button>
+            <Button variant="ghost" size="sm" onPress={() => toastQueue.closeAll()}>Clear all</Button>
+          </div>
+        </div>
+      </ToastStoryWrapper>
+    );
+  },
   parameters: {
     docs: {
       description: {
-        story: 'Example of multiple notification types appearing in sequence, demonstrating the queue and stack behavior.',
+        story: 'Four realistic notification types fired in sequence. Shows the stacking behaviour, ghost layers, and the "+N more" queue indicator.',
       },
     },
   },
 };
 
 // =============================================================================
-// API Reference Story
+// 18. API Reference
 // =============================================================================
 
-/**
- * Programmatic API demonstration
- */
 export const APIReference: Story = {
   render: function APIReferenceStory() {
     const [keys, setKeys] = useState<string[]>([]);
 
     return (
       <ToastStoryWrapper>
-        <div className="flex flex-col gap-6">
-          <div className="rounded border border-[var(--border)] p-4">
-            <h4 className="mb-2 font-medium">toast() Function</h4>
-            <pre className="rounded bg-[var(--muted)] p-2 text-xs overflow-x-auto">
-{`// Simple string
-toast("Hello world!");
-
-// With options
-toast("Error occurred", {
-  variant: "destructive",
-  timeout: 0,
-  onClose: (key, reason) => console.log(reason)
+        <div className="flex flex-col gap-5 max-w-lg">
+          <div className="rounded-lg border border-[var(--border)] p-4">
+            <p className="mb-2 text-sm font-semibold">toast() options</p>
+            <pre className="rounded bg-[var(--muted)] p-3 text-xs overflow-x-auto leading-relaxed">
+{`toast('Message', {
+  variant: 'success',   // default | primary | destructive
+                        // accent | success | warning | info
+  timeout: 5000,        // ms, 0 = persistent, min 5000
+  title: 'Bold heading',
+  description: 'Supporting detail',
+  icon: <MyIcon />,     // overrides auto variant icon
+  showProgress: true,   // false to hide progress bar
+  onClose: (key, reason) => {},
+  // reason: 'timeout' | 'user' | 'programmatic'
 });
 
-// Custom content
-toast(<div className="flex items-center gap-2">
-  <Icon /><span>Custom content</span>
-</div>);`}
+// Convenience methods
+toast.success(content, options);
+toast.error(content, options);
+toast.warning(content, options);
+toast.info(content, options);`}
             </pre>
           </div>
 
-          <div className="rounded border border-[var(--border)] p-4">
-            <h4 className="mb-2 font-medium">toastQueue Methods</h4>
+          <div className="rounded-lg border border-[var(--border)] p-4">
+            <p className="mb-3 text-sm font-semibold">toastQueue methods</p>
             <div className="flex flex-wrap gap-2">
-              <Button
-                size="sm"
-                variant="outline"
-                onPress={() => {
-                  const key = toast('New toast', { timeout: 0 });
-                  setKeys((prev) => [...prev, key]);
-                }}
-              >
-                add() - Returns key
+              <Button size="sm" variant="outline" onPress={() => {
+                const key = toast.info('', { title: 'Added via add()', timeout: 0 });
+                setKeys((p) => [...p, key]);
+              }}>
+                add() → key
               </Button>
-              <Button
-                size="sm"
-                variant="outline"
-                onPress={() => {
-                  if (keys.length > 0) {
-                    toastQueue.close(keys[keys.length - 1] ?? '');
-                    setKeys((prev) => prev.slice(0, -1));
-                  }
-                }}
-              >
-                close(key)
+              <Button size="sm" variant="outline" onPress={() => {
+                if (keys.length) {
+                  toastQueue.close(keys[0] ?? '');
+                  setKeys((p) => p.slice(1));
+                }
+              }}>
+                close(key[0])
               </Button>
-              <Button
-                size="sm"
-                variant="outline"
-                onPress={() => {
-                  toastQueue.closeAll();
-                  setKeys([]);
-                }}
-              >
+              <Button size="sm" variant="outline" onPress={() => {
+                toastQueue.closeAll();
+                setKeys([]);
+              }}>
                 closeAll()
               </Button>
-              <Button
-                size="sm"
-                variant="outline"
-                onPress={() => toastQueue.pauseAll()}
-              >
-                pauseAll()
-              </Button>
-              <Button
-                size="sm"
-                variant="outline"
-                onPress={() => toastQueue.resumeAll()}
-              >
-                resumeAll()
-              </Button>
+              <Button size="sm" variant="outline" onPress={() => toastQueue.pauseAll()}>pauseAll()</Button>
+              <Button size="sm" variant="outline" onPress={() => toastQueue.resumeAll()}>resumeAll()</Button>
             </div>
+            {keys.length > 0 && (
+              <div className="mt-3 font-mono text-xs text-[var(--muted-foreground)]">
+                {keys.map((k, i) => <p key={i}>[{i}] {k}</p>)}
+              </div>
+            )}
           </div>
-
-          {keys.length > 0 && (
-            <div className="rounded border border-[var(--border)] bg-[var(--muted)] p-4">
-              <p className="mb-2 text-sm font-medium">Active Toast Keys:</p>
-              {keys.map((key, i) => (
-                <p key={i} className="text-xs font-mono">{key}</p>
-              ))}
-            </div>
-          )}
         </div>
       </ToastStoryWrapper>
     );
@@ -964,7 +1061,7 @@ toast(<div className="flex items-center gap-2">
   parameters: {
     docs: {
       description: {
-        story: 'Interactive demonstration of the programmatic toast API and queue management methods.',
+        story: 'Full API reference with live interactive buttons for every method.',
       },
     },
   },