aural-ui 4.0.1 → 4.2.0

package/dist/components/toggle/Toggle.stories.tsx

@@ -1,142 +1,66 @@
-import React from "react"
+import React, { useState } from "react"
 import {
   AlertIcon,
   EditBigIcon,
   EyeCloseIcon,
   EyeOpenIcon,
   FileChartIcon,
-  PlusIcon,
+  MoonIcon,
+  PauseIcon,
   SearchIcon,
+  SkipBackwardIcon,
+  SkipForwardIcon,
   TickCircleIcon,
   TrashIcon,
+  VolumeFullIcon,
 } from "@icons/index"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import { Toggle } from "."
 
 const meta: Meta<typeof Toggle> = {
   title: "Components/UI/Toggle",
   component: Toggle,
+  tags: ["autodocs"],
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-# Toggle Component
-
-A flexible toggle button component built on top of Radix UI's Toggle primitive, providing on/off state management with visual feedback.
-
-## Features
-
-- **State Management**: Built-in pressed/unpressed state handling
-- **Keyboard Accessible**: Full keyboard navigation support
-- **Multiple Variants**: Default and outline styles
-- **Size Options**: Small, default, and large sizes
-- **Icon Support**: Automatic icon sizing and styling
-- **Disabled State**: Proper disabled state handling
-- **Focus Management**: Clear focus indicators
-- **ARIA Support**: Proper accessibility attributes
-
-## Variants
-
-### Default
-- **default**: Transparent background with accent highlighting
-- **outline**: Border style with shadow and hover effects
-
-### Sizes
-- **sm**: Small (32px height, compact padding)
-- **default**: Standard (36px height, balanced padding)
-- **lg**: Large (40px height, generous padding)
-
-## Usage Examples
-
-### Basic Toggle
-\`\`\`tsx
-<Toggle aria-label="Toggle bold">
-  Bold
-</Toggle>
-\`\`\`
-
-### With Icon
-\`\`\`tsx
-<Toggle aria-label="Toggle notifications">
-  <AlertIcon />
-  Notifications
-</Toggle>
-\`\`\`
-
-### Icon Only
-\`\`\`tsx
-<Toggle aria-label="Toggle visibility">
-  <EyeOpenIcon />
-</Toggle>
-\`\`\`
-
-### Controlled State
-\`\`\`tsx
-const [pressed, setPressed] = useState(false)
-
-<Toggle 
-  pressed={pressed} 
-  onPressedChange={setPressed}
-  aria-label="Toggle feature"
->
-  Feature
-</Toggle>
-\`\`\`
-
-### Different Variants
-\`\`\`tsx
-<Toggle variant="outline" size="sm">
-  Small Outline
-</Toggle>
-\`\`\`
-
-## Accessibility
-
-- **ARIA Label**: Always provide \`aria-label\` for screen readers
-- **Keyboard Navigation**: Spacebar and Enter toggle state
-- **Focus Indicators**: Clear visual focus ring
-- **State Announcement**: Screen readers announce pressed state
-- **Semantic HTML**: Uses proper button semantics
-
-## States
-
-- **Default**: Unpressed/off state
-- **Pressed**: Pressed/on state with accent styling
-- **Hover**: Subtle background change on hover
-- **Focus**: Clear focus ring for keyboard navigation
-- **Disabled**: Reduced opacity and no interaction
-
-## Best Practices
-
-- Always provide descriptive \`aria-label\` attributes
-- Use consistent toggle patterns throughout your app
-- Consider using icons to enhance visual clarity
-- Test with keyboard navigation and screen readers
-- Provide visual feedback for state changes
-        `,
+        component:
+          "A stateful toggle button built on Radix UI's Toggle primitive. Supports three visual variants (default, outline, filled), three sizes (sm, default, lg), pressed/unpressed states, disabled state, and icon or text content.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "3 Variants",
+              description: "Default, outline, filled",
+            },
+            {
+              title: "Pressed State",
+              description: "Controlled or uncontrolled",
+            },
+            {
+              title: "Icon or Text",
+              description: "Flexible content slot",
+            },
+          ]}
+        />
+      ),
     },
   },
-  tags: ["autodocs"],
   argTypes: {
     variant: {
       control: "select",
-      options: ["default", "outline"],
+      options: ["default", "outline", "filled"],
       description: "Visual style variant",
     },
     size: {
       control: "select",
       options: ["sm", "default", "lg"],
-      description: "Size of the toggle button",
+      description: "Size of the toggle",
     },
     pressed: {
       control: "boolean",
@@ -146,180 +70,178 @@ const [pressed, setPressed] = useState(false)
       control: "boolean",
       description: "Disabled state",
     },
-    className: {
-      control: "text",
-      description: "Additional CSS classes",
-    },
   },
 }
 
 export default meta
 type Story = StoryObj<typeof Toggle>
 
-// 1. Basic Toggle
-export const Basic: Story = {
+// ─── 1. Playground ────────────────────────────────────────────────────────────
+
+export const Playground: Story = {
   args: {
-    children: "Toggle me",
-    "aria-label": "Toggle basic example",
+    children: "Toggle",
+    variant: "default",
+    size: "default",
+    "aria-label": "Playground toggle",
   },
+  render: (args) => (
+    <div className="w-full max-w-sm space-y-4">
+      <div className="flex justify-center">
+        <Toggle {...args} />
+      </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)">{`<Toggle variant="${args.variant}" size="${args.size}">${args.children}</Toggle>`}</code>
+      </div>
+    </div>
+  ),
   parameters: {
     docs: {
       description: {
-        story: "A simple toggle button with text content.",
+        story:
+          "Adjust variant, size, pressed, and disabled using the controls panel in the sidebar.",
       },
     },
   },
 }
 
-// 2. Variants
-export const Variants: Story = {
-  render: () => (
-    <div className="flex flex-col gap-8 p-8">
-      <h3 className="text-fm-primary text-center text-lg font-medium">
-        Toggle Variants
-      </h3>
+// ─── 2. All Variants ──────────────────────────────────────────────────────────
 
-      <div className="grid grid-cols-1 gap-6 lg:grid-cols-2">
-        {/* Default Variant */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">
-            Default Variant
-          </h4>
-          <div className="flex flex-wrap gap-4">
-            <Toggle aria-label="Default unpressed">Default</Toggle>
-            <Toggle defaultPressed aria-label="Default pressed">
-              Pressed
+export const AllVariants: Story = {
+  render: () => (
+    <div className="space-y-8">
+      {/* Default variant × sizes */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Default variant — all sizes
+        </h4>
+        <div className="flex flex-wrap items-end gap-4">
+          <div className="space-y-2 text-center">
+            <Toggle size="sm" aria-label="Default small">
+              Small
             </Toggle>
-            <Toggle disabled aria-label="Default disabled">
-              Disabled
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              sm
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Toggle size="default" aria-label="Default default">
+              Default
             </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              default
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Toggle size="lg" aria-label="Default large">
+              Large
+            </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              lg
+            </p>
           </div>
         </div>
+      </div>
 
-        {/* Outline Variant */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">
-            Outline Variant
-          </h4>
-          <div className="flex flex-wrap gap-4">
-            <Toggle variant="outline" aria-label="Outline unpressed">
-              Outline
+      {/* Outline variant × sizes */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Outline variant — all sizes
+        </h4>
+        <div className="flex flex-wrap items-end gap-4">
+          <div className="space-y-2 text-center">
+            <Toggle variant="outline" size="sm" aria-label="Outline small">
+              Small
             </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              sm
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
             <Toggle
               variant="outline"
-              defaultPressed
-              aria-label="Outline pressed"
+              size="default"
+              aria-label="Outline default"
             >
-              Pressed
-            </Toggle>
-            <Toggle variant="outline" disabled aria-label="Outline disabled">
-              Disabled
+              Default
             </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              default
+            </p>
           </div>
-        </div>
-
-        {/* Filled Variant */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">
-            Filled Variant
-          </h4>
-          <div className="flex flex-wrap gap-4">
-            <Toggle variant="filled" aria-label="Filled unpressed">
-              Filled
-            </Toggle>
-            <Toggle variant="filled" defaultPressed aria-label="Filled pressed">
-              Pressed
-            </Toggle>
-            <Toggle variant="filled" disabled aria-label="Filled disabled">
-              Disabled
+          <div className="space-y-2 text-center">
+            <Toggle variant="outline" size="lg" aria-label="Outline large">
+              Large
             </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              lg
+            </p>
           </div>
         </div>
       </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Different visual variants showing default and outline styles in various states.",
-      },
-    },
-  },
-}
-
-// 3. Sizes
-export const Sizes: Story = {
-  render: () => (
-    <div className="space-y-8 p-8">
-      <h3 className="text-fm-primary text-center text-lg font-medium">
-        Toggle Sizes
-      </h3>
-
-      <div className="space-y-6">
-        {/* Size Comparison */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-center text-sm font-medium">
-            Size Comparison
-          </h4>
-          <div className="flex items-center justify-center gap-4">
-            <div className="flex flex-col items-center gap-2">
-              <Toggle size="sm" aria-label="Small toggle">
-                Small
-              </Toggle>
-              <span className="text-fm-secondary text-xs">Small (32px)</span>
-            </div>
-            <div className="flex flex-col items-center gap-2">
-              <Toggle size="default" aria-label="Default toggle">
-                Default
-              </Toggle>
-              <span className="text-fm-secondary text-xs">Default (36px)</span>
-            </div>
-            <div className="flex flex-col items-center gap-2">
-              <Toggle size="lg" aria-label="Large toggle">
-                Large
-              </Toggle>
-              <span className="text-fm-secondary text-xs">Large (40px)</span>
-            </div>
-          </div>
-        </div>
 
-        {/* Sizes with Icons */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-center text-sm font-medium">
-            With Icons
-          </h4>
-          <div className="flex items-center justify-center gap-4">
-            <Toggle size="sm" aria-label="Small with icon">
-              <AlertIcon />
+      {/* Filled variant × sizes */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Filled variant — all sizes
+        </h4>
+        <div className="flex flex-wrap items-end gap-4">
+          <div className="space-y-2 text-center">
+            <Toggle variant="filled" size="sm" aria-label="Filled small">
               Small
             </Toggle>
-            <Toggle size="default" aria-label="Default with icon">
-              <SearchIcon />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              sm
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Toggle variant="filled" size="default" aria-label="Filled default">
               Default
             </Toggle>
-            <Toggle size="lg" aria-label="Large with icon">
-              <EditBigIcon />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              default
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Toggle variant="filled" size="lg" aria-label="Filled large">
               Large
             </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              lg
+            </p>
           </div>
         </div>
+      </div>
 
-        {/* Icon Only Sizes */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-center text-sm font-medium">
-            Icon Only
-          </h4>
-          <div className="flex items-center justify-center gap-4">
-            <Toggle size="sm" aria-label="Small icon only">
-              <PlusIcon />
+      {/* Icon-only × all variants */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Icon-only — all variants
+        </h4>
+        <div className="flex flex-wrap items-center gap-4">
+          <div className="space-y-2 text-center">
+            <Toggle aria-label="Default icon only">
+              <SearchIcon />
             </Toggle>
-            <Toggle size="default" aria-label="Default icon only">
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              default
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Toggle variant="outline" aria-label="Outline icon only">
               <SearchIcon />
             </Toggle>
-            <Toggle size="lg" aria-label="Large icon only">
-              <EditBigIcon />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              outline
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Toggle variant="filled" aria-label="Filled icon only">
+              <SearchIcon />
             </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              filled
+            </p>
           </div>
         </div>
       </div>
@@ -329,405 +251,173 @@ export const Sizes: Story = {
     docs: {
       description: {
         story:
-          "Different size options for toggles, including text, icon with text, and icon-only variants.",
+          "Full variant × size matrix for all three visual styles (default, outline, filled), plus icon-only instances across each variant.",
       },
     },
   },
 }
 
-// 4. Icon Toggles
-export const IconToggles: Story = {
-  render: () => {
-    const [notifications, setNotifications] = React.useState(false)
-    const [visibility, setVisibility] = React.useState(false)
-    const [completed, setCompleted] = React.useState(false)
-
-    return (
-      <div className="space-y-8 p-8">
-        <h3 className="text-fm-primary text-center text-lg font-medium">
-          Icon Toggles
-        </h3>
+// ─── 3. States ────────────────────────────────────────────────────────────────
 
-        <div className="space-y-6">
-          {/* Icon with Text */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-center text-sm font-medium">
-              Icon with Text
-            </h4>
-            <div className="flex flex-wrap justify-center gap-4">
-              <Toggle
-                pressed={notifications}
-                onPressedChange={setNotifications}
-                aria-label="Toggle notifications"
-              >
-                <AlertIcon />
-                Notifications
-              </Toggle>
-
-              <Toggle
-                pressed={visibility}
-                onPressedChange={setVisibility}
-                aria-label="Toggle visibility"
-              >
-                {visibility ? <EyeOpenIcon /> : <EyeCloseIcon />}
-                {visibility ? "Visible" : "Hidden"}
-              </Toggle>
-
-              <Toggle
-                pressed={completed}
-                onPressedChange={setCompleted}
-                aria-label="Toggle completion"
-              >
-                <TickCircleIcon />
-                Complete
-              </Toggle>
-            </div>
+export const States: Story = {
+  render: () => (
+    <div className="space-y-8">
+      {/* Default variant states */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Default variant
+        </h4>
+        <div className="flex flex-wrap gap-4">
+          <div className="space-y-2 text-center">
+            <Toggle aria-label="Unpressed default">Unpressed</Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Unpressed
+            </p>
           </div>
-
-          {/* Icon Only */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-center text-sm font-medium">
-              Icon Only
-            </h4>
-            <div className="flex flex-wrap justify-center gap-4">
-              <Toggle aria-label="Toggle search">
-                <SearchIcon />
-              </Toggle>
-
-              <Toggle aria-label="Toggle edit mode">
-                <EditBigIcon />
-              </Toggle>
-
-              <Toggle aria-label="Toggle charts">
-                <FileChartIcon />
-              </Toggle>
-
-              <Toggle aria-label="Add to favorites" defaultPressed>
-                <PlusIcon />
-              </Toggle>
-
-              <Toggle aria-label="Delete mode" variant="outline">
-                <TrashIcon />
-              </Toggle>
-            </div>
+          <div className="space-y-2 text-center">
+            <Toggle defaultPressed aria-label="Pressed default">
+              Pressed
+            </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Pressed
+            </p>
           </div>
-
-          {/* Different Variants */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-center text-sm font-medium">
-              Different Variants
-            </h4>
-            <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">
-              <div className="space-y-2">
-                <span className="text-fm-secondary text-xs">
-                  Default Variant
-                </span>
-                <div className="flex flex-wrap gap-2">
-                  <Toggle aria-label="Default alert">
-                    <AlertIcon />
-                  </Toggle>
-                  <Toggle defaultPressed aria-label="Default search">
-                    <SearchIcon />
-                  </Toggle>
-                  <Toggle aria-label="Default edit">
-                    <EditBigIcon />
-                  </Toggle>
-                </div>
-              </div>
-
-              <div className="space-y-2">
-                <span className="text-fm-secondary text-xs">
-                  Outline Variant
-                </span>
-                <div className="flex flex-wrap gap-2">
-                  <Toggle variant="outline" aria-label="Outline alert">
-                    <AlertIcon />
-                  </Toggle>
-                  <Toggle
-                    variant="outline"
-                    defaultPressed
-                    aria-label="Outline search"
-                  >
-                    <SearchIcon />
-                  </Toggle>
-                  <Toggle variant="outline" aria-label="Outline edit">
-                    <EditBigIcon />
-                  </Toggle>
-                </div>
-              </div>
-            </div>
+          <div className="space-y-2 text-center">
+            <Toggle disabled aria-label="Disabled default">
+              Disabled
+            </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Disabled
+            </p>
           </div>
         </div>
       </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Icon-based toggles showing different configurations including dynamic icons and various states.",
-      },
-    },
-  },
-}
 
-// 5. Interactive States
-export const InteractiveStates: Story = {
-  render: () => {
-    const [states, setStates] = React.useState({
-      bold: false,
-      italic: false,
-      underline: false,
-      notifications: true,
-      autoSave: false,
-      darkMode: true,
-    })
-
-    const updateState = (key: keyof typeof states) => {
-      setStates((prev) => ({ ...prev, [key]: !prev[key] }))
-    }
-
-    return (
-      <div className="space-y-8 p-8">
-        <h3 className="text-fm-primary text-center text-lg font-medium">
-          Interactive States
-        </h3>
-
-        <div className="space-y-6">
-          {/* Text Formatting Toolbar */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-center text-sm font-medium">
-              Text Formatting Toolbar
-            </h4>
-            <div className="flex justify-center">
-              <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center gap-1 rounded-lg border p-2">
-                <Toggle
-                  size="sm"
-                  pressed={states.bold}
-                  onPressedChange={() => updateState("bold")}
-                  aria-label="Toggle bold"
-                >
-                  <span className="font-bold">B</span>
-                </Toggle>
-                <Toggle
-                  size="sm"
-                  pressed={states.italic}
-                  onPressedChange={() => updateState("italic")}
-                  aria-label="Toggle italic"
-                >
-                  <span className="italic">I</span>
-                </Toggle>
-                <Toggle
-                  size="sm"
-                  pressed={states.underline}
-                  onPressedChange={() => updateState("underline")}
-                  aria-label="Toggle underline"
-                >
-                  <span className="underline">U</span>
-                </Toggle>
-                <div className="bg-fm-surface-tertiary mx-2 h-6 w-px"></div>
-                <Toggle size="sm" aria-label="Add item">
-                  <PlusIcon />
-                </Toggle>
-                <Toggle size="sm" aria-label="Search">
-                  <SearchIcon />
-                </Toggle>
-              </div>
-            </div>
+      {/* Outline variant states */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Outline variant
+        </h4>
+        <div className="flex flex-wrap gap-4">
+          <div className="space-y-2 text-center">
+            <Toggle variant="outline" aria-label="Unpressed outline">
+              Unpressed
+            </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Unpressed
+            </p>
           </div>
-
-          {/* Settings Panel */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-center text-sm font-medium">
-              Settings Panel
-            </h4>
-            <div className="mx-auto max-w-xs space-y-3">
-              <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center justify-between rounded-lg border p-3">
-                <div className="flex items-center gap-3">
-                  <AlertIcon className="text-fm-icon-info h-4 w-4" />
-                  <span className="text-fm-primary text-sm">Notifications</span>
-                </div>
-                <Toggle
-                  size="sm"
-                  pressed={states.notifications}
-                  onPressedChange={() => updateState("notifications")}
-                  aria-label="Toggle notifications"
-                />
-              </div>
-
-              <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center justify-between rounded-lg border p-3">
-                <div className="flex items-center gap-3">
-                  <TickCircleIcon className="text-fm-icon-positive h-4 w-4" />
-                  <span className="text-fm-primary text-sm">Auto Save</span>
-                </div>
-                <Toggle
-                  size="sm"
-                  pressed={states.autoSave}
-                  onPressedChange={() => updateState("autoSave")}
-                  aria-label="Toggle auto save"
-                />
-              </div>
-
-              <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center justify-between rounded-lg border p-3">
-                <div className="flex items-center gap-3">
-                  <EyeOpenIcon className="text-fm-icon-brand-secondary h-4 w-4" />
-                  <span className="text-fm-primary text-sm">Dark Mode</span>
-                </div>
-                <Toggle
-                  size="sm"
-                  pressed={states.darkMode}
-                  onPressedChange={() => updateState("darkMode")}
-                  aria-label="Toggle dark mode"
-                />
-              </div>
-            </div>
+          <div className="space-y-2 text-center">
+            <Toggle
+              variant="outline"
+              defaultPressed
+              aria-label="Pressed outline"
+            >
+              Pressed
+            </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Pressed
+            </p>
           </div>
-
-          {/* State Display */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-center text-sm font-medium">
-              Current States
-            </h4>
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md rounded-lg border p-4">
-              <div className="grid grid-cols-2 gap-2 text-xs">
-                {Object.entries(states).map(([key, value]) => (
-                  <div key={key} className="flex justify-between">
-                    <span className="text-fm-secondary capitalize">{key}:</span>
-                    <span
-                      className={
-                        value
-                          ? "text-fm-icon-positive"
-                          : "text-fm-icon-negative"
-                      }
-                    >
-                      {value ? "ON" : "OFF"}
-                    </span>
-                  </div>
-                ))}
-              </div>
-            </div>
+          <div className="space-y-2 text-center">
+            <Toggle variant="outline" disabled aria-label="Disabled outline">
+              Disabled
+            </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Disabled
+            </p>
           </div>
         </div>
       </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Interactive examples showing toggles in real-world scenarios like toolbars and settings panels.",
-      },
-    },
-  },
-}
 
-// 6. Accessibility Demo
-export const AccessibilityDemo: Story = {
-  render: () => (
-    <div className="space-y-8 p-8">
-      <h3 className="text-fm-primary text-center text-lg font-medium">
-        Accessibility Features
-      </h3>
-
-      <div className="space-y-6">
-        <div className="border-fm-divider-secondary bg-fm-surface-info-sec rounded-lg border p-4">
-          <h4 className="text-fm-info mb-2 text-sm font-medium">
-            Keyboard Navigation
-          </h4>
-          <p className="text-fm-info-sec mb-2 text-xs">
-            Try these keyboard interactions:
-          </p>
-          <ul className="text-fm-info-sec space-y-1 text-xs">
-            <li>
-              • <kbd className="bg-fm-surface-secondary rounded px-1">Tab</kbd>{" "}
-              to focus toggles
-            </li>
-            <li>
-              •{" "}
-              <kbd className="bg-fm-surface-secondary rounded px-1">Space</kbd>{" "}
-              or{" "}
-              <kbd className="bg-fm-surface-secondary rounded px-1">Enter</kbd>{" "}
-              to toggle state
-            </li>
-            <li>• Clear focus indicators show current position</li>
-            <li>• Screen readers announce pressed state</li>
-          </ul>
+      {/* Filled variant states */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Filled variant
+        </h4>
+        <div className="flex flex-wrap gap-4">
+          <div className="space-y-2 text-center">
+            <Toggle variant="filled" aria-label="Unpressed filled">
+              Unpressed
+            </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Unpressed
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Toggle variant="filled" defaultPressed aria-label="Pressed filled">
+              Pressed
+            </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Pressed
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Toggle variant="filled" disabled aria-label="Disabled filled">
+              Disabled
+            </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Disabled
+            </p>
+          </div>
         </div>
+      </div>
 
-        {/* Keyboard Accessible Examples */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">
-            Keyboard Accessible Toggles
-          </h4>
-          <div className="flex flex-wrap justify-center gap-4">
-            <Toggle aria-label="Toggle feature A - currently off">
+      {/* Icon states */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Icon-only states
+        </h4>
+        <div className="flex flex-wrap gap-4">
+          <div className="space-y-2 text-center">
+            <Toggle aria-label="Alert unpressed">
               <AlertIcon />
-              Feature A
             </Toggle>
-
-            <Toggle defaultPressed aria-label="Toggle feature B - currently on">
-              <TickCircleIcon />
-              Feature B
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Unpressed
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Toggle defaultPressed aria-label="Alert pressed">
+              <AlertIcon />
             </Toggle>
-
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Pressed
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Toggle disabled aria-label="Alert disabled">
+              <AlertIcon />
+            </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Disabled
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
             <Toggle
               variant="outline"
-              aria-label="Toggle visibility - show or hide content"
+              defaultPressed
+              aria-label="Trash pressed outline"
             >
-              <EyeOpenIcon />
-              Visibility
-            </Toggle>
-
-            <Toggle size="sm" aria-label="Toggle search mode">
-              <SearchIcon />
+              <TrashIcon />
             </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Pressed outline
+            </p>
           </div>
-        </div>
-
-        {/* ARIA Labels Demo */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">
-            ARIA Labels Best Practices
-          </h4>
-          <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">
-            <div className="space-y-3">
-              <span className="text-fm-secondary text-xs">Good Examples</span>
-              <div className="space-y-2">
-                <Toggle aria-label="Toggle notifications - receive alerts when new messages arrive">
-                  <AlertIcon />
-                  Notifications
-                </Toggle>
-                <Toggle aria-label="Toggle edit mode - switch between viewing and editing">
-                  <EditBigIcon />
-                  Edit Mode
-                </Toggle>
-              </div>
-            </div>
-
-            <div className="space-y-3">
-              <span className="text-fm-secondary text-xs">Code Examples</span>
-              <div className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-tertiary rounded border p-3 font-mono text-xs">
-                <div>aria-label="Toggle notifications"</div>
-                <div>aria-label="Show/hide password"</div>
-                <div>aria-label="Enable dark mode"</div>
-              </div>
-            </div>
+          <div className="space-y-2 text-center">
+            <Toggle
+              variant="outline"
+              disabled
+              aria-label="Trash disabled outline"
+            >
+              <TrashIcon />
+            </Toggle>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Disabled outline
+            </p>
           </div>
         </div>
-
-        <div className="border-fm-divider-warning bg-fm-surface-warning-sec rounded-lg border p-4">
-          <h4 className="text-fm-warning mb-2 text-sm font-medium">
-            Best Practices
-          </h4>
-          <ul className="text-fm-warning-sec space-y-1 text-xs">
-            <li>• Always provide descriptive aria-label attributes</li>
-            <li>• Include current state in label when helpful</li>
-            <li>• Use consistent toggle patterns across your app</li>
-            <li>• Test with screen readers and keyboard navigation</li>
-            <li>• Ensure sufficient color contrast for all states</li>
-            <li>• Provide visual feedback for state changes</li>
-          </ul>
-        </div>
       </div>
     </div>
   ),
@@ -735,369 +425,236 @@ export const AccessibilityDemo: Story = {
     docs: {
       description: {
         story:
-          "Accessibility features including keyboard navigation, ARIA labels, and best practices for inclusive design.",
+          "Pressed, unpressed, and disabled states rendered for each variant. Disabled toggles suppress pointer events and render at reduced opacity.",
       },
     },
   },
 }
 
-// 7. Use Cases
-export const UseCases: Story = {
-  render: () => {
-    const [preferences, setPreferences] = React.useState({
-      notifications: true,
-      autoSave: false,
-      showPreview: true,
-      darkMode: true,
-    })
+// ─── 4. Interactive ───────────────────────────────────────────────────────────
 
-    const [toolbar, setToolbar] = React.useState({
+export const Interactive: Story = {
+  render: () => {
+    const [formatting, setFormatting] = useState({
       bold: false,
       italic: false,
-      list: false,
+      underline: false,
       code: false,
     })
 
-    const updatePreference = (key: keyof typeof preferences) => {
-      setPreferences((prev) => ({ ...prev, [key]: !prev[key] }))
-    }
+    const [playback, setPlayback] = useState({
+      shuffle: false,
+      repeat: false,
+      mute: false,
+    })
+
+    const [visibility, setVisibility] = useState(false)
+    const [done, setDone] = useState(false)
+
+    const toggleFormat = (key: keyof typeof formatting) =>
+      setFormatting((prev) => ({ ...prev, [key]: !prev[key] }))
 
-    const updateToolbar = (key: keyof typeof toolbar) => {
-      setToolbar((prev) => ({ ...prev, [key]: !prev[key] }))
-    }
+    const togglePlayback = (key: keyof typeof playback) =>
+      setPlayback((prev) => ({ ...prev, [key]: !prev[key] }))
+
+    const activeFormats = Object.entries(formatting)
+      .filter(([, v]) => v)
+      .map(([k]) => k)
 
     return (
-      <div className="space-y-8 p-8">
-        <h3 className="text-fm-primary text-center text-lg font-medium">
-          Real-world Use Cases
-        </h3>
+      <div className="w-full p-8">
+        <div className="mx-auto max-w-3xl space-y-6">
+          <div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
+            {/* Controls panel */}
+            <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-5 rounded-xl border p-5">
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                Current State
+              </p>
+
+              <div className="space-y-2">
+                <p className="text-fm-secondary font-fm-text text-fm-xs leading-fm-xs tracking-wider uppercase">
+                  Active formats
+                </p>
+                <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+                  {activeFormats.length === 0
+                    ? "None"
+                    : activeFormats.join(", ")}
+                </p>
+              </div>
+
+              <div className="border-fm-divider-secondary border-t pt-4" />
+
+              <div className="space-y-2">
+                <p className="text-fm-secondary font-fm-text text-fm-xs leading-fm-xs tracking-wider uppercase">
+                  Playback
+                </p>
+                <div className="flex flex-col gap-1">
+                  <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                    Shuffle:{" "}
+                    <span className="font-semibold">
+                      {playback.shuffle ? "ON" : "OFF"}
+                    </span>
+                  </p>
+                  <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                    Repeat:{" "}
+                    <span className="font-semibold">
+                      {playback.repeat ? "ON" : "OFF"}
+                    </span>
+                  </p>
+                  <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                    Mute:{" "}
+                    <span className="font-semibold">
+                      {playback.mute ? "ON" : "OFF"}
+                    </span>
+                  </p>
+                </div>
+              </div>
 
-        <div className="space-y-8">
-          {/* Editor Toolbar */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">
-              Editor Toolbar
-            </h4>
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
-              <div className="flex items-center gap-1">
-                <Toggle
-                  size="sm"
-                  pressed={toolbar.bold}
-                  onPressedChange={() => updateToolbar("bold")}
-                  aria-label="Toggle bold formatting"
-                >
-                  <span className="text-sm font-bold">B</span>
-                </Toggle>
-                <Toggle
-                  size="sm"
-                  pressed={toolbar.italic}
-                  onPressedChange={() => updateToolbar("italic")}
-                  aria-label="Toggle italic formatting"
-                >
-                  <span className="text-sm italic">I</span>
-                </Toggle>
-                <div className="bg-fm-surface-tertiary mx-2 h-4 w-px"></div>
-                <Toggle
-                  size="sm"
-                  pressed={toolbar.list}
-                  onPressedChange={() => updateToolbar("list")}
-                  aria-label="Toggle bullet list"
-                >
-                  • List
-                </Toggle>
-                <Toggle
-                  size="sm"
-                  pressed={toolbar.code}
-                  onPressedChange={() => updateToolbar("code")}
-                  aria-label="Toggle code formatting"
-                >
-                  <span className="font-mono text-sm">&lt;/&gt;</span>
-                </Toggle>
-                <div className="bg-fm-surface-tertiary mx-2 h-4 w-px"></div>
-                <Toggle size="sm" aria-label="Insert image">
-                  <FileChartIcon />
-                </Toggle>
-                <Toggle size="sm" aria-label="Add link">
-                  <PlusIcon />
-                </Toggle>
+              <div className="border-fm-divider-secondary border-t pt-4" />
+
+              <div className="space-y-2">
+                <p className="text-fm-secondary font-fm-text text-fm-xs leading-fm-xs tracking-wider uppercase">
+                  Visibility
+                </p>
+                <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+                  {visibility ? "Visible" : "Hidden"}
+                </p>
               </div>
             </div>
-          </div>
 
-          {/* User Preferences */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">
-              User Preferences
-            </h4>
-            <div className="grid grid-cols-1 gap-3 lg:grid-cols-2">
+            {/* Preview stage */}
+            <div className="flex flex-col gap-6 lg:col-span-2">
+              {/* Text formatting toolbar */}
               <div className="space-y-3">
-                <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center justify-between rounded-lg border p-3">
-                  <div className="flex items-center gap-3">
-                    <AlertIcon className="text-fm-icon-info h-4 w-4" />
-                    <div>
-                      <div className="text-fm-primary text-sm">
-                        Push Notifications
-                      </div>
-                      <div className="text-fm-secondary text-xs">
-                        Get notified of updates
-                      </div>
-                    </div>
-                  </div>
+                <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+                  Text formatting toolbar
+                </h4>
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary inline-flex items-center gap-1 rounded-lg border p-2">
                   <Toggle
-                    pressed={preferences.notifications}
-                    onPressedChange={() => updatePreference("notifications")}
-                    aria-label="Toggle push notifications"
-                  />
-                </div>
-
-                <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center justify-between rounded-lg border p-3">
-                  <div className="flex items-center gap-3">
-                    <TickCircleIcon className="text-fm-icon-positive h-4 w-4" />
-                    <div>
-                      <div className="text-fm-primary text-sm">Auto Save</div>
-                      <div className="text-fm-secondary text-xs">
-                        Save changes automatically
-                      </div>
-                    </div>
-                  </div>
+                    size="sm"
+                    pressed={formatting.bold}
+                    onPressedChange={() => toggleFormat("bold")}
+                    aria-label="Toggle bold"
+                  >
+                    <span className="font-bold">B</span>
+                  </Toggle>
+                  <Toggle
+                    size="sm"
+                    pressed={formatting.italic}
+                    onPressedChange={() => toggleFormat("italic")}
+                    aria-label="Toggle italic"
+                  >
+                    <span className="italic">I</span>
+                  </Toggle>
+                  <Toggle
+                    size="sm"
+                    pressed={formatting.underline}
+                    onPressedChange={() => toggleFormat("underline")}
+                    aria-label="Toggle underline"
+                  >
+                    <span className="underline">U</span>
+                  </Toggle>
+                  <div className="bg-fm-divider-secondary mx-1 h-5 w-px" />
                   <Toggle
-                    pressed={preferences.autoSave}
-                    onPressedChange={() => updatePreference("autoSave")}
-                    aria-label="Toggle auto save"
-                  />
+                    size="sm"
+                    pressed={formatting.code}
+                    onPressedChange={() => toggleFormat("code")}
+                    aria-label="Toggle code"
+                  >
+                    <span className="text-fm-xs font-(--font-fm-mono)">{`</>`}</span>
+                  </Toggle>
+                  <div className="bg-fm-divider-secondary mx-1 h-5 w-px" />
+                  <Toggle size="sm" aria-label="Search">
+                    <SearchIcon />
+                  </Toggle>
+                  <Toggle size="sm" aria-label="Edit">
+                    <EditBigIcon />
+                  </Toggle>
                 </div>
               </div>
 
+              {/* Playback controls */}
               <div className="space-y-3">
-                <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center justify-between rounded-lg border p-3">
-                  <div className="flex items-center gap-3">
-                    <EyeOpenIcon className="text-fm-icon-brand-secondary h-4 w-4" />
-                    <div>
-                      <div className="text-fm-primary text-sm">
-                        Preview Mode
-                      </div>
-                      <div className="text-fm-secondary text-xs">
-                        Show live preview
-                      </div>
-                    </div>
-                  </div>
+                <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+                  Playback controls
+                </h4>
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center justify-center gap-2 rounded-xl border p-4">
                   <Toggle
-                    pressed={preferences.showPreview}
-                    onPressedChange={() => updatePreference("showPreview")}
-                    aria-label="Toggle preview mode"
-                  />
-                </div>
-
-                <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center justify-between rounded-lg border p-3">
-                  <div className="flex items-center gap-3">
-                    <span className="text-lg">🌙</span>
-                    <div>
-                      <div className="text-fm-primary text-sm">Dark Mode</div>
-                      <div className="text-fm-secondary text-xs">
-                        Use dark theme
-                      </div>
-                    </div>
-                  </div>
+                    variant="outline"
+                    size="sm"
+                    pressed={playback.shuffle}
+                    onPressedChange={() => togglePlayback("shuffle")}
+                    aria-label="Toggle shuffle"
+                  >
+                    <FileChartIcon />
+                    Shuffle
+                  </Toggle>
+                  <Toggle size="default" aria-label="Skip backward">
+                    <SkipBackwardIcon />
+                  </Toggle>
+                  <Toggle size="lg" defaultPressed aria-label="Pause">
+                    <PauseIcon />
+                  </Toggle>
+                  <Toggle size="default" aria-label="Skip forward">
+                    <SkipForwardIcon />
+                  </Toggle>
                   <Toggle
-                    pressed={preferences.darkMode}
-                    onPressedChange={() => updatePreference("darkMode")}
-                    aria-label="Toggle dark mode"
-                  />
+                    variant="outline"
+                    size="sm"
+                    pressed={playback.repeat}
+                    onPressedChange={() => togglePlayback("repeat")}
+                    aria-label="Toggle repeat"
+                  >
+                    <TickCircleIcon />
+                    Repeat
+                  </Toggle>
                 </div>
               </div>
-            </div>
-          </div>
-
-          {/* Filter Toolbar */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">
-              Filter Toolbar
-            </h4>
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
-              <div className="flex flex-wrap gap-2">
-                <Toggle
-                  variant="outline"
-                  size="sm"
-                  aria-label="Show completed items"
-                >
-                  <TickCircleIcon />
-                  Completed
-                </Toggle>
-                <Toggle
-                  variant="outline"
-                  size="sm"
-                  aria-label="Show pending items"
-                >
-                  <AlertIcon />
-                  Pending
-                </Toggle>
-                <Toggle
-                  variant="outline"
-                  size="sm"
-                  aria-label="Show archived items"
-                >
-                  <FileChartIcon />
-                  Archived
-                </Toggle>
-                <Toggle
-                  variant="outline"
-                  size="sm"
-                  defaultPressed
-                  aria-label="Show active items"
-                >
-                  <EyeOpenIcon />
-                  Active
-                </Toggle>
-              </div>
-            </div>
-          </div>
 
-          {/* View Options */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">
-              View Options
-            </h4>
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary flex justify-center gap-1 rounded-lg border p-1">
-              <Toggle size="sm" defaultPressed aria-label="Grid view">
-                Grid
-              </Toggle>
-              <Toggle size="sm" aria-label="List view">
-                List
-              </Toggle>
-              <Toggle size="sm" aria-label="Card view">
-                Cards
-              </Toggle>
-            </div>
-          </div>
-        </div>
-      </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Real-world examples showing toggles in editor toolbars, user preferences, filters, and view options.",
-      },
-    },
-  },
-}
-
-// 8. Controlled vs Uncontrolled
-export const ControlledVsUncontrolled: Story = {
-  render: () => {
-    const [controlledState, setControlledState] = React.useState(false)
-    const [multipleStates, setMultipleStates] = React.useState({
-      option1: true,
-      option2: false,
-      option3: true,
-    })
-
-    return (
-      <div className="space-y-8 p-8">
-        <h3 className="text-fm-primary text-center text-lg font-medium">
-          Controlled vs Uncontrolled
-        </h3>
-
-        <div className="grid grid-cols-1 gap-8 lg:grid-cols-2">
-          {/* Uncontrolled */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">
-              Uncontrolled (Internal State)
-            </h4>
-            <div className="space-y-3">
-              <Toggle aria-label="Uncontrolled toggle 1">Default State</Toggle>
-              <Toggle defaultPressed aria-label="Uncontrolled toggle 2">
-                Default Pressed
-              </Toggle>
-              <Toggle variant="outline" aria-label="Uncontrolled toggle 3">
-                <AlertIcon />
-                With Icon
-              </Toggle>
-            </div>
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-tertiary rounded border p-3 font-mono text-xs">
-              <div>{"<Toggle>"}</div>
-              <div>{"  Default State"}</div>
-              <div>{"</Toggle>"}</div>
-              <br />
-              <div>{"<Toggle defaultPressed>"}</div>
-              <div>{"  Default Pressed"}</div>
-              <div>{"</Toggle>"}</div>
-            </div>
-          </div>
-
-          {/* Controlled */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">
-              Controlled (External State)
-            </h4>
-            <div className="space-y-3">
-              <Toggle
-                pressed={controlledState}
-                onPressedChange={setControlledState}
-                aria-label="Controlled toggle"
-              >
-                Controlled: {controlledState ? "ON" : "OFF"}
-              </Toggle>
-
-              <div className="space-y-2">
-                {Object.entries(multipleStates).map(([key, value]) => (
+              {/* Stateful icon swap */}
+              <div className="space-y-3">
+                <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+                  Stateful icon swap
+                </h4>
+                <div className="flex flex-wrap gap-3">
+                  <Toggle
+                    pressed={visibility}
+                    onPressedChange={setVisibility}
+                    aria-label="Toggle visibility"
+                  >
+                    {visibility ? <EyeOpenIcon /> : <EyeCloseIcon />}
+                    {visibility ? "Visible" : "Hidden"}
+                  </Toggle>
                   <Toggle
-                    key={key}
                     variant="outline"
-                    size="sm"
-                    pressed={value}
-                    onPressedChange={(pressed) =>
-                      setMultipleStates((prev) => ({ ...prev, [key]: pressed }))
-                    }
-                    aria-label={`Toggle ${key}`}
+                    pressed={done}
+                    onPressedChange={setDone}
+                    aria-label="Toggle complete"
                   >
                     <TickCircleIcon />
-                    {key}: {value ? "ON" : "OFF"}
+                    {done ? "Done" : "Mark done"}
+                  </Toggle>
+                  <Toggle
+                    variant="filled"
+                    pressed={playback.mute}
+                    onPressedChange={() => togglePlayback("mute")}
+                    aria-label="Toggle mute"
+                  >
+                    {playback.mute ? <VolumeFullIcon /> : <VolumeFullIcon />}
+                    {playback.mute ? "Unmute" : "Mute"}
+                  </Toggle>
+                  <Toggle disabled aria-label="Sleep — unavailable">
+                    <MoonIcon />
+                    Sleep
                   </Toggle>
-                ))}
+                </div>
               </div>
-            </div>
-
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-tertiary rounded border p-3 font-mono text-xs">
-              <div>{"const [state, setState] = useState(false)"}</div>
-              <br />
-              <div>{"<Toggle"}</div>
-              <div>{"  pressed={state}"}</div>
-              <div>{"  onPressedChange={setState}"}</div>
-              <div>{">"}</div>
-              <div>{"  Controlled"}</div>
-              <div>{"</Toggle>"}</div>
-            </div>
-          </div>
-        </div>
 
-        <div className="border-fm-divider-secondary bg-fm-surface-info-sec rounded-lg border p-4">
-          <h4 className="text-fm-info mb-2 text-sm font-medium">
-            When to Use Each
-          </h4>
-          <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">
-            <div>
-              <h5 className="text-fm-info mb-1 text-xs font-medium">
-                Uncontrolled
-              </h5>
-              <ul className="text-fm-info-sec space-y-1 text-xs">
-                <li>• Simple on/off toggles</li>
-                <li>• No external state dependency</li>
-                <li>• Form elements</li>
-                <li>• Less code complexity</li>
-              </ul>
-            </div>
-            <div>
-              <h5 className="text-fm-info mb-1 text-xs font-medium">
-                Controlled
-              </h5>
-              <ul className="text-fm-info-sec space-y-1 text-xs">
-                <li>• Complex state management</li>
-                <li>• Multiple dependent toggles</li>
-                <li>• Form validation</li>
-                <li>• External state updates</li>
-              </ul>
+              <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)">
+                  {`<Toggle pressed={bold} onPressedChange={setBold}>B</Toggle>`}
+                </code>
+              </div>
             </div>
           </div>
         </div>
@@ -1108,7 +665,7 @@ export const ControlledVsUncontrolled: Story = {
     docs: {
       description: {
         story:
-          "Comparison between controlled and uncontrolled toggle usage patterns with practical examples.",
+          "Live stateful toggles showing two real-world patterns: a text-formatting toolbar (multi-active) and playback controls. Click any button to toggle its pressed state.",
       },
     },
   },