aural-ui 4.0.1 → 4.1.0

package/dist/components/list/List.stories.tsx

@@ -1,24 +1,22 @@
 import React from "react"
 import { Badge } from "@components/badge"
 import {
-  BubbleCheckIcon,
-  BubbleSparkleIcon,
-  EditBigIcon,
-  EyeOpenIcon,
   FeatureShineIcon,
-  FileChartIcon,
-  ImageIcon,
-  ImportFolderIcon,
-  LightBulbSimpleIcon,
-  MagicBookIcon,
-  MaintenanceIcon,
+  HeartIcon,
+  MusicalNoteIcon,
+  PauseIcon,
   SearchIcon,
-  TickIcon,
+  SettingIcon,
+  SkipForwardIcon,
+  StarIcon,
   TrashIcon,
   UploadIcon,
+  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 {
   List,
   ListCheckboxItem,
@@ -35,114 +33,30 @@ const meta: Meta<typeof List> = {
   title: "Components/UI/List",
   component: List,
   parameters: {
-    layout: "fullscreen",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
+    layout: "centered",
     docs: {
       description: {
-        component: `
-# List Component
-
-A comprehensive atomic list component system that provides building blocks for creating rich interactive lists, menus, and selection interfaces. Built following atomic design principles.
-
-## Atomic Components
-
-### Container Level
-- **List**: Main container with styling variants and border options
-- **ListGroup**: Semantic grouping wrapper for related list items
-
-### Content Level  
-- **ListItem**: Basic interactive list item with states and variants
-- **ListCheckboxItem**: Checkbox-enabled list item for multi-selection
-- **ListRadioItem**: Radio button list item for single selection within groups
-- **ListLabel**: Semantic label component for list sections
-- **ListSeparator**: Visual separator using design system divider
-- **ListSubTrigger**: List item with chevron for nested navigation
-
-## Features
-
-- **Atomic Design**: Composable components following atomic design principles
-- **Flexible Styling**: CVA variants for size, state, and visual styling
-- **Interactive States**: Hover, focus, selected, and disabled states
-- **Selection Patterns**: Support for single, multi, and radio group selection
-- **Keyboard Navigation**: Full keyboard accessibility support
-- **Icon Integration**: Seamless icon support with proper sizing and coloring
-- **Shortcuts Display**: Built-in keyboard shortcut display
-- **Custom Styling**: Extensive customization through classes prop
-- **Semantic HTML**: Proper ARIA roles and attributes for accessibility
-
-## Usage Examples
-
-### Basic List
-\`\`\`tsx
-<List>
-  <ListItem>
-    <FileChartIcon />
-    Basic Item
-  </ListItem>
-  <ListSeparator />
-  <ListItem selected>
-    <ImageIcon />
-    Selected Item
-  </ListItem>
-</List>
-\`\`\`
-
-### Grouped List with Labels
-\`\`\`tsx
-<List>
-  <ListGroup>
-    <ListLabel>Actions</ListLabel>
-    <ListItem>
-      <EditBigIcon />
-      Edit File
-      <CommandShortcut>⌘E</CommandShortcut>
-    </ListItem>
-    <ListItem variant="destructive">
-      <TrashIcon />
-      Delete
-    </ListItem>
-  </ListGroup>
-</List>
-\`\`\`
-
-### Selection Lists
-\`\`\`tsx
-<List>
-  <ListCheckboxItem checked onCheckedChange={setChecked}>
-    Multi-select Item
-  </ListCheckboxItem>
-  
-  <ListRadioGroup value={value} onValueChange={setValue}>
-    <ListRadioItem value="option1">Option 1</ListRadioItem>
-    <ListRadioItem value="option2">Option 2</ListRadioItem>
-  </ListRadioGroup>
-</List>
-\`\`\`
-
-### Custom Styling
-\`\`\`tsx
-<List 
-  variant="elevated" 
-  size="lg" 
-  borderVariant="success"
-  classes={{ root: "custom-list" }}
->
-  <ListItem 
-    size="lg"
-    classes={{ root: "custom-item" }}
-  >
-    Custom Styled Item
-  </ListItem>
-</List>
-\`\`\`
-        `,
+        component:
+          "A compound list system built for composable menus, selection panels, and navigation drawers. Composed of List (container), ListGroup, ListLabel, ListItem, ListCheckboxItem, ListRadioGroup, ListRadioItem, ListSeparator, and ListSubTrigger. Supports three visual variants (default, elevated, flat), four container sizes (sm, default, lg, xl), and semantic top-border accents.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Rich Item Types",
+              description: "Checkbox, radio, sub-trigger",
+            },
+            {
+              title: "3 Variants",
+              description: "Default, elevated, flat",
+            },
+            {
+              title: "4 Container Sizes",
+              description: "sm to xl width",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -150,26 +64,26 @@ A comprehensive atomic list component system that provides building blocks for c
     variant: {
       control: "select",
       options: ["default", "elevated", "flat"],
-      description: "Visual style variant of the list container",
+      description: "Visual shadow depth of the list container",
     },
     size: {
       control: "select",
       options: ["sm", "default", "lg", "xl"],
-      description: "Size variant affecting minimum width",
+      description: "Minimum width of the list container",
     },
     rounded: {
       control: "select",
       options: ["none", "sm", "default", "lg"],
-      description: "Border radius variant",
+      description: "Border radius of the list container",
     },
     borderVariant: {
       control: "select",
       options: ["default", "error", "warning", "success", "info"],
-      description: "Color variant for the top border accent",
+      description: "Color of the top accent border stripe",
     },
     showBorder: {
       control: "boolean",
-      description: "Whether to show the top accent border",
+      description: "Toggle the top accent border stripe",
     },
   },
 }
@@ -177,789 +91,523 @@ A comprehensive atomic list component system that provides building blocks for c
 export default meta
 type Story = StoryObj<typeof List>
 
-// 1. Basic List
-export const BasicList: Story = {
-  args: {
-    variant: "default",
-    size: "default",
-    rounded: "default",
-    borderVariant: "default",
-    showBorder: true,
-  },
-  render: (args) => (
-    <div className="mx-auto max-w-md p-8">
-      <h3 className="text-fm-primary mb-4 text-lg font-medium">Basic List</h3>
-      <List {...args} className="backdrop-blur-none">
-        <ListItem>
-          <FileChartIcon />
-          Documents
-        </ListItem>
-        <ListItem>
-          <ImageIcon />
-          Images
-        </ListItem>
-        <ListItem selected>
-          <MagicBookIcon />
-          Magic Book (Selected)
-        </ListItem>
-        <ListItem disabled>
-          <TrashIcon />
-          Disabled Item
-        </ListItem>
-      </List>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Basic list with icons and different states including selected and disabled items.",
-      },
-    },
-  },
-}
+// ─── 1. Parts ─────────────────────────────────────────────────────────────────
 
-// 2. List with Groups and Labels
-export const GroupedList: Story = {
+export const Parts: Story = {
   render: () => (
-    <div className="mx-auto max-w-md p-8">
-      <h3 className="text-fm-primary mb-4 text-lg font-medium">
-        Grouped List with Labels
-      </h3>
-      <List>
-        <ListGroup>
-          <ListLabel>File Operations</ListLabel>
-          <ListItem>
-            <FileChartIcon />
-            New Document
-            <span className="ml-auto text-xs opacity-60">⌘N</span>
-          </ListItem>
+    <div className="mx-auto w-full max-w-2xl space-y-10">
+      {/* List (container) */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          List — container
+        </h4>
+        <List className="w-56">
+          <ListItem>Sample item A</ListItem>
+          <ListItem>Sample item B</ListItem>
+        </List>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            <strong className="text-fm-primary">List</strong> is the root
+            container. It applies a frosted-glass backdrop, shadow, and optional
+            top-accent border. Sets <code>role="listbox"</code> for
+            accessibility.
+          </p>
+        </div>
+      </div>
+
+      {/* ListGroup */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          ListGroup — semantic grouping
+        </h4>
+        <List className="w-56">
+          <ListGroup>
+            <ListItem>Group A · Item 1</ListItem>
+            <ListItem>Group A · Item 2</ListItem>
+          </ListGroup>
+          <ListSeparator />
+          <ListGroup>
+            <ListItem>Group B · Item 1</ListItem>
+          </ListGroup>
+        </List>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            <strong className="text-fm-primary">ListGroup</strong> wraps related
+            items with <code>role="group"</code>. Use it alongside{" "}
+            <code>ListSeparator</code> to divide the list into semantic
+            sections.
+          </p>
+        </div>
+      </div>
+
+      {/* ListLabel */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          ListLabel — section heading
+        </h4>
+        <List className="w-56">
+          <ListLabel>Playback</ListLabel>
           <ListItem>
-            <ImportFolderIcon />
-            Open Folder
-            <span className="ml-auto text-xs opacity-60">⌘O</span>
+            <PauseIcon className="size-4" />
+            Pause
           </ListItem>
           <ListItem>
-            <EditBigIcon />
-            Edit File
-            <span className="ml-auto text-xs opacity-60">⌘E</span>
+            <SkipForwardIcon className="size-4" />
+            Skip
           </ListItem>
-        </ListGroup>
-
-        <ListSeparator />
+        </List>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            <strong className="text-fm-primary">ListLabel</strong> renders a
+            small, muted uppercase heading above a group of items. It uses{" "}
+            <code>text-fm-label-secondary</code> — not interactive.
+          </p>
+        </div>
+      </div>
 
-        <ListGroup>
-          <ListLabel>Actions</ListLabel>
+      {/* ListItem */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          ListItem — basic row
+        </h4>
+        <List className="w-56">
           <ListItem>
-            <BubbleSparkleIcon />
-            Share
-            <Badge color="info" className="ml-auto">
-              New
-            </Badge>
+            <MusicalNoteIcon className="size-4" />
+            Default
           </ListItem>
-          <ListItem>
-            <UploadIcon />
-            Upload
+          <ListItem selected>
+            <StarIcon className="size-4" />
+            Selected
+          </ListItem>
+          <ListItem disabled>
+            <TrashIcon className="size-4" />
+            Disabled
           </ListItem>
-          <ListSubTrigger>
-            <MaintenanceIcon />
-            More Options
-          </ListSubTrigger>
-        </ListGroup>
-
-        <ListSeparator />
-
-        <ListGroup>
-          <ListLabel>Dangerous Actions</ListLabel>
           <ListItem variant="destructive">
-            <TrashIcon />
-            Delete
-            <span className="ml-auto text-xs opacity-60">⌘⌫</span>
+            <TrashIcon className="size-4" />
+            Destructive
           </ListItem>
-        </ListGroup>
-      </List>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Organized list with groups, labels, separators, shortcuts, badges, and a sub-trigger for nested navigation.",
-      },
-    },
-  },
-}
-
-// 3. Selection Lists
-export const SelectionLists: Story = {
-  render: () => {
-    const [checkedItems, setCheckedItems] = React.useState<string[]>([
-      "item1",
-      "item3",
-    ])
-    const [radioValue, setRadioValue] = React.useState("option2")
-
-    const handleCheckboxChange = (itemId: string, checked: boolean) => {
-      setCheckedItems((prev) =>
-        checked ? [...prev, itemId] : prev.filter((id) => id !== itemId)
-      )
-    }
-
-    return (
-      <div className="space-y-8 p-8">
-        <h3 className="text-fm-primary text-center text-lg font-medium">
-          Selection Lists
-        </h3>
-
-        <div className="grid grid-cols-1 gap-6 lg:grid-cols-2">
-          {/* Checkbox List */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">
-              Multi-Select (Checkbox)
-            </h4>
-            <List size="default">
-              <ListLabel>Choose Features</ListLabel>
-              <ListCheckboxItem
-                checked={checkedItems.includes("item1")}
-                onCheckedChange={(checked) =>
-                  handleCheckboxChange("item1", checked)
-                }
-              >
-                <FeatureShineIcon />
-                Advanced Analytics
-              </ListCheckboxItem>
-              <ListCheckboxItem
-                checked={checkedItems.includes("item2")}
-                onCheckedChange={(checked) =>
-                  handleCheckboxChange("item2", checked)
-                }
-              >
-                <BubbleSparkleIcon />
-                Real-time Sync
-              </ListCheckboxItem>
-              <ListCheckboxItem
-                checked={checkedItems.includes("item3")}
-                onCheckedChange={(checked) =>
-                  handleCheckboxChange("item3", checked)
-                }
-              >
-                <LightBulbSimpleIcon />
-                AI Suggestions
-              </ListCheckboxItem>
-              <ListCheckboxItem
-                disabled
-                checked={checkedItems.includes("item4")}
-                onCheckedChange={(checked) =>
-                  handleCheckboxChange("item4", checked)
-                }
-              >
-                <MaintenanceIcon />
-                Premium Feature (Disabled)
-              </ListCheckboxItem>
-            </List>
-
-            {checkedItems.length > 0 && (
-              <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-3">
-                <p className="text-fm-secondary text-xs">
-                  Selected: {checkedItems.length} feature
-                  {checkedItems.length !== 1 ? "s" : ""}
-                </p>
-              </div>
-            )}
-          </div>
-
-          {/* Radio List */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">
-              Single Select (Radio)
-            </h4>
-            <List size="default">
-              <ListLabel>Choose Theme</ListLabel>
-              <ListRadioGroup value={radioValue} onValueChange={setRadioValue}>
-                <ListRadioItem value="option1">
-                  <EyeOpenIcon />
-                  Light Theme
-                </ListRadioItem>
-                <ListRadioItem value="option2">
-                  <MaintenanceIcon />
-                  Dark Theme
-                </ListRadioItem>
-                <ListRadioItem value="option3">
-                  <FeatureShineIcon />
-                  Auto Theme
-                </ListRadioItem>
-                <ListRadioItem value="option4" disabled>
-                  <BubbleSparkleIcon />
-                  Custom Theme (Pro)
-                </ListRadioItem>
-              </ListRadioGroup>
-            </List>
-
-            <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-3">
-              <p className="text-fm-secondary text-xs">
-                Selected:{" "}
-                {radioValue === "option1"
-                  ? "Light Theme"
-                  : radioValue === "option2"
-                    ? "Dark Theme"
-                    : radioValue === "option3"
-                      ? "Auto Theme"
-                      : "Custom Theme"}
-              </p>
-            </div>
-          </div>
+        </List>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            <strong className="text-fm-primary">ListItem</strong> is the primary
+            interactive row. Supports <code>selected</code>,{" "}
+            <code>disabled</code>, and <code>variant="destructive"</code>{" "}
+            states, plus an optional right-aligned keyboard shortcut via the{" "}
+            <code>shortcut</code> prop.
+          </p>
         </div>
       </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Interactive selection lists showing checkbox multi-select and radio single-select patterns with state management.",
-      },
-    },
-  },
-}
-
-// 4. List Variants
-export const ListVariants: Story = {
-  render: () => (
-    <div className="space-y-8 p-8">
-      <h3 className="text-fm-primary text-center text-lg font-medium">
-        List Variants
-      </h3>
-
-      <div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
-        {/* Default Variant */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">Default</h4>
-          <List variant="default" size="default">
-            <ListItem>
-              <FileChartIcon />
-              Default Style
-            </ListItem>
-            <ListItem selected>
-              <ImageIcon />
-              Selected Item
-            </ListItem>
-            <ListItem>
-              <MagicBookIcon />
-              Regular Item
-            </ListItem>
-          </List>
-        </div>
-
-        {/* Elevated Variant */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">Elevated</h4>
-          <List variant="elevated" size="default">
-            <ListItem>
-              <FeatureShineIcon />
-              Elevated Style
-            </ListItem>
-            <ListItem selected>
-              <BubbleSparkleIcon />
-              More Shadow
-            </ListItem>
-            <ListItem>
-              <LightBulbSimpleIcon />
-              Premium Feel
-            </ListItem>
-          </List>
-        </div>
 
-        {/* Flat Variant */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">Flat</h4>
-          <List variant="flat" size="default">
-            <ListItem>
-              <MaintenanceIcon />
-              Flat Style
-            </ListItem>
-            <ListItem selected>
-              <EyeOpenIcon />
-              Minimal Shadow
-            </ListItem>
-            <ListItem>
-              <SearchIcon />
-              Clean Look
-            </ListItem>
-          </List>
+      {/* ListCheckboxItem */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          ListCheckboxItem — multi-select row
+        </h4>
+        <List className="w-56">
+          <ListCheckboxItem checked>
+            <FeatureShineIcon className="size-4" />
+            Spatial Audio
+          </ListCheckboxItem>
+          <ListCheckboxItem>
+            <VolumeFullIcon className="size-4" />
+            Crossfade
+          </ListCheckboxItem>
+          <ListCheckboxItem disabled>
+            <SettingIcon className="size-4" />
+            Equalizer (Pro)
+          </ListCheckboxItem>
+        </List>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            <strong className="text-fm-primary">ListCheckboxItem</strong>{" "}
+            extends ListItem with a tick indicator on the right. Use{" "}
+            <code>checked</code> and <code>onCheckedChange</code> for controlled
+            state.
+          </p>
         </div>
       </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Different visual variants of the list component: default, elevated (more shadow), and flat (minimal shadow).",
-      },
-    },
-  },
-}
-
-// 5. List Sizes
-export const ListSizes: Story = {
-  render: () => (
-    <div className="space-y-8 p-8">
-      <h3 className="text-fm-primary text-center text-lg font-medium">
-        List Sizes
-      </h3>
-
-      <div className="grid grid-cols-1 gap-6 lg:grid-cols-2 xl:grid-cols-4">
-        {/* Small */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">Small</h4>
-          <List size="sm">
-            <ListItem size="sm">
-              <FileChartIcon />
-              Small Item
-            </ListItem>
-            <ListItem size="sm" selected>
-              <ImageIcon />
-              Selected
-            </ListItem>
-          </List>
-        </div>
-
-        {/* Default */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">Default</h4>
-          <List size="default">
-            <ListItem size="default">
-              <MagicBookIcon />
-              Default Item
-            </ListItem>
-            <ListItem size="default" selected>
-              <FeatureShineIcon />
-              Selected
-            </ListItem>
-          </List>
-        </div>
 
-        {/* Large */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">Large</h4>
-          <List size="lg">
-            <ListItem size="lg">
-              <BubbleSparkleIcon />
-              Large Item
-            </ListItem>
-            <ListItem size="lg" selected>
-              <LightBulbSimpleIcon />
-              Selected
-            </ListItem>
-          </List>
-        </div>
-
-        {/* Extra Large */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">Extra Large</h4>
-          <List size="xl">
-            <ListItem size="lg">
-              <MaintenanceIcon />
-              XL Container
-            </ListItem>
-            <ListItem size="lg" selected>
-              <EyeOpenIcon />
-              Large Items
-            </ListItem>
-          </List>
+      {/* ListRadioItem */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          ListRadioItem — single-select row
+        </h4>
+        <List className="w-56">
+          <ListRadioGroup value="high">
+            <ListRadioItem value="low">Low Quality</ListRadioItem>
+            <ListRadioItem value="normal">Normal Quality</ListRadioItem>
+            <ListRadioItem value="high">High Quality</ListRadioItem>
+          </ListRadioGroup>
+        </List>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            <strong className="text-fm-primary">ListRadioItem</strong> must be
+            nested inside a <code>ListRadioGroup</code>. The group manages the{" "}
+            <code>value</code>/<code>onValueChange</code> context so only one
+            item is selected at a time. Sets <code>role="radio"</code>.
+          </p>
         </div>
       </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Different size variants affecting the minimum width of list containers and padding of list items.",
-      },
-    },
-  },
-}
-
-// 6. Border Variants
-export const BorderVariants: Story = {
-  render: () => (
-    <div className="space-y-8 p-8">
-      <h3 className="text-fm-primary text-center text-lg font-medium">
-        Border Variants
-      </h3>
-
-      <div className="grid grid-cols-1 gap-6 lg:grid-cols-3 xl:grid-cols-5">
-        {/* Default */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">Default</h4>
-          <List borderVariant="default">
-            <ListItem>
-              <FileChartIcon />
-              Neutral
-            </ListItem>
-            <ListItem>
-              <ImageIcon />
-              Border
-            </ListItem>
-          </List>
-        </div>
-
-        {/* Success */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">Success</h4>
-          <List borderVariant="success">
-            <ListItem>
-              <BubbleCheckIcon />
-              Success
-            </ListItem>
-            <ListItem>
-              <TickIcon />
-              Complete
-            </ListItem>
-          </List>
-        </div>
 
-        {/* Error */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">Error</h4>
-          <List borderVariant="error">
-            <ListItem>
-              <TrashIcon />
-              Error
-            </ListItem>
-            <ListItem>
-              <MaintenanceIcon />
-              Issues
-            </ListItem>
-          </List>
-        </div>
-
-        {/* Warning */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">Warning</h4>
-          <List borderVariant="warning">
-            <ListItem>
-              <LightBulbSimpleIcon />
-              Warning
-            </ListItem>
-            <ListItem>
-              <MaintenanceIcon />
-              Caution
-            </ListItem>
-          </List>
-        </div>
-
-        {/* Info */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">Info</h4>
-          <List borderVariant="info">
-            <ListItem>
-              <FeatureShineIcon />
-              Info
-            </ListItem>
-            <ListItem>
-              <BubbleSparkleIcon />
-              Details
-            </ListItem>
-          </List>
+      {/* ListSeparator */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          ListSeparator — visual divider
+        </h4>
+        <List className="w-56">
+          <ListItem>Above separator</ListItem>
+          <ListSeparator />
+          <ListItem>Below separator</ListItem>
+        </List>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            <strong className="text-fm-primary">ListSeparator</strong> renders a
+            dashed divider using the design system <code>Divider</code>{" "}
+            component with <code>role="separator"</code>.
+          </p>
         </div>
       </div>
 
-      {/* No Border */}
-      <div className="mx-auto max-w-md">
-        <h4 className="text-fm-secondary mb-4 text-sm font-medium">
-          No Border
+      {/* ListSubTrigger */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          ListSubTrigger — nested navigation
         </h4>
-        <List showBorder={false}>
+        <List className="w-56">
           <ListItem>
-            <SearchIcon />
-            No top border
-          </ListItem>
-          <ListItem>
-            <EyeOpenIcon />
-            Clean look
+            <SearchIcon className="size-4" />
+            Search
           </ListItem>
+          <ListSubTrigger>
+            <SettingIcon className="size-4" />
+            More Options
+          </ListSubTrigger>
         </List>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            <strong className="text-fm-primary">ListSubTrigger</strong> is a
+            ListItem with a right-aligned chevron icon indicating a nested
+            sub-menu or flyout panel.
+          </p>
+        </div>
       </div>
     </div>
   ),
   parameters: {
+    layout: "padded",
     docs: {
       description: {
         story:
-          "Different border color variants for semantic meaning and option to hide the border entirely.",
+          "Each sub-component of the List compound shown individually with a role explanation. Use this as a reference when composing list-based menus and selection panels.",
       },
     },
   },
 }
 
-// 7. Custom Styling
-export const CustomStyling: Story = {
+// ─── 2. AllVariants ───────────────────────────────────────────────────────────
+
+export const AllVariants: Story = {
   render: () => (
-    <div className="space-y-8 p-8">
-      <h3 className="text-fm-primary text-center text-lg font-medium">
-        Custom Styling
-      </h3>
+    <div className="space-y-8">
+      {/* Variant axis */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Variant
+        </h4>
+        <div className="flex flex-wrap items-start justify-center gap-6">
+          {(["default", "elevated", "flat"] as const).map((variant) => (
+            <div key={variant} className="space-y-2 text-center">
+              <List variant={variant} className="w-44">
+                <ListItem>
+                  <MusicalNoteIcon className="size-4" />
+                  Track item
+                </ListItem>
+                <ListItem selected>
+                  <StarIcon className="size-4" />
+                  Selected
+                </ListItem>
+                <ListItem>
+                  <HeartIcon className="size-4" />
+                  Liked
+                </ListItem>
+              </List>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm capitalize">
+                {variant}
+              </p>
+            </div>
+          ))}
+        </div>
+      </div>
 
-      <div className="grid grid-cols-1 gap-6 lg:grid-cols-2">
-        {/* Custom Classes */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">
-            Custom Classes
-          </h4>
-          <List
-            className="border-purple-500/30 bg-purple-900/10"
-            classes={{
-              root: "backdrop-blur-xl",
-              border: "bg-gradient-to-r from-purple-500 to-pink-500",
-            }}
-            borderVariant="info"
-          >
-            <ListItem
-              classes={{
-                root: "hover:bg-purple-500/20 text-purple-100",
-              }}
-            >
-              <FeatureShineIcon />
-              Purple Theme
-            </ListItem>
-            <ListItem
-              selected
-              classes={{
-                root: "bg-purple-500/30 text-white",
-              }}
-            >
-              <BubbleSparkleIcon />
-              Custom Selected
-            </ListItem>
-            <ListItem
-              classes={{
-                root: "hover:bg-purple-500/20 text-purple-100",
-              }}
-            >
-              <MagicBookIcon />
-              Magic Item
-            </ListItem>
-          </List>
+      {/* Size axis */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Size
+        </h4>
+        <div className="flex flex-wrap items-start justify-center gap-6">
+          {(["sm", "default", "lg", "xl"] as const).map((size) => (
+            <div key={size} className="space-y-2 text-center">
+              <List size={size}>
+                <ListItem size={size === "xl" ? "lg" : size}>
+                  <MusicalNoteIcon className="size-4" />
+                  Item
+                </ListItem>
+                <ListItem size={size === "xl" ? "lg" : size} selected>
+                  <StarIcon className="size-4" />
+                  Selected
+                </ListItem>
+              </List>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                {size}
+              </p>
+            </div>
+          ))}
         </div>
+      </div>
 
-        {/* Complex Layout */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">
-            Complex Layout
-          </h4>
-          <List variant="elevated" size="lg">
-            <ListLabel size="lg">Premium Features</ListLabel>
-            <ListItem size="lg">
-              <div className="flex items-center gap-3">
-                <div className="rounded-full bg-green-500/20 p-2">
-                  <TickIcon className="text-fm-icon-positive size-4" />
-                </div>
-                <div className="flex-1">
-                  <div className="text-fm-primary font-medium">
-                    Advanced Analytics
-                  </div>
-                  <div className="text-fm-secondary text-xs">
-                    Deep insights and reporting
-                  </div>
-                </div>
-                <Badge color="positive">Active</Badge>
-              </div>
-            </ListItem>
-            <ListItem size="lg">
-              <div className="flex items-center gap-3">
-                <div className="rounded-full bg-blue-500/20 p-2">
-                  <FeatureShineIcon className="text-fm-icon-info size-4" />
-                </div>
-                <div className="flex-1">
-                  <div className="text-fm-primary font-medium">
-                    AI Assistant
-                  </div>
-                  <div className="text-fm-secondary text-xs">
-                    Intelligent automation
-                  </div>
-                </div>
-                <Badge color="info">Beta</Badge>
+      {/* Border variant axis */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Border Variant
+        </h4>
+        <div className="flex flex-wrap items-start justify-center gap-6">
+          {(["default", "success", "error", "warning", "info"] as const).map(
+            (bv) => (
+              <div key={bv} className="space-y-2 text-center">
+                <List borderVariant={bv} className="w-36">
+                  <ListItem>Item A</ListItem>
+                  <ListItem>Item B</ListItem>
+                </List>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm capitalize">
+                  {bv}
+                </p>
               </div>
-            </ListItem>
-            <ListItem size="lg" disabled>
-              <div className="flex items-center gap-3">
-                <div className="bg-fm-surface-secondary rounded-full p-2">
-                  <LightBulbSimpleIcon className="text-fm-tertiary size-4" />
-                </div>
-                <div className="flex-1">
-                  <div className="font-medium">Custom Workflows</div>
-                  <div className="text-fm-tertiary text-xs">Coming soon</div>
-                </div>
-                <Badge color="neutral">Soon</Badge>
+            )
+          )}
+          <div className="space-y-2 text-center">
+            <List showBorder={false} className="w-36">
+              <ListItem>Item A</ListItem>
+              <ListItem>Item B</ListItem>
+            </List>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              No border
+            </p>
+          </div>
+        </div>
+      </div>
+
+      {/* Variant × size matrix */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Variant × Size matrix
+        </h4>
+        <div className="mx-auto grid max-w-4xl grid-cols-2 gap-6 sm:grid-cols-3 lg:grid-cols-4">
+          {(["default", "elevated", "flat"] as const).flatMap((variant) =>
+            (["sm", "default", "lg"] as const).map((size) => (
+              <div key={`${variant}-${size}`} className="space-y-2 text-center">
+                <List variant={variant} size={size}>
+                  <ListItem size={size}>
+                    <MusicalNoteIcon className="size-4" />
+                    Track
+                  </ListItem>
+                  <ListItem size={size} selected>
+                    <StarIcon className="size-4" />
+                    Active
+                  </ListItem>
+                </List>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  {variant} · {size}
+                </p>
               </div>
-            </ListItem>
-          </List>
+            ))
+          )}
         </div>
       </div>
     </div>
   ),
   parameters: {
+    layout: "padded",
     docs: {
       description: {
         story:
-          "Examples of custom styling using classes prop and complex layouts with rich content, badges, and custom color schemes.",
+          "Full visual matrix across variants (default, elevated, flat), sizes (sm, default, lg, xl), border variants, and a variant × size cross-axis comparison.",
       },
     },
   },
 }
 
-// 8. Interactive Showcase
-export const InteractiveShowcase: Story = {
+// ─── 3. Interactive ───────────────────────────────────────────────────────────
+
+export const Interactive: Story = {
   render: () => {
-    const [selectedItems, setSelectedItems] = React.useState<string[]>([
-      "item2",
-    ])
-    const [checkedFeatures, setCheckedFeatures] = React.useState<string[]>([
-      "analytics",
+    const [enabledFeatures, setEnabledFeatures] = React.useState<string[]>([
+      "spatial",
+      "crossfade",
     ])
-    const [theme, setTheme] = React.useState("dark")
+    const [audioQuality, setAudioQuality] = React.useState("high")
+    const [activeTab, setActiveTab] = React.useState("tracks")
 
-    const handleItemSelect = (itemId: string) => {
-      setSelectedItems([itemId])
+    const toggleFeature = (id: string, checked: boolean) => {
+      setEnabledFeatures((prev) =>
+        checked ? [...prev, id] : prev.filter((f) => f !== id)
+      )
     }
 
-    const handleFeatureToggle = (featureId: string, checked: boolean) => {
-      setCheckedFeatures((prev) =>
-        checked ? [...prev, featureId] : prev.filter((id) => id !== featureId)
-      )
+    const qualityLabel: Record<string, string> = {
+      low: "Low (96 kbps)",
+      normal: "Normal (160 kbps)",
+      high: "High (320 kbps)",
+      lossless: "Lossless (FLAC)",
     }
 
     return (
-      <div className="space-y-8 p-8">
-        <h3 className="text-fm-primary text-center text-lg font-medium">
-          Interactive Showcase
-        </h3>
-
-        <div className="grid grid-cols-1 gap-8 lg:grid-cols-3">
-          {/* Navigation List */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">
-              Navigation
-            </h4>
-            <List>
-              <ListLabel>Main Menu</ListLabel>
-              <ListItem
-                selected={selectedItems.includes("item1")}
-                onClick={() => handleItemSelect("item1")}
-                className="cursor-pointer"
-              >
-                <FileChartIcon />
-                Dashboard
-              </ListItem>
-              <ListItem
-                selected={selectedItems.includes("item2")}
-                onClick={() => handleItemSelect("item2")}
-                className="cursor-pointer"
-              >
-                <ImageIcon />
-                Media Library
-                <Badge color="info" className="ml-auto">
-                  12
-                </Badge>
-              </ListItem>
-              <ListItem
-                selected={selectedItems.includes("item3")}
-                onClick={() => handleItemSelect("item3")}
-                className="cursor-pointer"
-              >
-                <MaintenanceIcon />
-                Settings
-              </ListItem>
-              <ListSeparator />
-              <ListSubTrigger>
-                <BubbleSparkleIcon />
-                Advanced Options
-              </ListSubTrigger>
-            </List>
-          </div>
+      <div className="w-full p-8">
+        <div className="mx-auto w-full max-w-4xl 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">
+                Navigation
+              </p>
+              <List showBorder={false} className="w-full">
+                <ListItem
+                  selected={activeTab === "tracks"}
+                  className="cursor-pointer"
+                  onClick={() => setActiveTab("tracks")}
+                >
+                  <MusicalNoteIcon className="size-4" />
+                  Tracks
+                </ListItem>
+                <ListItem
+                  selected={activeTab === "artists"}
+                  className="cursor-pointer"
+                  onClick={() => setActiveTab("artists")}
+                >
+                  <StarIcon className="size-4" />
+                  Artists
+                  <Badge
+                    color="info"
+                    size="xs"
+                    className="bg-fm-surface-info-sec text-fm-info-sec ml-auto"
+                  >
+                    NEW
+                  </Badge>
+                </ListItem>
+                <ListItem
+                  selected={activeTab === "liked"}
+                  className="cursor-pointer"
+                  onClick={() => setActiveTab("liked")}
+                >
+                  <HeartIcon className="size-4" />
+                  Liked Songs
+                </ListItem>
+                <ListItem
+                  selected={activeTab === "uploads"}
+                  className="cursor-pointer"
+                  onClick={() => setActiveTab("uploads")}
+                >
+                  <UploadIcon className="size-4" />
+                  Uploads
+                </ListItem>
+                <ListSeparator />
+                <ListSubTrigger>
+                  <SettingIcon className="size-4" />
+                  Settings
+                </ListSubTrigger>
+              </List>
+            </div>
 
-          {/* Feature Selection */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">Features</h4>
-            <List borderVariant="success">
-              <ListLabel>Enable Features</ListLabel>
-              <ListCheckboxItem
-                checked={checkedFeatures.includes("analytics")}
-                onCheckedChange={(checked) =>
-                  handleFeatureToggle("analytics", checked)
-                }
-              >
-                <FeatureShineIcon />
-                Analytics
-              </ListCheckboxItem>
-              <ListCheckboxItem
-                checked={checkedFeatures.includes("ai")}
-                onCheckedChange={(checked) =>
-                  handleFeatureToggle("ai", checked)
-                }
-              >
-                <LightBulbSimpleIcon />
-                AI Features
-              </ListCheckboxItem>
-              <ListCheckboxItem
-                checked={checkedFeatures.includes("sync")}
-                onCheckedChange={(checked) =>
-                  handleFeatureToggle("sync", checked)
-                }
-              >
-                <BubbleSparkleIcon />
-                Real-time Sync
-              </ListCheckboxItem>
-            </List>
-          </div>
+            {/* Preview stage */}
+            <div className="flex flex-col gap-6 lg:col-span-2">
+              {/* Feature toggles */}
+              <div className="space-y-3">
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                  Playback Features (multi-select)
+                </p>
+                <List borderVariant="success" className="w-full">
+                  <ListLabel>Audio Enhancements</ListLabel>
+                  <ListCheckboxItem
+                    checked={enabledFeatures.includes("spatial")}
+                    onCheckedChange={(c) => toggleFeature("spatial", c)}
+                  >
+                    <VolumeFullIcon className="size-4" />
+                    Spatial Audio
+                  </ListCheckboxItem>
+                  <ListCheckboxItem
+                    checked={enabledFeatures.includes("crossfade")}
+                    onCheckedChange={(c) => toggleFeature("crossfade", c)}
+                  >
+                    <FeatureShineIcon className="size-4" />
+                    Crossfade
+                  </ListCheckboxItem>
+                  <ListCheckboxItem
+                    checked={enabledFeatures.includes("normalize")}
+                    onCheckedChange={(c) => toggleFeature("normalize", c)}
+                  >
+                    <SettingIcon className="size-4" />
+                    Volume Normalize
+                  </ListCheckboxItem>
+                  <ListCheckboxItem disabled>
+                    <StarIcon className="size-4" />
+                    Dolby Atmos (Pro)
+                  </ListCheckboxItem>
+                </List>
+              </div>
 
-          {/* Theme Selection */}
-          <div className="space-y-4">
-            <h4 className="text-fm-secondary text-sm font-medium">Theme</h4>
-            <List borderVariant="info">
-              <ListLabel>Appearance</ListLabel>
-              <ListRadioGroup value={theme}>
-                <ListRadioItem value="light" onSelect={setTheme}>
-                  <EyeOpenIcon />
-                  Light Theme
-                </ListRadioItem>
-                <ListRadioItem value="dark" onSelect={setTheme}>
-                  <MaintenanceIcon />
-                  Dark Theme
-                </ListRadioItem>
-                <ListRadioItem value="auto" onSelect={setTheme}>
-                  <FeatureShineIcon />
-                  Auto Theme
-                </ListRadioItem>
-              </ListRadioGroup>
-            </List>
-          </div>
-        </div>
+              {/* Quality selector */}
+              <div className="space-y-3">
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                  Streaming Quality (single-select)
+                </p>
+                <List borderVariant="info" className="w-full">
+                  <ListLabel>Audio Quality</ListLabel>
+                  <ListRadioGroup
+                    value={audioQuality}
+                    onValueChange={setAudioQuality}
+                  >
+                    <ListRadioItem value="low">Low (96 kbps)</ListRadioItem>
+                    <ListRadioItem value="normal">
+                      Normal (160 kbps)
+                    </ListRadioItem>
+                    <ListRadioItem value="high">High (320 kbps)</ListRadioItem>
+                    <ListRadioItem value="lossless">
+                      Lossless (FLAC)
+                    </ListRadioItem>
+                  </ListRadioGroup>
+                </List>
+              </div>
 
-        {/* Status Display */}
-        <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-2xl rounded-lg border p-4">
-          <h4 className="text-fm-primary mb-3 text-sm font-medium">
-            Current State
-          </h4>
-          <div className="text-fm-secondary grid grid-cols-1 gap-3 text-xs md:grid-cols-3">
-            <div>
-              <strong>Selected Page:</strong>{" "}
-              {selectedItems.includes("item1")
-                ? "Dashboard"
-                : selectedItems.includes("item2")
-                  ? "Media Library"
-                  : selectedItems.includes("item3")
-                    ? "Settings"
-                    : "None"}
-            </div>
-            <div>
-              <strong>Enabled Features:</strong>{" "}
-              {checkedFeatures.length > 0 ? checkedFeatures.join(", ") : "None"}
-            </div>
-            <div>
-              <strong>Theme:</strong> {theme}
+              {/* State readout */}
+              <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+                <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm mb-3 font-semibold">
+                  Current State
+                </p>
+                <div className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm grid grid-cols-1 gap-2 sm:grid-cols-3">
+                  <div>
+                    <span className="text-fm-primary font-medium">
+                      Section:{" "}
+                    </span>
+                    <span className="capitalize">{activeTab}</span>
+                  </div>
+                  <div>
+                    <span className="text-fm-primary font-medium">
+                      Features:{" "}
+                    </span>
+                    <span>
+                      {enabledFeatures.length > 0
+                        ? enabledFeatures.join(", ")
+                        : "none"}
+                    </span>
+                  </div>
+                  <div>
+                    <span className="text-fm-primary font-medium">
+                      Quality:{" "}
+                    </span>
+                    <span>{qualityLabel[audioQuality]}</span>
+                  </div>
+                </div>
+              </div>
             </div>
           </div>
         </div>
@@ -967,10 +615,11 @@ export const InteractiveShowcase: Story = {
     )
   },
   parameters: {
+    layout: "fullscreen",
     docs: {
       description: {
         story:
-          "Fully interactive showcase demonstrating navigation selection, feature toggles, and theme selection with real-time state updates.",
+          "Fully interactive story demonstrating navigation selection (single active tab), multi-select feature toggles via ListCheckboxItem, and streaming quality selection via ListRadioItem — all with live state readout.",
       },
     },
   },