aural-ui 4.0.1 → 4.1.0

package/dist/components/tag/Tag.stories.tsx

@@ -1,6 +1,8 @@
 import React from "react"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import { Tag } from "."
 
 const meta: Meta<typeof Tag> = {
@@ -8,12 +10,29 @@ const meta: Meta<typeof Tag> = {
   component: Tag,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
+    docs: {
+      description: {
+        component:
+          "A compact inline label for categorising and filtering content. Supports two variants (promotional and system), ten colors, three emphasis levels (primary/secondary/tertiary), three sizes, and optional left/right icons.",
+      },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "10 Colors",
+              description: "Neutral to neongreen",
+            },
+            {
+              title: "3 Emphasis Levels",
+              description: "Filled, tinted, outline",
+            },
+            {
+              title: "Icon Slots",
+              description: "Left and right icons",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -21,7 +40,8 @@ const meta: Meta<typeof Tag> = {
     variant: {
       control: "select",
       options: ["promotional", "system"],
-      description: "Determines the visual style of the tag",
+      description:
+        "Visual style family — promotional uses brand colors, system uses semantic colors",
     },
     color: {
       control: "select",
@@ -37,39 +57,36 @@ const meta: Meta<typeof Tag> = {
         "electricblue",
         "neongreen",
       ],
-      description: "The color scheme of the tag",
+      description: "Color scheme applied to the tag surface and text",
     },
     emphasis: {
       control: "select",
       options: ["primary", "secondary", "tertiary"],
-      description: "Defines the visual weight of the tag",
+      description:
+        "Visual weight — primary is filled, secondary is tinted, tertiary is transparent",
     },
     size: {
       control: "select",
-      options: ["sm", "md"],
-      description: "Size of the tag",
+      options: ["xs", "sm", "md"],
+      description: "Tag size",
     },
     leftIcon: {
       control: "boolean",
       description:
-        "Shows an icon on the left side of the tag text or accepts a custom React node",
+        "Show default FeatureShineIcon on the left, or pass a custom React node",
     },
     rightIcon: {
       control: "boolean",
       description:
-        "Shows an icon on the right side of the tag text or accepts a custom React node",
+        "Show default FeatureShineIcon on the right, or pass a custom React node",
     },
-    className: {
+    children: {
       control: "text",
-      description: "Set the class for the tag",
+      description: "Tag label text",
     },
     iconProps: {
       control: "object",
-      description: "Props to pass to the default FeatureShineIcon",
-    },
-    children: {
-      control: "text",
-      description: "The content of the tag",
+      description: "Props forwarded to the default FeatureShineIcon",
     },
   },
 } satisfies Meta<typeof Tag>
@@ -77,556 +94,711 @@ const meta: Meta<typeof Tag> = {
 export default meta
 type Story = StoryObj<typeof meta>
 
-export const Default: Story = {
-  args: {
-    children: "Tag",
-    variant: "system",
-    color: "neutral",
-    emphasis: "primary",
-    size: "md",
-    leftIcon: true,
-    rightIcon: false,
-  },
-}
+// ─── 1. Playground ────────────────────────────────────────────────────────────
 
-// System Tag Variants
-export const SystemNeutralPrimary: Story = {
+export const Playground: Story = {
   args: {
-    ...Default.args,
-    variant: "system",
-    color: "neutral",
-    emphasis: "primary",
-    children: "Neutral Primary",
-  },
-}
-
-export const SystemNeutralSecondary: Story = {
-  args: {
-    ...Default.args,
-    variant: "system",
-    color: "neutral",
-    emphasis: "secondary",
-    children: "Neutral Secondary",
-  },
-}
-
-export const SystemNeutralTertiary: Story = {
-  args: {
-    ...Default.args,
-    variant: "system",
-    color: "neutral",
-    emphasis: "tertiary",
-    children: "Neutral Tertiary",
-  },
-}
-
-export const SystemInfoPrimary: Story = {
-  args: {
-    ...Default.args,
-    variant: "system",
-    color: "info",
-    emphasis: "primary",
-    children: "Info Primary",
-  },
-}
-
-export const SystemInfoSecondary: Story = {
-  args: {
-    ...Default.args,
-    variant: "system",
-    color: "info",
-    emphasis: "secondary",
-    children: "Info Secondary",
-  },
-}
-
-export const SystemInfoTertiary: Story = {
-  args: {
-    ...Default.args,
+    children: "Label",
     variant: "system",
     color: "info",
-    emphasis: "tertiary",
-    children: "Info Tertiary",
-  },
-}
-
-export const SystemPositivePrimary: Story = {
-  args: {
-    ...Default.args,
-    variant: "system",
-    color: "positive",
-    emphasis: "primary",
-    children: "Positive Primary",
-  },
-}
-
-export const SystemPositiveSecondary: Story = {
-  args: {
-    ...Default.args,
-    variant: "system",
-    color: "positive",
-    emphasis: "secondary",
-    children: "Positive Secondary",
-  },
-}
-
-export const SystemPositiveTertiary: Story = {
-  args: {
-    ...Default.args,
-    variant: "system",
-    color: "positive",
-    emphasis: "tertiary",
-    children: "Positive Tertiary",
-  },
-}
-
-export const SystemNegativePrimary: Story = {
-  args: {
-    ...Default.args,
-    variant: "system",
-    color: "negative",
-    emphasis: "primary",
-    children: "Negative Primary",
-  },
-}
-
-export const SystemNegativeSecondary: Story = {
-  args: {
-    ...Default.args,
-    variant: "system",
-    color: "negative",
     emphasis: "secondary",
-    children: "Negative Secondary",
-  },
-}
-
-export const SystemNegativeTertiary: Story = {
-  args: {
-    ...Default.args,
-    variant: "system",
-    color: "negative",
-    emphasis: "tertiary",
-    children: "Negative Tertiary",
-  },
-}
-
-export const SystemNegativeNoFill: Story = {
-  args: {
-    ...Default.args,
-    variant: "system",
-    color: "negative",
-    emphasis: "no-fill",
-    children: "Negative No Fill",
-  },
-}
-
-export const SystemWarningPrimary: Story = {
-  args: {
-    ...Default.args,
-    variant: "system",
-    color: "warning",
-    emphasis: "primary",
-    children: "Warning Primary",
-  },
-}
-
-export const SystemWarningSecondary: Story = {
-  args: {
-    ...Default.args,
-    variant: "system",
-    color: "warning",
-    emphasis: "secondary",
-    children: "Warning Secondary",
-  },
-}
-
-export const SystemWarningTertiary: Story = {
-  args: {
-    ...Default.args,
-    variant: "system",
-    color: "warning",
-    emphasis: "tertiary",
-    children: "Warning Tertiary",
-  },
-}
-
-// Promotional Tag Variants
-export const PromotionalLemonPrimary: Story = {
-  args: {
-    ...Default.args,
-    variant: "promotional",
-    color: "lemon",
-    emphasis: "primary",
-    children: "Lemon Primary",
-  },
-}
-
-export const PromotionalLemonSecondary: Story = {
-  args: {
-    ...Default.args,
-    variant: "promotional",
-    color: "lemon",
-    emphasis: "secondary",
-    children: "Lemon Secondary",
-  },
-}
-
-export const PromotionalLemonTertiary: Story = {
-  args: {
-    ...Default.args,
-    variant: "promotional",
-    color: "lemon",
-    emphasis: "tertiary",
-    children: "Lemon Tertiary",
-  },
-}
-
-export const PromotionalEmeraldPrimary: Story = {
-  args: {
-    ...Default.args,
-    variant: "promotional",
-    color: "emerald",
-    emphasis: "primary",
-    children: "Emerald Primary",
-  },
-}
-
-export const PromotionalEmeraldSecondary: Story = {
-  args: {
-    ...Default.args,
-    variant: "promotional",
-    color: "emerald",
-    emphasis: "secondary",
-    children: "Emerald Secondary",
-  },
-}
-
-export const PromotionalEmeraldTertiary: Story = {
-  args: {
-    ...Default.args,
-    variant: "promotional",
-    color: "emerald",
-    emphasis: "tertiary",
-    children: "Emerald Tertiary",
-  },
-}
-
-export const PromotionalHotpinkPrimary: Story = {
-  args: {
-    ...Default.args,
-    variant: "promotional",
-    color: "hotpink",
-    emphasis: "primary",
-    children: "Hotpink Primary",
-  },
-}
-
-export const PromotionalHotpinkSecondary: Story = {
-  args: {
-    ...Default.args,
-    variant: "promotional",
-    color: "hotpink",
-    emphasis: "secondary",
-    children: "Hotpink Secondary",
-  },
-}
-
-export const PromotionalHotpinkTertiary: Story = {
-  args: {
-    ...Default.args,
-    variant: "promotional",
-    color: "hotpink",
-    emphasis: "tertiary",
-    children: "Hotpink Tertiary",
-  },
-}
-
-export const PromotionalElectricbluePrimary: Story = {
-  args: {
-    ...Default.args,
-    variant: "promotional",
-    color: "electricblue",
-    emphasis: "primary",
-    children: "Electricblue Primary",
-  },
-}
-
-export const PromotionalElectricblueSecondary: Story = {
-  args: {
-    ...Default.args,
-    variant: "promotional",
-    color: "electricblue",
-    emphasis: "secondary",
-    children: "Electricblue Secondary",
-  },
-}
-
-export const PromotionalElectricblueTertiary: Story = {
-  args: {
-    ...Default.args,
-    variant: "promotional",
-    color: "electricblue",
-    emphasis: "tertiary",
-    children: "Electricblue Tertiary",
-  },
-}
-
-export const PromotionalNeonGreenPrimary: Story = {
-  args: {
-    ...Default.args,
-    variant: "promotional",
-    color: "neongreen",
-    emphasis: "primary",
-    children: "Neongreen Primary",
-  },
-}
-
-export const PromotionalNeonGreenSecondary: Story = {
-  args: {
-    ...Default.args,
-    variant: "promotional",
-    color: "neongreen",
-    emphasis: "secondary",
-    children: "Neongreen Secondary",
-  },
-}
-
-export const PromotionalNeonGreenTertiary: Story = {
-  args: {
-    ...Default.args,
-    variant: "promotional",
-    color: "neongreen",
-    emphasis: "tertiary",
-    children: "Neongreen Tertiary",
-  },
-}
-
-// Size variants
-export const SmallSize: Story = {
-  args: {
-    ...Default.args,
-    size: "sm",
-    children: "Small Tag",
-  },
-}
-
-export const MediumSize: Story = {
-  args: {
-    ...Default.args,
     size: "md",
-    children: "Medium Tag",
-  },
-}
-
-// Icon variants
-export const WithLeftIcon: Story = {
-  args: {
-    ...Default.args,
-    leftIcon: true,
-    rightIcon: false,
-    children: "Left Icon",
-  },
-}
-
-export const WithRightIcon: Story = {
-  args: {
-    ...Default.args,
-    leftIcon: false,
-    rightIcon: true,
-    children: "Right Icon",
-  },
-}
-
-export const WithBothIcons: Story = {
-  args: {
-    ...Default.args,
-    leftIcon: true,
-    rightIcon: true,
-    children: "Both Icons",
-  },
-}
-
-// Custom Icon examples
-export const WithCustomIconProps: Story = {
-  args: {
-    ...Default.args,
     leftIcon: true,
-    iconProps: { color: "red", width: 20, height: 20 },
-    children: "Custom Icon Props",
   },
-}
-
-export const WithCustomLeftIcon: Story = {
-  args: {
-    ...Default.args,
-    leftIcon: (
-      <svg
-        width="16"
-        height="16"
-        viewBox="0 0 16 16"
-        fill="none"
-        xmlns="http://www.w3.org/2000/svg"
-      >
-        <circle cx="8" cy="8" r="7" stroke="currentColor" strokeWidth="2" />
-        <path
-          d="M5 8L7 10L11 6"
-          stroke="currentColor"
-          strokeWidth="2"
-          strokeLinecap="round"
-          strokeLinejoin="round"
-        />
-      </svg>
-    ),
-    children: "Custom Left Icon",
+  render: (args) => (
+    <div className="w-full max-w-sm space-y-4">
+      <div className="flex justify-center">
+        <Tag {...args} />
+      </div>
+      <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+        <code
+          className="text-fm-secondary text-fm-md leading-fm-md"
+          style={{ fontFamily: "var(--font-fm-mono)" }}
+        >
+          {`<Tag variant="${args.variant}" color="${args.color}" emphasis="${args.emphasis}" size="${args.size}">${String(args.children)}</Tag>`}
+        </code>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Use the controls panel to explore variant (promotional/system), color, emphasis, size, and icon placement.",
+      },
+    },
   },
 }
 
-export const WithCustomRightIcon: Story = {
-  args: {
-    ...Default.args,
-    leftIcon: false,
-    rightIcon: (
-      <svg
-        width="16"
-        height="16"
-        viewBox="0 0 16 16"
-        fill="none"
-        xmlns="http://www.w3.org/2000/svg"
-      >
-        <path
-          d="M8 3V13"
-          stroke="currentColor"
-          strokeWidth="2"
-          strokeLinecap="round"
-        />
-        <path
-          d="M13 8L3 8"
-          stroke="currentColor"
-          strokeWidth="2"
-          strokeLinecap="round"
-        />
-      </svg>
-    ),
-    children: "Custom Right Icon",
-  },
-}
+// ─── 2. All Variants ──────────────────────────────────────────────────────────
 
-// Additional story to show multiple tags together
-export const TagCollection: Story = {
-  args: {
-    ...Default.args,
-  },
+export const AllVariants: Story = {
   render: () => (
-    <div className="flex flex-wrap gap-2">
-      <Tag variant="system" color="neutral" emphasis="primary">
-        Neutral
-      </Tag>
-      <Tag variant="system" color="info" emphasis="primary">
-        Info
-      </Tag>
-      <Tag variant="system" color="positive" emphasis="primary">
-        Success
-      </Tag>
-      <Tag variant="system" color="warning" emphasis="primary">
-        Warning
-      </Tag>
-      <Tag variant="system" color="negative" emphasis="primary">
-        Error
-      </Tag>
-      <Tag variant="promotional" color="lemon" emphasis="primary">
-        Lemon
-      </Tag>
-      <Tag variant="promotional" color="emerald" emphasis="primary">
-        Emerald
-      </Tag>
-      <Tag variant="promotional" color="hotpink" emphasis="primary">
-        Hotpink
-      </Tag>
-      <Tag variant="promotional" color="electricblue" emphasis="primary">
-        Electric Blue
-      </Tag>
-      <Tag
-        variant="promotional"
-        color="neongreen"
-        emphasis="primary"
-        className="px-10"
-      >
-        Neon Green
-      </Tag>
+    <div className="space-y-8">
+      {/* System variant */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          System — Primary Emphasis
+        </h4>
+        <div className="flex flex-wrap gap-3">
+          {(
+            ["neutral", "info", "positive", "negative", "warning"] as const
+          ).map((color) => (
+            <div key={color} className="space-y-2 text-center">
+              <Tag variant="system" color={color} emphasis="primary" leftIcon>
+                {color}
+              </Tag>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm capitalize">
+                {color}
+              </p>
+            </div>
+          ))}
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          System — Secondary Emphasis
+        </h4>
+        <div className="flex flex-wrap gap-3">
+          {(
+            ["neutral", "info", "positive", "negative", "warning"] as const
+          ).map((color) => (
+            <div key={color} className="space-y-2 text-center">
+              <Tag variant="system" color={color} emphasis="secondary" leftIcon>
+                {color}
+              </Tag>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm capitalize">
+                {color}
+              </p>
+            </div>
+          ))}
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          System — Tertiary Emphasis
+        </h4>
+        <div className="flex flex-wrap gap-3">
+          {(
+            ["neutral", "info", "positive", "negative", "warning"] as const
+          ).map((color) => (
+            <div key={color} className="space-y-2 text-center">
+              <Tag variant="system" color={color} emphasis="tertiary" leftIcon>
+                {color}
+              </Tag>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm capitalize">
+                {color}
+              </p>
+            </div>
+          ))}
+        </div>
+      </div>
+
+      {/* Promotional variant */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Promotional — Primary Emphasis
+        </h4>
+        <div className="flex flex-wrap gap-3">
+          {(
+            [
+              "lemon",
+              "emerald",
+              "hotpink",
+              "electricblue",
+              "neongreen",
+            ] as const
+          ).map((color) => (
+            <div key={color} className="space-y-2 text-center">
+              <Tag
+                variant="promotional"
+                color={color}
+                emphasis="primary"
+                leftIcon
+              >
+                {color}
+              </Tag>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm capitalize">
+                {color}
+              </p>
+            </div>
+          ))}
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Promotional — Secondary Emphasis
+        </h4>
+        <div className="flex flex-wrap gap-3">
+          {(
+            [
+              "lemon",
+              "emerald",
+              "hotpink",
+              "electricblue",
+              "neongreen",
+            ] as const
+          ).map((color) => (
+            <div key={color} className="space-y-2 text-center">
+              <Tag
+                variant="promotional"
+                color={color}
+                emphasis="secondary"
+                leftIcon
+              >
+                {color}
+              </Tag>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm capitalize">
+                {color}
+              </p>
+            </div>
+          ))}
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Promotional — Tertiary Emphasis
+        </h4>
+        <div className="flex flex-wrap gap-3">
+          {(
+            [
+              "lemon",
+              "emerald",
+              "hotpink",
+              "electricblue",
+              "neongreen",
+            ] as const
+          ).map((color) => (
+            <div key={color} className="space-y-2 text-center">
+              <Tag
+                variant="promotional"
+                color={color}
+                emphasis="tertiary"
+                leftIcon
+              >
+                {color}
+              </Tag>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm capitalize">
+                {color}
+              </p>
+            </div>
+          ))}
+        </div>
+      </div>
     </div>
   ),
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        story:
+          "Full variant × color × emphasis matrix. System colors (neutral, info, positive, negative, warning) across all three emphasis levels, then promotional colors (lemon, emerald, hotpink, electricblue, neongreen) across all three emphasis levels.",
+      },
+    },
+  },
 }
 
-// Showcase different emphasis styles
-export const EmphasisVariants: Story = {
-  args: {
-    ...Default.args,
-  },
+// ─── 2. Sizes ─────────────────────────────────────────────────────────────────
+
+export const Sizes: Story = {
   render: () => (
-    <div className="flex flex-wrap gap-2">
-      <Tag variant="system" color="info" emphasis="primary">
-        Primary
-      </Tag>
-      <Tag variant="system" color="info" emphasis="secondary">
-        Secondary
-      </Tag>
-      <Tag variant="system" color="info" emphasis="tertiary">
-        Tertiary
-      </Tag>
+    <div className="space-y-8">
+      <div className="flex flex-wrap items-end justify-center gap-6">
+        <div className="space-y-2 text-center">
+          <Tag
+            variant="system"
+            color="info"
+            emphasis="secondary"
+            size="xs"
+            leftIcon
+          >
+            Extra Small
+          </Tag>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            xs
+          </p>
+        </div>
+        <div className="space-y-2 text-center">
+          <Tag
+            variant="system"
+            color="info"
+            emphasis="secondary"
+            size="sm"
+            leftIcon
+          >
+            Small
+          </Tag>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            sm
+          </p>
+        </div>
+        <div className="space-y-2 text-center">
+          <Tag
+            variant="system"
+            color="info"
+            emphasis="secondary"
+            size="md"
+            leftIcon
+          >
+            Medium
+          </Tag>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            md (default)
+          </p>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Size × Color
+        </h4>
+        <div className="flex flex-wrap items-end justify-center gap-4">
+          {(["xs", "sm", "md"] as const).map((size) => (
+            <div key={size} className="space-y-3">
+              <div className="space-y-2 text-center">
+                <Tag
+                  variant="system"
+                  color="positive"
+                  emphasis="secondary"
+                  size={size}
+                  leftIcon
+                >
+                  Positive
+                </Tag>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  positive · {size}
+                </p>
+              </div>
+              <div className="space-y-2 text-center">
+                <Tag
+                  variant="promotional"
+                  color="lemon"
+                  emphasis="primary"
+                  size={size}
+                  leftIcon
+                >
+                  Lemon
+                </Tag>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  lemon · {size}
+                </p>
+              </div>
+              <div className="space-y-2 text-center">
+                <Tag
+                  variant="system"
+                  color="warning"
+                  emphasis="secondary"
+                  size={size}
+                  leftIcon
+                >
+                  Warning
+                </Tag>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  warning · {size}
+                </p>
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
     </div>
   ),
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        story:
+          "Three sizes (xs, sm, md) shown side by side, plus a size × color cross-axis grid.",
+      },
+    },
+  },
 }
 
-// Showcase different sizes
-export const SizeVariants: Story = {
-  args: {
-    ...Default.args,
-  },
+// ─── 3. Configurations ────────────────────────────────────────────────────────
+
+export const Configurations: Story = {
   render: () => (
-    <div className="flex flex-wrap items-center gap-2">
-      <Tag variant="system" color="positive" size="sm">
-        Small Tag
-      </Tag>
-      <Tag variant="system" color="positive" size="md">
-        Medium Tag
-      </Tag>
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Icon Placement
+        </h4>
+        <div className="flex flex-wrap items-center gap-3">
+          <div className="space-y-2 text-center">
+            <Tag variant="system" color="neutral" emphasis="primary">
+              No Icon
+            </Tag>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              none
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Tag variant="system" color="neutral" emphasis="primary" leftIcon>
+              Left Icon
+            </Tag>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              left
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Tag variant="system" color="neutral" emphasis="primary" rightIcon>
+              Right Icon
+            </Tag>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              right
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Tag
+              variant="system"
+              color="neutral"
+              emphasis="primary"
+              leftIcon
+              rightIcon
+            >
+              Both Icons
+            </Tag>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              both
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Icon Placement × Variant
+        </h4>
+        <div className="flex flex-wrap gap-6">
+          {(
+            [
+              { variant: "system", color: "info", emphasis: "secondary" },
+              { variant: "system", color: "positive", emphasis: "secondary" },
+              { variant: "system", color: "negative", emphasis: "secondary" },
+              { variant: "promotional", color: "lemon", emphasis: "primary" },
+              { variant: "promotional", color: "hotpink", emphasis: "primary" },
+            ] as const
+          ).map(({ variant, color, emphasis }) => (
+            <div key={`${variant}-${color}`} className="space-y-2">
+              <div className="flex flex-wrap items-center gap-2">
+                <Tag
+                  variant={variant}
+                  color={color}
+                  emphasis={emphasis}
+                  leftIcon
+                >
+                  {color}
+                </Tag>
+                <Tag
+                  variant={variant}
+                  color={color}
+                  emphasis={emphasis}
+                  rightIcon
+                >
+                  {color}
+                </Tag>
+                <Tag
+                  variant={variant}
+                  color={color}
+                  emphasis={emphasis}
+                  leftIcon
+                  rightIcon
+                >
+                  {color}
+                </Tag>
+              </div>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm capitalize">
+                {color} · {emphasis}
+              </p>
+            </div>
+          ))}
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Custom SVG Icons
+        </h4>
+        <div className="flex flex-wrap items-center gap-3">
+          <div className="space-y-2 text-center">
+            <Tag
+              variant="system"
+              color="positive"
+              emphasis="secondary"
+              leftIcon={
+                <svg width="12" height="12" viewBox="0 0 16 16" fill="none">
+                  <circle
+                    cx="8"
+                    cy="8"
+                    r="7"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                  />
+                  <path
+                    d="M5 8L7 10L11 6"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                  />
+                </svg>
+              }
+            >
+              Verified
+            </Tag>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              custom left
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Tag
+              variant="system"
+              color="info"
+              emphasis="secondary"
+              rightIcon={
+                <svg width="12" height="12" viewBox="0 0 16 16" fill="none">
+                  <path
+                    d="M8 3V13M13 8H3"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                    strokeLinecap="round"
+                  />
+                </svg>
+              }
+            >
+              Add More
+            </Tag>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              custom right
+            </p>
+          </div>
+        </div>
+      </div>
     </div>
   ),
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        story:
+          "Icon placement options (none/left/right/both) across multiple variant × color combinations, plus custom SVG icon examples.",
+      },
+    },
+  },
 }
 
-// Showcase different icon combinations
-export const IconVariants: Story = {
-  args: {
-    ...Default.args,
-  },
+// ─── 4. Use Cases ─────────────────────────────────────────────────────────────
+
+export const UseCases: Story = {
   render: () => (
-    <div className="flex flex-wrap gap-2">
-      <Tag variant="system" color="warning" leftIcon={true}>
-        Left Icon
-      </Tag>
-      <Tag variant="system" color="warning" leftIcon={false} rightIcon={true}>
-        Right Icon
-      </Tag>
-      <Tag variant="system" color="warning" leftIcon={true} rightIcon={true}>
-        Both Icons
-      </Tag>
-      <Tag
-        variant="system"
-        color="warning"
-        leftIcon={
-          <svg
-            width="16"
-            height="16"
-            viewBox="0 0 16 16"
-            fill="none"
-            xmlns="http://www.w3.org/2000/svg"
-          >
-            <circle cx="8" cy="8" r="6" stroke="currentColor" strokeWidth="2" />
-          </svg>
-        }
-      >
-        Custom Icon
-      </Tag>
+    <div className="mx-auto max-w-3xl space-y-8 p-8">
+      {/* Genre Tags */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Genre Tags
+        </h4>
+        <div className="flex flex-wrap gap-2">
+          {(
+            [
+              { label: "Pop", color: "hotpink" },
+              { label: "Hip-Hop", color: "lemon" },
+              { label: "Electronic", color: "electricblue" },
+              { label: "Jazz", color: "emerald" },
+              { label: "Rock", color: "neongreen" },
+              { label: "Classical", color: "hotpink" },
+              { label: "R&B", color: "lemon" },
+            ] as const
+          ).map(({ label, color }) => (
+            <Tag
+              key={label}
+              variant="promotional"
+              color={color}
+              emphasis="secondary"
+              size="sm"
+            >
+              {label}
+            </Tag>
+          ))}
+        </div>
+      </div>
+
+      {/* Mood Tags */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Mood Tags
+        </h4>
+        <div className="flex flex-wrap gap-2">
+          {(
+            [
+              { label: "Chill", color: "info" },
+              { label: "Energetic", color: "positive" },
+              { label: "Melancholic", color: "negative" },
+              { label: "Upbeat", color: "warning" },
+              { label: "Focus", color: "info" },
+              { label: "Party", color: "warning" },
+            ] as const
+          ).map(({ label, color }) => (
+            <Tag
+              key={label}
+              variant="system"
+              color={color}
+              emphasis="secondary"
+              size="sm"
+              leftIcon
+            >
+              {label}
+            </Tag>
+          ))}
+        </div>
+      </div>
+
+      {/* Filter Chips */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Filter Chips
+        </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">
+            Active filters
+          </p>
+          <div className="flex flex-wrap gap-2">
+            {(
+              [
+                { label: "New Releases", color: "info", emphasis: "secondary" },
+                {
+                  label: "Verified Artist",
+                  color: "positive",
+                  emphasis: "secondary",
+                },
+                { label: "Explicit", color: "negative", emphasis: "secondary" },
+                { label: "HD Audio", color: "neutral", emphasis: "primary" },
+              ] as const
+            ).map(({ label, color, emphasis }) => (
+              <Tag
+                key={label}
+                variant="system"
+                color={color}
+                emphasis={emphasis}
+                size="sm"
+                rightIcon={
+                  <svg width="10" height="10" viewBox="0 0 16 16" fill="none">
+                    <path
+                      d="M4 4L12 12M12 4L4 12"
+                      stroke="currentColor"
+                      strokeWidth="2"
+                      strokeLinecap="round"
+                    />
+                  </svg>
+                }
+              >
+                {label}
+              </Tag>
+            ))}
+          </div>
+        </div>
+      </div>
+
+      {/* Track Metadata Row */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Track Metadata
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-3 rounded-xl border p-4">
+          {[
+            {
+              title: "Midnight Dreams",
+              artist: "Luna Wave",
+              tags: [
+                {
+                  label: "NEW",
+                  variant: "system",
+                  color: "info",
+                  emphasis: "secondary",
+                },
+                {
+                  label: "CHILL",
+                  variant: "system",
+                  color: "neutral",
+                  emphasis: "primary",
+                },
+              ] as const,
+            },
+            {
+              title: "Electric Sunrise",
+              artist: "Neon Pulse",
+              tags: [
+                {
+                  label: "TRENDING",
+                  variant: "promotional",
+                  color: "lemon",
+                  emphasis: "primary",
+                },
+                {
+                  label: "ENERGETIC",
+                  variant: "system",
+                  color: "positive",
+                  emphasis: "secondary",
+                },
+              ] as const,
+            },
+            {
+              title: "Echoes in Rain",
+              artist: "Dusk & Dawn",
+              tags: [
+                {
+                  label: "EXPLICIT",
+                  variant: "system",
+                  color: "negative",
+                  emphasis: "secondary",
+                },
+                {
+                  label: "JAZZ",
+                  variant: "promotional",
+                  color: "emerald",
+                  emphasis: "secondary",
+                },
+              ] as const,
+            },
+          ].map(({ title, artist, tags }) => (
+            <div key={title} className="flex items-center justify-between">
+              <div>
+                <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                  {title}
+                </p>
+                <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                  {artist}
+                </p>
+              </div>
+              <div className="flex items-center gap-2">
+                {tags.map(({ label, variant, color, emphasis }) => (
+                  <Tag
+                    key={label}
+                    variant={variant}
+                    color={color}
+                    emphasis={emphasis}
+                    size="xs"
+                  >
+                    {label}
+                  </Tag>
+                ))}
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
     </div>
   ),
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        story:
+          "Real audio-app usage: genre tags in promotional colors, mood tags with system semantic colors, active filter chips with dismiss icons, and track metadata rows combining multiple tag types.",
+      },
+    },
+  },
 }