aural-ui 3.0.7 → 4.1.0

package/dist/components/marquee/Marquee.stories.tsx

@@ -1,16 +1,9 @@
 import React from "react"
-import {
-  AlertIcon,
-  EditBigIcon,
-  EyeOpenIcon,
-  FileChartIcon,
-  PlusIcon,
-  SearchIcon,
-  TickCircleIcon,
-  TrashIcon,
-} from "@icons/index"
+import { MusicalNoteIcon, TickCircleIcon } from "@icons/index"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import Marquee from "."
 
 const meta: Meta<typeof Marquee> = {
@@ -18,114 +11,29 @@ const meta: Meta<typeof Marquee> = {
   component: Marquee,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-# Marquee Component
-
-A smooth, customizable marquee component for creating continuous scrolling content animations. Perfect for displaying logos, announcements, testimonials, or any repeating content.
-
-## Features
-
-- **Horizontal & Vertical**: Support for both horizontal and vertical scrolling
-- **Pause on Hover**: Optional pause animation when hovering
-- **Reverse Direction**: Ability to reverse the animation direction
-- **Customizable Speed**: Control animation duration via CSS custom properties
-- **Responsive Design**: Adapts to container width and content
-- **Smooth Animation**: Hardware-accelerated CSS animations
-- **Repeat Control**: Configure how many times content repeats
-- **Gap Control**: Customizable spacing between repeated items
-
-## Props
-
-### Core Props
-- **children**: Content to be animated in the marquee
-- **className**: Additional CSS classes for the container
-- **itemClassName**: CSS classes for individual marquee items
-- **vertical**: Switch between horizontal (default) and vertical scrolling
-- **reverse**: Reverse the animation direction
-- **pauseOnHover**: Pause animation when hovering (default: false)
-- **repeat**: Number of times to repeat the content (default: 4)
-
-## Usage Examples
-
-### Basic Horizontal Marquee
-\`\`\`tsx
-<Marquee>
-  <div>Item 1</div>
-  <div>Item 2</div>
-  <div>Item 3</div>
-</Marquee>
-\`\`\`
-
-### Vertical Marquee
-\`\`\`tsx
-<Marquee vertical>
-  <div>Vertical Item 1</div>
-  <div>Vertical Item 2</div>
-  <div>Vertical Item 3</div>
-</Marquee>
-\`\`\`
-
-### With Pause on Hover
-\`\`\`tsx
-<Marquee pauseOnHover>
-  <div>Hover to pause</div>
-  <div>This content</div>
-</Marquee>
-\`\`\`
-
-### Reverse Direction
-\`\`\`tsx
-<Marquee reverse>
-  <div>Reversed</div>
-  <div>Animation</div>
-</Marquee>
-\`\`\`
-
-### Custom Speed
-\`\`\`tsx
-<Marquee 
-  className="[--duration:20s]" 
-  style={{ '--duration': '20s' }}
->
-  <div>Faster animation</div>
-</Marquee>
-\`\`\`
-
-## Use Cases
-
-- **Logo Carousels**: Showcase partner or client logos
-- **News Tickers**: Display breaking news or announcements
-- **Testimonials**: Rotating customer testimonials
-- **Social Media Feeds**: Live social media content
-- **Product Showcases**: Continuous product displays
-- **Stock Tickers**: Financial data displays
-- **Event Announcements**: Scrolling event information
-
-## Accessibility
-
-- Consider users with motion sensitivity
-- Provide pause controls for accessibility
-- Ensure content is accessible via keyboard navigation
-- Don't rely solely on marquee for critical information
-- Test with screen readers for content accessibility
-
-## Performance
-
-- Uses CSS transforms for hardware acceleration
-- Minimal JavaScript overhead
-- Efficient DOM structure with repeated elements
-- Smooth 60fps animations on modern browsers
-        `,
+        component:
+          "A smooth, CSS-animated marquee component for continuous horizontal or vertical scrolling content. Supports pause-on-hover, reverse direction, configurable speed, repeat count, and gutter spacing.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Horizontal & Vertical",
+              description: "Direction via prop",
+            },
+            {
+              title: "Pause on Hover",
+              description: "Built-in hover pause",
+            },
+            {
+              title: "Speed & Gutter",
+              description: "CSS duration and gap",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -140,27 +48,19 @@ A smooth, customizable marquee component for creating continuous scrolling conte
     },
     pauseOnHover: {
       control: "boolean",
-      description: "Pause animation when hovering",
+      description: "Pause animation when the pointer is over the marquee",
     },
     repeat: {
       control: { type: "number", min: 1, max: 10, step: 1 },
-      description: "Number of times to repeat the content",
-    },
-    className: {
-      control: "text",
-      description: "Additional CSS classes for the container",
-    },
-    itemClassName: {
-      control: "text",
-      description: "CSS classes for individual marquee items",
+      description: "Number of times to repeat the children",
     },
     gutter: {
       control: "text",
-      description: "Spacing between repeated items (default: 1rem)",
+      description: "Gap between repeated instances (CSS value, default: 1rem)",
     },
     duration: {
       control: "text",
-      description: "Animation duration in seconds (default: 40s)",
+      description: "Animation cycle duration (CSS time value, default: 40s)",
     },
   },
 }
@@ -168,521 +68,240 @@ A smooth, customizable marquee component for creating continuous scrolling conte
 export default meta
 type Story = StoryObj<typeof Marquee>
 
-// 1. Basic Marquee
-export const Basic: Story = {
-  args: {
-    children: (
-      <>
-        <div className="flex h-16 w-32 items-center justify-center rounded-lg bg-blue-500/20 text-sm font-medium text-blue-300">
-          Item 1
-        </div>
-        <div className="flex h-16 w-32 items-center justify-center rounded-lg bg-green-500/20 text-sm font-medium text-green-300">
-          Item 2
-        </div>
-        <div className="flex h-16 w-32 items-center justify-center rounded-lg bg-purple-500/20 text-sm font-medium text-purple-300">
-          Item 3
-        </div>
-        <div className="flex h-16 w-32 items-center justify-center rounded-lg bg-orange-500/20 text-sm font-medium text-orange-300">
-          Item 4
-        </div>
-      </>
-    ),
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: "A basic horizontal marquee with simple content blocks.",
-      },
-    },
-  },
-}
-
-// 2. Logo Carousel
-export const LogoCarousel: Story = {
-  render: () => (
-    <div className="w-full max-w-4xl">
-      <h3 className="mb-6 text-center text-lg font-medium text-white">
-        Our Partners
-      </h3>
-      <Marquee pauseOnHover={false} duration="30s">
-        <div className="flex h-20 w-40 items-center justify-center rounded-lg border border-white/10 bg-white/5 transition-colors hover:bg-white/10">
-          <div className="text-center">
-            <div className="text-2xl font-bold text-white">ACME</div>
-            <div className="text-xs text-white/60">Corporation</div>
-          </div>
-        </div>
-        <div className="flex h-20 w-40 items-center justify-center rounded-lg border border-white/10 bg-white/5 transition-colors hover:bg-white/10">
-          <div className="text-center">
-            <div className="text-2xl font-bold text-blue-400">TechCorp</div>
-            <div className="text-xs text-white/60">Innovation</div>
-          </div>
-        </div>
-        <div className="flex h-20 w-40 items-center justify-center rounded-lg border border-white/10 bg-white/5 transition-colors hover:bg-white/10">
-          <div className="text-center">
-            <div className="text-2xl font-bold text-green-400">GlobalTech</div>
-            <div className="text-xs text-white/60">Solutions</div>
-          </div>
-        </div>
-        <div className="flex h-20 w-40 items-center justify-center rounded-lg border border-white/10 bg-white/5 transition-colors hover:bg-white/10">
-          <div className="text-center">
-            <div className="text-2xl font-bold text-purple-400">
-              InnovateLab
-            </div>
-            <div className="text-xs text-white/60">Research</div>
-          </div>
-        </div>
-        <div className="flex h-20 w-40 items-center justify-center rounded-lg border border-white/10 bg-white/5 transition-colors hover:bg-white/10">
-          <div className="text-center">
-            <div className="text-2xl font-bold text-orange-400">FutureTech</div>
-            <div className="text-xs text-white/60">Systems</div>
-          </div>
-        </div>
-      </Marquee>
+// ─── shared content helpers ───────────────────────────────────────────────────
+
+/** A pill-shaped label card styled with design tokens only */
+function TokenChip({
+  label,
+  surface,
+}: {
+  label: string
+  surface:
+    | "secondary"
+    | "info-sec"
+    | "positive-sec"
+    | "warning-sec"
+    | "negative-sec"
+}) {
+  const surfaceClass = {
+    secondary: "bg-fm-surface-secondary border-fm-divider-secondary",
+    "info-sec": "bg-fm-surface-info-sec border-fm-divider-secondary",
+    "positive-sec": "bg-fm-surface-positive-sec border-fm-divider-secondary",
+    "warning-sec": "bg-fm-surface-warning-sec border-fm-divider-secondary",
+    "negative-sec": "bg-fm-surface-negative-sec border-fm-divider-secondary",
+  }[surface]
+
+  return (
+    <div
+      className={`flex h-10 items-center rounded-full border px-4 whitespace-nowrap ${surfaceClass}`}
+    >
+      <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+        {label}
+      </span>
     </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "A logo carousel showcasing partner companies with hover pause functionality.",
-      },
-    },
-  },
+  )
 }
 
-// 3. News Ticker
-export const NewsTicker: Story = {
-  render: () => (
-    <div className="w-full max-w-4xl">
-      <div className="flex items-center bg-red-600 px-4 py-2 text-sm font-medium text-white">
-        <span className="mr-3 rounded bg-white px-2 py-1 text-xs font-bold text-red-600">
-          LIVE
+/** Artist avatar card using design tokens */
+function ArtistCard({ initials, name }: { initials: string; name: string }) {
+  return (
+    <div className="border-fm-divider-secondary bg-fm-surface-secondary flex w-32 flex-col items-center gap-2 rounded-xl border p-3">
+      <div className="border-fm-divider-secondary bg-fm-surface-tertiary flex size-12 items-center justify-center rounded-full border">
+        <span className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+          {initials}
         </span>
-        <Marquee duration="25s" pauseOnHover>
-          <span className="whitespace-nowrap">
-            🔴 Breaking: New product launch scheduled for next month
-          </span>
-          <span className="whitespace-nowrap">
-            📈 Stock market reaches new highs as tech sector surges
-          </span>
-          <span className="whitespace-nowrap">
-            🚀 Space mission successfully launches with international crew
-          </span>
-          <span className="whitespace-nowrap">
-            💡 Revolutionary AI breakthrough announced by research team
-          </span>
-        </Marquee>
       </div>
+      <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm truncate text-center">
+        {name}
+      </p>
     </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story: "A news ticker with live updates and breaking news format.",
-      },
-    },
-  },
+  )
 }
 
-// 4. Testimonials
-export const Testimonials: Story = {
-  render: () => (
-    <div className="w-full max-w-5xl">
-      <h3 className="mb-6 text-center text-lg font-medium text-white">
-        What Our Customers Say
-      </h3>
-      <Marquee pauseOnHover duration="35s">
-        <div className="w-80 rounded-lg border border-white/10 bg-white/5 p-6 transition-colors hover:bg-white/10">
-          <div className="flex items-start space-x-4">
-            <div className="flex h-12 w-12 flex-shrink-0 items-center justify-center rounded-full bg-gradient-to-br from-blue-500 to-purple-600">
-              <span className="font-semibold text-white">JD</span>
-            </div>
-            <div className="space-y-2">
-              <p className="text-sm leading-relaxed text-white/80">
-                "This product has completely transformed our workflow. The
-                intuitive design and powerful features make it indispensable."
-              </p>
-              <div>
-                <div className="text-sm font-medium text-white">John Doe</div>
-                <div className="text-xs text-white/60">CEO, TechStart</div>
-              </div>
-            </div>
-          </div>
-        </div>
+// ─── 1. Playground ────────────────────────────────────────────────────────────
 
-        <div className="w-80 rounded-lg border border-white/10 bg-white/5 p-6 transition-colors hover:bg-white/10">
-          <div className="flex items-start space-x-4">
-            <div className="flex h-12 w-12 flex-shrink-0 items-center justify-center rounded-full bg-gradient-to-br from-green-500 to-teal-600">
-              <span className="font-semibold text-white">SS</span>
-            </div>
-            <div className="space-y-2">
-              <p className="text-sm leading-relaxed text-white/80">
-                "Outstanding customer support and a product that delivers on all
-                its promises. Highly recommended for any team."
-              </p>
-              <div>
-                <div className="text-sm font-medium text-white">
-                  Sarah Smith
-                </div>
-                <div className="text-xs text-white/60">
-                  Designer, CreativeHub
-                </div>
-              </div>
-            </div>
-          </div>
-        </div>
-
-        <div className="w-80 rounded-lg border border-white/10 bg-white/5 p-6 transition-colors hover:bg-white/10">
-          <div className="flex items-start space-x-4">
-            <div className="flex h-12 w-12 flex-shrink-0 items-center justify-center rounded-full bg-gradient-to-br from-orange-500 to-red-600">
-              <span className="font-semibold text-white">MJ</span>
-            </div>
-            <div className="space-y-2">
-              <p className="text-sm leading-relaxed text-white/80">
-                "The ROI has been incredible. We've seen a 300% increase in
-                productivity since implementation."
-              </p>
-              <div>
-                <div className="text-sm font-medium text-white">
-                  Mike Johnson
-                </div>
-                <div className="text-xs text-white/60">CTO, InnovateNow</div>
-              </div>
-            </div>
-          </div>
-        </div>
+export const Playground: Story = {
+  args: {
+    pauseOnHover: true,
+    reverse: false,
+    vertical: false,
+    repeat: 4,
+    gutter: "1rem",
+    duration: "35s",
+  },
+  render: (args) => (
+    <div className="w-full max-w-2xl space-y-4">
+      <Marquee {...args}>
+        <TokenChip label="Electronic" surface="secondary" />
+        <TokenChip label="Hip-Hop" surface="secondary" />
+        <TokenChip label="Jazz" surface="secondary" />
+        <TokenChip label="Ambient" surface="secondary" />
+        <TokenChip label="R&B" surface="secondary" />
+        <TokenChip label="Indie" surface="secondary" />
+        <TokenChip label="Soul" surface="secondary" />
       </Marquee>
+      <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+        <code className="text-fm-secondary text-fm-md leading-fm-md font-(--font-fm-mono)">{`<Marquee duration="${args.duration}" reverse={${args.reverse}} pauseOnHover={${args.pauseOnHover}} vertical={${args.vertical}} repeat={${args.repeat}} gutter="${args.gutter}" />`}</code>
+      </div>
     </div>
   ),
   parameters: {
     docs: {
       description: {
         story:
-          "Customer testimonials in card format with avatars and company information.",
+          "Controls-driven playground. Use the Storybook sidebar to adjust duration, direction, pause-on-hover, orientation, repeat count, and gutter spacing.",
       },
     },
   },
 }
 
-// 5. Icon Showcase
-export const IconShowcase: Story = {
+// ─── 2. Configurations ────────────────────────────────────────────────────────
+
+export const Configurations: Story = {
   render: () => (
     <div className="w-full max-w-4xl space-y-8">
-      <h3 className="text-center text-lg font-medium text-white">
-        Feature Icons
-      </h3>
-
-      {/* Horizontal Icons */}
-      <div className="space-y-4">
-        <h4 className="text-center text-sm font-medium text-white/70">
-          Horizontal Scroll
+      {/* Horizontal (default) */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Horizontal (default)
         </h4>
-        <Marquee pauseOnHover duration="20s">
-          <div className="flex w-24 flex-col items-center space-y-2">
-            <div className="flex h-16 w-16 items-center justify-center rounded-lg bg-blue-500/20">
-              <SearchIcon className="h-8 w-8 text-blue-400" />
-            </div>
-            <span className="text-xs text-white/70">Search</span>
-          </div>
-          <div className="flex w-24 flex-col items-center space-y-2">
-            <div className="flex h-16 w-16 items-center justify-center rounded-lg bg-green-500/20">
-              <TickCircleIcon className="h-8 w-8 text-green-400" />
-            </div>
-            <span className="text-xs text-white/70">Complete</span>
-          </div>
-          <div className="flex w-24 flex-col items-center space-y-2">
-            <div className="flex h-16 w-16 items-center justify-center rounded-lg bg-purple-500/20">
-              <EditBigIcon className="h-8 w-8 text-purple-400" />
-            </div>
-            <span className="text-xs text-white/70">Edit</span>
-          </div>
-          <div className="flex w-24 flex-col items-center space-y-2">
-            <div className="flex h-16 w-16 items-center justify-center rounded-lg bg-orange-500/20">
-              <FileChartIcon className="h-8 w-8 text-orange-400" />
-            </div>
-            <span className="text-xs text-white/70">Analytics</span>
-          </div>
-          <div className="flex w-24 flex-col items-center space-y-2">
-            <div className="flex h-16 w-16 items-center justify-center rounded-lg bg-red-500/20">
-              <AlertIcon className="h-8 w-8 text-red-400" />
-            </div>
-            <span className="text-xs text-white/70">Alert</span>
-          </div>
-          <div className="flex w-24 flex-col items-center space-y-2">
-            <div className="flex h-16 w-16 items-center justify-center rounded-lg bg-cyan-500/20">
-              <EyeOpenIcon className="h-8 w-8 text-cyan-400" />
-            </div>
-            <span className="text-xs text-white/70">View</span>
-          </div>
+        <Marquee duration="35s" pauseOnHover>
+          <TokenChip label="Electronic" surface="secondary" />
+          <TokenChip label="Hip-Hop" surface="secondary" />
+          <TokenChip label="Jazz" surface="secondary" />
+          <TokenChip label="Ambient" surface="secondary" />
+          <TokenChip label="R&B" surface="secondary" />
+          <TokenChip label="Indie" surface="secondary" />
         </Marquee>
+        <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+          Hover to pause
+        </p>
       </div>
 
-      {/* Reverse Direction */}
-      <div className="space-y-4">
-        <h4 className="text-center text-sm font-medium text-white/70">
+      {/* Reverse direction */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
           Reverse Direction
         </h4>
-        <Marquee reverse pauseOnHover duration="25s">
-          <div className="flex items-center space-x-3 rounded-lg border border-white/10 bg-white/5 px-4 py-2">
-            <PlusIcon className="h-5 w-5 text-green-400" />
-            <span className="text-sm text-white">Add New</span>
-          </div>
-          <div className="flex items-center space-x-3 rounded-lg border border-white/10 bg-white/5 px-4 py-2">
-            <TrashIcon className="h-5 w-5 text-red-400" />
-            <span className="text-sm text-white">Delete</span>
-          </div>
-          <div className="flex items-center space-x-3 rounded-lg border border-white/10 bg-white/5 px-4 py-2">
-            <EditBigIcon className="h-5 w-5 text-blue-400" />
-            <span className="text-sm text-white">Edit</span>
-          </div>
-          <div className="flex items-center space-x-3 rounded-lg border border-white/10 bg-white/5 px-4 py-2">
-            <EyeOpenIcon className="h-5 w-5 text-purple-400" />
-            <span className="text-sm text-white">Preview</span>
-          </div>
+        <Marquee duration="35s" reverse pauseOnHover>
+          <TokenChip label="Electronic" surface="info-sec" />
+          <TokenChip label="Hip-Hop" surface="info-sec" />
+          <TokenChip label="Jazz" surface="info-sec" />
+          <TokenChip label="Ambient" surface="info-sec" />
+          <TokenChip label="R&B" surface="info-sec" />
+          <TokenChip label="Indie" surface="info-sec" />
         </Marquee>
+        <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+          Scrolls right-to-left in reverse
+        </p>
       </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Icon showcase with feature icons and action buttons in normal and reverse directions.",
-      },
-    },
-  },
-}
 
-// 6. Vertical Marquee
-export const VerticalMarquee: Story = {
-  render: () => (
-    <div className="flex justify-center space-x-8">
-      {/* Social Media Feed */}
-      <div className="space-y-4">
-        <h4 className="text-center text-sm font-medium text-white/70">
-          Social Feed
+      {/* Pause on hover — compare */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          pauseOnHover: off vs. on
         </h4>
-        <div className="h-96 w-80">
-          <Marquee vertical pauseOnHover duration="30s" className="h-full">
-            <div className="rounded-lg border border-white/10 bg-white/5 p-4 transition-colors hover:bg-white/10">
-              <div className="flex items-start space-x-3">
-                <div className="flex h-10 w-10 items-center justify-center rounded-full bg-gradient-to-br from-blue-500 to-purple-600">
-                  <span className="text-sm font-semibold text-white">@A</span>
-                </div>
-                <div className="space-y-1">
-                  <div className="text-sm font-medium text-white">
-                    @alice_dev
-                  </div>
-                  <p className="text-sm text-white/70">
-                    Just shipped a new feature! The team's hard work really paid
-                    off. 🚀
-                  </p>
-                  <div className="text-xs text-white/50">2 minutes ago</div>
-                </div>
-              </div>
-            </div>
-
-            <div className="rounded-lg border border-white/10 bg-white/5 p-4 transition-colors hover:bg-white/10">
-              <div className="flex items-start space-x-3">
-                <div className="flex h-10 w-10 items-center justify-center rounded-full bg-gradient-to-br from-green-500 to-teal-600">
-                  <span className="text-sm font-semibold text-white">@B</span>
-                </div>
-                <div className="space-y-1">
-                  <div className="text-sm font-medium text-white">
-                    @bob_designer
-                  </div>
-                  <p className="text-sm text-white/70">
-                    Working on some exciting new designs. Can't wait to share
-                    them with everyone! ✨
-                  </p>
-                  <div className="text-xs text-white/50">5 minutes ago</div>
-                </div>
-              </div>
-            </div>
-
-            <div className="rounded-lg border border-white/10 bg-white/5 p-4 transition-colors hover:bg-white/10">
-              <div className="flex items-start space-x-3">
-                <div className="flex h-10 w-10 items-center justify-center rounded-full bg-gradient-to-br from-orange-500 to-red-600">
-                  <span className="text-sm font-semibold text-white">@C</span>
-                </div>
-                <div className="space-y-1">
-                  <div className="text-sm font-medium text-white">
-                    @charlie_pm
-                  </div>
-                  <p className="text-sm text-white/70">
-                    Great sprint review today! The team exceeded all
-                    expectations. 📊
-                  </p>
-                  <div className="text-xs text-white/50">8 minutes ago</div>
-                </div>
-              </div>
-            </div>
+        <div className="space-y-2">
+          <Marquee duration="25s" pauseOnHover={false}>
+            <TokenChip label="Always moving" surface="negative-sec" />
+            <TokenChip label="No pause" surface="negative-sec" />
+            <TokenChip label="Continuous" surface="negative-sec" />
+            <TokenChip label="Non-stop" surface="negative-sec" />
           </Marquee>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            pauseOnHover: false — never pauses
+          </p>
         </div>
-      </div>
-
-      {/* Notification Feed */}
-      <div className="space-y-4">
-        <h4 className="text-center text-sm font-medium text-white/70">
-          Notifications
-        </h4>
-        <div className="h-96 w-72">
-          <Marquee
-            vertical
-            reverse
-            pauseOnHover
-            duration="25s"
-            className="h-full"
-          >
-            <div className="flex items-center space-x-3 rounded-lg border border-blue-500/20 bg-blue-500/10 p-3">
-              <AlertIcon className="h-5 w-5 flex-shrink-0 text-blue-400" />
-              <div>
-                <div className="text-sm text-white">New message received</div>
-                <div className="text-xs text-white/60">From John Doe</div>
-              </div>
-            </div>
-
-            <div className="flex items-center space-x-3 rounded-lg border border-green-500/20 bg-green-500/10 p-3">
-              <TickCircleIcon className="h-5 w-5 flex-shrink-0 text-green-400" />
-              <div>
-                <div className="text-sm text-white">Task completed</div>
-                <div className="text-xs text-white/60">
-                  Design review finished
-                </div>
-              </div>
-            </div>
-
-            <div className="flex items-center space-x-3 rounded-lg border border-purple-500/20 bg-purple-500/10 p-3">
-              <FileChartIcon className="h-5 w-5 flex-shrink-0 text-purple-400" />
-              <div>
-                <div className="text-sm text-white">Report generated</div>
-                <div className="text-xs text-white/60">
-                  Monthly analytics ready
-                </div>
-              </div>
-            </div>
-
-            <div className="flex items-center space-x-3 rounded-lg border border-orange-500/20 bg-orange-500/10 p-3">
-              <EditBigIcon className="h-5 w-5 flex-shrink-0 text-orange-400" />
-              <div>
-                <div className="text-sm text-white">Document updated</div>
-                <div className="text-xs text-white/60">
-                  Project specs modified
-                </div>
-              </div>
-            </div>
+        <div className="space-y-2">
+          <Marquee duration="25s" pauseOnHover>
+            <TokenChip label="Hover me" surface="positive-sec" />
+            <TokenChip label="Pauses here" surface="positive-sec" />
+            <TokenChip label="Mouse over" surface="positive-sec" />
+            <TokenChip label="Try it" surface="positive-sec" />
           </Marquee>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            pauseOnHover: true — pauses on hover
+          </p>
         </div>
       </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Vertical marquees showing social media feeds and notifications with different directions.",
-      },
-    },
-  },
-}
-
-// 7. Speed Variations
-export const SpeedVariations: Story = {
-  render: () => (
-    <div className="w-full max-w-4xl space-y-8">
-      <h3 className="text-center text-lg font-medium text-white">
-        Speed Variations
-      </h3>
 
-      <div className="space-y-6">
-        {/* Slow */}
+      {/* Speed variations */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Speed Variations
+        </h4>
         <div className="space-y-2">
-          <h4 className="text-sm font-medium text-white/70">
-            Slow Speed (60s)
-          </h4>
           <Marquee duration="60s" pauseOnHover>
-            <div className="rounded-lg bg-blue-500/20 px-6 py-3 text-blue-300">
-              Slow marquee content
-            </div>
-            <div className="rounded-lg bg-green-500/20 px-6 py-3 text-green-300">
-              Takes 60 seconds
-            </div>
-            <div className="rounded-lg bg-purple-500/20 px-6 py-3 text-purple-300">
-              To complete cycle
-            </div>
-            <div className="rounded-lg bg-orange-500/20 px-6 py-3 text-orange-300">
-              Very relaxed pace
-            </div>
-          </Marquee>
-        </div>
-
-        {/* Normal */}
-        <div className="space-y-2">
-          <h4 className="text-sm font-medium text-white/70">
-            Normal Speed (40s - Default)
-          </h4>
-          <Marquee pauseOnHover>
-            <div className="rounded-lg bg-blue-500/20 px-6 py-3 text-blue-300">
-              Normal speed content
-            </div>
-            <div className="rounded-lg bg-green-500/20 px-6 py-3 text-green-300">
-              Standard 40 seconds
-            </div>
-            <div className="rounded-lg bg-purple-500/20 px-6 py-3 text-purple-300">
-              Balanced timing
-            </div>
-            <div className="rounded-lg bg-orange-500/20 px-6 py-3 text-orange-300">
-              Good for most cases
-            </div>
+            <TokenChip label="Slow — 60s" surface="secondary" />
+            <TokenChip label="Relaxed pace" surface="secondary" />
+            <TokenChip label="Ambient feel" surface="secondary" />
+            <TokenChip label="Low energy" surface="secondary" />
           </Marquee>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            60s — slow
+          </p>
         </div>
-
-        {/* Fast */}
         <div className="space-y-2">
-          <h4 className="text-sm font-medium text-white/70">
-            Fast Speed (20s)
-          </h4>
-          <Marquee duration="20s" pauseOnHover>
-            <div className="rounded-lg bg-blue-500/20 px-6 py-3 text-blue-300">
-              Fast moving content
-            </div>
-            <div className="rounded-lg bg-green-500/20 px-6 py-3 text-green-300">
-              Only 20 seconds
-            </div>
-            <div className="rounded-lg bg-purple-500/20 px-6 py-3 text-purple-300">
-              Quick cycling
-            </div>
-            <div className="rounded-lg bg-orange-500/20 px-6 py-3 text-orange-300">
-              High energy
-            </div>
+          <Marquee duration="30s" pauseOnHover>
+            <TokenChip label="Normal — 30s" surface="secondary" />
+            <TokenChip label="Default feel" surface="secondary" />
+            <TokenChip label="Balanced" surface="secondary" />
+            <TokenChip label="Versatile" surface="secondary" />
           </Marquee>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            30s — normal
+          </p>
         </div>
-
-        {/* Very Fast */}
         <div className="space-y-2">
-          <h4 className="text-sm font-medium text-white/70">
-            Very Fast Speed (10s)
-          </h4>
-          <Marquee duration="10s" pauseOnHover>
-            <div className="rounded-lg bg-blue-500/20 px-6 py-3 text-blue-300">
-              Lightning fast
-            </div>
-            <div className="rounded-lg bg-green-500/20 px-6 py-3 text-green-300">
-              Just 10 seconds
-            </div>
-            <div className="rounded-lg bg-purple-500/20 px-6 py-3 text-purple-300">
-              Rapid movement
-            </div>
-            <div className="rounded-lg bg-orange-500/20 px-6 py-3 text-orange-300">
-              Dynamic feel
-            </div>
+          <Marquee duration="12s" pauseOnHover>
+            <TokenChip label="Fast — 12s" surface="warning-sec" />
+            <TokenChip label="High energy" surface="warning-sec" />
+            <TokenChip label="Urgent" surface="warning-sec" />
+            <TokenChip label="Dynamic" surface="warning-sec" />
           </Marquee>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            12s — fast
+          </p>
         </div>
       </div>
 
-      <div className="text-center text-xs text-white/60">
-        <p>
-          All examples have pauseOnHover enabled - hover to pause any marquee
+      {/* Vertical */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Vertical Orientation
+        </h4>
+        <div className="flex justify-center">
+          <div className="h-48 w-56 overflow-hidden">
+            <Marquee vertical duration="18s" pauseOnHover className="h-full">
+              <div className="border-fm-divider-secondary bg-fm-surface-secondary my-1 flex items-center gap-2 rounded-lg border px-3 py-2">
+                <MusicalNoteIcon className="text-fm-secondary h-4 w-4 shrink-0" />
+                <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                  Bicep — Glue
+                </span>
+              </div>
+              <div className="border-fm-divider-secondary bg-fm-surface-secondary my-1 flex items-center gap-2 rounded-lg border px-3 py-2">
+                <MusicalNoteIcon className="text-fm-secondary h-4 w-4 shrink-0" />
+                <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                  Four Tet — Baby
+                </span>
+              </div>
+              <div className="border-fm-divider-secondary bg-fm-surface-secondary my-1 flex items-center gap-2 rounded-lg border px-3 py-2">
+                <MusicalNoteIcon className="text-fm-secondary h-4 w-4 shrink-0" />
+                <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                  Floating Points
+                </span>
+              </div>
+              <div className="border-fm-divider-secondary bg-fm-surface-secondary my-1 flex items-center gap-2 rounded-lg border px-3 py-2">
+                <MusicalNoteIcon className="text-fm-secondary h-4 w-4 shrink-0" />
+                <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                  Jon Hopkins
+                </span>
+              </div>
+            </Marquee>
+          </div>
+        </div>
+        <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm text-center">
+          vertical: true — scrolls top to bottom
         </p>
       </div>
     </div>
@@ -691,128 +310,171 @@ export const SpeedVariations: Story = {
     docs: {
       description: {
         story:
-          "Different animation speeds from very slow (60s) to very fast (10s) showing the flexibility of the marquee component.",
+          "Comparison of all main configuration axes: horizontal vs. vertical orientation, normal vs. reverse direction, pauseOnHover toggle, and speed variations from 12s (fast) to 60s (slow).",
       },
     },
   },
 }
 
-// 8. Interactive Controls
-export const InteractiveControls: Story = {
-  render: () => {
-    const [speed, setSpeed] = React.useState(40)
-    const [isPaused, setIsPaused] = React.useState(false)
-    const [isReverse, setIsReverse] = React.useState(false)
-    const [isVertical, setIsVertical] = React.useState(false)
+// ─── 2. UseCases ──────────────────────────────────────────────────────────────
 
-    return (
-      <div className="w-full max-w-4xl space-y-6">
-        <h3 className="text-center text-lg font-medium text-white">
-          Interactive Controls
-        </h3>
-
-        {/* Controls */}
-        <div className="rounded-lg border border-white/10 bg-white/5 p-4">
-          <div className="grid grid-cols-2 gap-4 lg:grid-cols-4">
-            <div className="space-y-2">
-              <label className="text-sm text-white/70">Speed (seconds)</label>
-              <input
-                type="range"
-                min="5"
-                max="60"
-                value={speed}
-                onChange={(e) => setSpeed(Number(e.target.value))}
-                className="w-full"
-              />
-              <div className="text-center text-xs text-white/60">{speed}s</div>
-            </div>
-
-            <div className="space-y-2">
-              <label className="text-sm text-white/70">Direction</label>
-              <button
-                onClick={() => setIsReverse(!isReverse)}
-                className={`w-full rounded px-3 py-2 text-sm transition-colors ${
-                  isReverse
-                    ? "bg-blue-500 text-white"
-                    : "bg-white/10 text-white/70 hover:bg-white/20"
-                }`}
-              >
-                {isReverse ? "Reverse" : "Normal"}
-              </button>
-            </div>
-
-            <div className="space-y-2">
-              <label className="text-sm text-white/70">Orientation</label>
-              <button
-                onClick={() => setIsVertical(!isVertical)}
-                className={`w-full rounded px-3 py-2 text-sm transition-colors ${
-                  isVertical
-                    ? "bg-green-500 text-white"
-                    : "bg-white/10 text-white/70 hover:bg-white/20"
-                }`}
-              >
-                {isVertical ? "Vertical" : "Horizontal"}
-              </button>
-            </div>
+export const UseCases: Story = {
+  render: () => (
+    <div className="mx-auto max-w-3xl space-y-8 p-8">
+      {/* Artist avatar / label carousel */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Artist Carousel
+        </h4>
+        <Marquee duration="40s" pauseOnHover gutter="1rem">
+          <ArtistCard initials="BC" name="Bicep" />
+          <ArtistCard initials="FT" name="Four Tet" />
+          <ArtistCard initials="FP" name="Floating Pts" />
+          <ArtistCard initials="JH" name="Jon Hopkins" />
+          <ArtistCard initials="RP" name="Röyksopp" />
+          <ArtistCard initials="AP" name="Aphex Twin" />
+          <ArtistCard initials="BB" name="Bonobo" />
+          <ArtistCard initials="OV" name="Overmono" />
+        </Marquee>
+      </div>
 
-            <div className="space-y-2">
-              <label className="text-sm text-white/70">Animation</label>
-              <button
-                onClick={() => setIsPaused(!isPaused)}
-                className={`w-full rounded px-3 py-2 text-sm transition-colors ${
-                  isPaused
-                    ? "bg-red-500 text-white"
-                    : "bg-white/10 text-white/70 hover:bg-white/20"
-                }`}
-              >
-                {isPaused ? "Paused" : "Playing"}
-              </button>
-            </div>
+      {/* News ticker / announcement strip */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Announcements Ticker
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center gap-3 overflow-hidden rounded-lg border px-4 py-2">
+          <div className="bg-fm-surface-negative-sec text-fm-primary text-fm-xs leading-fm-xs shrink-0 rounded px-2 py-0.5 font-semibold tracking-widest uppercase">
+            Live
           </div>
+          <Marquee duration="28s" pauseOnHover className="flex-1">
+            <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm px-6 whitespace-nowrap">
+              Bicep announce headline set at Primavera Sound 2026
+            </span>
+            <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm px-6 whitespace-nowrap">
+              ·
+            </span>
+            <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm px-6 whitespace-nowrap">
+              Four Tet drops surprise EP on Bandcamp — download now
+            </span>
+            <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm px-6 whitespace-nowrap">
+              ·
+            </span>
+            <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm px-6 whitespace-nowrap">
+              PocketFM 3.0 launch: redesigned player and social listening
+            </span>
+            <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm px-6 whitespace-nowrap">
+              ·
+            </span>
+            <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm px-6 whitespace-nowrap">
+              New editorial playlists updated every Friday
+            </span>
+          </Marquee>
         </div>
+      </div>
 
-        {/* Live Marquee */}
-        <div className={`${isVertical ? "h-64" : ""}`}>
-          <Marquee
-            vertical={isVertical}
-            reverse={isReverse}
-            pauseOnHover
-            duration={`${speed}s`}
-            className={`${isPaused ? "[animation-play-state:paused]" : ""} ${isVertical ? "h-full" : ""}`}
-          >
-            <div className="flex min-w-[120px] flex-col items-center space-y-2 rounded-lg bg-blue-500/20 p-4 text-blue-300">
-              <AlertIcon className="h-8 w-8" />
-              <span className="text-sm font-medium">Alert</span>
-            </div>
-            <div className="flex min-w-[120px] flex-col items-center space-y-2 rounded-lg bg-green-500/20 p-4 text-green-300">
-              <TickCircleIcon className="h-8 w-8" />
-              <span className="text-sm font-medium">Success</span>
-            </div>
-            <div className="flex min-w-[120px] flex-col items-center space-y-2 rounded-lg bg-purple-500/20 p-4 text-purple-300">
-              <EditBigIcon className="h-8 w-8" />
-              <span className="text-sm font-medium">Edit</span>
-            </div>
-            <div className="flex min-w-[120px] flex-col items-center space-y-2 rounded-lg bg-orange-500/20 p-4 text-orange-300">
-              <SearchIcon className="h-8 w-8" />
-              <span className="text-sm font-medium">Search</span>
-            </div>
+      {/* Song queue strip */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Now Playing Queue Strip
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-xl border p-4">
+          <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mb-3 tracking-widest uppercase">
+            Up next
+          </p>
+          <Marquee duration="50s" pauseOnHover gutter="0.75rem">
+            {[
+              { track: "Glue", artist: "Bicep", active: true },
+              { track: "Baby", artist: "Four Tet", active: false },
+              { track: "Nacht 001-iv", artist: "Floating Pts", active: false },
+              { track: "Emerald Rush", artist: "Jon Hopkins", active: false },
+              { track: "Fridge Hum", artist: "Bonobo", active: false },
+              { track: "Kerning", artist: "Overmono", active: false },
+              { track: "Monument", artist: "Röyksopp", active: false },
+              { track: "Alberto Balsam", artist: "Aphex Twin", active: false },
+            ].map((item) => (
+              <div
+                key={item.track}
+                className={[
+                  "flex shrink-0 flex-col gap-0.5 rounded-lg border px-3 py-2 transition-colors",
+                  item.active
+                    ? "border-fm-divider-brand-secondary bg-fm-surface-secondary"
+                    : "border-fm-divider-secondary bg-fm-surface-secondary",
+                ].join(" ")}
+              >
+                <div className="flex items-center gap-2">
+                  {item.active && (
+                    <TickCircleIcon className="text-fm-positive h-3 w-3 shrink-0" />
+                  )}
+                  <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium whitespace-nowrap">
+                    {item.track}
+                  </p>
+                </div>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm whitespace-nowrap">
+                  {item.artist}
+                </p>
+              </div>
+            ))}
           </Marquee>
         </div>
+      </div>
 
-        <div className="text-center text-xs text-white/60">
-          <p>
-            Adjust the controls above to see real-time changes to the marquee
-            behavior
-          </p>
+      {/* Dual-row reverse for status badges */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Genre Tag Cloud (dual-row)
+        </h4>
+        <div className="space-y-2 overflow-hidden">
+          <Marquee duration="45s" pauseOnHover>
+            {[
+              "Techno",
+              "House",
+              "Drum & Bass",
+              "Jungle",
+              "UK Garage",
+              "Deep House",
+              "Trance",
+              "Breaks",
+              "Electro",
+            ].map((g) => (
+              <TokenChip key={g} label={g} surface="secondary" />
+            ))}
+          </Marquee>
+          <Marquee duration="38s" reverse pauseOnHover>
+            {[
+              "Neo-Soul",
+              "Lo-Fi",
+              "Jazz Fusion",
+              "Afrobeat",
+              "Latin",
+              "Bossa Nova",
+              "Downtempo",
+              "Trip-Hop",
+              "Chillout",
+            ].map((g) => (
+              <TokenChip key={g} label={g} surface="info-sec" />
+            ))}
+          </Marquee>
         </div>
       </div>
-    )
-  },
+
+      {/* Info box */}
+      <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">
+          All marquee examples above use only design system tokens for color,
+          spacing, and typography — no hardcoded values. Reduced-motion users
+          will see a paused state automatically, as the component respects
+          <code className="text-fm-primary mx-1">prefers-reduced-motion</code>.
+        </p>
+      </div>
+    </div>
+  ),
   parameters: {
+    layout: "fullscreen",
     docs: {
       description: {
         story:
-          "Interactive controls allowing real-time adjustment of marquee properties including speed, direction, orientation, and play state.",
+          "Real product-shaped examples: an artist avatar carousel, a live announcements ticker, a now-playing queue strip, and a dual-row genre tag cloud. All using design system tokens.",
       },
     },
   },