@ds-mo/ui 0.1.0

package/src/components/Tag/Tag.module.css

@@ -0,0 +1,270 @@
+/* ==========================================================================
+   Tag — hover/pressed via direct background-color + color-mix().
+   No pseudo-element overlays.
+   ========================================================================== */
+
+.tag {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--dimension-radius-050);
+  box-sizing: border-box;
+  color: var(--color-foreground-primary);
+  position: relative;
+
+  /* Interaction — ghost defaults */
+  --_hover-bg: var(--color-interaction-hover);
+  --_pressed-bg: var(--color-interaction-pressed);
+}
+
+/* ==========================================================================
+   Sizes
+   md  28px — no size-350 token, expressed as 7/2 × base
+   sm  20px — size-250
+   xs  12px — size-150
+   ========================================================================== */
+
+.sizeMd { height: calc(var(--dimension-size-base) * 7 / 2); padding: 0 var(--dimension-space-075); gap: 0; }
+.sizeSm { height: var(--dimension-size-250);                padding: 0 var(--dimension-space-050); gap: 0; }
+.sizeXs { height: var(--dimension-size-150);                padding: 0 var(--dimension-space-012); gap: 0; }
+
+/* ==========================================================================
+   Rounded
+   ========================================================================== */
+
+.rounded { border-radius: var(--dimension-radius-half); }
+
+/*
+ * Pill padding correction — add space-050 to sides that have no content anchor.
+ * Applied by Tag.tsx based on whether a leading icon or trailing remove is present:
+ *   no leading icon  → roundedLeft{Size}   (left side is bare label text)
+ *   no trailing icon → roundedRight{Size}  (right side is bare label text)
+ * Placed after size rules so same-specificity cascade wins correctly.
+ */
+
+/* MD — base: space-075 */
+.roundedLeftMD  { padding-left:  calc(var(--dimension-space-075) + var(--dimension-space-050)); }
+.roundedRightMD { padding-right: calc(var(--dimension-space-075) + var(--dimension-space-050)); }
+
+/* SM — base: space-050 */
+.roundedLeftSM  { padding-left:  calc(var(--dimension-space-050) + var(--dimension-space-050)); }
+.roundedRightSM { padding-right: calc(var(--dimension-space-050) + var(--dimension-space-050)); }
+
+/* XS — base: space-012 (1px) */
+.roundedLeftXS  { padding-left:  calc(var(--dimension-space-012) + var(--dimension-space-050)); }
+.roundedRightXS { padding-right: calc(var(--dimension-space-012) + var(--dimension-space-050)); }
+
+/*
+ * Icon-edge padding correction — when an icon (leading or remove) sits on a
+ * side, that side's padding should match the top/bottom optical gap:
+ *   (height − icon_size) / 2
+ *
+ *   md: (28 − 20) / 2 = 4px  → space-050
+ *   sm: (20 − 16) / 2 = 2px  → space-025
+ *   xs: (12 − 12) / 2 = 0px  → 0
+ *
+ * Applied by Tag.tsx: iconLeft when Icon present, iconRight when removable.
+ * Placed after size + rounded rules so same-specificity cascade wins.
+ */
+.iconLeftMD  { padding-left:  var(--dimension-space-050); }
+.iconRightMD { padding-right: var(--dimension-space-050); }
+
+.iconLeftSM  { padding-left:  var(--dimension-space-025); }
+.iconRightSM { padding-right: var(--dimension-space-025); }
+
+.iconLeftXS  { padding-left:  0; }
+.iconRightXS { padding-right: 0; }
+
+/* ==========================================================================
+   Background context — parent surface awareness
+   ========================================================================== */
+
+.onMedium {
+  --_hover-bg: var(--color-interaction-on-medium-background-hover);
+  --_pressed-bg: var(--color-interaction-on-medium-background-pressed);
+}
+
+.onBold {
+  --_hover-bg: var(--color-interaction-on-bold-background-hover);
+  --_pressed-bg: var(--color-interaction-on-bold-background-pressed);
+}
+
+.onStrong {
+  --_hover-bg: var(--color-interaction-on-strong-background-hover);
+  --_pressed-bg: var(--color-interaction-on-strong-background-pressed);
+}
+
+.onAlwaysDark {
+  --_hover-bg: var(--color-always-dark-interaction-hover);
+  --_pressed-bg: var(--color-always-dark-interaction-pressed);
+}
+
+/* ==========================================================================
+   Elevation
+   none     — filled intent bg, no border, no shadow  (default)
+   flat     — transparent bg + intent-coloured border ring
+   elevated — filled intent bg + elevated shadow
+   ========================================================================== */
+
+/* elevationNone — no extra chrome needed, intent+contrast classes handle fill */
+
+.elevationFlat {
+  background-color: transparent !important;
+  box-shadow: inset 0 0 0 var(--dimension-stroke-width-015) currentColor;
+}
+
+/* Flat: no background — use on-surface fg tokens matched to the contrast level.
+   The border ring is currentColor so it follows text color automatically.
+   3-class specificity beats the 2-class intent+contrast filled rules above. */
+
+.elevationFlat.intentNeutral.contrastBold   { color: var(--color-foreground-bold-neutral);   }
+.elevationFlat.intentBrand.contrastBold     { color: var(--color-foreground-bold-brand);     }
+.elevationFlat.intentAi.contrastBold        { color: var(--color-foreground-bold-ai);        }
+.elevationFlat.intentNegative.contrastBold  { color: var(--color-foreground-bold-negative);  }
+.elevationFlat.intentWarning.contrastBold   { color: var(--color-foreground-bold-warning);   }
+.elevationFlat.intentCaution.contrastBold   { color: var(--color-foreground-bold-caution);   }
+.elevationFlat.intentPositive.contrastBold  { color: var(--color-foreground-bold-positive);  }
+
+.elevationFlat.intentNeutral.contrastStrong   { color: var(--color-foreground-strong-neutral);   }
+.elevationFlat.intentBrand.contrastStrong     { color: var(--color-foreground-strong-brand);     }
+.elevationFlat.intentAi.contrastStrong        { color: var(--color-foreground-strong-ai);        }
+.elevationFlat.intentNegative.contrastStrong  { color: var(--color-foreground-strong-negative);  }
+.elevationFlat.intentWarning.contrastStrong   { color: var(--color-foreground-strong-warning);   }
+.elevationFlat.intentCaution.contrastStrong   { color: var(--color-foreground-strong-caution);   }
+.elevationFlat.intentPositive.contrastStrong  { color: var(--color-foreground-strong-positive);  }
+
+.elevationFlat.intentNeutral.contrastMedium   { color: var(--color-foreground-medium-neutral);   }
+.elevationFlat.intentBrand.contrastMedium     { color: var(--color-foreground-medium-brand);     }
+.elevationFlat.intentAi.contrastMedium        { color: var(--color-foreground-medium-ai);        }
+.elevationFlat.intentNegative.contrastMedium  { color: var(--color-foreground-medium-negative);  }
+.elevationFlat.intentWarning.contrastMedium   { color: var(--color-foreground-medium-warning);   }
+.elevationFlat.intentCaution.contrastMedium   { color: var(--color-foreground-medium-caution);   }
+.elevationFlat.intentPositive.contrastMedium  { color: var(--color-foreground-medium-positive);  }
+
+.elevationFlat.intentNeutral.contrastFaint   { color: var(--color-foreground-faint-neutral);   }
+.elevationFlat.intentBrand.contrastFaint     { color: var(--color-foreground-faint-brand);     }
+.elevationFlat.intentAi.contrastFaint        { color: var(--color-foreground-faint-ai);        }
+.elevationFlat.intentNegative.contrastFaint  { color: var(--color-foreground-faint-negative);  }
+.elevationFlat.intentWarning.contrastFaint   { color: var(--color-foreground-faint-warning);   }
+.elevationFlat.intentCaution.contrastFaint   { color: var(--color-foreground-faint-caution);   }
+.elevationFlat.intentPositive.contrastFaint  { color: var(--color-foreground-faint-positive);  }
+
+.elevationElevated { box-shadow: var(--effect-elevation-elevated-sm); }
+
+/* ==========================================================================
+   Intent + contrast — strong
+   ========================================================================== */
+
+.intentNeutral.contrastStrong  { background-color: var(--color-background-strong-neutral);  color: var(--color-foreground-medium-neutral);  }
+.intentBrand.contrastStrong    { background-color: var(--color-background-strong-brand);    color: var(--color-foreground-medium-brand);    }
+.intentAi.contrastStrong       { background-color: var(--color-background-strong-ai);       color: var(--color-foreground-medium-ai);       }
+.intentNegative.contrastStrong { background-color: var(--color-background-strong-negative); color: var(--color-foreground-medium-negative); }
+.intentWarning.contrastStrong  { background-color: var(--color-background-strong-warning);  color: var(--color-foreground-medium-warning);  }
+.intentCaution.contrastStrong  { background-color: var(--color-background-strong-caution);  color: var(--color-foreground-medium-caution);  }
+.intentPositive.contrastStrong { background-color: var(--color-background-strong-positive); color: var(--color-foreground-medium-positive); }
+
+/* ==========================================================================
+   Intent + contrast — bold
+   ========================================================================== */
+
+.intentNeutral.contrastBold  { background-color: var(--color-background-bold-neutral);  color: var(--color-foreground-on-bold-background-primary); }
+.intentBrand.contrastBold    { background-color: var(--color-background-bold-brand);    color: var(--color-foreground-on-bold-background-primary); }
+.intentAi.contrastBold       { background-color: var(--color-background-bold-ai);       color: var(--color-foreground-on-bold-background-primary); }
+.intentNegative.contrastBold { background-color: var(--color-background-bold-negative); color: var(--color-foreground-on-bold-background-primary); }
+.intentWarning.contrastBold  { background-color: var(--color-background-bold-warning);  color: var(--color-foreground-on-bold-background-primary); }
+.intentCaution.contrastBold  { background-color: var(--color-background-bold-caution);  color: var(--color-foreground-on-bold-background-primary); }
+.intentPositive.contrastBold { background-color: var(--color-background-bold-positive); color: var(--color-foreground-on-bold-background-primary); }
+
+/* ==========================================================================
+   Intent + contrast — medium
+   ========================================================================== */
+
+.intentNeutral.contrastMedium  { background-color: var(--color-background-medium-neutral);  color: var(--color-foreground-strong-neutral);  }
+.intentBrand.contrastMedium    { background-color: var(--color-background-medium-brand);    color: var(--color-foreground-strong-brand);    }
+.intentAi.contrastMedium       { background-color: var(--color-background-medium-ai);       color: var(--color-foreground-strong-ai);       }
+.intentNegative.contrastMedium { background-color: var(--color-background-medium-negative); color: var(--color-foreground-strong-negative); }
+.intentWarning.contrastMedium  { background-color: var(--color-background-medium-warning);  color: var(--color-foreground-strong-warning);  }
+.intentCaution.contrastMedium  { background-color: var(--color-background-medium-caution);  color: var(--color-foreground-strong-caution);  }
+.intentPositive.contrastMedium { background-color: var(--color-background-medium-positive); color: var(--color-foreground-strong-positive); }
+
+/* ==========================================================================
+   Intent + contrast — faint
+   ========================================================================== */
+
+.intentNeutral.contrastFaint  { background-color: var(--color-background-faint-neutral);  color: var(--color-foreground-bold-neutral);  }
+.intentBrand.contrastFaint    { background-color: var(--color-background-faint-brand);    color: var(--color-foreground-bold-brand);    }
+.intentAi.contrastFaint       { background-color: var(--color-background-faint-ai);       color: var(--color-foreground-bold-ai);       }
+.intentNegative.contrastFaint { background-color: var(--color-background-faint-negative); color: var(--color-foreground-bold-negative); }
+.intentWarning.contrastFaint  { background-color: var(--color-background-faint-warning);  color: var(--color-foreground-bold-warning);  }
+.intentCaution.contrastFaint  { background-color: var(--color-background-faint-caution);  color: var(--color-foreground-bold-caution);  }
+.intentPositive.contrastFaint { background-color: var(--color-background-faint-positive); color: var(--color-foreground-bold-positive); }
+
+/* ==========================================================================
+   Interactive (clickable / filter-chip)
+   ========================================================================== */
+
+.interactive {
+  cursor: pointer;
+  -webkit-user-select: none;
+  user-select: none;
+  outline: none;
+}
+
+.interactive:hover  { background-color: var(--_hover-bg); }
+.interactive:active { background-color: var(--_pressed-bg); }
+
+.interactive:focus-visible {
+  outline: var(--dimension-stroke-width-025) solid var(--color-interaction-focus);
+  outline-offset: var(--dimension-space-025);
+}
+
+/* ==========================================================================
+   Pressed / selected (filter-chip active state)
+   Always brand — same language as ToggleButton
+   ========================================================================== */
+
+.tag.pressed {
+  background-color: var(--color-background-faint-brand) !important;
+  color: var(--color-foreground-bold-brand) !important;
+  border-color: transparent !important;
+}
+
+/* ==========================================================================
+   Remove button — keeps ::before overlay for its own isolated hit area
+   ========================================================================== */
+
+.removable { gap: var(--dimension-space-025); }
+.sizeXs.removable { gap: 0; }
+
+.removeButton {
+  padding: 0; margin: 0; border: none; background: none;
+  display: flex; align-items: center; justify-content: center;
+  cursor: pointer; color: inherit; flex-shrink: 0;
+  position: relative; border-radius: var(--dimension-radius-050);
+}
+
+.removeButton::before {
+  content: ''; position: absolute; inset: -2px;
+  border-radius: var(--dimension-radius-025);
+  background-color: transparent;
+  transition: var(--effect-transition-interaction-background-short-2);
+  pointer-events: none;
+}
+
+.removeButton:hover::before  { background-color: var(--color-interaction-hover); }
+.removeButton:active::before { background-color: var(--color-interaction-pressed); }
+
+/* SM — 1px gap, inset -1px → 18×18 hover area */
+.sizeSm .removeButton::before { inset: -1px; border-radius: 3px; }
+
+/* XS — flush, inset 0 → 12×12 hover area matching tag radius */
+.sizeXs .removeButton::before { inset: 0; border-radius: var(--dimension-radius-050); }
+
+.rounded .removeButton,
+.rounded .removeButton::before { border-radius: var(--dimension-radius-half); }
+
+/* ==========================================================================
+   Disabled
+   ========================================================================== */
+
+.inactive { opacity: 0.5; pointer-events: none; cursor: not-allowed; }

package/src/components/Tag/Tag.stories.tsx

@@ -0,0 +1,399 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import React, { useState } from 'react';
+import { Tag } from './Tag';
+import { Surface } from '@/components/Surface';
+import type { TagIntent, TagContrast, TagElevation, TagSize, TagBackground } from './Tag';
+import type { IconComponent } from '@/types/icons';
+
+const PlaceholderIcon: IconComponent = ({ size = 16 }) => (
+  <svg width={size} height={size} viewBox="0 0 20 20" fill="currentColor">
+    <circle cx="10" cy="10" r="6" />
+  </svg>
+);
+
+const meta: Meta<typeof Tag> = {
+  title: 'Primitives (Reviewed)/Tag',
+  component: Tag,
+  args: {
+    label:     'Tag',
+    intent:    'neutral',
+    contrast:  'faint',
+    elevation: 'none',
+    size:      'md',
+    rounded:   false,
+    inactive:  false,
+  },
+  argTypes: {
+    intent:    { control: 'select', options: ['neutral', 'brand', 'ai', 'negative', 'warning', 'caution', 'positive'] },
+    contrast:  { control: 'select', options: ['strong', 'bold', 'medium', 'faint'] },
+    elevation: { control: 'select', options: ['none', 'flat', 'elevated'] },
+    size:      { control: 'select', options: ['md', 'sm', 'xs'] },
+    label:     { control: 'text' },
+    rounded:   { control: 'boolean' },
+    removable: { control: 'boolean' },
+    inactive:  { control: 'boolean' },
+    icon: {
+      control: 'boolean',
+      mapping: { true: PlaceholderIcon, false: undefined },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Tag>;
+
+export const Playground: Story = {};
+
+// ─── Matrix helpers ───────────────────────────────────────────────────────────
+
+const INTENTS:    TagIntent[]    = ['neutral', 'brand', 'ai', 'negative', 'warning', 'caution', 'positive'];
+const CONTRASTS:  TagContrast[]  = ['strong', 'bold', 'medium', 'faint'];
+const ELEVATIONS: TagElevation[] = ['none', 'flat', 'elevated'];
+const SIZES:      TagSize[]      = ['md', 'sm', 'xs'];
+
+const col: React.CSSProperties = { display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'flex-start' };
+const row: React.CSSProperties = { display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' };
+const lbl = (): React.CSSProperties => ({ fontSize: 10, fontFamily: 'monospace', color: '#888', minWidth: 80, flexShrink: 0 });
+const section = (text: string) => (
+  <div style={{ fontSize: 11, fontWeight: 600, letterSpacing: '0.05em', textTransform: 'uppercase', color: '#555', marginTop: 8 }}>
+    {text}
+  </div>
+);
+const divider = <hr style={{ border: 'none', borderTop: '1px solid #e0e0e0', margin: '16px 0' }} />;
+
+export const Matrix: Story = {
+  parameters: { layout: 'padded' },
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 0, fontFamily: 'sans-serif' }}>
+
+      {/* ── Intents × Contrasts — none ── */}
+      {section('Intents × Contrasts — elevation: none')}
+      <div style={{ ...col, marginTop: 12 }}>
+        <div style={row}>
+          <span style={lbl()}></span>
+          {CONTRASTS.map(c => <span key={c} style={{ ...lbl(), minWidth: 90 }}>{c}</span>)}
+        </div>
+        {INTENTS.map(intent => (
+          <div key={intent} style={row}>
+            <span style={lbl()}>{intent}</span>
+            {CONTRASTS.map(contrast => (
+              <Tag key={contrast} label={intent.charAt(0).toUpperCase() + intent.slice(1)} intent={intent} contrast={contrast} />
+            ))}
+          </div>
+        ))}
+      </div>
+
+      {divider}
+
+      {/* ── Intents × Contrasts — flat ── */}
+      {section('Intents × Contrasts — elevation: flat')}
+      <div style={{ ...col, marginTop: 12 }}>
+        {INTENTS.map(intent => (
+          <div key={intent} style={row}>
+            <span style={lbl()}>{intent}</span>
+            {CONTRASTS.map(contrast => (
+              <Tag key={contrast} label={intent.charAt(0).toUpperCase() + intent.slice(1)} intent={intent} contrast={contrast} elevation="flat" />
+            ))}
+          </div>
+        ))}
+      </div>
+
+      {divider}
+
+      {/* ── Sizes ── */}
+      {section('Sizes')}
+      <div style={{ ...col, marginTop: 12 }}>
+        {SIZES.map(size => (
+          <div key={size} style={row}>
+            <span style={lbl()}>{size}</span>
+            <Tag label="Label" size={size} intent="brand" />
+            <Tag label="Label" size={size} intent="brand" icon={PlaceholderIcon} />
+            <Tag label="Label" size={size} intent="brand" removable onRemove={() => {}} />
+            <Tag label="Label" size={size} intent="brand" icon={PlaceholderIcon} removable onRemove={() => {}} />
+          </div>
+        ))}
+      </div>
+
+      {divider}
+
+      {/* ── Sizes × Elevation ── */}
+      {section('Sizes × Elevation')}
+      <div style={{ ...col, marginTop: 12 }}>
+        {SIZES.map(size => (
+          <div key={size} style={row}>
+            <span style={lbl()}>{size}</span>
+            {ELEVATIONS.map(elevation => (
+              <Tag key={elevation} label={elevation} size={size} intent="brand" elevation={elevation} />
+            ))}
+          </div>
+        ))}
+      </div>
+
+      {divider}
+
+      {/* ── Rounded — content variants ── */}
+      {section('Rounded — content variants')}
+      <div style={{ ...col, marginTop: 12 }}>
+        {([
+          { combo: 'label only',       icon: false, removable: false },
+          { combo: 'icon + label',     icon: true,  removable: false },
+          { combo: 'removable',        icon: false, removable: true  },
+          { combo: 'icon + removable', icon: true,  removable: true  },
+        ] as const).map(({ combo, icon, removable }) => (
+          <div key={combo} style={row}>
+            <span style={lbl()}>{combo}</span>
+            {SIZES.map(size => (
+              <Tag
+                key={size}
+                label="Label"
+                size={size}
+                intent="brand"
+                rounded
+                icon={icon ? PlaceholderIcon : undefined}
+                removable={removable}
+                onRemove={removable ? () => {} : undefined}
+              />
+            ))}
+          </div>
+        ))}
+      </div>
+
+      {divider}
+
+      {/* ── Content variants × Intents ── */}
+      {section('Content variants × Intents')}
+      <div style={{ ...col, marginTop: 12 }}>
+        {([
+          { combo: 'label only',       icon: false, removable: false },
+          { combo: 'icon + label',     icon: true,  removable: false },
+          { combo: 'removable',        icon: false, removable: true  },
+          { combo: 'icon + removable', icon: true,  removable: true  },
+        ] as const).map(({ combo, icon, removable }) => (
+          <div key={combo} style={row}>
+            <span style={lbl()}>{combo}</span>
+            {INTENTS.map(intent => (
+              <Tag
+                key={intent}
+                label={intent.charAt(0).toUpperCase() + intent.slice(1)}
+                intent={intent}
+                icon={icon ? PlaceholderIcon : undefined}
+                removable={removable}
+                onRemove={removable ? () => {} : undefined}
+              />
+            ))}
+          </div>
+        ))}
+      </div>
+
+      {divider}
+
+      {/* ── Content variants × Elevations ── */}
+      {section('Content variants × Elevations')}
+      <div style={{ ...col, marginTop: 12 }}>
+        {([
+          { combo: 'label only',       icon: false, removable: false },
+          { combo: 'icon + label',     icon: true,  removable: false },
+          { combo: 'removable',        icon: false, removable: true  },
+          { combo: 'icon + removable', icon: true,  removable: true  },
+        ] as const).map(({ combo, icon, removable }) => (
+          <div key={combo} style={row}>
+            <span style={lbl()}>{combo}</span>
+            {ELEVATIONS.map(elevation => (
+              <Tag
+                key={elevation}
+                label="Label"
+                elevation={elevation}
+                intent="brand"
+                icon={icon ? PlaceholderIcon : undefined}
+                removable={removable}
+                onRemove={removable ? () => {} : undefined}
+              />
+            ))}
+          </div>
+        ))}
+      </div>
+
+      {divider}
+
+      {/* ── States ── */}
+      {section('States')}
+      <div style={{ ...col, marginTop: 12 }}>
+        {([
+          { label: 'default',  props: {} },
+          { label: 'rounded',  props: { rounded: true } },
+          { label: 'Inactive', props: { inactive: true } },
+          { label: 'elevated', props: { elevation: 'elevated' as const } },
+          { label: 'flat',     props: { elevation: 'flat' as const } },
+          { label: 'pressed',  props: { pressed: true } },
+        ]).map(({ label: stateLabel, props }) => (
+          <div key={stateLabel} style={row}>
+            <span style={lbl()}>{stateLabel}</span>
+            <Tag label="Label" intent="brand" {...(props as object)} />
+            <Tag label="Label" intent="negative" {...(props as object)} />
+          </div>
+        ))}
+      </div>
+
+    </div>
+  ),
+};
+
+// ─── Individual stories ───────────────────────────────────────────────────────
+
+export const Intents: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', alignItems: 'center' }}>
+      {INTENTS.map(intent => <Tag key={intent} label={intent.charAt(0).toUpperCase() + intent.slice(1)} intent={intent} />)}
+    </div>
+  ),
+};
+
+export const Contrasts: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+      <Tag label="Strong" contrast="strong" intent="brand" />
+      <Tag label="Bold"   contrast="bold"   intent="brand" />
+      <Tag label="Medium" contrast="medium" intent="brand" />
+      <Tag label="Faint"  contrast="faint"  intent="brand" />
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+      <Tag label="Medium"      size="md" intent="brand" />
+      <Tag label="Small"       size="sm" intent="brand" />
+      <Tag label="Extra Small" size="xs" intent="brand" />
+    </div>
+  ),
+};
+
+export const WithIcon: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', alignItems: 'center' }}>
+      {INTENTS.map(intent => <Tag key={intent} label={intent.charAt(0).toUpperCase() + intent.slice(1)} intent={intent} icon={PlaceholderIcon} />)}
+    </div>
+  ),
+};
+
+export const Removable: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+      <Tag label="Remove me" intent="brand"    removable onRemove={() => {}} />
+      <Tag label="Remove me" intent="negative" removable onRemove={() => {}} size="sm" />
+      <Tag label="Remove me" intent="positive" removable onRemove={() => {}} size="xs" />
+      <Tag label="With icon" intent="brand"    removable onRemove={() => {}} icon={PlaceholderIcon} />
+    </div>
+  ),
+};
+
+export const Flat: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', alignItems: 'center' }}>
+      {INTENTS.map(intent => <Tag key={intent} label={intent.charAt(0).toUpperCase() + intent.slice(1)} intent={intent} elevation="flat" />)}
+    </div>
+  ),
+};
+
+export const Elevation: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
+      <Tag label="none"     intent="brand" elevation="none" />
+      <Tag label="flat"     intent="brand" elevation="flat" />
+      <Tag label="elevated" intent="brand" elevation="elevated" />
+    </div>
+  ),
+};
+
+export const Interactive: Story = {
+  render: () => {
+    const [pressed, setPressed] = useState(false);
+    const [filters, setFilters] = useState<Record<string, boolean>>({
+      positive: false, negative: false, warning: false, brand: false, ai: false,
+    });
+    const toggle = (key: string) => setFilters(f => ({ ...f, [key]: !f[key] }));
+
+    return (
+      <div style={{ ...col, gap: 16 }}>
+        <div>
+          <div style={{ ...lbl(), marginBottom: 8 }}>Single toggle</div>
+          <Tag
+            label={pressed ? 'Selected' : 'Click me'}
+            intent="brand"
+            pressed={pressed}
+            onPressedChange={setPressed}
+          />
+        </div>
+        <div>
+          <div style={{ ...lbl(), marginBottom: 8 }}>Filter chips</div>
+          <div style={row}>
+            {(Object.keys(filters) as TagIntent[]).map(intent => (
+              <Tag
+                key={intent}
+                label={intent.charAt(0).toUpperCase() + intent.slice(1)}
+                intent={intent}
+                pressed={filters[intent]}
+                onPressedChange={() => toggle(intent)}
+              />
+            ))}
+          </div>
+        </div>
+        <div>
+          <div style={{ ...lbl(), marginBottom: 8 }}>Click only (no toggle)</div>
+          <Tag label="Click me" intent="neutral" onClick={() => alert('clicked')} />
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Inactive: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+      <Tag label="Inactive"         intent="brand" inactive />
+      <Tag label="Inactive remove"  intent="brand" inactive removable onRemove={() => {}} />
+      <Tag label="Inactive flat"    intent="brand" inactive elevation="flat" />
+    </div>
+  ),
+};
+
+// ─── Background Context ──────────────────────────────────────────────────────
+
+const TAG_BG_CONTEXTS: { bg: TagBackground; contrast: 'faint' | 'medium' | 'bold' | 'strong' }[] = [
+  { bg: 'faint',  contrast: 'faint'  },
+  { bg: 'medium', contrast: 'medium' },
+  { bg: 'bold',   contrast: 'bold'   },
+  { bg: 'strong', contrast: 'strong' },
+];
+
+export const BackgroundContext: Story = {
+  parameters: { layout: 'padded' },
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 24 }}>
+      {TAG_BG_CONTEXTS.map(({ bg, contrast }) => (
+        <Surface key={bg} intent="neutral" contrast={contrast} radius="md" style={{ padding: 20 }}>
+          <span style={{ fontSize: 10, fontFamily: 'monospace', opacity: 0.7, display: 'block', marginBottom: 12 }}>
+            background="{bg}" — interactive tags, hover to test
+          </span>
+          <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', alignItems: 'center' }}>
+            <Tag label="Brand"    intent="brand"    background={bg} onClick={() => {}} />
+            <Tag label="Neutral"  intent="neutral"  background={bg} onClick={() => {}} />
+            <Tag label="Negative" intent="negative" background={bg} onClick={() => {}} />
+            <Tag label="With Icon" intent="brand"   background={bg} onClick={() => {}} icon={PlaceholderIcon} />
+            <Tag label="Removable" intent="brand"   background={bg} removable onRemove={() => {}} />
+          </div>
+        </Surface>
+      ))}
+      <div style={{ background: '#1a1a2e', borderRadius: 8, padding: 20 }}>
+        <span style={{ fontSize: 10, fontFamily: 'monospace', color: 'rgba(255,255,255,0.5)', display: 'block', marginBottom: 12 }}>
+          background="always-dark"
+        </span>
+        <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', alignItems: 'center' }}>
+          <Tag label="Brand"   intent="brand"   background="always-dark" onClick={() => {}} />
+          <Tag label="Neutral" intent="neutral" background="always-dark" onClick={() => {}} />
+        </div>
+      </div>
+    </div>
+  ),
+};