aural-ui 4.0.1 → 4.2.0

package/dist/components/table/Table.stories.tsx

@@ -1,17 +1,17 @@
 import React from "react"
 import { Badge } from "@components/badge"
-import { Button } from "@components/button"
 import { Checkbox } from "@components/checkbox"
 import {
   ChevronDownIcon,
   ChevronUpIcon,
-  EditBigIcon,
-  EyeOpenIcon,
-  TrashIcon,
-  VerticalMenuIcon,
+  HeartIcon,
+  MusicalNoteIcon,
+  PauseIcon,
 } from "@icons/index"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import {
   Table,
   TableBody,
@@ -28,210 +28,36 @@ const meta: Meta<typeof Table> = {
   component: Table,
   parameters: {
     layout: "fullscreen",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-# Table Component
-
-A comprehensive table component system built with semantic HTML elements and design system integration.
-
-## Components
-
-### Core Components
-- **Table**: Root table wrapper with overflow handling
-- **TableHeader**: Table header (\`<thead>\`) element
-- **TableBody**: Table body (\`<tbody>\`) element  
-- **TableFooter**: Table footer (\`<tfoot>\`) element
-- **TableRow**: Table row (\`<tr>\`) with hover and selection states
-- **TableHead**: Table header cell (\`<th>\`) with design system styling
-- **TableCell**: Table data cell (\`<td>\`) with consistent typography
-- **TableCaption**: Table caption with tertiary label styling
-
-## Features
-
-- **Responsive Design**: Horizontal scroll on smaller screens
-- **Interactive Rows**: Hover effects and selection states
-- **Checkbox Integration**: Built-in support for row selection
-- **Typography System**: Consistent text styling with design tokens
-- **Semantic HTML**: Proper table structure for accessibility
-- **Design System**: Integrated with FM design tokens
-- **Customizable**: All components accept className for customization
-- **Data Slots**: Component identification with data-slot attributes
-
-## Styling
-
-### Table Structure
-- **Background**: \`bg-fm-surface-primary\` - Primary surface background
-- **Container**: Responsive overflow with \`overflow-x-auto\`
-- **Layout**: Full width with \`w-full\`
-
-### TableHead Styling
-- **Typography**: Brand font with small leading
-- **Color**: \`text-fm-tertiary\` - Tertiary text color
-- **Text**: Uppercase, left-aligned, nowrap
-- **Size**: \`--text-fm-sm\` design token
-- **Padding**: \`p-4\` consistent spacing
-
-### TableCell Styling  
-- **Typography**: Text font with medium leading
-- **Color**: \`text-fm-primary\` - Primary text color
-- **Text**: Left-aligned, nowrap
-- **Size**: \`--text-fm-md\` design token
-- **Padding**: \`p-4\` consistent spacing
-
-### TableRow Interactions
-- **Hover**: \`hover:bg-fm-surface-frosted/30\` - Subtle frosted effect
-- **Selected**: \`data-[state=selected]:bg-fm-surface-frosted/50\` - Stronger selection state
-- **Transition**: Smooth color transitions
-
-### Checkbox Integration
-- **Positioning**: Automatic translation for alignment
-- **Padding**: Reduced right padding for checkbox columns
-- **Accessibility**: Proper role attributes maintained
-
-## Usage Examples
-
-### Basic Table
-\`\`\`tsx
-<Table>
-  <TableHeader>
-    <TableRow>
-      <TableHead>Name</TableHead>
-      <TableHead>Email</TableHead>
-      <TableHead>Role</TableHead>
-    </TableRow>
-  </TableHeader>
-  <TableBody>
-    <TableRow>
-      <TableCell>John Doe</TableCell>
-      <TableCell>john@example.com</TableCell>
-      <TableCell>Admin</TableCell>
-    </TableRow>
-  </TableBody>
-</Table>
-\`\`\`
-
-### With Selection
-\`\`\`tsx
-<Table>
-  <TableHeader>
-    <TableRow>
-      <TableHead>
-        <Checkbox />
-      </TableHead>
-      <TableHead>Name</TableHead>
-      <TableHead>Status</TableHead>
-    </TableRow>
-  </TableHeader>
-  <TableBody>
-    <TableRow data-state="selected">
-      <TableCell>
-        <Checkbox checked />
-      </TableCell>
-      <TableCell>Selected Row</TableCell>
-      <TableCell>Active</TableCell>
-    </TableRow>
-  </TableBody>
-</Table>
-\`\`\`
-
-### With Actions
-\`\`\`tsx
-<Table>
-  <TableBody>
-    <TableRow>
-      <TableCell>Data</TableCell>
-      <TableCell>
-        <div className="flex gap-2">
-          <Button size="sm" variant="ghost">Edit</Button>
-          <Button size="sm" variant="ghost">Delete</Button>
-        </div>
-      </TableCell>
-    </TableRow>
-  </TableBody>
-</Table>
-\`\`\`
-
-### With Caption and Footer
-\`\`\`tsx
-<Table>
-  <TableCaption>User management table</TableCaption>
-  <TableHeader>
-    <TableRow>
-      <TableHead>Name</TableHead>
-      <TableHead>Count</TableHead>
-    </TableRow>
-  </TableHeader>
-  <TableBody>
-    <TableRow>
-      <TableCell>Users</TableCell>
-      <TableCell>150</TableCell>
-    </TableRow>
-  </TableBody>
-  <TableFooter>
-    <TableRow>
-      <TableCell>Total</TableCell>
-      <TableCell>150</TableCell>
-    </TableRow>
-  </TableFooter>
-</Table>
-\`\`\`
-
-## Accessibility
-
-- **Semantic HTML**: Proper table structure with thead, tbody, tfoot
-- **ARIA Support**: Compatible with screen readers
-- **Keyboard Navigation**: Standard table navigation
-- **Role Attributes**: Proper checkbox roles maintained
-- **Focus Management**: Consistent focus indicators
-- **Screen Reader**: Table structure announced properly
-
-## Design Tokens
-
-### Typography
-- \`font-fm-brand\`: Header typography
-- \`font-fm-text\`: Cell typography
-- \`leading-fm-sm\`: Small line height for headers
-- \`leading-fm-md\`: Medium line height for cells
-- \`leading-fm-xs\`: Extra small line height for captions
-
-### Colors
-- \`text-fm-tertiary\`: Header text color
-- \`text-fm-primary\`: Cell text color
-- \`text-fm-label-tertiary\`: Caption text color
-- \`bg-fm-surface-primary\`: Table background
-- \`bg-fm-surface-frosted\`: Hover and selection states
-
-### Sizing
-- \`--text-fm-sm\`: Header font size
-- \`--text-fm-md\`: Cell font size  
-- \`--text-fm-xs\`: Caption font size
-
-## Best Practices
-
-1. **Always use TableHeader for headers** - Semantic structure
-2. **Include TableCaption for complex tables** - Accessibility
-3. **Use data-state="selected" for selection** - Consistent styling
-4. **Wrap interactive elements properly** - Button integration
-5. **Consider responsive behavior** - Horizontal scroll handling
-6. **Maintain consistent spacing** - Use default padding
-7. **Follow typography hierarchy** - Headers vs cells distinction
-        `,
+        component:
+          "A semantic compound table for structured data. Composed of Table (root), TableHeader (thead), TableBody (tbody), TableFooter (tfoot), TableRow (tr), TableHead (th), TableCell (td), and TableCaption. Designed for audio app contexts: track listings, album catalogs, queue management, and analytics. Supports row selection states, sortable headers, dense layouts, and responsive horizontal scrolling.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Semantic Parts",
+              description: "thead, tbody, tfoot",
+            },
+            {
+              title: "Sortable Headers",
+              description: "Click to sort columns",
+            },
+            {
+              title: "Row Selection",
+              description: "Checkbox select rows",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
   argTypes: {
     className: {
       control: "text",
-      description: "Additional CSS classes for the table",
+      description: "Additional CSS classes applied to the table root",
     },
   },
 }
@@ -239,451 +65,358 @@ A comprehensive table component system built with semantic HTML elements and des
 export default meta
 type Story = StoryObj<typeof Table>
 
-// Sample data for stories
-const sampleUsers = [
-  {
-    id: 1,
-    name: "John Doe",
-    email: "john.doe@example.com",
-    role: "Admin",
-    status: "Active",
-    lastSeen: "2 minutes ago",
-    avatar: "JD",
-  },
-  {
-    id: 2,
-    name: "Jane Smith",
-    email: "jane.smith@example.com",
-    role: "Editor",
-    status: "Active",
-    lastSeen: "1 hour ago",
-    avatar: "JS",
-  },
-  {
-    id: 3,
-    name: "Bob Johnson",
-    email: "bob.johnson@example.com",
-    role: "Viewer",
-    status: "Inactive",
-    lastSeen: "3 days ago",
-    avatar: "BJ",
-  },
-  {
-    id: 4,
-    name: "Alice Brown",
-    email: "alice.brown@example.com",
-    role: "Editor",
-    status: "Active",
-    lastSeen: "30 minutes ago",
-    avatar: "AB",
-  },
-  {
-    id: 5,
-    name: "Charlie Wilson",
-    email: "charlie.wilson@example.com",
-    role: "Admin",
-    status: "Active",
-    lastSeen: "Just now",
-    avatar: "CW",
-  },
-]
-
-const sampleProjects = [
-  {
-    id: 1,
-    name: "Website Redesign",
-    status: "In Progress",
-    priority: "High",
-    assignee: "John Doe",
-    dueDate: "Dec 15, 2024",
-    progress: 75,
-  },
-  {
-    id: 2,
-    name: "Mobile App",
-    status: "Planning",
-    priority: "Medium",
-    assignee: "Jane Smith",
-    dueDate: "Jan 20, 2025",
-    progress: 25,
-  },
-  {
-    id: 3,
-    name: "API Integration",
-    status: "Completed",
-    priority: "High",
-    assignee: "Bob Johnson",
-    dueDate: "Nov 30, 2024",
-    progress: 100,
-  },
-  {
-    id: 4,
-    name: "Documentation",
-    status: "In Progress",
-    priority: "Low",
-    assignee: "Alice Brown",
-    dueDate: "Dec 31, 2024",
-    progress: 50,
-  },
-]
+// ─── 1. Parts ─────────────────────────────────────────────────────────────────
 
-// 1. Basic Table
-export const Basic: Story = {
+export const Parts: Story = {
   render: () => (
-    <div className="p-8">
-      <Table>
-        <TableHeader>
-          <TableRow>
-            <TableHead>Name</TableHead>
-            <TableHead>Email</TableHead>
-            <TableHead>Role</TableHead>
-            <TableHead>Status</TableHead>
-          </TableRow>
-        </TableHeader>
-        <TableBody>
-          {sampleUsers.slice(0, 3).map((user) => (
-            <TableRow key={user.id}>
-              <TableCell>{user.name}</TableCell>
-              <TableCell>{user.email}</TableCell>
-              <TableCell>{user.role}</TableCell>
+    <div className="space-y-10 p-8">
+      {/* Table */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Table — root container
+        </h4>
+        <Table>
+          <TableBody>
+            <TableRow>
               <TableCell>
-                <Badge
-                  color={user.status === "Active" ? "positive" : "neutral"}
-                >
-                  {user.status}
-                </Badge>
+                Root container wraps a scrollable div + semantic table element.
               </TableCell>
             </TableRow>
-          ))}
-        </TableBody>
-      </Table>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Basic table structure with headers and data cells. Shows proper typography hierarchy and spacing.",
-      },
-    },
-  },
-}
-
-// 2. With Selection
-export const WithSelection: Story = {
-  render: () => {
-    const [selectedRows, setSelectedRows] = React.useState<number[]>([2])
-    const [selectAll, setSelectAll] = React.useState(false)
-
-    const handleSelectAll = () => {
-      if (selectAll) {
-        setSelectedRows([])
-      } else {
-        setSelectedRows(sampleUsers.map((user) => user.id))
-      }
-      setSelectAll(!selectAll)
-    }
+          </TableBody>
+        </Table>
+        <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">Table</strong> renders a{" "}
+            <code>div[data-slot="table-container"]</code> with{" "}
+            <code>overflow-x-auto</code> for responsive scrolling, wrapping a
+            semantic <code>&lt;table&gt;</code> with{" "}
+            <code>bg-fm-surface-primary</code>.
+          </p>
+        </div>
+      </div>
 
-    const handleSelectRow = (id: number) => {
-      setSelectedRows((prev) =>
-        prev.includes(id) ? prev.filter((rowId) => rowId !== id) : [...prev, id]
-      )
-    }
+      {/* TableHeader */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          TableHeader — thead element
+        </h4>
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>#</TableHead>
+              <TableHead>Title</TableHead>
+              <TableHead>Artist</TableHead>
+              <TableHead>Duration</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            <TableRow>
+              <TableCell>1</TableCell>
+              <TableCell>Midnight Dreams</TableCell>
+              <TableCell>Aura Band</TableCell>
+              <TableCell>4:17</TableCell>
+            </TableRow>
+          </TableBody>
+        </Table>
+        <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">TableHeader</strong> renders a{" "}
+            <code>&lt;thead&gt;</code> with a subtle frosted background (
+            <code>bg-fm-surface-frosted/10</code>). Always place{" "}
+            <code>TableHead</code> cells inside it for correct semantic
+            structure.
+          </p>
+        </div>
+      </div>
 
-    return (
-      <div className="p-8">
+      {/* TableHead */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          TableHead — th cell
+        </h4>
         <Table>
           <TableHeader>
             <TableRow>
-              <TableHead>
-                <Checkbox checked={selectAll} onChange={handleSelectAll} />
-              </TableHead>
-              <TableHead>User</TableHead>
-              <TableHead>Email</TableHead>
-              <TableHead>Role</TableHead>
-              <TableHead>Status</TableHead>
-              <TableHead>Last Seen</TableHead>
+              <TableHead>Track</TableHead>
+              <TableHead>Album</TableHead>
+              <TableHead>Plays</TableHead>
+              <TableHead className="text-right">Actions</TableHead>
             </TableRow>
           </TableHeader>
           <TableBody>
-            {sampleUsers.map((user) => (
-              <TableRow
-                key={user.id}
-                data-state={
-                  selectedRows.includes(user.id) ? "selected" : undefined
-                }
-              >
-                <TableCell>
-                  <Checkbox
-                    checked={selectedRows.includes(user.id)}
-                    onChange={() => handleSelectRow(user.id)}
-                  />
-                </TableCell>
-                <TableCell>
-                  <div className="flex items-center gap-3">
-                    <div className="bg-fm-surface-secondary text-fm-primary flex h-8 w-8 items-center justify-center rounded-full text-sm font-medium">
-                      {user.avatar}
-                    </div>
-                    <span>{user.name}</span>
-                  </div>
-                </TableCell>
-                <TableCell className="text-fm-secondary">
-                  {user.email}
-                </TableCell>
-                <TableCell>{user.role}</TableCell>
-                <TableCell>
-                  <Badge
-                    color={user.status === "Active" ? "positive" : "neutral"}
-                  >
-                    {user.status}
-                  </Badge>
-                </TableCell>
-                <TableCell className="text-fm-tertiary">
-                  {user.lastSeen}
-                </TableCell>
-              </TableRow>
-            ))}
+            <TableRow>
+              <TableCell>Electric Sunrise</TableCell>
+              <TableCell>Wavelength EP</TableCell>
+              <TableCell>1.2M</TableCell>
+              <TableCell className="text-right">—</TableCell>
+            </TableRow>
           </TableBody>
         </Table>
+        <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">TableHead</strong> renders a{" "}
+            <code>&lt;th&gt;</code> with <code>text-fm-tertiary</code>, brand
+            font, uppercase, and <code>text-fm-sm</code> sizing. Accepts{" "}
+            <code>className</code> for alignment overrides (e.g.{" "}
+            <code>text-right</code>).
+          </p>
+        </div>
+      </div>
 
-        <div className="text-fm-secondary mt-4 text-sm">
-          {selectedRows.length > 0 && (
-            <p>
-              {selectedRows.length} row{selectedRows.length !== 1 ? "s" : ""}{" "}
-              selected
-            </p>
-          )}
+      {/* TableBody */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          TableBody — tbody element
+        </h4>
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Title</TableHead>
+              <TableHead>Duration</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            <TableRow>
+              <TableCell>Echoes in Rain</TableCell>
+              <TableCell>3:42</TableCell>
+            </TableRow>
+            <TableRow>
+              <TableCell>Neon Horizon</TableCell>
+              <TableCell>5:01</TableCell>
+            </TableRow>
+          </TableBody>
+        </Table>
+        <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">TableBody</strong> renders a{" "}
+            <code>&lt;tbody&gt;</code> that applies{" "}
+            <code>hover:bg-fm-surface-frosted/15</code> to every child{" "}
+            <code>TableRow</code> via a descendant selector.
+          </p>
         </div>
       </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Table with row selection functionality. Shows selected state styling and checkbox integration.",
-      },
-    },
-  },
-}
 
-// 3. With Actions
-export const WithActions: Story = {
-  render: () => (
-    <div className="p-8">
-      <Table>
-        <TableHeader>
-          <TableRow>
-            <TableHead>Project</TableHead>
-            <TableHead>Status</TableHead>
-            <TableHead>Priority</TableHead>
-            <TableHead>Assignee</TableHead>
-            <TableHead>Due Date</TableHead>
-            <TableHead>Progress</TableHead>
-            <TableHead className="text-right">Actions</TableHead>
-          </TableRow>
-        </TableHeader>
-        <TableBody>
-          {sampleProjects.map((project) => (
-            <TableRow key={project.id}>
-              <TableCell className="font-medium">{project.name}</TableCell>
+      {/* TableRow */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          TableRow — tr element
+        </h4>
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>State</TableHead>
+              <TableHead>Track</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            <TableRow>
               <TableCell>
-                <Badge
-                  color={
-                    project.status === "Completed"
-                      ? "positive"
-                      : project.status === "In Progress"
-                        ? "warning"
-                        : "neutral"
-                  }
-                >
-                  {project.status}
-                </Badge>
+                <Badge color="neutral">Default</Badge>
               </TableCell>
+              <TableCell>Midnight Dreams</TableCell>
+            </TableRow>
+            <TableRow data-state="selected">
               <TableCell>
                 <Badge
-                  color={
-                    project.priority === "High"
-                      ? "negative"
-                      : project.priority === "Medium"
-                        ? "warning"
-                        : "neutral"
-                  }
+                  color="info"
+                  className="bg-fm-surface-info-sec text-fm-info-sec"
                 >
-                  {project.priority}
+                  Selected
                 </Badge>
               </TableCell>
-              <TableCell>{project.assignee}</TableCell>
-              <TableCell className="text-fm-secondary">
-                {project.dueDate}
-              </TableCell>
-              <TableCell>
-                <div className="flex items-center gap-2">
-                  <div className="bg-fm-surface-secondary h-2 w-20 rounded-full">
-                    <div
-                      className="bg-fm-primary-600 h-2 rounded-full"
-                      style={{ width: `${project.progress}%` }}
-                    />
-                  </div>
-                  <span className="text-fm-tertiary text-sm">
-                    {project.progress}%
-                  </span>
-                </div>
-              </TableCell>
-              <TableCell>
-                <div className="flex items-center justify-end gap-2">
-                  <Button size="sm" variant="text">
-                    <EyeOpenIcon className="h-4 w-4" />
-                  </Button>
-                  <Button size="sm" variant="text">
-                    <EditBigIcon className="h-4 w-4" />
-                  </Button>
-                  <Button size="sm" variant="text">
-                    <TrashIcon className="h-4 w-4" />
-                  </Button>
-                  <Button size="sm" variant="text">
-                    <VerticalMenuIcon className="h-4 w-4" />
-                  </Button>
-                </div>
-              </TableCell>
+              <TableCell>Electric Sunrise</TableCell>
             </TableRow>
-          ))}
-        </TableBody>
-      </Table>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Table with action buttons and rich content including progress bars, badges, and button groups.",
-      },
-    },
-  },
-}
-
-// 4. With Footer and Caption
-export const WithFooterAndCaption: Story = {
-  render: () => {
-    const totalUsers = sampleUsers.length
-    const activeUsers = sampleUsers.filter(
-      (user) => user.status === "Active"
-    ).length
-    const inactiveUsers = totalUsers - activeUsers
+          </TableBody>
+        </Table>
+        <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">TableRow</strong> renders a{" "}
+            <code>&lt;tr&gt;</code> with transition-colors. Apply{" "}
+            <code>data-state="selected"</code> to activate the selection
+            highlight (<code>bg-fm-secondary-50</code>).
+          </p>
+        </div>
+      </div>
 
-    return (
-      <div className="p-8">
+      {/* TableCell */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          TableCell — td element
+        </h4>
         <Table>
-          <TableCaption>User statistics and management overview</TableCaption>
           <TableHeader>
             <TableRow>
-              <TableHead>Metric</TableHead>
-              <TableHead className="text-right">Count</TableHead>
-              <TableHead className="text-right">Percentage</TableHead>
+              <TableHead>Primary text</TableHead>
+              <TableHead>Secondary text</TableHead>
+              <TableHead>Tertiary text</TableHead>
             </TableRow>
           </TableHeader>
           <TableBody>
             <TableRow>
-              <TableCell>Active Users</TableCell>
-              <TableCell className="text-right font-medium">
-                {activeUsers}
+              <TableCell>text-fm-primary (default)</TableCell>
+              <TableCell className="text-fm-secondary">
+                text-fm-secondary
               </TableCell>
-              <TableCell className="text-right">
-                {Math.round((activeUsers / totalUsers) * 100)}%
+              <TableCell className="text-fm-tertiary">
+                text-fm-tertiary
               </TableCell>
             </TableRow>
+          </TableBody>
+        </Table>
+        <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">TableCell</strong> renders a{" "}
+            <code>&lt;td&gt;</code> with <code>text-fm-primary</code>, text
+            font, <code>text-fm-md</code> sizing, and <code>p-4</code> padding.
+            Override <code>className</code> for secondary or tertiary text
+            hierarchy.
+          </p>
+        </div>
+      </div>
+
+      {/* TableFooter */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          TableFooter — tfoot element
+        </h4>
+        <Table>
+          <TableHeader>
             <TableRow>
-              <TableCell>Inactive Users</TableCell>
-              <TableCell className="text-right font-medium">
-                {inactiveUsers}
-              </TableCell>
-              <TableCell className="text-right">
-                {Math.round((inactiveUsers / totalUsers) * 100)}%
-              </TableCell>
+              <TableHead>Track</TableHead>
+              <TableHead className="text-right">Plays</TableHead>
             </TableRow>
+          </TableHeader>
+          <TableBody>
             <TableRow>
-              <TableCell>Admins</TableCell>
-              <TableCell className="text-right font-medium">
-                {sampleUsers.filter((user) => user.role === "Admin").length}
-              </TableCell>
-              <TableCell className="text-right">
-                {Math.round(
-                  (sampleUsers.filter((user) => user.role === "Admin").length /
-                    totalUsers) *
-                    100
-                )}
-                %
-              </TableCell>
+              <TableCell>Midnight Dreams</TableCell>
+              <TableCell className="text-right">1.2M</TableCell>
             </TableRow>
             <TableRow>
-              <TableCell>Editors</TableCell>
-              <TableCell className="text-right font-medium">
-                {sampleUsers.filter((user) => user.role === "Editor").length}
-              </TableCell>
-              <TableCell className="text-right">
-                {Math.round(
-                  (sampleUsers.filter((user) => user.role === "Editor").length /
-                    totalUsers) *
-                    100
-                )}
-                %
-              </TableCell>
+              <TableCell>Electric Sunrise</TableCell>
+              <TableCell className="text-right">890K</TableCell>
             </TableRow>
           </TableBody>
           <TableFooter>
             <TableRow>
-              <TableCell className="font-bold">Total Users</TableCell>
-              <TableCell className="text-right font-bold">
-                {totalUsers}
-              </TableCell>
-              <TableCell className="text-right font-bold">100%</TableCell>
+              <TableCell className="font-semibold">Total</TableCell>
+              <TableCell className="text-right font-semibold">2.09M</TableCell>
             </TableRow>
           </TableFooter>
         </Table>
+        <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">TableFooter</strong> renders a{" "}
+            <code>&lt;tfoot&gt;</code> with the same frosted background as{" "}
+            <code>TableHeader</code>. Use it for totals, aggregates, or
+            pagination controls.
+          </p>
+        </div>
       </div>
-    )
-  },
+
+      {/* TableCaption */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          TableCaption — caption element
+        </h4>
+        <Table>
+          <TableCaption>Top tracks by play count — last 30 days</TableCaption>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Track</TableHead>
+              <TableHead className="text-right">Plays</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            <TableRow>
+              <TableCell>Midnight Dreams</TableCell>
+              <TableCell className="text-right">1.2M</TableCell>
+            </TableRow>
+          </TableBody>
+        </Table>
+        <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">TableCaption</strong> renders a{" "}
+            <code>&lt;caption&gt;</code> below the table using{" "}
+            <code>text-fm-label-tertiary</code>, brand font, and uppercase small
+            text. It is announced by screen readers for accessibility context.
+          </p>
+        </div>
+      </div>
+    </div>
+  ),
   parameters: {
+    layout: "fullscreen",
     docs: {
       description: {
         story:
-          "Table with caption and footer sections. Shows proper semantic structure for complex data tables.",
+          "Each sub-component of the Table compound shown individually with a role explanation and live example. Use this as a reference when composing data table layouts.",
       },
     },
   },
 }
 
-// 5. Sortable Table
-export const SortableTable: Story = {
-  render: () => {
-    const [sortField, setSortField] = React.useState<string | null>(null)
-    const [sortDirection, setSortDirection] = React.useState<"asc" | "desc">(
-      "asc"
-    )
-
-    const sortedUsers = React.useMemo(() => {
-      if (!sortField) return sampleUsers
+// ─── 2. Configurations ────────────────────────────────────────────────────────
 
-      return [...sampleUsers].sort((a, b) => {
-        const aValue = a[sortField as keyof typeof a]
-        const bValue = b[sortField as keyof typeof b]
+export const Configurations: Story = {
+  render: () => {
+    const [selectedRows, setSelectedRows] = React.useState<number[]>([2])
+    const [sortField, setSortField] = React.useState<string | null>("title")
+    const [sortDir, setSortDir] = React.useState<"asc" | "desc">("asc")
+
+    const tracks = [
+      {
+        id: 1,
+        title: "Midnight Dreams",
+        artist: "Aura Band",
+        album: "Dark Frequencies",
+        duration: "4:17",
+        plays: 1200000,
+      },
+      {
+        id: 2,
+        title: "Electric Sunrise",
+        artist: "Neon Collective",
+        album: "Wavelength EP",
+        duration: "5:01",
+        plays: 890000,
+      },
+      {
+        id: 3,
+        title: "Echoes in Rain",
+        artist: "The Drifters",
+        album: "Reflections",
+        duration: "3:42",
+        plays: 640000,
+      },
+      {
+        id: 4,
+        title: "Neon Horizon",
+        artist: "Synthwave FM",
+        album: "Future Bass",
+        duration: "4:58",
+        plays: 410000,
+      },
+    ]
 
-        if (aValue < bValue) return sortDirection === "asc" ? -1 : 1
-        if (aValue > bValue) return sortDirection === "asc" ? 1 : -1
-        return 0
-      })
-    }, [sortField, sortDirection])
+    const sorted = [...tracks].sort((a, b) => {
+      if (!sortField) return 0
+      const av = a[sortField as keyof typeof a]
+      const bv = b[sortField as keyof typeof b]
+      if (av < bv) return sortDir === "asc" ? -1 : 1
+      if (av > bv) return sortDir === "asc" ? 1 : -1
+      return 0
+    })
 
     const handleSort = (field: string) => {
       if (sortField === field) {
-        setSortDirection(sortDirection === "asc" ? "desc" : "asc")
+        setSortDir((d) => (d === "asc" ? "desc" : "asc"))
       } else {
         setSortField(field)
-        setSortDirection("asc")
+        setSortDir("asc")
       }
     }
 
-    const SortableHeader = ({
+    const SortHead = ({
       field,
       children,
     }: {
@@ -692,228 +425,512 @@ export const SortableTable: Story = {
     }) => (
       <TableHead>
         <button
-          className="hover:text-fm-primary flex items-center gap-2 transition-colors"
+          className="text-fm-tertiary hover:text-fm-primary flex items-center gap-1.5 transition-colors"
           onClick={() => handleSort(field)}
         >
           {children}
-          {sortField === field &&
-            (sortDirection === "asc" ? (
-              <ChevronUpIcon className="h-4 w-4" />
+          {sortField === field ? (
+            sortDir === "asc" ? (
+              <ChevronUpIcon className="size-3.5" />
             ) : (
-              <ChevronDownIcon className="h-4 w-4" />
-            ))}
+              <ChevronDownIcon className="size-3.5" />
+            )
+          ) : (
+            <ChevronUpIcon className="text-fm-tertiary/40 size-3.5" />
+          )}
         </button>
       </TableHead>
     )
 
+    const handleToggle = (id: number) =>
+      setSelectedRows((prev) =>
+        prev.includes(id) ? prev.filter((r) => r !== id) : [...prev, id]
+      )
+
     return (
-      <div className="p-8">
-        <Table>
-          <TableHeader>
-            <TableRow>
-              <SortableHeader field="name">Name</SortableHeader>
-              <SortableHeader field="email">Email</SortableHeader>
-              <SortableHeader field="role">Role</SortableHeader>
-              <SortableHeader field="status">Status</SortableHeader>
-              <TableHead>Last Seen</TableHead>
-            </TableRow>
-          </TableHeader>
-          <TableBody>
-            {sortedUsers.map((user) => (
-              <TableRow key={user.id}>
-                <TableCell>
-                  <div className="flex items-center gap-3">
-                    <div className="bg-fm-surface-secondary text-fm-primary flex h-8 w-8 items-center justify-center rounded-full text-sm font-medium">
-                      {user.avatar}
-                    </div>
-                    <span className="font-medium">{user.name}</span>
-                  </div>
-                </TableCell>
-                <TableCell className="text-fm-secondary">
-                  {user.email}
-                </TableCell>
-                <TableCell>{user.role}</TableCell>
-                <TableCell>
-                  <Badge
-                    color={user.status === "Active" ? "positive" : "neutral"}
-                  >
-                    {user.status}
-                  </Badge>
-                </TableCell>
-                <TableCell className="text-fm-tertiary">
-                  {user.lastSeen}
+      <div className="space-y-8 p-8">
+        {/* Row selection */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Row selection
+          </h4>
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead>
+                  <Checkbox
+                    checked={selectedRows.length === tracks.length}
+                    onCheckedChange={() =>
+                      setSelectedRows(
+                        selectedRows.length === tracks.length
+                          ? []
+                          : tracks.map((t) => t.id)
+                      )
+                    }
+                  />
+                </TableHead>
+                <TableHead>Title</TableHead>
+                <TableHead>Artist</TableHead>
+                <TableHead>Duration</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {tracks.map((t) => (
+                <TableRow
+                  key={t.id}
+                  data-state={
+                    selectedRows.includes(t.id) ? "selected" : undefined
+                  }
+                >
+                  <TableCell>
+                    <Checkbox
+                      checked={selectedRows.includes(t.id)}
+                      onCheckedChange={() => handleToggle(t.id)}
+                    />
+                  </TableCell>
+                  <TableCell className="font-medium">{t.title}</TableCell>
+                  <TableCell className="text-fm-secondary">
+                    {t.artist}
+                  </TableCell>
+                  <TableCell className="text-fm-tertiary">
+                    {t.duration}
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+            <TableFooter>
+              <TableRow>
+                <TableCell colSpan={4}>
+                  <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    {selectedRows.length} of {tracks.length} track
+                    {tracks.length !== 1 ? "s" : ""} selected
+                  </span>
                 </TableCell>
               </TableRow>
-            ))}
-          </TableBody>
-        </Table>
+            </TableFooter>
+          </Table>
+        </div>
 
-        <div className="text-fm-secondary mt-4 text-sm">
-          {sortField && (
-            <p>
-              Sorted by {sortField} (
-              {sortDirection === "asc" ? "ascending" : "descending"})
-            </p>
-          )}
+        {/* Sortable columns */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Sortable columns
+          </h4>
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <SortHead field="title">Title</SortHead>
+                <SortHead field="artist">Artist</SortHead>
+                <SortHead field="plays">Plays</SortHead>
+                <SortHead field="duration">Duration</SortHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {sorted.map((t) => (
+                <TableRow key={t.id}>
+                  <TableCell className="font-medium">{t.title}</TableCell>
+                  <TableCell className="text-fm-secondary">
+                    {t.artist}
+                  </TableCell>
+                  <TableCell>{(t.plays / 1_000_000).toFixed(1)}M</TableCell>
+                  <TableCell className="text-fm-tertiary">
+                    {t.duration}
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </div>
+
+        {/* Dense layout */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Dense layout
+          </h4>
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead className="py-2">#</TableHead>
+                <TableHead className="py-2">Title</TableHead>
+                <TableHead className="py-2">Artist</TableHead>
+                <TableHead className="py-2">Album</TableHead>
+                <TableHead className="py-2">Duration</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {tracks.map((t) => (
+                <TableRow key={t.id}>
+                  <TableCell className="text-fm-tertiary py-2">
+                    {t.id}
+                  </TableCell>
+                  <TableCell className="py-2 font-medium">{t.title}</TableCell>
+                  <TableCell className="text-fm-secondary py-2">
+                    {t.artist}
+                  </TableCell>
+                  <TableCell className="text-fm-tertiary py-2">
+                    {t.album}
+                  </TableCell>
+                  <TableCell className="text-fm-tertiary py-2">
+                    {t.duration}
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
         </div>
       </div>
     )
   },
   parameters: {
+    layout: "fullscreen",
     docs: {
       description: {
         story:
-          "Interactive sortable table with clickable column headers and sort indicators.",
+          "Three configuration modes: row selection with checkboxes and footer count, sortable column headers with direction indicators, and a dense layout with reduced vertical padding.",
       },
     },
   },
 }
 
-// 6. Responsive Table
-export const ResponsiveTable: Story = {
-  render: () => (
-    <div className="p-8">
-      <div className="mb-4">
-        <h3 className="text-fm-primary mb-2 text-lg font-medium">
-          Responsive Table
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Resize your browser or view on mobile to see horizontal scrolling
-          behavior
-        </p>
-      </div>
+// ─── 3. UseCases ──────────────────────────────────────────────────────────────
 
-      <Table>
-        <TableHeader>
-          <TableRow>
-            <TableHead>ID</TableHead>
-            <TableHead>Full Name</TableHead>
-            <TableHead>Email Address</TableHead>
-            <TableHead>Role</TableHead>
-            <TableHead>Department</TableHead>
-            <TableHead>Status</TableHead>
-            <TableHead>Created Date</TableHead>
-            <TableHead>Last Activity</TableHead>
-            <TableHead>Actions</TableHead>
-          </TableRow>
-        </TableHeader>
-        <TableBody>
-          {sampleUsers.map((user) => (
-            <TableRow key={user.id}>
-              <TableCell className="font-mono">
-                #{user.id.toString().padStart(3, "0")}
-              </TableCell>
-              <TableCell className="font-medium">{user.name}</TableCell>
-              <TableCell className="text-fm-secondary">{user.email}</TableCell>
-              <TableCell>{user.role}</TableCell>
-              <TableCell>Engineering</TableCell>
-              <TableCell>
-                <Badge
-                  color={user.status === "Active" ? "positive" : "neutral"}
-                >
-                  {user.status}
-                </Badge>
-              </TableCell>
-              <TableCell>Nov 15, 2024</TableCell>
-              <TableCell className="text-fm-tertiary">
-                {user.lastSeen}
-              </TableCell>
-              <TableCell>
-                <div className="flex gap-1">
-                  <Button size="sm" variant="text">
-                    <EditBigIcon className="h-4 w-4" />
-                  </Button>
-                  <Button size="sm" variant="text">
-                    <TrashIcon className="h-4 w-4" />
-                  </Button>
-                </div>
-              </TableCell>
-            </TableRow>
-          ))}
-        </TableBody>
-      </Table>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Table with many columns demonstrating responsive horizontal scrolling behavior.",
+export const UseCases: Story = {
+  render: () => {
+    const [nowPlaying, setNowPlaying] = React.useState<number | null>(1)
+    const [liked, setLiked] = React.useState<number[]>([1, 3])
+
+    const tracks = [
+      {
+        id: 1,
+        num: 1,
+        title: "Midnight Dreams",
+        artist: "Aura Band",
+        duration: "4:17",
+        plays: "1.2M",
+        explicit: false,
       },
-    },
-  },
-}
+      {
+        id: 2,
+        num: 2,
+        title: "Electric Sunrise",
+        artist: "Neon Collective",
+        duration: "5:01",
+        plays: "890K",
+        explicit: true,
+      },
+      {
+        id: 3,
+        num: 3,
+        title: "Echoes in Rain",
+        artist: "The Drifters",
+        duration: "3:42",
+        plays: "640K",
+        explicit: false,
+      },
+      {
+        id: 4,
+        num: 4,
+        title: "Neon Horizon",
+        artist: "Synthwave FM",
+        duration: "4:58",
+        plays: "410K",
+        explicit: false,
+      },
+      {
+        id: 5,
+        num: 5,
+        title: "Crystal Waves",
+        artist: "Luna Echo",
+        duration: "3:18",
+        plays: "310K",
+        explicit: false,
+      },
+    ]
+
+    const albums = [
+      {
+        id: 1,
+        title: "Dark Frequencies",
+        artist: "Aura Band",
+        year: 2024,
+        tracks: 12,
+        genre: "Electronic",
+        status: "Released",
+      },
+      {
+        id: 2,
+        title: "Wavelength EP",
+        artist: "Neon Collective",
+        year: 2024,
+        tracks: 6,
+        genre: "Ambient",
+        status: "Released",
+      },
+      {
+        id: 3,
+        title: "Future Bass Vol. 3",
+        artist: "Synthwave FM",
+        year: 2025,
+        tracks: 9,
+        genre: "Bass",
+        status: "Pre-order",
+      },
+      {
+        id: 4,
+        title: "Reflections",
+        artist: "The Drifters",
+        year: 2023,
+        tracks: 14,
+        genre: "Indie",
+        status: "Released",
+      },
+    ]
 
-// 7. Empty State
-export const EmptyState: Story = {
-  render: () => (
-    <div className="p-8">
-      <Table>
-        <TableHeader>
-          <TableRow>
-            <TableHead>Name</TableHead>
-            <TableHead>Email</TableHead>
-            <TableHead>Role</TableHead>
-            <TableHead>Status</TableHead>
-          </TableRow>
-        </TableHeader>
-        <TableBody>
-          <TableRow>
-            <TableCell colSpan={4}>
-              <div className="flex flex-col items-center justify-center py-12 text-center">
-                <div className="bg-fm-surface-secondary mb-4 rounded-full p-3">
-                  <EyeOpenIcon className="text-fm-tertiary h-6 w-6" />
-                </div>
-                <h3 className="text-fm-primary mb-2 text-lg font-medium">
-                  No users found
-                </h3>
-                <p className="text-fm-secondary mb-4">
-                  Get started by adding your first user to the system.
-                </p>
-                <Button>Add User</Button>
-              </div>
-            </TableCell>
-          </TableRow>
-        </TableBody>
-      </Table>
-    </div>
-  ),
+    const toggleLike = (id: number) =>
+      setLiked((prev) =>
+        prev.includes(id) ? prev.filter((l) => l !== id) : [...prev, id]
+      )
+
+    return (
+      <div className="mx-auto max-w-3xl space-y-8 p-8">
+        {/* Track Listing */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Track listing
+          </h4>
+          <Table>
+            <TableCaption>
+              Late Night Sessions — 5 tracks · 21m 16s
+            </TableCaption>
+            <TableHeader>
+              <TableRow>
+                <TableHead className="w-10">#</TableHead>
+                <TableHead>Title</TableHead>
+                <TableHead>Plays</TableHead>
+                <TableHead className="text-right">Duration</TableHead>
+                <TableHead className="w-10" />
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {tracks.map((t) => {
+                const isPlaying = nowPlaying === t.id
+                return (
+                  <TableRow
+                    key={t.id}
+                    data-state={isPlaying ? "selected" : undefined}
+                  >
+                    <TableCell>
+                      <button
+                        className="text-fm-tertiary hover:text-fm-primary flex items-center justify-center transition-colors"
+                        onClick={() => setNowPlaying(isPlaying ? null : t.id)}
+                        aria-label={
+                          isPlaying ? `Pause ${t.title}` : `Play ${t.title}`
+                        }
+                      >
+                        {isPlaying ? (
+                          <PauseIcon className="size-4" />
+                        ) : (
+                          <span className="font-fm-text text-fm-sm leading-fm-sm">
+                            {t.num}
+                          </span>
+                        )}
+                      </button>
+                    </TableCell>
+                    <TableCell>
+                      <div className="flex flex-col gap-0.5">
+                        <span
+                          className={
+                            isPlaying
+                              ? "text-fm-label-primary font-medium"
+                              : "font-medium"
+                          }
+                        >
+                          {t.title}
+                        </span>
+                        <div className="flex items-center gap-2">
+                          <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                            {t.artist}
+                          </span>
+                          {t.explicit && (
+                            <Badge
+                              color="neutral"
+                              className="text-fm-xs px-1 py-0"
+                            >
+                              E
+                            </Badge>
+                          )}
+                        </div>
+                      </div>
+                    </TableCell>
+                    <TableCell className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                      {t.plays}
+                    </TableCell>
+                    <TableCell className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm text-right">
+                      {t.duration}
+                    </TableCell>
+                    <TableCell>
+                      <button
+                        className={
+                          liked.includes(t.id)
+                            ? "text-fm-label-primary"
+                            : "text-fm-tertiary hover:text-fm-primary transition-colors"
+                        }
+                        onClick={() => toggleLike(t.id)}
+                        aria-label={
+                          liked.includes(t.id)
+                            ? `Unlike ${t.title}`
+                            : `Like ${t.title}`
+                        }
+                      >
+                        <HeartIcon className="size-4" />
+                      </button>
+                    </TableCell>
+                  </TableRow>
+                )
+              })}
+            </TableBody>
+          </Table>
+        </div>
+
+        {/* Album catalog */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Album catalog
+          </h4>
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead>Album</TableHead>
+                <TableHead>Artist</TableHead>
+                <TableHead>Year</TableHead>
+                <TableHead>Genre</TableHead>
+                <TableHead>Tracks</TableHead>
+                <TableHead>Status</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {albums.map((a) => (
+                <TableRow key={a.id}>
+                  <TableCell>
+                    <div className="flex items-center gap-3">
+                      <div className="bg-fm-surface-secondary flex size-9 shrink-0 items-center justify-center rounded">
+                        <MusicalNoteIcon className="text-fm-tertiary size-4" />
+                      </div>
+                      <span className="font-medium">{a.title}</span>
+                    </div>
+                  </TableCell>
+                  <TableCell className="text-fm-secondary">
+                    {a.artist}
+                  </TableCell>
+                  <TableCell className="text-fm-tertiary">{a.year}</TableCell>
+                  <TableCell>
+                    <Badge color="neutral">{a.genre}</Badge>
+                  </TableCell>
+                  <TableCell className="text-fm-secondary">
+                    {a.tracks}
+                  </TableCell>
+                  <TableCell>
+                    <Badge
+                      color={a.status === "Released" ? "positive" : "warning"}
+                      className={
+                        a.status === "Released"
+                          ? "bg-fm-surface-positive-sec text-fm-positive-sec"
+                          : "bg-fm-yellow-200 text-fm-yellow-900"
+                      }
+                    >
+                      {a.status}
+                    </Badge>
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+            <TableFooter>
+              <TableRow>
+                <TableCell colSpan={4} className="font-semibold">
+                  4 albums
+                </TableCell>
+                <TableCell className="font-semibold">
+                  {albums.reduce((s, a) => s + a.tracks, 0)}
+                </TableCell>
+                <TableCell />
+              </TableRow>
+            </TableFooter>
+          </Table>
+        </div>
+      </div>
+    )
+  },
   parameters: {
+    layout: "fullscreen",
     docs: {
       description: {
         story:
-          "Table with empty state design using colspan for centered content.",
+          "Two realistic audio app scenarios: an interactive track listing with play/pause toggle and like buttons, and an album catalog with genre badges, release status, and a totals footer.",
       },
     },
   },
 }
 
-// 8. Dense Table
-export const DenseTable: Story = {
-  render: () => (
+// ─── 4. Playground ────────────────────────────────────────────────────────────
+
+export const Playground: Story = {
+  args: {
+    className: "",
+  },
+  render: (args) => (
     <div className="p-8">
-      <Table>
+      <Table {...args}>
+        <TableCaption>
+          Playground table — adjust className via controls
+        </TableCaption>
         <TableHeader>
           <TableRow>
-            <TableHead className="py-2">Name</TableHead>
-            <TableHead className="py-2">Email</TableHead>
-            <TableHead className="py-2">Role</TableHead>
-            <TableHead className="py-2">Status</TableHead>
+            <TableHead>#</TableHead>
+            <TableHead>Title</TableHead>
+            <TableHead>Artist</TableHead>
+            <TableHead>Duration</TableHead>
+            <TableHead>Status</TableHead>
           </TableRow>
         </TableHeader>
         <TableBody>
-          {sampleUsers.map((user) => (
-            <TableRow key={user.id}>
-              <TableCell className="py-2">{user.name}</TableCell>
-              <TableCell className="text-fm-secondary py-2">
-                {user.email}
-              </TableCell>
-              <TableCell className="py-2">{user.role}</TableCell>
-              <TableCell className="py-2">
+          {[
+            {
+              id: 1,
+              title: "Midnight Dreams",
+              artist: "Aura Band",
+              duration: "4:17",
+              status: "Playing",
+            },
+            {
+              id: 2,
+              title: "Electric Sunrise",
+              artist: "Neon Collective",
+              duration: "5:01",
+              status: "Queued",
+            },
+            {
+              id: 3,
+              title: "Echoes in Rain",
+              artist: "The Drifters",
+              duration: "3:42",
+              status: "Queued",
+            },
+          ].map((t) => (
+            <TableRow key={t.id}>
+              <TableCell className="text-fm-tertiary">{t.id}</TableCell>
+              <TableCell className="font-medium">{t.title}</TableCell>
+              <TableCell className="text-fm-secondary">{t.artist}</TableCell>
+              <TableCell className="text-fm-tertiary">{t.duration}</TableCell>
+              <TableCell>
                 <Badge
-                  color={user.status === "Active" ? "positive" : "neutral"}
+                  color={t.status === "Playing" ? "positive" : "neutral"}
+                  className={
+                    t.status === "Playing"
+                      ? "bg-fm-surface-positive-sec text-fm-positive-sec"
+                      : undefined
+                  }
                 >
-                  {user.status}
+                  {t.status}
                 </Badge>
               </TableCell>
             </TableRow>
@@ -922,175 +939,12 @@ export const DenseTable: Story = {
       </Table>
     </div>
   ),
-  parameters: {
-    docs: {
-      description: {
-        story: "Compact table with reduced padding for dense data display.",
-      },
-    },
-  },
-}
-
-// 9. Complete Showcase
-export const CompleteShowcase: Story = {
-  render: () => {
-    const [selectedRows] = React.useState<number[]>([])
-    const [currentPage, setCurrentPage] = React.useState(1)
-    const itemsPerPage = 3
-
-    const paginatedData = sampleUsers.slice(
-      (currentPage - 1) * itemsPerPage,
-      currentPage * itemsPerPage
-    )
-
-    const totalPages = Math.ceil(sampleUsers.length / itemsPerPage)
-
-    return (
-      <div className="space-y-6 p-8">
-        <div className="flex items-center justify-between">
-          <div>
-            <h2 className="text-fm-primary text-xl font-bold">
-              User Management
-            </h2>
-            <p className="text-fm-secondary">
-              Manage your team members and their permissions
-            </p>
-          </div>
-          <Button>Add User</Button>
-        </div>
-
-        <Table>
-          <TableCaption>
-            A list of all users in your organization with their current status
-            and roles
-          </TableCaption>
-          <TableHeader>
-            <TableRow>
-              <TableHead>
-                <Checkbox />
-              </TableHead>
-              <TableHead>User</TableHead>
-              <TableHead>Role</TableHead>
-              <TableHead>Status</TableHead>
-              <TableHead>Last Activity</TableHead>
-              <TableHead className="text-right">Actions</TableHead>
-            </TableRow>
-          </TableHeader>
-          <TableBody>
-            {paginatedData.map((user) => (
-              <TableRow
-                key={user.id}
-                data-state={
-                  selectedRows.includes(user.id) ? "selected" : undefined
-                }
-              >
-                <TableCell>
-                  <Checkbox />
-                </TableCell>
-                <TableCell>
-                  <div className="flex items-center gap-3">
-                    <div className="bg-fm-surface-secondary text-fm-primary flex h-10 w-10 items-center justify-center rounded-full text-sm font-medium">
-                      {user.avatar}
-                    </div>
-                    <div>
-                      <div className="text-fm-primary font-medium">
-                        {user.name}
-                      </div>
-                      <div className="text-fm-secondary text-sm">
-                        {user.email}
-                      </div>
-                    </div>
-                  </div>
-                </TableCell>
-                <TableCell>
-                  <Badge color="info">{user.role}</Badge>
-                </TableCell>
-                <TableCell>
-                  <div className="flex items-center gap-2">
-                    <div
-                      className={`h-2 w-2 rounded-full ${
-                        user.status === "Active"
-                          ? "bg-fm-surface-positive"
-                          : "bg-fm-surface-tertiary"
-                      }`}
-                    />
-                    <span
-                      className={
-                        user.status === "Active"
-                          ? "text-fm-positive"
-                          : "text-fm-tertiary"
-                      }
-                    >
-                      {user.status}
-                    </span>
-                  </div>
-                </TableCell>
-                <TableCell className="text-fm-tertiary">
-                  {user.lastSeen}
-                </TableCell>
-                <TableCell>
-                  <div className="flex items-center justify-end gap-2">
-                    <Button size="sm" variant="text">
-                      <EyeOpenIcon className="h-4 w-4" />
-                    </Button>
-                    <Button size="sm" variant="text">
-                      <EditBigIcon className="h-4 w-4" />
-                    </Button>
-                    <Button
-                      size="sm"
-                      variant="text"
-                      className="text-fm-icon-negative hover:text-fm-icon-negative"
-                    >
-                      <TrashIcon className="h-4 w-4" />
-                    </Button>
-                  </div>
-                </TableCell>
-              </TableRow>
-            ))}
-          </TableBody>
-          <TableFooter>
-            <TableRow>
-              <TableCell colSpan={6}>
-                <div className="flex items-center justify-between">
-                  <div className="text-fm-secondary text-sm">
-                    Showing {(currentPage - 1) * itemsPerPage + 1} to{" "}
-                    {Math.min(currentPage * itemsPerPage, sampleUsers.length)}{" "}
-                    of {sampleUsers.length} users
-                  </div>
-                  <div className="flex gap-2">
-                    <Button
-                      size="sm"
-                      variant="outline"
-                      disabled={currentPage === 1}
-                      onClick={() => setCurrentPage((p) => Math.max(1, p - 1))}
-                    >
-                      Previous
-                    </Button>
-                    <Button
-                      size="sm"
-                      variant="outline"
-                      disabled={currentPage === totalPages}
-                      onClick={() =>
-                        setCurrentPage((p) => Math.min(totalPages, p + 1))
-                      }
-                    >
-                      Next
-                    </Button>
-                  </div>
-                </div>
-              </TableCell>
-            </TableRow>
-          </TableFooter>
-        </Table>
-      </div>
-    )
-  },
   parameters: {
     layout: "fullscreen",
     docs: {
       description: {
         story:
-          "Complete table implementation with all features: selection, actions, pagination, and proper semantic structure.",
+          "Controls-driven story. Use the Storybook sidebar to adjust the className prop and observe styling changes on the table root.",
       },
     },
   },