@elabs-ai/components-ui 4.1.0 → 5.0.0

package/src/components/badge/badge.stories.tsx

@@ -1,3 +1,4 @@
+import type { CSSProperties } from "react";
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { Badge } from "./badge";
 
@@ -21,6 +22,15 @@ const meta = {
       options: ["default", "secondary", "outline", "success", "warning", "destructive", "info"],
       table: { category: "Appearance" },
     },
+    appearance: {
+      description:
+        "Explicit fill/border/ink treatment override. Unset (default) renders no " +
+        "`data-appearance` attribute, so the ancestor `--badge-appearance` token decides " +
+        "(`auto` = today's look). Meaningful only on the colour-bearing variants.",
+      control: { type: "select" },
+      options: [undefined, "tint", "solid", "outline", "neutral"],
+      table: { category: "Appearance" },
+    },
     children: {
       description: "Badge label content.",
       control: "text",
@@ -50,3 +60,55 @@ export const Statuses: Story = {
     </div>
   ),
 };
+
+/**
+ * The four explicit `appearance` overrides (`tint`/`solid`/`outline`/`neutral`)
+ * on every colour-bearing variant — each renders a `data-appearance` attribute
+ * and a fixed fill/border/ink recipe regardless of the ancestor
+ * `--badge-appearance` token. `secondary`/`outline` are already a neutral pill
+ * and an outline respectively, so `appearance` has no additional effect there.
+ */
+export const Appearances: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      {(["tint", "solid", "outline", "neutral"] as const).map((appearance) => (
+        <div key={appearance} className="flex flex-wrap items-center gap-2">
+          <span className="w-16 text-caption text-muted-foreground">{appearance}</span>
+          <Badge appearance={appearance}>Default</Badge>
+          <Badge appearance={appearance} variant="success">
+            Success
+          </Badge>
+          <Badge appearance={appearance} variant="warning">
+            Warning
+          </Badge>
+          <Badge appearance={appearance} variant="destructive">
+            Error
+          </Badge>
+          <Badge appearance={appearance} variant="info">
+            Info
+          </Badge>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+/**
+ * With no explicit `appearance` prop, an ancestor's `--badge-appearance`
+ * token (a theme, or a region wrapper) drives the treatment instead — the
+ * badges below carry no `data-appearance` attribute at all.
+ */
+export const TokenDrivenAppearance: Story = {
+  render: () => (
+    <div
+      className="flex flex-wrap gap-2"
+      style={{ "--badge-appearance": "solid" } as CSSProperties}
+    >
+      <Badge>Default</Badge>
+      <Badge variant="success">Success</Badge>
+      <Badge variant="warning">Warning</Badge>
+      <Badge variant="destructive">Error</Badge>
+      <Badge variant="info">Info</Badge>
+    </div>
+  ),
+};

package/src/components/badge/badge.test.tsx

@@ -1,3 +1,4 @@
+import { createRef } from "react";
 import { describe, expect, it } from "vitest";
 import { render, screen } from "@testing-library/react";
 import { Badge } from "./badge";
@@ -7,4 +8,32 @@ describe("Badge", () => {
     render(<Badge>New</Badge>);
     expect(screen.getByText("New")).toBeInTheDocument();
   });
+
+  it("forwards its ref to the rendered <span>", () => {
+    const ref = createRef<HTMLSpanElement>();
+    render(<Badge ref={ref}>New</Badge>);
+    expect(ref.current).toBeInstanceOf(HTMLSpanElement);
+    expect(ref.current).toBe(screen.getByText("New"));
+  });
+
+  it("renders no data-appearance attribute when appearance is unset", () => {
+    render(<Badge>New</Badge>);
+    expect(screen.getByText("New")).not.toHaveAttribute("data-appearance");
+  });
+
+  it("renders data-appearance when an explicit appearance is passed", () => {
+    render(<Badge appearance="solid">New</Badge>);
+    expect(screen.getByText("New")).toHaveAttribute("data-appearance", "solid");
+  });
+
+  it("carries the appearance recipe classes on a colour-bearing variant", () => {
+    render(
+      <Badge appearance="tint" variant="success">
+        New
+      </Badge>,
+    );
+    const badge = screen.getByText("New");
+    expect(badge.classList.contains("badge-tint:bg-(--badge-fill)/10")).toBe(true);
+    expect(badge.classList.contains("[--badge-fill:var(--success)]")).toBe(true);
+  });
 });

package/src/components/badge/badge.tsx

@@ -1,28 +1,118 @@
-import { type HTMLAttributes } from "react";
+import { forwardRef, type HTMLAttributes } from "react";
 import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../../lib/cn";
 
+/**
+ * The four opt-in treatments a colour-bearing badge can take, gated purely by
+ * CSS (`themes.css`'s `badge-tint`/`badge-solid`/`badge-outline`/
+ * `badge-neutral` custom variants): each fires when the element carries the
+ * matching `data-appearance` attribute (the explicit `appearance` prop), OR
+ * carries none and an ancestor's `--badge-appearance` token resolves to that
+ * value (a container style query — set the token on a THEME/region, never on
+ * the badge itself). With no explicit prop and the default token (`auto`),
+ * none of the four match, so the unprefixed recipe below (today's exact
+ * look) renders unchanged.
+ *
+ * `tint`/`outline`/`neutral` read `--badge-ink` (a `-text` token — coloured
+ * TEXT on an ordinary surface, ≥4.5:1); `solid` reads `--badge-on` (a
+ * `-foreground` token — ink for a SOLID plate ONLY, never a wash), per the
+ * status-rung convention. Each colour-bearing variant below sets
+ * `--badge-fill`/`--badge-ink`/`--badge-on` from its own tokens; a variant
+ * that never sets them (`secondary`, already a neutral pill; `outline`,
+ * already an outline with no colour role) does not receive these classes —
+ * `appearance` has no additional effect there.
+ *
+ * Literal strings, not built via interpolation — Tailwind scans source
+ * statically, so a template-literal class would emit no CSS (see
+ * `status-badge.tsx`'s `STATUS_ROLE` docblock for the same rule).
+ */
+const BADGE_APPEARANCE_TINT =
+  "badge-tint:bg-(--badge-fill)/10 badge-tint:border-(--badge-fill)/40 badge-tint:text-(--badge-ink)";
+const BADGE_APPEARANCE_SOLID =
+  "badge-solid:bg-(--badge-fill) badge-solid:border-transparent badge-solid:text-(--badge-on)";
+const BADGE_APPEARANCE_OUTLINE =
+  "badge-outline:bg-transparent badge-outline:border-(--badge-fill) badge-outline:text-(--badge-ink)";
+const BADGE_APPEARANCE_NEUTRAL =
+  "badge-neutral:bg-muted badge-neutral:border-transparent badge-neutral:text-foreground";
+
+/** tint + solid + outline + neutral — every colour-bearing Badge variant. */
+export const BADGE_APPEARANCE_RECIPES = `${BADGE_APPEARANCE_TINT} ${BADGE_APPEARANCE_SOLID} ${BADGE_APPEARANCE_OUTLINE} ${BADGE_APPEARANCE_NEUTRAL}`;
+
+/**
+ * tint + outline + neutral only — never `solid`. Reused by `StatusBadge`'s
+ * out-of-vocabulary `tone` hatch, which must stay CALM-ONLY (its own
+ * integrity constraint, see `status-badge.tsx`): the loud solid fill must
+ * never reach a custom tone, even via a theme's global `--badge-appearance`
+ * override.
+ */
+export const BADGE_APPEARANCE_RECIPES_CALM = `${BADGE_APPEARANCE_TINT} ${BADGE_APPEARANCE_OUTLINE} ${BADGE_APPEARANCE_NEUTRAL}`;
+
 export const badgeVariants = cva(
-  "inline-flex items-center gap-1 rounded-full border px-2.5 py-0.5 text-meta font-medium transition-colors focus-ring focus-visible:ring-offset-2",
+  "inline-flex items-center gap-1 rounded-badge border px-2.5 py-0.5 text-meta font-medium transition-colors focus-ring focus-visible:ring-offset-2",
   {
     variants: {
       variant: {
-        default: "border-transparent bg-primary text-primary-foreground",
+        default: cn(
+          "border-transparent bg-primary text-primary-foreground",
+          "[--badge-fill:var(--primary)] [--badge-ink:var(--primary-text)] [--badge-on:var(--primary-foreground)]",
+          BADGE_APPEARANCE_RECIPES,
+        ),
+        // Already a neutral pill — `appearance` has no additional effect.
         secondary: "border-transparent bg-secondary text-secondary-foreground",
+        // Already an outline with no colour role — `appearance` has no additional effect.
         outline: "text-foreground",
-        success: "border-transparent bg-success text-success-foreground",
-        warning: "border-transparent bg-warning text-warning-foreground",
-        destructive: "border-transparent bg-destructive text-destructive-foreground",
-        info: "border-transparent bg-info text-info-foreground",
+        success: cn(
+          "border-transparent bg-success text-success-foreground",
+          "[--badge-fill:var(--success)] [--badge-ink:var(--success-text)] [--badge-on:var(--success-foreground)]",
+          BADGE_APPEARANCE_RECIPES,
+        ),
+        warning: cn(
+          "border-transparent bg-warning text-warning-foreground",
+          "[--badge-fill:var(--warning)] [--badge-ink:var(--warning-text)] [--badge-on:var(--warning-foreground)]",
+          BADGE_APPEARANCE_RECIPES,
+        ),
+        destructive: cn(
+          "border-transparent bg-destructive text-destructive-foreground",
+          "[--badge-fill:var(--destructive)] [--badge-ink:var(--destructive-text)] [--badge-on:var(--destructive-foreground)]",
+          BADGE_APPEARANCE_RECIPES,
+        ),
+        info: cn(
+          "border-transparent bg-info text-info-foreground",
+          "[--badge-fill:var(--info)] [--badge-ink:var(--info-text)] [--badge-on:var(--info-foreground)]",
+          BADGE_APPEARANCE_RECIPES,
+        ),
       },
     },
     defaultVariants: { variant: "default" },
   },
 );
 
-export interface BadgeProps
-  extends HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badgeVariants> {}
+export type BadgeAppearance = "tint" | "solid" | "outline" | "neutral";
 
-export function Badge({ className, variant, ...props }: BadgeProps) {
-  return <span className={cn(badgeVariants({ variant }), className)} {...props} />;
+export interface BadgeProps
+  extends HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badgeVariants> {
+  /**
+   * Explicit per-instance override of the fill/border/ink treatment. Unset
+   * (default) renders NO `data-appearance` attribute, so the badge is driven
+   * purely by the ancestor `--badge-appearance` token (`auto` = each
+   * variant's own recipe, today's look). Meaningful only on the
+   * colour-bearing variants (`default`, `success`, `warning`, `destructive`,
+   * `info`) — see `badgeVariants`.
+   */
+  appearance?: BadgeAppearance;
 }
+
+export const Badge = forwardRef<HTMLSpanElement, BadgeProps>(function Badge(
+  { className, variant, appearance, ...props },
+  ref,
+) {
+  return (
+    <span
+      ref={ref}
+      data-slot="badge"
+      data-appearance={appearance}
+      className={cn(badgeVariants({ variant }), className)}
+      {...props}
+    />
+  );
+});

package/src/components/bento-grid/bento-grid.test.tsx

@@ -1,5 +1,5 @@
-import { render, screen } from "@testing-library/react";
-import { describe, expect, it } from "vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
 
 import { BentoGrid, BentoGridItem } from "./bento-grid";
 
@@ -116,4 +116,25 @@ describe("BentoGridItem", () => {
     );
     expect(screen.getByTestId("item").className).toMatch(/from-primary/);
   });
+
+  it("cancels a pending spotlight rAF on unmount", () => {
+    const rafSpy = vi.spyOn(window, "requestAnimationFrame").mockReturnValue(7);
+    const cafSpy = vi.spyOn(window, "cancelAnimationFrame").mockImplementation(() => {});
+    const { unmount } = render(
+      <BentoGridItem spotlight data-testid="item">
+        content
+      </BentoGridItem>,
+    );
+    const item = screen.getByTestId("item");
+    fireEvent.mouseMove(item, { clientX: 10, clientY: 10 });
+    expect(rafSpy).toHaveBeenCalled();
+
+    unmount();
+    // A mouse move right before the tile unmounts (removed from the grid
+    // while hovered) must not leave a scheduled frame pending after teardown.
+    expect(cafSpy).toHaveBeenCalledWith(7);
+
+    rafSpy.mockRestore();
+    cafSpy.mockRestore();
+  });
 });

package/src/components/bento-grid/bento-grid.tsx

@@ -34,6 +34,7 @@ import {
   createContext,
   forwardRef,
   use,
+  useEffect,
   useRef,
   useCallback,
   type CSSProperties,
@@ -244,6 +245,15 @@ export const BentoGridItem = forwardRef<HTMLDivElement, BentoGridItemProps>(func
   // rAF ref so we only schedule one frame at a time.
   const rafRef = useRef<number>(0);
 
+  // Cancel a pending frame on unmount — otherwise a mouse move right before
+  // the tile unmounts (removed from the grid while hovered) still fires the
+  // scheduled callback after teardown.
+  useEffect(() => {
+    return () => {
+      if (rafRef.current) cancelAnimationFrame(rafRef.current);
+    };
+  }, []);
+
   const handleMouseMove = useCallback(
     (e: React.MouseEvent<HTMLDivElement>) => {
       if (!spotlightOn || !tileRef.current || !overlayRef.current) return;

package/src/components/bounded-number/bounded-number.test.tsx

@@ -18,7 +18,7 @@ describe("BoundedNumber", () => {
   it("hides the empty label once a value is set", () => {
     render(<BoundedNumber aria-label="Limit" defaultValue={250} />);
     expect(screen.queryByText("No limit")).not.toBeInTheDocument();
-    expect(screen.getByRole("spinbutton", { name: "Limit" })).toHaveValue(250);
+    expect(screen.getByRole("spinbutton", { name: "Limit" })).toHaveValue("250");
   });
 
   it("hides the empty label while focused so the field reads as truly empty", async () => {

package/src/components/bounded-number/bounded-number.tsx

@@ -28,83 +28,86 @@ export interface BoundedNumberProps extends NumberInputProps {
  * `null` AND the field is not focused, so the underlying input stays fully
  * clickable/typable and still round-trips to `null` on an empty blur.
  */
-export const BoundedNumber = forwardRef<HTMLDivElement, BoundedNumberProps>(function BoundedNumber(
-  {
-    value: valueProp,
-    defaultValue,
-    onValueChange,
-    emptyLabel,
-    onFocus,
-    onBlur,
-    className,
-    ...props
-  },
-  ref,
-) {
-  const { t } = useLocale();
-  const resolvedEmptyLabel = emptyLabel ?? t("ui.boundedNumber.emptyLabel");
-  const isControlled = valueProp !== undefined;
-  const [internalValue, setInternalValue] = useState<number | null>(
-    defaultValue !== undefined ? defaultValue : null,
-  );
-  const [focused, setFocused] = useState(false);
-  const currentValue = isControlled ? valueProp : internalValue;
-
-  const handleValueChange = useCallback(
-    (next: number | null) => {
-      if (!isControlled) setInternalValue(next);
-      onValueChange?.(next);
+export const BoundedNumber = forwardRef<HTMLInputElement, BoundedNumberProps>(
+  function BoundedNumber(
+    {
+      value: valueProp,
+      defaultValue,
+      onValueChange,
+      emptyLabel,
+      onFocus,
+      onBlur,
+      className,
+      ...props
     },
-    [isControlled, onValueChange],
-  );
+    ref,
+  ) {
+    const { t } = useLocale();
+    const resolvedEmptyLabel = emptyLabel ?? t("ui.boundedNumber.emptyLabel");
+    const isControlled = valueProp !== undefined;
+    const [internalValue, setInternalValue] = useState<number | null>(
+      defaultValue !== undefined ? defaultValue : null,
+    );
+    const [focused, setFocused] = useState(false);
+    const currentValue = isControlled ? valueProp : internalValue;
 
-  const handleFocus = useCallback(
-    (event: FocusEvent<HTMLDivElement>) => {
-      setFocused(true);
-      onFocus?.(event);
-    },
-    [onFocus],
-  );
+    const handleValueChange = useCallback(
+      (next: number | null) => {
+        if (!isControlled) setInternalValue(next);
+        onValueChange?.(next);
+      },
+      [isControlled, onValueChange],
+    );
 
-  const handleBlur = useCallback(
-    (event: FocusEvent<HTMLDivElement>) => {
-      setFocused(false);
-      onBlur?.(event);
-    },
-    [onBlur],
-  );
+    const handleFocus = useCallback(
+      (event: FocusEvent<HTMLDivElement>) => {
+        setFocused(true);
+        onFocus?.(event);
+      },
+      [onFocus],
+    );
+
+    const handleBlur = useCallback(
+      (event: FocusEvent<HTMLDivElement>) => {
+        setFocused(false);
+        onBlur?.(event);
+      },
+      [onBlur],
+    );
 
-  const showEmptyLabel = currentValue == null && !focused;
+    const showEmptyLabel = currentValue == null && !focused;
 
-  return (
-    // `className` lands on the ROOT (the positioning context), not on the
-    // inner `NumberInput`: a width utility on the inner control would resolve
-    // against a shrink-to-fit wrapper and silently do nothing, so
-    // `className="w-full"` could never widen the field. `w-36` here is
-    // `NumberInput`'s own default width, re-declared so `cn()` lets the caller
-    // override it; the input then simply fills the root.
-    <div className={cn("relative inline-block w-36", className)} data-slot="bounded-number">
-      <NumberInput
-        ref={ref}
-        value={currentValue}
-        onValueChange={handleValueChange}
-        onFocus={handleFocus}
-        onBlur={handleBlur}
-        className="w-full"
-        {...props}
-      />
-      {showEmptyLabel && (
-        <span
-          aria-hidden="true"
-          data-slot="bounded-number-empty-label"
-          className={cn(
-            "pointer-events-none absolute inset-0 flex items-center justify-center",
-            "text-body text-muted-foreground",
-          )}
-        >
-          {resolvedEmptyLabel}
-        </span>
-      )}
-    </div>
-  );
-});
+    return (
+      // `className` lands on the ROOT (the positioning context), not on the
+      // inner `NumberInput`: a width utility on the inner control would resolve
+      // against a shrink-to-fit wrapper and silently do nothing, so
+      // `className="w-full"` could never widen the field. `w-36` is this
+      // preset's own default width (`NumberInput` itself is unconstrained and
+      // fills its container) — `cn()` lets the caller override it, and the
+      // inner `NumberInput` simply fills the root via `className="w-full"`.
+      <div className={cn("relative inline-block w-36", className)} data-slot="bounded-number">
+        <NumberInput
+          ref={ref}
+          value={currentValue}
+          onValueChange={handleValueChange}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          className="w-full"
+          {...props}
+        />
+        {showEmptyLabel && (
+          <span
+            aria-hidden="true"
+            data-slot="bounded-number-empty-label"
+            className={cn(
+              "pointer-events-none absolute inset-0 flex items-center justify-center",
+              "text-body text-muted-foreground",
+            )}
+          >
+            {resolvedEmptyLabel}
+          </span>
+        )}
+      </div>
+    );
+  },
+);

package/src/components/breadcrumb/breadcrumb.stories.tsx

@@ -57,7 +57,7 @@ export const Default: Story = {
  * mirroring `Button`'s `CompoundFocusIndicator` lock.
  */
 export const FocusIndicator: Story = {
-  name: "Focus indicator (#310)",
+  name: "Keyboard focus",
   render: () => (
     <Breadcrumb>
       <BreadcrumbList>

package/src/components/breadcrumb/breadcrumb.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { forwardRef, type ComponentProps, type ReactNode } from "react";
 import { Slot } from "@radix-ui/react-slot";
 import { ChevronRight, MoreHorizontal } from "lucide-react";
@@ -6,7 +8,8 @@ import { useLocale } from "../locale-provider";
 
 export const Breadcrumb = forwardRef<HTMLElement, ComponentProps<"nav">>(
   function Breadcrumb(props, ref) {
-    return <nav ref={ref} aria-label="breadcrumb" {...props} />;
+    const { t } = useLocale();
+    return <nav ref={ref} aria-label={t("ui.breadcrumb.label")} {...props} />;
   },
 );
 export const BreadcrumbList = forwardRef<HTMLOListElement, ComponentProps<"ol">>(
@@ -15,7 +18,7 @@ export const BreadcrumbList = forwardRef<HTMLOListElement, ComponentProps<"ol">>
       <ol
         ref={ref}
         className={cn(
-          "flex flex-wrap items-center gap-1.5 break-words text-sm text-muted-foreground",
+          "flex flex-wrap items-center gap-1.5 break-words text-body text-muted-foreground",
           className,
         )}
         {...props}

package/src/components/button/button.stories.tsx

@@ -42,6 +42,10 @@ export const Ghost: Story = { args: { variant: "ghost" } };
 // `rgba(0, 0, 0, 0)` and fail — where a plain `toBeVisible()` would still pass
 // on the unstyled element.
 export const CssCheck: Story = {
+  // A harness, not a demo: it renders the default Button and asserts the token
+  // stylesheet resolved. `!dev` keeps it in the test run and out of the sidebar.
+  name: "Theme tokens applied",
+  tags: ["!dev"],
   play: async ({ canvas }) => {
     const btn = canvas.getByRole("button", { name: "Button" });
 
@@ -99,7 +103,7 @@ export const AllVariants: Story = {
  * one story covers `light`, `dark` and any consumer theme a fork adds.
  */
 export const CompoundFocusIndicator: Story = {
-  name: "Compound focus indicator (WCAG 1.4.11)",
+  name: "Keyboard focus (WCAG 1.4.11)",
   play: async ({ canvas, userEvent }) => {
     const btn = canvas.getByRole("button", { name: "Button" });
 

package/src/components/button/button.tsx

@@ -4,37 +4,54 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../../lib/cn";
 
 export const buttonVariants = cva(
-  "inline-flex items-center justify-center gap-2 whitespace-nowrap touch-manipulation rounded-md text-body font-medium transition-[color,background-color,border-color,box-shadow,scale] duration-fast ease-standard active:scale-[0.98] motion-reduce:active:scale-100 focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap touch-manipulation rounded-control text-body font-control transition-[color,background-color,border-color,box-shadow,scale] duration-fast ease-standard active:scale-[0.98] motion-reduce:active:scale-100 focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
   {
     variants: {
       variant: {
+        // Disabled treatment is ONE rule for every variant, inherited from the
+        // base string above (`disabled:pointer-events-none disabled:opacity-50`)
+        // — no per-variant fill swap. A solid-fill variant fading via opacity
+        // still reads as "off" against `--muted`/`--background` in both themes;
+        // keeping one mechanism (vs. a bg-muted swap on some variants only) is
+        // what made Input's disabled state internally inconsistent (#286).
         default:
-          "bg-primary text-primary-foreground hover:bg-primary/90 disabled:bg-muted disabled:text-muted-foreground disabled:opacity-100",
-        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+          "bg-primary text-primary-foreground hover:bg-primary-hover active:bg-primary-active",
+        // `inset-ring`, not `border`: a real border would widen the plate by 2px.
+        // `--secondary-border` defaults to transparent (today's borderless plate);
+        // a theme can give the neutral button an edge without switching variants.
+        secondary:
+          "inset-ring inset-ring-secondary-border bg-secondary text-secondary-text hover:bg-secondary/80",
         destructive:
-          "bg-destructive text-destructive-foreground hover:bg-destructive/90 disabled:bg-muted disabled:text-muted-foreground disabled:opacity-100",
-        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+          "bg-destructive text-destructive-foreground hover:bg-destructive-hover active:bg-destructive-active",
+        // `text-foreground` is load-bearing, not decoration: an outline button
+        // paints its OWN `bg-background` plate, so inheriting the surrounding
+        // ink turns it invisible on a coloured band (a `bg-primary` CTA handed
+        // it `--primary-foreground`, 1.06:1 against its own plate). A caller's
+        // own `text-*` still wins through `cn()`.
+        outline:
+          "border border-button-outline-border bg-background text-foreground hover:bg-accent hover:text-accent-foreground",
         // The calm "outlined but quiet" rung (#194, research 02 §3a). `outline` uses
-        // the form-field `border-input` token, `outline-subtle` uses `border-border`.
-        // Since the ADR 0010 Amendment (2026-06-20) returned `--input` to the subtle
-        // rung, these two are now VISUALLY IDENTICAL by default — both variant names
-        // are kept as a SEMANTIC SEAM (a future brand could re-separate `--input` from
-        // `--border`) and to avoid churning `outline-subtle` callers (e.g.
+        // `--button-outline-border` (default `var(--input)`, split from the
+        // form-field token), `outline-subtle` uses `border-border`. Since the ADR
+        // 0010 Amendment (2026-06-20) returned `--input` to the subtle rung, these
+        // two are now VISUALLY IDENTICAL by default — both variant names are kept
+        // as a SEMANTIC SEAM (a theme can now give buttons and text fields
+        // different edges) and to avoid churning `outline-subtle` callers (e.g.
         // change-review.tsx). `outline` stays for genuinely form-adjacent controls.
         "outline-subtle":
-          "border border-border bg-background hover:bg-accent hover:text-accent-foreground",
+          "border border-border bg-background text-foreground hover:bg-accent hover:text-accent-foreground",
         ghost: "hover:bg-accent hover:text-accent-foreground",
-        // #399 — a link button is TEXT on the page, so it takes the on-surface
-        // `-text` rung; `bg-primary` above keeps the fill rung.
-        link: "text-primary-text underline-offset-4 hover:underline",
+        // #399 — a link button is TEXT on the page: `--link` defaults to the
+        // on-surface `--primary-text` rung; `bg-primary` above keeps the fill rung.
+        link: "text-link underline-offset-4 hover:underline",
       },
       size: {
-        sm: "h-8 rounded-md px-3 text-meta",
-        default: "h-9 px-4 py-2",
-        lg: "h-10 rounded-md px-6",
-        icon: "size-9",
-        "icon-sm": "size-8",
-        "icon-lg": "size-10",
+        sm: "h-control-sm px-3 text-meta",
+        default: "h-control px-4 py-2",
+        lg: "h-control-lg px-6",
+        icon: "size-control",
+        "icon-sm": "size-control-sm",
+        "icon-lg": "size-control-lg",
       },
     },
     defaultVariants: { variant: "default", size: "default" },

package/src/components/button-group/button-group.tsx

@@ -44,7 +44,7 @@ export const ButtonGroupText = forwardRef<
     <Comp
       ref={ref}
       className={cn(
-        "flex items-center gap-2 rounded-md border bg-muted px-4 text-sm font-medium shadow-sm [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+        "flex items-center gap-2 rounded-md border bg-muted px-4 text-body font-medium shadow-sm [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
         className,
       )}
       {...props}