aural-ui 4.0.1 → 4.1.0

package/dist/components/stepper/Stepper.stories.tsx

@@ -1,6 +1,8 @@
 import * as React from "react"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import { Stepper } from "."
 
 const meta: Meta<typeof Stepper> = {
@@ -8,52 +10,63 @@ const meta: Meta<typeof Stepper> = {
   component: Stepper,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
         component:
-          "A flexible stepper component that guides users through a multi-step process. Supports both automatic step generation and custom composition patterns with clickable navigation.",
+          "A multi-step progress indicator that guides users through sequential flows. Supports four color variants, horizontal and vertical orientations, three sizes, step labels, and clickable navigation with optional keyboard support.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "4 Color Variants",
+              description: "Primary to warning",
+            },
+            {
+              title: "H & V Orientations",
+              description: "Horizontal or vertical",
+            },
+            {
+              title: "Clickable Steps",
+              description: "onStepClick navigation",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
   argTypes: {
     steps: {
       control: { type: "number", min: 1, max: 10 },
-      description: "Number of steps to generate automatically",
+      description: "Number of steps to render automatically",
     },
     activeStep: {
       control: { type: "number", min: 0, max: 9 },
-      description: "Currently active step (0-indexed)",
+      description: "Currently active step index (0-based)",
     },
     variant: {
       control: { type: "select" },
       options: ["primary", "positive", "negative", "warning"],
-      description: "Visual variant of the stepper",
+      description: "Color variant applied to active and completed steps",
     },
     orientation: {
       control: { type: "select" },
       options: ["horizontal", "vertical"],
-      description: "Layout orientation",
+      description: "Layout orientation of the step list",
     },
     size: {
       control: { type: "select" },
       options: ["sm", "md", "lg"],
-      description: "Size of the step indicators",
+      description: "Size of the step indicator circles",
     },
     stepLabels: {
       control: { type: "object" },
-      description: "Array of labels for each step",
+      description: "Array of label strings for each step",
     },
     onStepClick: {
       action: "stepClicked",
-      description: "Callback function when a step is clicked",
+      description: "Callback fired when a clickable step is selected",
     },
   },
 }
@@ -61,586 +74,430 @@ const meta: Meta<typeof Stepper> = {
 export default meta
 type Story = StoryObj<typeof Stepper>
 
-// Basic Examples
-export const Default: Story = {
-  args: {
-    steps: 4,
-    activeStep: 1,
-    variant: "primary",
-    orientation: "horizontal",
-    size: "md",
-    className: "text-fm-primary w-[600px]",
-    stepLabels: ["Step 1", "Step 2", "Step 3", "Step 4"],
-  },
-}
+// ─── 1. Playground ────────────────────────────────────────────────────────────
 
-export const WithLabels: Story = {
+export const Playground: Story = {
   args: {
     steps: 4,
     activeStep: 1,
     variant: "primary",
     orientation: "horizontal",
     size: "md",
-    className: "text-fm-primary w-[600px]",
-    stepLabels: ["Account", "Profile", "Payment", "Confirmation"],
-  },
-}
-
-export const Completed: Story = {
-  args: {
-    steps: 4,
-    activeStep: 4,
-    variant: "primary",
-    orientation: "horizontal",
-    size: "md",
-    className: "text-fm-primary w-[600px]",
-    stepLabels: ["Account", "Profile", "Payment", "Confirmation"],
-  },
-}
-
-// Clickable Examples
-export const ClickableBasic: Story = {
-  render: () => {
-    const [activeStep, setActiveStep] = React.useState(1)
-
-    return (
-      <div className="space-y-4">
-        <div className="text-fm-primary text-sm">
-          Click on any step to navigate. Current step: {activeStep + 1}
-        </div>
-        <Stepper
-          steps={4}
-          activeStep={activeStep}
-          variant="primary"
-          className="text-fm-primary w-[600px]"
-          stepLabels={["Account", "Profile", "Payment", "Confirmation"]}
-          onStepClick={(stepIndex) => setActiveStep(stepIndex)}
-        />
+    stepLabels: ["Account", "Profile", "Payment", "Confirm"],
+  },
+  render: (args) => (
+    <div className="w-full max-w-xl space-y-4">
+      <Stepper {...args} className="text-fm-primary w-full" />
+      <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"
+          style={{ fontFamily: "var(--font-fm-mono)" }}
+        >
+          {`<Stepper steps={${args.steps}} activeStep={${args.activeStep}} variant="${args.variant}" size="${args.size}" orientation="${args.orientation}" />`}
+        </code>
       </div>
-    )
-  },
+    </div>
+  ),
   parameters: {
     docs: {
       description: {
         story:
-          "Stepper with clickable steps. Users can click on any step to navigate directly.",
+          "Use the controls panel to explore steps count, active step index, variant, size, and orientation.",
       },
     },
   },
 }
 
-export const ClickableWithRestrictions: Story = {
-  render: () => {
-    const [activeStep, setActiveStep] = React.useState(0)
+// ─── 2. All Variants ──────────────────────────────────────────────────────────
 
-    const handleStepClick = (stepIndex: number) => {
-      // Only allow navigation to completed steps or the next step
-      if (stepIndex <= activeStep + 1) {
-        setActiveStep(stepIndex)
-      }
-    }
-
-    return (
-      <div className="space-y-4">
-        <div className="text-fm-primary text-sm">
-          Click on completed steps or the next step to navigate. Current step:{" "}
-          {activeStep + 1}
-        </div>
-        <Stepper
-          steps={5}
-          activeStep={activeStep}
-          variant="primary"
-          className="text-fm-primary w-[700px]"
-          stepLabels={["Start", "Info", "Review", "Payment", "Complete"]}
-          onStepClick={handleStepClick}
-        />
-        <div className="flex gap-2">
-          <button
-            onClick={() => setActiveStep(Math.max(0, activeStep - 1))}
-            disabled={activeStep === 0}
-            className="bg-fm-surface-tertiary text-fm-primary rounded px-3 py-1 text-sm disabled:opacity-50"
-          >
-            Previous
-          </button>
-          <button
-            onClick={() => setActiveStep(Math.min(4, activeStep + 1))}
-            disabled={activeStep === 4}
-            className="bg-fm-surface-info text-fm-surface-primary rounded px-3 py-1 text-sm disabled:opacity-50"
-          >
-            Next
-          </button>
+export const AllVariants: Story = {
+  render: () => (
+    <div className="space-y-8">
+      {(
+        [
+          {
+            variant: "primary",
+            label: "Primary",
+            labels: ["Account", "Profile", "Payment", "Confirm"],
+          },
+          {
+            variant: "positive",
+            label: "Positive",
+            labels: ["Setup", "Configure", "Test", "Deploy"],
+          },
+          {
+            variant: "negative",
+            label: "Negative",
+            labels: ["Report", "Review", "Resolve", "Close"],
+          },
+          {
+            variant: "warning",
+            label: "Warning",
+            labels: ["Draft", "Validate", "Approve", "Publish"],
+          },
+        ] as const
+      ).map(({ variant, label, labels }) => (
+        <div key={variant} className="space-y-3">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium capitalize">
+            {label}
+          </h4>
+          <div className="space-y-2 text-center">
+            <Stepper
+              steps={4}
+              activeStep={2}
+              variant={variant}
+              stepLabels={[...labels]}
+              className="text-fm-primary w-150"
+            />
+          </div>
         </div>
-      </div>
-    )
-  },
+      ))}
+    </div>
+  ),
   parameters: {
+    layout: "padded",
     docs: {
       description: {
         story:
-          "Stepper with navigation restrictions. Users can only click on completed steps or the immediate next step.",
+          "All four variants (primary, positive, negative, warning) shown with step labels at active step 3 — displaying completed, active, and inactive states simultaneously.",
       },
     },
   },
 }
 
-export const ClickableVertical: Story = {
-  render: () => {
-    const [activeStep, setActiveStep] = React.useState(1)
+// ─── 2. Sizes ─────────────────────────────────────────────────────────────────
 
-    return (
-      <div className="flex gap-8">
-        <div className="space-y-4">
-          <div className="text-fm-primary text-sm">
-            Vertical clickable stepper
-          </div>
+export const Sizes: Story = {
+  render: () => (
+    <div className="space-y-8">
+      <div className="flex flex-wrap items-end justify-center gap-8">
+        <div className="space-y-3 text-center">
           <Stepper
-            steps={4}
-            activeStep={activeStep}
-            variant="positive"
-            orientation="vertical"
-            className="text-fm-primary h-[400px]"
-            stepLabels={["Setup", "Configure", "Test", "Deploy"]}
-            onStepClick={(stepIndex) => setActiveStep(stepIndex)}
+            steps={3}
+            activeStep={1}
+            variant="primary"
+            size="sm"
+            stepLabels={["Start", "Middle", "End"]}
+            className="text-fm-primary w-80"
           />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Small (sm)
+          </p>
         </div>
-        <div className="bg-fm-surface-secondary min-w-[300px] rounded-lg p-4">
-          <h3 className="text-fm-primary mb-2 font-semibold">Step Content</h3>
-          <p className="text-fm-secondary text-sm">
-            Content for step:{" "}
-            {["Setup", "Configure", "Test", "Deploy"][activeStep] ||
-              "Completed"}
+        <div className="space-y-3 text-center">
+          <Stepper
+            steps={3}
+            activeStep={1}
+            variant="primary"
+            size="md"
+            stepLabels={["Start", "Middle", "End"]}
+            className="text-fm-primary w-80"
+          />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Medium (md) — default
+          </p>
+        </div>
+        <div className="space-y-3 text-center">
+          <Stepper
+            steps={3}
+            activeStep={1}
+            variant="primary"
+            size="lg"
+            stepLabels={["Start", "Middle", "End"]}
+            className="text-fm-primary w-80"
+          />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Large (lg)
           </p>
         </div>
       </div>
-    )
-  },
-  parameters: {
-    layout: "padded",
-    docs: {
-      description: {
-        story: "Vertical orientation stepper with clickable navigation.",
-      },
-    },
-  },
-}
 
-export const ClickableCompound: Story = {
-  render: () => {
-    const [activeStep, setActiveStep] = React.useState(0)
-    const steps = ["Personal", "Address", "Payment", "Review"]
-
-    return (
-      <div className="space-y-6">
-        <Stepper
-          variant="primary"
-          activeStep={activeStep}
-          onStepClick={(stepIndex) => setActiveStep(stepIndex)}
-        >
-          {steps.map((step, index) => (
-            <Stepper.Step
-              key={index}
-              index={index}
-              label={step}
-              isLast={index === steps.length - 1}
-            />
-          ))}
-
-          <Stepper.Content>
-            <div className="bg-fm-surface-secondary min-h-[200px] rounded-lg p-6">
-              <h3 className="mb-4 text-lg font-semibold">
-                {steps[activeStep]} Information
-              </h3>
-              <p className="text-fm-secondary mb-6">
-                Please fill out your {steps[activeStep].toLowerCase()}{" "}
-                information below.
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Size × Variant
+        </h4>
+        <div className="flex flex-wrap items-center gap-8">
+          {(["sm", "md", "lg"] as const).map((size) => (
+            <div key={size} className="space-y-3 text-center">
+              <Stepper
+                steps={4}
+                activeStep={2}
+                variant="positive"
+                size={size}
+                className="text-fm-primary w-72"
+              />
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                positive · {size}
               </p>
-
-              <div className="flex gap-4">
-                <button
-                  onClick={() => setActiveStep(Math.max(0, activeStep - 1))}
-                  disabled={activeStep === 0}
-                  className="bg-fm-surface-tertiary text-fm-primary rounded px-4 py-2 disabled:opacity-50"
-                >
-                  Previous
-                </button>
-                <button
-                  onClick={() =>
-                    setActiveStep(Math.min(steps.length - 1, activeStep + 1))
-                  }
-                  disabled={activeStep === steps.length - 1}
-                  className="bg-fm-surface-info text-fm-surface-primary rounded px-4 py-2 disabled:opacity-50"
-                >
-                  {activeStep === steps.length - 1 ? "Complete" : "Next"}
-                </button>
-              </div>
             </div>
-          </Stepper.Content>
-        </Stepper>
+          ))}
+        </div>
       </div>
-    )
-  },
+    </div>
+  ),
   parameters: {
     layout: "padded",
     docs: {
       description: {
         story:
-          "Compound component pattern with clickable steps and integrated content area.",
+          "Three indicator sizes (sm, md, lg) compared side by side with labels, plus a size × variant cross-axis row.",
       },
     },
   },
 }
 
-export const ClickableAllVariants: Story = {
-  render: () => {
-    const [activeSteps, setActiveSteps] = React.useState({
-      primary: 1,
-      positive: 2,
-      negative: 0,
-      warning: 3,
-    })
+// ─── 3. Configurations ────────────────────────────────────────────────────────
+
+export const Configurations: Story = {
+  render: () => (
+    <div className="space-y-10">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Horizontal Orientation
+        </h4>
+        <div className="space-y-3 text-center">
+          <Stepper
+            steps={4}
+            activeStep={2}
+            variant="primary"
+            orientation="horizontal"
+            stepLabels={["Account", "Profile", "Payment", "Confirm"]}
+            className="text-fm-primary w-150"
+          />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            horizontal (default)
+          </p>
+        </div>
+      </div>
 
-    const handleStepClick = (
-      variant: keyof typeof activeSteps,
-      stepIndex: number
-    ) => {
-      setActiveSteps((prev) => ({
-        ...prev,
-        [variant]: stepIndex,
-      }))
-    }
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Vertical Orientation
+        </h4>
+        <div className="flex flex-wrap gap-10">
+          <div className="space-y-3 text-center">
+            <Stepper
+              steps={4}
+              activeStep={2}
+              variant="primary"
+              orientation="vertical"
+              stepLabels={["Account", "Profile", "Payment", "Confirm"]}
+              className="text-fm-primary h-48"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              primary · vertical
+            </p>
+          </div>
+          <div className="space-y-3 text-center">
+            <Stepper
+              steps={4}
+              activeStep={1}
+              variant="positive"
+              orientation="vertical"
+              stepLabels={["Setup", "Configure", "Test", "Deploy"]}
+              className="text-fm-primary h-48"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              positive · vertical
+            </p>
+          </div>
+          <div className="space-y-3 text-center">
+            <Stepper
+              steps={4}
+              activeStep={3}
+              variant="warning"
+              orientation="vertical"
+              stepLabels={["Draft", "Review", "Approve", "Publish"]}
+              className="text-fm-primary h-48"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              warning · vertical
+            </p>
+          </div>
+        </div>
+      </div>
 
-    return (
-      <div className="text-fm-primary space-y-8">
-        {(["primary", "positive", "negative", "warning"] as const).map(
-          (variant) => (
-            <div key={variant} className="space-y-2">
-              <h4 className="text-sm font-medium capitalize">
-                {variant} - Active Step: {activeSteps[variant] + 1}
-              </h4>
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Progress States
+        </h4>
+        <div className="space-y-4">
+          {[
+            { active: 0, label: "Step 1 active (all inactive)" },
+            { active: 1, label: "Step 2 active (1 completed)" },
+            { active: 3, label: "Step 4 active (3 completed)" },
+            { active: 4, label: "All completed" },
+          ].map(({ active, label }) => (
+            <div key={active} className="space-y-2">
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                {label}
+              </p>
               <Stepper
                 steps={4}
-                activeStep={activeSteps[variant]}
-                variant={variant}
-                stepLabels={["Step 1", "Step 2", "Step 3", "Step 4"]}
-                onStepClick={(stepIndex) => handleStepClick(variant, stepIndex)}
+                activeStep={active}
+                variant="primary"
+                stepLabels={["Start", "Build", "Test", "Ship"]}
+                className="text-fm-primary w-125"
               />
             </div>
-          )
-        )}
-      </div>
-    )
-  },
-  parameters: {
-    layout: "padded",
-    docs: {
-      description: {
-        story:
-          "All variants with clickable functionality to demonstrate different visual styles.",
-      },
-    },
-  },
-}
-
-export const ClickableWithKeyboard: Story = {
-  render: () => {
-    const [activeStep, setActiveStep] = React.useState(1)
-
-    return (
-      <div className="space-y-4">
-        <div className="bg-fm-surface-warning-sec text-fm-warning rounded-lg p-4 text-sm">
-          <strong>Keyboard Navigation:</strong>
-          <ul className="mt-2 space-y-1">
-            <li>• Use Tab to focus on clickable steps</li>
-            <li>• Press Enter or Space to navigate to a step</li>
-            <li>• Use mouse click for direct navigation</li>
-          </ul>
-        </div>
-        <Stepper
-          steps={5}
-          activeStep={activeStep}
-          variant="primary"
-          className="text-fm-primary w-[700px]"
-          stepLabels={["Start", "Personal", "Details", "Review", "Finish"]}
-          onStepClick={(stepIndex) => setActiveStep(stepIndex)}
-          aria-label="Registration process stepper"
-        />
-        <div className="text-fm-primary text-sm">
-          Current step: {activeStep + 1} of 5
+          ))}
         </div>
       </div>
-    )
-  },
+    </div>
+  ),
   parameters: {
+    layout: "padded",
     docs: {
       description: {
         story:
-          "Demonstrates keyboard accessibility features for clickable steps. Focus management and ARIA labels provide screen reader support.",
+          "Horizontal vs vertical orientation comparison, plus a full sweep of progress states from step 1 through all-completed.",
       },
     },
   },
 }
 
-// Variant Examples
-export const PrimaryVariant: Story = {
-  args: {
-    steps: 4,
-    activeStep: 2,
-    variant: "primary",
-    className: "text-fm-primary w-[600px]",
-    stepLabels: ["Step 1", "Step 2", "Step 3", "Step 4"],
-  },
-}
+// ─── 4. Interactive ───────────────────────────────────────────────────────────
 
-export const PositiveVariant: Story = {
-  args: {
-    steps: 4,
-    activeStep: 2,
-    variant: "positive",
-    className: "text-fm-primary w-[600px]",
-    stepLabels: ["Step 1", "Step 2", "Step 3", "Step 4"],
-  },
-}
-
-export const NegativeVariant: Story = {
-  args: {
-    steps: 4,
-    activeStep: 2,
-    variant: "negative",
-    className: "text-fm-primary w-[600px]",
-    stepLabels: ["Step 1", "Step 2", "Step 3", "Step 4"],
-  },
-}
-
-export const WarningVariant: Story = {
-  args: {
-    steps: 4,
-    activeStep: 2,
-    variant: "warning",
-    className: "text-fm-primary w-[600px]",
-    stepLabels: ["Step 1", "Step 2", "Step 3", "Step 4"],
-  },
-}
-
-// Size Examples
-export const SmallSize: Story = {
-  args: {
-    steps: 4,
-    activeStep: 2,
-    variant: "primary",
-    className: "text-fm-primary w-[600px]",
-    size: "sm",
-    stepLabels: ["Step 1", "Step 2", "Step 3", "Step 4"],
-  },
-}
-
-export const MediumSize: Story = {
-  args: {
-    steps: 4,
-    activeStep: 2,
-    variant: "primary",
-    size: "md",
-    className: "text-fm-primary w-[600px]",
-    stepLabels: ["Step 1", "Step 2", "Step 3", "Step 4"],
-  },
-}
-
-export const LargeSize: Story = {
-  args: {
-    steps: 4,
-    activeStep: 2,
-    variant: "primary",
-    size: "lg",
-    className: "text-fm-primary w-[600px]",
-    stepLabels: ["Step 1", "Step 2", "Step 3", "Step 4"],
-  },
-}
-
-// Orientation Examples
-export const HorizontalOrientation: Story = {
-  args: {
-    steps: 4,
-    activeStep: 2,
-    variant: "primary",
-    orientation: "horizontal",
-    className: "text-fm-primary w-[600px]",
-    stepLabels: ["Step 1", "Step 2", "Step 3", "Step 4"],
-  },
-}
-
-export const VerticalOrientation: Story = {
-  args: {
-    steps: 4,
-    activeStep: 2,
-    variant: "primary",
-    orientation: "vertical",
-    stepLabels: ["Step 1", "Step 2", "Step 3", "Step 4"],
-    className: "text-fm-primary h-[400px]",
-  },
-  parameters: {
-    layout: "padded",
-  },
-}
-
-// Interactive Example
 export const Interactive: Story = {
   render: () => {
-    const [activeStep, setActiveStep] = React.useState(0)
     const steps = [
-      "Account Setup",
-      "Personal Info",
-      "Preferences",
-      "Review",
-      "Complete",
+      {
+        label: "Account Setup",
+        description:
+          "Create your account credentials and verify your email address.",
+      },
+      {
+        label: "Profile Info",
+        description:
+          "Add your display name, bio, and profile photo to personalise your experience.",
+      },
+      {
+        label: "Preferences",
+        description:
+          "Choose your music genres, languages, and notification settings.",
+      },
+      {
+        label: "Review",
+        description:
+          "Confirm all your details before we activate your account.",
+      },
+      {
+        label: "Complete",
+        description:
+          "Your account is ready. Start discovering music tailored to you.",
+      },
     ]
 
+    const [activeStep, setActiveStep] = React.useState(0)
+    const isComplete = activeStep >= steps.length
+
     return (
-      <div className="space-y-8">
-        <Stepper activeStep={activeStep}>
-          {steps.map((step, index) => (
-            <Stepper.Step
-              key={index}
-              index={index}
-              label={step}
-              isLast={index === steps.length - 1}
-            />
-          ))}
-          <Stepper.Content>
-            <div className="bg-fm-surface-secondary min-h-[200px] rounded-lg p-6">
-              <h3 className="mb-4 text-lg font-semibold">
-                {steps[activeStep] || "Completed!"}
-              </h3>
-              <p className="text-fm-secondary mb-6">
-                {activeStep < steps.length
-                  ? `This is the content for ${steps[activeStep]}`
-                  : "All steps completed successfully!"}
+      <div className="w-full p-8">
+        <div className="mx-auto max-w-3xl space-y-6">
+          <div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
+            {/* Controls Panel */}
+            <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-5 rounded-xl border p-5">
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                Jump to Step
               </p>
-
-              <div className="flex gap-4">
-                <button
-                  onClick={() => setActiveStep(Math.max(0, activeStep - 1))}
-                  disabled={activeStep === 0}
-                  className="bg-fm-surface-tertiary text-fm-primary rounded px-4 py-2 disabled:opacity-50"
-                >
-                  Previous
-                </button>
-                <button
-                  onClick={() =>
-                    setActiveStep(Math.min(steps.length, activeStep + 1))
-                  }
-                  disabled={activeStep >= steps.length}
-                  className="bg-fm-surface-info text-fm-surface-primary rounded px-4 py-2 disabled:opacity-50"
-                >
-                  {activeStep === steps.length - 1 ? "Complete" : "Next"}
-                </button>
+              <div className="space-y-2">
+                {steps.map((step, index) => (
+                  <button
+                    key={index}
+                    onClick={() => setActiveStep(index)}
+                    className={[
+                      "font-fm-text text-fm-sm leading-fm-sm w-full rounded-lg border px-3 py-2 text-left transition-colors",
+                      activeStep === index
+                        ? "border-fm-divider-brand-secondary bg-fm-surface-secondary text-fm-primary"
+                        : "border-fm-divider-secondary text-fm-secondary hover:text-fm-primary hover:border-fm-divider-secondary",
+                    ].join(" ")}
+                  >
+                    {index + 1}. {step.label}
+                  </button>
+                ))}
               </div>
+              <div className="border-fm-divider-secondary border-t pt-4" />
+              <button
+                onClick={() => setActiveStep(0)}
+                className="border-fm-divider-secondary text-fm-secondary hover:text-fm-primary font-fm-text text-fm-sm leading-fm-sm w-full rounded-lg border px-3 py-2 text-left transition-colors"
+              >
+                Reset
+              </button>
             </div>
-          </Stepper.Content>
-        </Stepper>
-      </div>
-    )
-  },
-  parameters: {
-    layout: "padded",
-  },
-}
-
-// Custom Composition Example
-export const CustomComposition: Story = {
-  render: () => (
-    <Stepper variant="primary" activeStep={1}>
-      <Stepper.Step index={0} label="Start" />
-      <Stepper.Step index={1} label="Progress" />
-      <Stepper.Step index={2} label="Finish" isLast />
-
-      <Stepper.Content>
-        <div className="bg-fm-surface-secondary rounded-lg p-4">
-          <p>Custom content area with flexible composition</p>
-        </div>
-      </Stepper.Content>
-    </Stepper>
-  ),
-  parameters: {
-    layout: "padded",
-  },
-}
-
-// All Variants Showcase
-export const AllVariants: Story = {
-  render: () => (
-    <div className="text-fm-primary space-y-8">
-      {(["primary", "positive", "negative", "warning"] as const).map(
-        (variant) => (
-          <div key={variant} className="space-y-2">
-            <h4 className="text-sm font-medium capitalize">{variant}</h4>
-            <Stepper
-              steps={4}
-              activeStep={2}
-              variant={variant}
-              stepLabels={["Step 1", "Step 2", "Step 3", "Step 4"]}
-            />
-          </div>
-        )
-      )}
-    </div>
-  ),
-  parameters: {
-    layout: "padded",
-  },
-}
-
-// Progressive States Example
-export const ProgressiveStates: Story = {
-  render: () => {
-    const steps = ["Not Started", "In Progress", "Completed"]
 
-    return (
-      <div className="text-fm-primary space-y-8">
-        {[0, 1, 2, 3].map((activeStep) => (
-          <div key={activeStep} className="space-y-2">
-            <h4 className="text-sm font-medium">
-              Active Step: {activeStep}{" "}
-              {activeStep === 3 ? "(All Complete)" : ""}
-            </h4>
-            <Stepper
-              steps={3}
-              activeStep={activeStep}
-              variant="primary"
-              stepLabels={steps}
-            />
+            {/* Preview Stage */}
+            <div className="flex flex-col gap-4 lg:col-span-2">
+              <Stepper
+                activeStep={activeStep}
+                onStepClick={(i) => setActiveStep(i)}
+                variant="primary"
+                className="text-fm-primary w-full"
+              >
+                {steps.map((step, index) => (
+                  <Stepper.Step
+                    key={index}
+                    index={index}
+                    label={step.label}
+                    isLast={index === steps.length - 1}
+                  />
+                ))}
+                <Stepper.Content>
+                  <div className="border-fm-divider-secondary bg-fm-surface-secondary min-h-44 rounded-xl border p-6">
+                    {isComplete ? (
+                      <div className="space-y-2">
+                        <p className="text-fm-primary font-fm-brand text-fm-lg leading-fm-xl font-semibold">
+                          All done!
+                        </p>
+                        <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+                          All steps completed successfully.
+                        </p>
+                      </div>
+                    ) : (
+                      <div className="space-y-2">
+                        <p className="text-fm-primary font-fm-brand text-fm-lg leading-fm-xl font-semibold">
+                          {steps[activeStep].label}
+                        </p>
+                        <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+                          {steps[activeStep].description}
+                        </p>
+                      </div>
+                    )}
+                    <div className="mt-6 flex gap-3">
+                      <button
+                        onClick={() =>
+                          setActiveStep(Math.max(0, activeStep - 1))
+                        }
+                        disabled={activeStep === 0}
+                        className="border-fm-divider-secondary text-fm-secondary hover:text-fm-primary font-fm-text text-fm-sm leading-fm-sm rounded-lg border px-4 py-2 transition-colors disabled:opacity-40"
+                      >
+                        Previous
+                      </button>
+                      <button
+                        onClick={() =>
+                          setActiveStep(Math.min(steps.length, activeStep + 1))
+                        }
+                        disabled={isComplete}
+                        className="bg-fm-surface-info-sec text-fm-info-sec font-fm-text text-fm-sm leading-fm-sm rounded-lg px-4 py-2 transition-opacity disabled:opacity-40"
+                      >
+                        {activeStep === steps.length - 1 ? "Finish" : "Next"}
+                      </button>
+                    </div>
+                  </div>
+                </Stepper.Content>
+              </Stepper>
+            </div>
           </div>
-        ))}
+        </div>
       </div>
     )
   },
   parameters: {
-    layout: "padded",
-  },
-}
-
-// Vertical with Content Example
-export const VerticalWithContent: Story = {
-  render: () => (
-    <div className="text-fm-primary">
-      <Stepper
-        steps={4}
-        activeStep={2}
-        variant="primary"
-        orientation="vertical"
-        stepLabels={["Account", "Profile", "Settings", "Review"]}
-        className="h-[800px]"
-      >
-        <Stepper.Content>
-          <div className="bg-fm-surface-secondary text-fm-secondary rounded-lg p-6">
-            <h3 className="mb-4 text-lg font-semibold">
-              Settings Configuration
-            </h3>
-            <p>Configure your account settings and preferences.</p>
-          </div>
-        </Stepper.Content>
-      </Stepper>
-    </div>
-  ),
-  parameters: {
-    layout: "padded",
+    layout: "fullscreen",
+    docs: {
+      description: {
+        story:
+          "Clickable wizard with five steps, step content panels, Previous/Next buttons, and a jump-to-step sidebar. Demonstrates compound component usage with Stepper.Step and Stepper.Content.",
+      },
+    },
   },
 }