@lovett/ui 0.0.4 → 0.0.6

package/src/theme-v2.css

@@ -0,0 +1,466 @@
+/*
+ * @lovett/ui — v2 theme, SCOPED.
+ *
+ * ─────────────────────────────────────────────────────────────────────
+ * SUPERSEDED FOR NEW WORK by `src/v2/theme.css`.
+ *
+ * That file is the OKLCH design layer: a namespaced `--lv-*` token set,
+ * an explicit surface ladder, elevation as shadow + inner highlight, and
+ * both appearances driven by `prefers-color-scheme` AND `data-theme`.
+ * New surfaces should import it and use `@lovett/ui/v2`.
+ *
+ * ── THAT DIRECTIVE IS NO LONGER TRUE (2026-08-20) ─────────────────────────
+ * `@lovett/ui/v2` is NOT EXPORTED any more. The `./v2`, `./v2/theme.css` and
+ * `./v2/__demo__/showcase` entries were removed from `package.json` under
+ * ADR-CE-0027 D6 step 5, on the owner's decision, after a search that reaches
+ * gitignored trees confirmed **zero consumers family-wide**. It cleared four
+ * name collisions (`EmptyState`, `EmptyStateProps`, `Panel`, `Toolbar`).
+ *
+ * NO SOURCE WAS DELETED. `src/v2/` is intact and the removal is three lines of
+ * `exports` to restore, which is why it was done this way rather than by
+ * deleting components.
+ *
+ * THIS FILE STAYS AND IS STILL LIVE — two ignite worktrees import it as
+ * `@lovett/ui/theme-v2.css` in their `index.css`. Do not confuse it with
+ * `src/v2/theme.css`, which is a different, larger file and is the one that
+ * went unexported.
+ *
+ * Consequence to know about: the v2 BRIDGE below (section 3) maps `--lv-*` so
+ * v2 primitives render in a `data-ds="v2"` subtree. With no public `./v2`
+ * entry, nothing can import those primitives, so the bridge is inert. It is
+ * left in place because it is harmless, because removing it is the source
+ * surgery this change deliberately avoided, and because it becomes live again
+ * the moment the exports are restored.
+ *
+ * This file stays because live consumers depend on it. Everything ABOVE
+ * the "APPENDED" marker near the bottom is untouched and still generated
+ * — every existing declaration resolves to exactly the value it always
+ * did. The appended region is hand-authored and additive: it bridges
+ * this scope onto the v2 token names and adds the automatic-dark support
+ * this file never had. If you re-run the generator, re-apply that region.
+ * ─────────────────────────────────────────────────────────────────────
+ *
+ * GENERATED (region above the marker). Regenerate with:
+ *   python3 scripts/figma/emit-theme.py <corpus> --out packages/ui/src/theme-v2.css
+ *
+ * Opt in by putting `data-ds="v2"` on any element. Everything inside it
+ * renders on the v2 palette, including existing @lovett/ui primitives —
+ * they read the same token names, which now resolve to different values.
+ * Nothing outside the scope changes.
+ *
+ * Derived from a 13-kit Figma corpus; see docs/design-system/figma-corpus/.
+ * The direction is Vertex Lab: pure-white trays, near-neutral greys, a
+ * navy-tinted ink used as a SURFACE and not only as text.
+ *
+ * The semantic reassignment is the load-bearing change:
+ *   --accent       red    brand identity and the primary action, nothing else
+ *   --success      green  save, publish, approve, live
+ *   --destructive  AMBER  destructive. No longer red.
+ *   --warning      gold   caution
+ *   --info         violet
+ *
+ * Consequence worth knowing before adopting: amber is a weaker danger
+ * signal than red, so destructive actions must carry an icon and an
+ * explicit verb. Colour alone no longer does that work.
+ */
+
+[data-ds="v2"] {
+  /* ── Surfaces ─────────────────────────────────────────────── */
+  /* The frame/tray step is 2.1 pts — ratified as `medium`. Both being
+     white removes the distinction the card pattern is built on. */
+  --page-bg: 240 241 242;
+  --background: 240 241 242;
+  --main-content-bg: 240 241 242;
+  --bg-surface: 248 248 249;
+  --surface-frame: 248 248 249;
+  --card-frame-bg: 248 248 249;
+  --bg-card: 255 255 255;
+  --card: 255 255 255;
+  --tray-bg: 255 255 255;
+  --bg-elevated: 255 255 255;
+  --surface-raised: 255 255 255;
+  --popover: 255 255 255;
+  --bg-input: 255 255 255;
+  --bg-card-hover: 250 251 252;
+  --bg-input-hover: 250 251 252;
+  --muted: 246 247 248;
+  --canvas-placement-bg: 246 247 248;
+
+  /* ── Ink ──────────────────────────────────────────────────── */
+  /* Navy-tinted, not black. Vertex uses #1c274c 6,522 times — far too
+     many for text: it is a panel colour, so it gets a full ramp. */
+  --ink-15: 253 253 253;
+  --ink-25: 250 251 254;
+  --ink-30: 247 248 252;
+  --ink-40: 241 245 253;
+  --ink-60: 235 241 254;
+  --ink-50: 243 247 255;
+  --ink-100: 229 237 254;
+  --ink-200: 207 217 238;
+  --ink-300: 182 193 217;
+  --ink-400: 150 163 191;
+  --ink-500: 119 134 165;
+  --ink-600: 93 108 140;
+  --ink-700: 70 82 109;
+  --ink-800: 48 58 80;
+  --ink-900: 27 35 51;
+  --ink-950: 11 16 28;
+  --foreground: 11 16 28;
+  --card-foreground: 11 16 28;
+  --popover-foreground: 11 16 28;
+  --text-secondary: 93 108 140;
+  --muted-foreground: 93 108 140;
+  --text-tertiary: 119 134 165;
+  --text-muted: 150 163 191;
+  --secondary: 246 247 248;
+  --secondary-foreground: 11 16 28;
+
+  /* ── Borders ──────────────────────────────────────────────── */
+  /* Structure only. Depth is shadow — a hard hairline on a depth
+     surface reads as a form field. Inputs keep theirs deliberately. */
+  --border: 0 0 0 / 0.05;
+  --border-strong: 0 0 0 / 0.10;
+  --border-card: 0 0 0 / 0.06;
+  --border-input: 0 0 0 / 0.12;
+  --main-content-border: 0 0 0 / 0.06;
+  --input: 246 247 248;
+
+  /* ── Brand ────────────────────────────────────────────────── */
+  /* --accent is the AA-safe action red (4.77:1 with white). The bright
+     step is 4.01:1 and cannot carry a white label, so it is exposed
+     separately for accents, marks, charts and active fills. */
+  --accent: 221 40 34;
+  --accent-bright: 228 70 58;
+  --accent-hover: 201 17 17;
+  --accent-muted: 228 70 58 / 0.10;
+  --accent-subtle: 228 70 58 / 0.05;
+  --accent-glow: 228 70 58 / 0.22;
+  --primary: 221 40 34;
+  --primary-hover: 201 17 17;
+  --primary-foreground: 255 255 255;
+  --ring: 221 40 34;
+  --brand-15: 253 253 253;
+  --brand-25: 252 251 250;
+  --brand-30: 252 247 246;
+  --brand-40: 255 242 240;
+  --brand-60: 254 237 234;
+  --brand-50: 255 244 242;
+  --brand-100: 253 231 228;
+  --brand-200: 253 204 196;
+  --brand-300: 254 166 154;
+  --brand-400: 251 114 99;
+  --brand-500: 228 70 58;
+  --brand-600: 201 17 17;
+  --brand-700: 157 8 9;
+  --brand-800: 114 4 4;
+  --brand-900: 72 2 2;
+  --brand-950: 41 0 0;
+
+  /* ── Semantic — REASSIGNED ────────────────────────────────── */
+  --success: 13 128 75;
+  --success-bg: 6 160 93 / 0.12;
+  --warning: 100 80 1;
+  --warning-bg: 161 131 18 / 0.14;
+  /* Amber. The collision between a red brand and a red danger state
+     cannot be solved by moving the hue — every credible danger red
+     sits within a few degrees of the brand. Moving the MEANING can. */
+  --destructive: 115 71 9;
+  --destructive-bg: 187 116 2 / 0.14;
+  --destructive-foreground: 255 255 255;
+  --info: 130 62 210;
+  --info-bg: 155 97 235 / 0.12;
+
+  /* ── Categorical series ───────────────────────────────────── */
+  /* Constant lightness so no series outranks another; chroma tuned per
+     hue so each is equally vivid rather than equally saturated. */
+  --series-1: 226 74 62;
+  --series-2: 153 100 229;
+  --series-3: 9 160 93;
+  --series-4: 186 116 4;
+  --series-5: 2 137 234;
+  --series-6: 14 154 148;
+  --series-7: 212 73 150;
+  --series-8: 113 149 3;
+
+  /* ── Elevation ────────────────────────────────────────────── */
+  --shadow-sm: 0 0 0 1px oklch(0 0 0 / 0.06), 0 1px 2px -1px oklch(0 0 0 / 0.06), 0 2px 4px 0 oklch(0 0 0 / 0.04);
+  --shadow-md: 0 0 0 1px oklch(0 0 0 / 0.06), 0 2px 4px -2px oklch(0 0 0 / 0.08), 0 4px 10px -2px oklch(0 0 0 / 0.06);
+  --shadow-lg: 0 0 0 1px oklch(0 0 0 / 0.06), 0 6px 16px -4px oklch(0 0 0 / 0.12);
+  --shadow-xl: 0 0 0 1px oklch(0 0 0 / 0.06), 0 12px 32px -8px oklch(0 0 0 / 0.18);
+  --shadow-2xl: 0 0 0 1px oklch(0 0 0 / 0.06), 0 24px 56px -12px oklch(0 0 0 / 0.24);
+  --shadow-glow: 0 0 20px oklch(0 0 0 / 0);
+  --card-shadow-rest: 0 0 0 1px oklch(0 0 0 / 0.06), 0 1px 2px -1px oklch(0 0 0 / 0.06), 0 2px 4px 0 oklch(0 0 0 / 0.04), inset 0 1px 0 0 oklch(1 0 0 / 0.9);
+  --card-shadow-hover: 0 0 0 1px oklch(0 0 0 / 0.08), 0 2px 4px -1px oklch(0 0 0 / 0.08), 0 6px 14px -2px oklch(0 0 0 / 0.08), inset 0 1px 0 0 oklch(1 0 0 / 0.9);
+  --inset-highlight: 255 255 255 / 0.9;
+  --modal-overlay: 0 0 0 / 0.32;
+  --ring-focus: 0 0 0 3px rgb(221 40 34 / 0.22);
+  --ring-error: 0 0 0 3px rgb(151 93 1 / 0.22);
+}
+
+/*
+ * Dark. Derived by SELECTING different steps from the same OKLCH ramps,
+ * not by inverting the light values — mechanical inversion is what
+ * produces muddy dark modes. The ink ramp supplies the surfaces here,
+ * which is the same navy that supplies the text in light.
+ */
+[data-ds="v2"][data-theme="dark"] {
+  --page-bg: 11 16 28;
+  --background: 11 16 28;
+  --main-content-bg: 11 16 28;
+  --bg-surface: 27 35 51;
+  --surface-frame: 27 35 51;
+  --card-frame-bg: 27 35 51;
+  --bg-card: 48 58 80;
+  --card: 48 58 80;
+  --tray-bg: 48 58 80;
+  --bg-elevated: 70 82 109;
+  --surface-raised: 70 82 109;
+  --popover: 70 82 109;
+  --bg-input: 27 35 51;
+  --bg-card-hover: 70 82 109;
+  --bg-input-hover: 48 58 80;
+  --muted: 48 58 80;
+  --canvas-placement-bg: 27 35 51;
+  --foreground: 250 251 252;
+  --card-foreground: 250 251 252;
+  --popover-foreground: 250 251 252;
+  --text-secondary: 192 193 195;
+  --muted-foreground: 192 193 195;
+  --text-tertiary: 162 163 165;
+  --text-muted: 133 134 136;
+  --secondary: 48 58 80;
+  --secondary-foreground: 250 251 252;
+  --border: 255 255 255 / 0.08;
+  --border-strong: 255 255 255 / 0.14;
+  --border-card: 255 255 255 / 0.08;
+  --border-input: 255 255 255 / 0.14;
+  --main-content-border: 255 255 255 / 0.08;
+  /* Accents brighten in dark — the light-mode steps go muddy on a dark
+     surface because the surrounding lightness has moved. */
+  --accent: 228 70 58;
+  --accent-bright: 251 114 99;
+  --accent-hover: 251 114 99;
+  --primary: 228 70 58;
+  --primary-hover: 251 114 99;
+  --success: 80 188 126;
+  --warning: 190 160 64;
+  --destructive: 218 145 55;
+  --info: 181 134 254;
+  --success-bg: 6 160 93 / 0.16;
+  --warning-bg: 161 131 18 / 0.16;
+  --destructive-bg: 187 116 2 / 0.16;
+  --info-bg: 155 97 235 / 0.16;
+  /* Layered depth shadows are invisible on dark; a single ring reads. */
+  --shadow-sm: 0 0 0 1px oklch(1 0 0 / 0.08);
+  --shadow-md: 0 0 0 1px oklch(1 0 0 / 0.08), 0 4px 12px oklch(0 0 0 / 0.4);
+  --shadow-lg: 0 0 0 1px oklch(1 0 0 / 0.08), 0 8px 24px oklch(0 0 0 / 0.5);
+  --shadow-xl: 0 0 0 1px oklch(1 0 0 / 0.10), 0 16px 40px oklch(0 0 0 / 0.55);
+  --shadow-2xl: 0 0 0 1px oklch(1 0 0 / 0.10), 0 24px 60px oklch(0 0 0 / 0.6);
+  --card-shadow-rest: 0 0 0 1px oklch(1 0 0 / 0.08);
+  --card-shadow-hover: 0 0 0 1px oklch(1 0 0 / 0.14);
+  --inset-highlight: 255 255 255 / 0.05;
+  --modal-overlay: 0 0 0 / 0.7;
+  --ring-focus: 0 0 0 3px rgb(228 70 58 / 0.3);
+}
+
+/* ══════════════════════════════════════════════════════════════════════
+   ═══════════════════════════ APPENDED ═══════════════════════════════
+   Hand-authored, additive. Nothing above this line was changed.
+   Three things this region adds:
+
+     1. AUTOMATIC DARK. The generated file only goes dark on an explicit
+        `data-theme="dark"`. A surface that wants to follow the OS opts
+        in with `data-theme="auto"`; the block below is a verbatim copy
+        of the explicit-dark map, because a media query and an attribute
+        selector cannot share a rule. Keep the two in sync.
+
+     2. THE SURFACE LADDER, as first-class names. The generated file
+        encodes the ladder implicitly across a dozen aliases
+        (--page-bg / --bg-surface / --bg-card / --tray-bg ...). These
+        five names say what the tier IS, which is what a component
+        should be reading.
+
+     3. A BRIDGE to the v2 `--lv-*` tokens, so `@lovett/ui/v2`
+        primitives render correctly inside an existing `data-ds="v2"`
+        subtree without also loading `src/v2/theme.css`. Migration can
+        then happen one component at a time.
+   ══════════════════════════════════════════════════════════════════════ */
+
+/* ── 1. Automatic dark (opt-in via data-theme="auto") ─────────────── */
+
+@media (prefers-color-scheme: dark) {
+  [data-ds='v2'][data-theme='auto'] {
+    color-scheme: dark;
+
+    --page-bg: 11 16 28;
+    --background: 11 16 28;
+    --main-content-bg: 11 16 28;
+    --bg-surface: 27 35 51;
+    --surface-frame: 27 35 51;
+    --card-frame-bg: 27 35 51;
+    --bg-card: 48 58 80;
+    --card: 48 58 80;
+    --tray-bg: 48 58 80;
+    --bg-elevated: 70 82 109;
+    --surface-raised: 70 82 109;
+    --popover: 70 82 109;
+    --bg-input: 27 35 51;
+    --bg-card-hover: 70 82 109;
+    --bg-input-hover: 48 58 80;
+    --muted: 48 58 80;
+    --canvas-placement-bg: 27 35 51;
+    --foreground: 250 251 252;
+    --card-foreground: 250 251 252;
+    --popover-foreground: 250 251 252;
+    --text-secondary: 192 193 195;
+    --muted-foreground: 192 193 195;
+    --text-tertiary: 162 163 165;
+    --text-muted: 133 134 136;
+    --secondary: 48 58 80;
+    --secondary-foreground: 250 251 252;
+    --border: 255 255 255 / 0.08;
+    --border-strong: 255 255 255 / 0.14;
+    --border-card: 255 255 255 / 0.08;
+    --border-input: 255 255 255 / 0.14;
+    --main-content-border: 255 255 255 / 0.08;
+    --accent: 228 70 58;
+    --accent-bright: 251 114 99;
+    --accent-hover: 251 114 99;
+    --primary: 228 70 58;
+    --primary-hover: 251 114 99;
+    --success: 80 188 126;
+    --warning: 190 160 64;
+    --destructive: 218 145 55;
+    --info: 181 134 254;
+    --success-bg: 6 160 93 / 0.16;
+    --warning-bg: 161 131 18 / 0.16;
+    --destructive-bg: 187 116 2 / 0.16;
+    --info-bg: 155 97 235 / 0.16;
+    --shadow-sm: 0 0 0 1px oklch(1 0 0 / 0.08);
+    --shadow-md: 0 0 0 1px oklch(1 0 0 / 0.08), 0 4px 12px oklch(0 0 0 / 0.4);
+    --shadow-lg: 0 0 0 1px oklch(1 0 0 / 0.08), 0 8px 24px oklch(0 0 0 / 0.5);
+    --shadow-xl: 0 0 0 1px oklch(1 0 0 / 0.1), 0 16px 40px oklch(0 0 0 / 0.55);
+    --shadow-2xl: 0 0 0 1px oklch(1 0 0 / 0.1), 0 24px 60px oklch(0 0 0 / 0.6);
+    --card-shadow-rest: 0 0 0 1px oklch(1 0 0 / 0.08);
+    --card-shadow-hover: 0 0 0 1px oklch(1 0 0 / 0.14);
+    --inset-highlight: 255 255 255 / 0.05;
+    --modal-overlay: 0 0 0 / 0.7;
+    --ring-focus: 0 0 0 3px rgb(228 70 58 / 0.3);
+  }
+}
+
+/* `data-theme` must win in BOTH directions: forced light under a dark OS
+   is as much a requirement as forced dark under a light one. The two
+   explicit values are already unconditional rules, so they beat the
+   media query above by source order; this only declares the native
+   `color-scheme` so form controls and scrollbars agree. */
+[data-ds='v2'][data-theme='light'] {
+  color-scheme: light;
+}
+[data-ds='v2'][data-theme='dark'] {
+  color-scheme: dark;
+}
+
+/* ── 2. The surface ladder, named ─────────────────────────────────── */
+/* page → shell → section → card, each one notch brighter; `inset` goes
+   the other way, because a recessed panel inside a card is the system's
+   strongest single move and it only reads as recessed if it is darker.
+   Aliases, not new values — these resolve to what the tiers already are. */
+
+[data-ds='v2'] {
+  --surface-page: rgb(var(--page-bg));
+  --surface-shell: rgb(var(--bg-surface));
+  --surface-section: rgb(var(--muted));
+  --surface-card: rgb(var(--bg-card));
+  --surface-inset: rgb(var(--canvas-placement-bg));
+}
+
+@media (prefers-color-scheme: dark) {
+  [data-ds='v2'][data-theme='auto'] {
+    --surface-section: rgb(27 35 51);
+    --surface-inset: rgb(27 35 51);
+  }
+}
+
+[data-ds='v2'][data-theme='dark'] {
+  --surface-section: rgb(27 35 51);
+  --surface-inset: rgb(27 35 51);
+}
+
+/* ── 3. Bridge to the v2 `--lv-*` tokens ──────────────────────────── */
+/* Lets `@lovett/ui/v2` primitives render inside this scope. Only the
+   tokens v2 components actually read are mapped; the scales (space,
+   radius, type, motion) are appearance-independent and are defined
+   unconditionally in `src/v2/theme.css`, which must still be imported
+   for those. This block covers colour and depth only — the parts that
+   have to agree with whichever theme the subtree is on. */
+
+[data-ds='v2'] {
+  --lv-surface-page: var(--surface-page);
+  --lv-surface-shell: var(--surface-shell);
+  --lv-surface-section: var(--surface-section);
+  --lv-surface-card: var(--surface-card);
+  --lv-surface-inset: var(--surface-inset);
+  --lv-surface-raised: rgb(var(--surface-raised));
+  --lv-surface-overlay: rgb(var(--modal-overlay));
+  --lv-surface-hover: rgb(var(--bg-card-hover));
+  --lv-surface-active: rgb(var(--border-strong));
+  --lv-surface-selected: rgb(var(--accent-muted));
+
+  --lv-text-primary: rgb(var(--foreground));
+  --lv-text-secondary: rgb(var(--text-secondary));
+  --lv-text-tertiary: rgb(var(--text-tertiary));
+  --lv-text-faint: rgb(var(--text-muted));
+  --lv-text-disabled: rgb(var(--text-muted));
+  --lv-text-on-accent: rgb(var(--primary-foreground));
+
+  --lv-hairline: rgb(var(--border));
+  --lv-hairline-strong: rgb(var(--border-strong));
+  --lv-border-field: rgb(var(--border-input));
+
+  --lv-accent: rgb(var(--accent));
+  --lv-accent-hover: rgb(var(--accent-hover));
+  --lv-accent-active: rgb(var(--accent-hover));
+  --lv-accent-text: rgb(var(--accent));
+  --lv-accent-mark: rgb(var(--accent-bright));
+  --lv-accent-soft: rgb(var(--accent-muted));
+  --lv-accent-rule: rgb(var(--accent-glow));
+  --lv-focus: rgb(var(--ring));
+
+  /* The generated palette's semantic reassignment carries straight over:
+     success green, warning gold, destructive amber, info violet. v2's
+     own danger hue (48°) was chosen for the same reason this file moved
+     destructive off red — the brand is red, and two reds on one page
+     cannot be told apart. */
+  --lv-success-text: rgb(var(--success));
+  --lv-success-mark: rgb(var(--success));
+  --lv-success-soft: rgb(var(--success-bg));
+  --lv-success-rule: rgb(var(--success));
+
+  --lv-warning-text: rgb(var(--warning));
+  --lv-warning-mark: rgb(var(--warning));
+  --lv-warning-soft: rgb(var(--warning-bg));
+  --lv-warning-rule: rgb(var(--warning));
+
+  --lv-danger-text: rgb(var(--destructive));
+  --lv-danger-mark: rgb(var(--destructive));
+  --lv-danger-soft: rgb(var(--destructive-bg));
+  --lv-danger-rule: rgb(var(--destructive));
+
+  --lv-info-text: rgb(var(--info));
+  --lv-info-mark: rgb(var(--info));
+  --lv-info-soft: rgb(var(--info-bg));
+  --lv-info-rule: rgb(var(--info));
+
+  --lv-highlight: inset 0 1px 0 0 rgb(var(--inset-highlight));
+  --lv-elev-0: none;
+  --lv-elev-1: var(--shadow-sm);
+  --lv-elev-2: var(--shadow-md);
+  --lv-elev-3: var(--shadow-lg);
+  --lv-elev-4: var(--shadow-xl);
+  --lv-elev-inset: inset 0 1px 2px 0 oklch(0 0 0 / 0.07),
+    inset 0 0 0 1px rgb(var(--border));
+
+  --lv-skeleton-base: rgb(var(--border-strong));
+  --lv-skeleton-sheen: rgb(var(--border));
+}

package/src/token-badge.tsx

@@ -0,0 +1,92 @@
+/**
+ * TokenBadge — tinted, token-driven category badge.
+ *
+ * Promoted in ADR-123 (Budget Flighting redesign) from the lens-local
+ * `TacticBadge`. Distinct from `<Badge>`: Badge carries only the 6 fixed
+ * semantic tones (success / warning / …); TokenBadge tints from ANY public
+ * token base name, so a categorical palette like `--folder-*` (tactic colors,
+ * flight-group colors) works. The lens keeps a thin `TacticBadge` wrapper that
+ * passes the matching `--folder-*` token.
+ *
+ * Token discipline: the only color input is a public token *name*; fill/border/
+ * text are derived from it via `rgb(var(--token) / a)`. No literals.
+ */
+
+import type { ReactNode } from 'react'
+
+import { cn } from './lib/utils'
+
+export interface TokenBadgeProps {
+  /** Public token name to tint from, e.g. `--folder-teal`, `--accent`,
+   *  `--success`. Must include the leading `--`. */
+  colorVar: string
+  children: ReactNode
+  /** `soft` = tinted fill (default). `outline` = transparent fill + tinted
+   *  border. */
+  variant?: 'soft' | 'outline'
+  /** Optional leading status dot in the token color. Ignored when `icon` set. */
+  dot?: boolean
+  /** Optional leading icon (12–14px expected). */
+  icon?: ReactNode
+  /** `sm` (10px) · `md` (11px, default) · `lg` (12px, taller). */
+  size?: 'sm' | 'md' | 'lg'
+  /** Pill (`full`) vs squared category tag (`tag`, default). */
+  shape?: 'tag' | 'pill'
+  /** Uppercase + wider tracking for short category codes (PRG, YT…). */
+  uppercase?: boolean
+  className?: string
+}
+
+const SIZE_CLASS: Record<NonNullable<TokenBadgeProps['size']>, string> = {
+  sm: 'h-[18px] px-1.5 text-[10px]',
+  md: 'h-5 px-2 text-[11px]',
+  lg: 'h-[22px] px-2.5 text-xs',
+}
+
+export function TokenBadge({
+  colorVar,
+  children,
+  variant = 'soft',
+  dot = false,
+  icon,
+  size = 'md',
+  shape = 'tag',
+  uppercase = false,
+  className,
+}: TokenBadgeProps) {
+  const solid = `rgb(var(${colorVar}))`
+  const style =
+    variant === 'outline'
+      ? {
+          background: 'transparent',
+          color: solid,
+          boxShadow: `inset 0 0 0 1px rgb(var(${colorVar}) / 0.4)`,
+        }
+      : { background: `rgb(var(${colorVar}) / 0.12)`, color: solid }
+
+  return (
+    <span
+      className={cn(
+        'inline-flex w-fit shrink-0 items-center gap-1 font-bold whitespace-nowrap',
+        uppercase && 'uppercase tracking-[0.06em]',
+        SIZE_CLASS[size],
+        className,
+      )}
+      style={{
+        ...style,
+        borderRadius:
+          shape === 'pill' ? 'var(--radius-full)' : 'var(--radius-xs)',
+      }}
+    >
+      {dot && !icon ? (
+        <span
+          aria-hidden
+          className="size-1.5 shrink-0 rounded-full"
+          style={{ background: 'currentColor' }}
+        />
+      ) : null}
+      {icon && <span className="flex shrink-0 items-center">{icon}</span>}
+      {children}
+    </span>
+  )
+}