@elabs-ai/components-ui 4.2.0 → 5.1.0

package/src/components/tabs/tabs.tsx

@@ -72,16 +72,37 @@ function scrollTriggerIntoStrip(trigger: HTMLElement, behavior: ScrollBehavior)
  * first tab off the left edge once the set overflows; `safe` falls back to
  * start-alignment on overflow while staying visually identical when the
  * strip fits (see #344).
+ *
+ * Token-driven default (`--tabs-variant`, default `segmented`): when the
+ * caller passes NO `variant`, `TabsList`/`TabsTrigger` render with no
+ * `data-variant` attribute at all — the `segmented` cva branch below, plus
+ * these `tabs-underline:`-prefixed overrides, which the `tabs-underline`
+ * custom variant (`themes.css`) only activates via a container style query
+ * on an ancestor's `--tabs-variant`. An explicit `variant` prop always
+ * renders `data-variant`, which the same custom variant's `:not([data-variant])`
+ * guard excludes — so these overrides are inert on an explicit strip and its
+ * own `underline` branch (below) renders unchanged. Literal strings, not
+ * built via interpolation — see `badge.tsx`'s note on the same rule.
  */
+const TABS_UNDERLINE_LIST_OVERRIDE =
+  "tabs-underline:flex tabs-underline:h-auto tabs-underline:w-full tabs-underline:justify-start tabs-underline:rounded-none tabs-underline:bg-transparent tabs-underline:p-0 tabs-underline:border-b tabs-underline:border-rule";
+
+const TABS_UNDERLINE_TRIGGER_OVERRIDE =
+  "tabs-underline:h-12 tabs-underline:rounded-none tabs-underline:border-b-(length:--tabs-indicator-width) tabs-underline:border-transparent tabs-underline:px-4 tabs-underline:py-0 tabs-underline:hover:text-foreground tabs-underline:focus-ring-inset tabs-underline:focus-visible:ring-offset-0 tabs-underline:data-[state=active]:bg-transparent tabs-underline:data-[state=active]:shadow-none tabs-underline:data-[state=active]:border-primary";
+
 export const tabsListVariants = cva(
   "max-w-full items-center overflow-x-auto text-muted-foreground",
   {
     variants: {
       variant: {
-        // Recessed pill track with a raised active segment.
-        segmented: "inline-flex h-9 justify-center-safe rounded-lg bg-muted p-1",
+        // Recessed pill track with a raised active segment. Also the
+        // TOKEN-DRIVEN DEFAULT's base — see `TABS_UNDERLINE_LIST_OVERRIDE`.
+        segmented: cn(
+          "inline-flex h-9 justify-center-safe rounded-lg bg-muted p-1",
+          TABS_UNDERLINE_LIST_OVERRIDE,
+        ),
         // Line tabs: a transparent start-aligned row over a 1px rule; the active
-        // tab's 2px underline sits on top of it (see `tabsTriggerVariants`).
+        // tab's underline sits on top of it (see `tabsTriggerVariants`).
         underline: "flex w-full justify-start border-b border-rule",
       },
     },
@@ -94,16 +115,19 @@ export const tabsTriggerVariants = cva(
   {
     variants: {
       variant: {
+        // Also the TOKEN-DRIVEN DEFAULT's base — see `TABS_UNDERLINE_TRIGGER_OVERRIDE`.
         segmented: cn(
           "rounded-control px-3 py-1",
           // `ring-offset-1`, not `-2`: the compound indicator's reach is
           // `ring-offset` + 2px ring + 1px contour, and `TabsList` is an
           // `overflow-x-auto` strip with `p-1` (4px). At offset 2 the reach is 5px
           // and the scroll box clips the contour on three sides (#67 fix round 2,
-          // measured on `patterns-templates-object-detail-hub--default` tab stop
+          // measured on `patterns-templates-starters-object-detail-hub--default` tab stop
           // 9); at offset 1 it is exactly 4px and the loop closes.
           "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
           "data-[state=active]:bg-surface-elevated data-[state=active]:text-foreground data-[state=active]:shadow-sm",
+          "data-[state=active]:font-tabs-active",
+          TABS_UNDERLINE_TRIGGER_OVERRIDE,
         ),
         underline: cn(
           // The underline is a bottom BORDER inside the fixed height, transparent
@@ -111,9 +135,10 @@ export const tabsTriggerVariants = cva(
           // overlap the list's rule: the list scrolls (`overflow-x-auto`), which
           // would clip anything hanging past its padding box. The strip has no
           // padding for an outer ring either, so the indicator is drawn inset.
-          "h-12 rounded-none border-b-2 border-transparent px-4 hover:text-foreground",
+          "h-12 rounded-none border-b-(length:--tabs-indicator-width) border-transparent px-4 hover:text-foreground",
           "focus-ring-inset",
           "data-[state=active]:border-primary data-[state=active]:text-foreground",
+          "data-[state=active]:font-tabs-active",
         ),
       },
     },
@@ -123,8 +148,14 @@ export const tabsTriggerVariants = cva(
 
 export type TabsVariant = NonNullable<VariantProps<typeof tabsListVariants>["variant"]>;
 
-// The list owns the variant; its triggers read it, so a strip never mixes two.
-const TabsVariantContext = createContext<TabsVariant>("segmented");
+/**
+ * The list owns the variant; its triggers read it, so a strip never mixes
+ * two. `undefined` = the caller passed no `variant` on `TabsList` — the
+ * token-driven default (`--tabs-variant`): neither the list nor its triggers
+ * render a `data-variant` attribute, so the `tabs-underline:` custom
+ * variant's container style query decides the look.
+ */
+const TabsVariantContext = createContext<TabsVariant | undefined>(undefined);
 
 export interface TabsListProps
   extends
@@ -133,7 +164,11 @@ export interface TabsListProps
 
 export const TabsList = forwardRef<ElementRef<typeof TabsPrimitive.List>, TabsListProps>(
   function TabsList({ className, variant, ...props }, ref) {
-    const resolved = variant ?? "segmented";
+    // cva's `VariantProps` types `variant` as possibly `null` (an explicit
+    // opt-out); normalize it to `undefined` so it matches `TabsVariant |
+    // undefined` — same DOM/CSS effect either way (no `data-variant`).
+    const explicitVariant = variant ?? undefined;
+    const resolved = explicitVariant ?? "segmented";
     const innerRef = useRef<HTMLDivElement | null>(null);
     const mergedRef = useMemo(() => mergeRefs(ref, innerRef), [ref]);
     // Honours the in-app tri-state motion preference on `ThemeProvider` as well
@@ -227,11 +262,14 @@ export const TabsList = forwardRef<ElementRef<typeof TabsPrimitive.List>, TabsLi
     }, [reducedMotion]);
 
     return (
-      <TabsVariantContext.Provider value={resolved}>
+      // The normalized `explicitVariant` (undefined when unset), not
+      // `resolved` — an undefined Provider value is what lets a
+      // variant-less `TabsTrigger` also omit its own `data-variant` below.
+      <TabsVariantContext.Provider value={explicitVariant}>
         <TabsPrimitive.List
           ref={mergedRef}
           data-slot="tabs-list"
-          data-variant={resolved}
+          data-variant={explicitVariant}
           className={cn(tabsListVariants({ variant: resolved }), className)}
           {...props}
         />
@@ -245,12 +283,14 @@ export const TabsTrigger = forwardRef<
   ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger>
 >(function TabsTrigger({ className, ...props }, ref) {
   const variant = use(TabsVariantContext);
+  const resolved = variant ?? "segmented";
 
   return (
     <TabsPrimitive.Trigger
       ref={ref}
       data-slot="tabs-trigger"
-      className={cn(tabsTriggerVariants({ variant }), className)}
+      data-variant={variant}
+      className={cn(tabsTriggerVariants({ variant: resolved }), className)}
       {...props}
     />
   );

package/src/components/textarea/textarea.tsx

@@ -13,7 +13,7 @@ export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function
       className={cn(
         "flex min-h-20 w-full rounded-control border border-input bg-input-background px-3 py-2 text-body shadow-input transition-[color,background-color,border-color,box-shadow] duration-fast ease-standard",
         "placeholder:text-muted-foreground",
-        "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+        "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background focus-visible:border-input-focus",
         "disabled:cursor-not-allowed disabled:opacity-50 disabled:border-border",
         "aria-[invalid=true]:border-destructive aria-[invalid=true]:ring-destructive",
         className,

package/src/components/theme-family-switch/index.ts

@@ -0,0 +1,10 @@
+export {
+  DEFAULT_THEME_FAMILY_SWITCH_LABELS,
+  ThemeFamilySwitch,
+  type ThemeFamilySwatch,
+  type ThemeFamilySwitchFamily,
+  type ThemeFamilySwitchLabels,
+  type ThemeFamilySwitchMode,
+  type ThemeFamilySwitchProps,
+  type ThemeFamilySwitchSize,
+} from "./theme-family-switch";

package/src/components/theme-family-switch/theme-family-switch.stories.tsx

@@ -0,0 +1,97 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, userEvent, within } from "storybook/test";
+import {
+  ThemeFamilySwitch,
+  type ThemeFamilySwitchFamily,
+  type ThemeFamilySwitchMode,
+  type ThemeFamilySwitchProps,
+} from "./theme-family-switch";
+
+/** Sample chips painted from tokens; a real host passes each family's resolved colours. */
+const families: ThemeFamilySwitchFamily[] = [
+  {
+    id: "default",
+    label: "Default",
+    swatch: { background: "var(--background)", primary: "var(--primary)" },
+  },
+  {
+    id: "ocean",
+    label: "Ocean",
+    swatch: { background: "var(--muted)", primary: "var(--chart-1)" },
+  },
+  {
+    id: "graphite",
+    label: "Graphite",
+    swatch: { background: "var(--card)", primary: "var(--chart-2)" },
+  },
+  {
+    id: "qlik",
+    label: "Qlik",
+    swatch: { background: "var(--background)", primary: "var(--chart-3)" },
+  },
+  { id: "heap", label: "Heap", swatch: { background: "var(--muted)", primary: "var(--chart-4)" } },
+];
+
+function Controlled(props: Partial<ThemeFamilySwitchProps>) {
+  const [value, setValue] = useState(props.value ?? "default");
+  const [mode, setMode] = useState<ThemeFamilySwitchMode>(props.mode ?? "light");
+  return (
+    <ThemeFamilySwitch
+      families={families}
+      {...props}
+      value={value}
+      onChange={(id) => {
+        setValue(id);
+        props.onChange?.(id);
+      }}
+      mode={mode}
+      onModeChange={(next) => {
+        setMode(next);
+        props.onModeChange?.(next);
+      }}
+    />
+  );
+}
+
+const meta = {
+  title: "Core/ThemeFamilySwitch",
+  component: ThemeFamilySwitch,
+  parameters: { layout: "padded" },
+  tags: ["autodocs"],
+  args: { families, value: "default", onChange: fn(), mode: "light", onModeChange: fn() },
+  render: (args) => <Controlled {...args} />,
+} satisfies Meta<typeof ThemeFamilySwitch>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const Small: Story = { args: { size: "sm" } };
+
+export const Large: Story = { args: { size: "lg" } };
+
+/** Without `onModeChange` the switch shows the family row only. */
+export const FamiliesOnly: Story = {
+  args: { onModeChange: undefined, mode: undefined },
+  render: (args) => <ThemeFamilySwitch {...args} />,
+};
+
+/** Tab enters the row on the selected chip, arrows move focus without applying, Enter applies. */
+export const KeyboardInteraction: Story = {
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    await userEvent.tab();
+    const current = canvas.getByRole("radio", { name: "Default" });
+    await expect(current).toHaveFocus();
+    await userEvent.keyboard("{ArrowRight}");
+    const ocean = canvas.getByRole("radio", { name: "Ocean" });
+    await expect(ocean).toHaveFocus();
+    await expect(args.onChange).not.toHaveBeenCalled();
+    await userEvent.keyboard("{Enter}");
+    await expect(args.onChange).toHaveBeenCalledWith("ocean");
+    await expect(ocean).toHaveAttribute("aria-checked", "true");
+    await userEvent.keyboard("{ArrowRight}{ }");
+    await expect(args.onChange).toHaveBeenLastCalledWith("graphite");
+  },
+};

package/src/components/theme-family-switch/theme-family-switch.test.tsx

@@ -0,0 +1,85 @@
+import { createRef } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { ThemeFamilySwitch, type ThemeFamilySwitchFamily } from "./theme-family-switch";
+
+const families: ThemeFamilySwitchFamily[] = [
+  { id: "default", label: "Default", swatch: { background: "white", primary: "black" } },
+  { id: "ocean", label: "Ocean", swatch: { background: "azure", primary: "navy" } },
+  { id: "qlik", label: "Qlik", swatch: { background: "white", primary: "green" } },
+];
+
+describe("ThemeFamilySwitch", () => {
+  it("names every chip by its family and marks the active one", () => {
+    render(<ThemeFamilySwitch families={families} value="ocean" onChange={() => {}} />);
+    expect(screen.getByRole("group", { name: "Theme family" })).toBeInTheDocument();
+    expect(screen.getByRole("radio", { name: "Ocean" })).toHaveAttribute("aria-checked", "true");
+    expect(screen.getByRole("radio", { name: "Qlik" })).toHaveAttribute("aria-checked", "false");
+  });
+
+  it("paints each chip from the host's swatch values", () => {
+    const { container } = render(
+      <ThemeFamilySwitch families={families} value="default" onChange={() => {}} />,
+    );
+    const chips = container.querySelectorAll<HTMLElement>(
+      '[data-slot="theme-family-switch-swatch"]',
+    );
+    expect(chips).toHaveLength(3);
+    expect(chips[1]?.style.background).toContain("navy");
+  });
+
+  it("roves focus with arrow keys without applying", async () => {
+    const onChange = vi.fn();
+    render(<ThemeFamilySwitch families={families} value="default" onChange={onChange} />);
+    const first = screen.getByRole("radio", { name: "Default" });
+    first.focus();
+    fireEvent.keyDown(first, { key: "ArrowRight" });
+    // Radix moves roving focus on the next tick.
+    await waitFor(() => expect(screen.getByRole("radio", { name: "Ocean" })).toHaveFocus());
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("applies a family on activation, and never un-applies the active one", () => {
+    const onChange = vi.fn();
+    render(<ThemeFamilySwitch families={families} value="default" onChange={onChange} />);
+    fireEvent.click(screen.getByRole("radio", { name: "Qlik" }));
+    expect(onChange).toHaveBeenCalledWith("qlik");
+    fireEvent.click(screen.getByRole("radio", { name: "Default" }));
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("renders the mode toggle only with onModeChange, and reports the new mode", () => {
+    const onModeChange = vi.fn();
+    const { rerender } = render(
+      <ThemeFamilySwitch families={families} value="default" onChange={() => {}} mode="light" />,
+    );
+    expect(screen.queryByRole("group", { name: "Colour mode" })).toBeNull();
+    rerender(
+      <ThemeFamilySwitch
+        families={families}
+        value="default"
+        onChange={() => {}}
+        mode="light"
+        onModeChange={onModeChange}
+        labels={{ dark: "Dunkel" }}
+      />,
+    );
+    fireEvent.click(screen.getByRole("radio", { name: "Dunkel" }));
+    expect(onModeChange).toHaveBeenCalledWith("dark");
+  });
+
+  it("forwards its ref, merges className and exposes data-slot", () => {
+    const ref = createRef<HTMLDivElement>();
+    const { container } = render(
+      <ThemeFamilySwitch
+        ref={ref}
+        className="probe"
+        families={families}
+        value="default"
+        onChange={() => {}}
+      />,
+    );
+    expect(ref.current).toBe(container.querySelector('[data-slot="theme-family-switch"]'));
+    expect(ref.current).toHaveClass("probe");
+  });
+});

package/src/components/theme-family-switch/theme-family-switch.tsx

@@ -0,0 +1,166 @@
+"use client";
+
+import { forwardRef, type HTMLAttributes } from "react";
+import { cn } from "../../lib/cn";
+import { ToggleGroup, ToggleGroupItem } from "../toggle-group";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "../tooltip";
+
+export type ThemeFamilySwitchMode = "light" | "dark";
+export type ThemeFamilySwitchSize = "sm" | "md" | "lg";
+
+/** The two colours a family's chip is painted with — any CSS colour, resolved by the host. */
+export interface ThemeFamilySwatch {
+  /** The family's ground (`--background` in the active mode). */
+  background: string;
+  /** The family's accent (`--primary` in the active mode). */
+  primary: string;
+}
+
+export interface ThemeFamilySwitchFamily {
+  /** Family id — what `value` holds and `onChange` reports. */
+  id: string;
+  /** Display name: the swatch's accessible name and its tooltip wordmark. */
+  label: string;
+  /** Chip colours. The switch never imports a theme; the host passes these in. */
+  swatch: ThemeFamilySwatch;
+}
+
+export interface ThemeFamilySwitchLabels {
+  /** Accessible name of the swatch row. */
+  families: string;
+  /** Accessible name of the mode toggle. */
+  mode: string;
+  light: string;
+  dark: string;
+}
+
+export const DEFAULT_THEME_FAMILY_SWITCH_LABELS: ThemeFamilySwitchLabels = {
+  families: "Theme family",
+  mode: "Colour mode",
+  light: "Light",
+  dark: "Dark",
+};
+
+export interface ThemeFamilySwitchProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "onChange" | "defaultValue"
+> {
+  /** Families in display order. */
+  families: readonly ThemeFamilySwitchFamily[];
+  /** Id of the active family. */
+  value: string;
+  /** A family was applied (click, Enter or Space). Arrow keys only move focus. */
+  onChange: (familyId: string) => void;
+  /** Active mode; with `onModeChange`, renders the Light/Dark toggle after the swatches. */
+  mode?: ThemeFamilySwitchMode;
+  onModeChange?: (mode: ThemeFamilySwitchMode) => void;
+  size?: ThemeFamilySwitchSize;
+  /** UI strings, for localisation. */
+  labels?: Partial<ThemeFamilySwitchLabels>;
+}
+
+/** Hit target per size (the chip sits inside it, inset by the selection border). */
+const ITEM_SIZE: Record<ThemeFamilySwitchSize, string> = {
+  sm: "size-7",
+  md: "size-9",
+  lg: "size-11",
+};
+const MODE_SIZE: Record<ThemeFamilySwitchSize, "sm" | "default" | "lg"> = {
+  sm: "sm",
+  md: "default",
+  lg: "lg",
+};
+
+/**
+ * One control that re-skins a page across theme families (concept §5a): a row of two-tone
+ * family chips with roving focus — Tab enters the row, arrow keys move, Enter/Space apply —
+ * plus an optional Light/Dark toggle. The selected chip carries a solid ring (a shape cue,
+ * not colour alone) and `aria-checked`; each chip is named by its family.
+ */
+export const ThemeFamilySwitch = forwardRef<HTMLDivElement, ThemeFamilySwitchProps>(
+  function ThemeFamilySwitch(
+    {
+      families,
+      value,
+      onChange,
+      mode,
+      onModeChange,
+      size = "md",
+      labels: labelsProp,
+      className,
+      ...props
+    },
+    ref,
+  ) {
+    const labels = { ...DEFAULT_THEME_FAMILY_SWITCH_LABELS, ...labelsProp };
+    return (
+      <TooltipProvider delayDuration={300}>
+        <div
+          ref={ref}
+          data-slot="theme-family-switch"
+          data-size={size}
+          className={cn("inline-flex flex-wrap items-center gap-3", className)}
+          {...props}
+        >
+          <ToggleGroup
+            type="single"
+            value={value}
+            // Radix reports "" when the pressed item is pressed again — a family stays applied.
+            onValueChange={(next) => {
+              if (next && next !== value) onChange(next);
+            }}
+            aria-label={labels.families}
+            data-slot="theme-family-switch-families"
+            className="flex-wrap gap-1"
+          >
+            {families.map((family) => (
+              <Tooltip key={family.id}>
+                <TooltipTrigger asChild>
+                  <ToggleGroupItem
+                    value={family.id}
+                    aria-label={family.label}
+                    data-slot="theme-family-switch-item"
+                    className={cn(
+                      ITEM_SIZE[size],
+                      "min-w-0 rounded-full border-2 border-transparent p-0.5",
+                      "bg-transparent hover:bg-transparent data-[state=on]:bg-transparent aria-checked:bg-transparent",
+                      "data-[state=on]:border-foreground aria-checked:border-foreground",
+                    )}
+                  >
+                    <span
+                      aria-hidden="true"
+                      data-slot="theme-family-switch-swatch"
+                      className="size-full rounded-full shadow-hairline"
+                      style={{
+                        background: `linear-gradient(135deg, ${family.swatch.background} 0 50%, ${family.swatch.primary} 50% 100%)`,
+                      }}
+                    />
+                  </ToggleGroupItem>
+                </TooltipTrigger>
+                <TooltipContent data-slot="theme-family-switch-wordmark">
+                  {family.label}
+                </TooltipContent>
+              </Tooltip>
+            ))}
+          </ToggleGroup>
+          {mode !== undefined && onModeChange ? (
+            <ToggleGroup
+              type="single"
+              variant="segmented"
+              size={MODE_SIZE[size]}
+              value={mode}
+              onValueChange={(next) => {
+                if (next === "light" || next === "dark") onModeChange(next);
+              }}
+              aria-label={labels.mode}
+              data-slot="theme-family-switch-mode"
+            >
+              <ToggleGroupItem value="light">{labels.light}</ToggleGroupItem>
+              <ToggleGroupItem value="dark">{labels.dark}</ToggleGroupItem>
+            </ToggleGroup>
+          ) : null}
+        </div>
+      </TooltipProvider>
+    );
+  },
+);

package/src/components/theme-switcher/theme-switcher.tsx

@@ -13,7 +13,7 @@ import {
   type ThemeScheme,
 } from "@elabs-ai/components-tokens";
 
-import { Button } from "../button";
+import { Button, type ButtonProps } from "../button";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -59,6 +59,12 @@ export interface ThemeSwitcherProps extends Omit<HTMLAttributes<HTMLButtonElemen
   effect?: ThemeTransitionEffect;
   /** Control size. Default "default". */
   size?: ButtonSize;
+  /**
+   * The trigger button's variant. Default: `"outline"` for the dropdown forms and `"ghost"` for
+   * the two-theme toggle (today's behaviour). Pass `"ghost"` when the switcher sits in a row of
+   * borderless icon buttons — an app top bar — so it reads as one of them.
+   */
+  variant?: ButtonProps["variant"];
   /**
    * Controlled preference (#366). When set, the switcher derives its "current"
    * state — including "system" — from this prop instead of its own internal,
@@ -113,6 +119,7 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
       showSystem = true,
       effect = "polygon",
       size = "default",
+      variant,
       preference,
       onPreferenceChange,
       className,
@@ -274,7 +281,7 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
           <DropdownMenuTrigger asChild>
             <Button
               ref={ref}
-              variant="outline"
+              variant={variant ?? "outline"}
               size={ICON_SIZE[size]}
               aria-label={t("ui.themeSwitcher.theme")}
               className={className}
@@ -328,7 +335,7 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
           <DropdownMenuTrigger asChild>
             <Button
               ref={ref}
-              variant="outline"
+              variant={variant ?? "outline"}
               size={ICON_SIZE[size]}
               aria-label={t("ui.themeSwitcher.theme")}
               className={className}
@@ -390,7 +397,7 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
           <TooltipTrigger asChild>
             <Button
               ref={ref}
-              variant="ghost"
+              variant={variant ?? "ghost"}
               size={ICON_SIZE[size]}
               aria-label={`Theme: ${roleLabel(current)}. Activate to switch to ${roleLabel(next)}.`}
               onClick={apply}

package/src/components/token-spotlight/index.ts

@@ -0,0 +1,11 @@
+export {
+  TokenSpotlight,
+  DEFAULT_TOKEN_SPOTLIGHT_LABELS,
+  TOKEN_SPOTLIGHT_SCAN_LIMIT,
+  resolveTokenDisplayValue,
+  resolveTokenMatchValue,
+  scanForConsumers,
+  type TokenSpotlightLabels,
+  type TokenSpotlightProps,
+  type TokenSpotlightToken,
+} from "./token-spotlight";

package/src/components/token-spotlight/token-spotlight.css

@@ -0,0 +1,32 @@
+/*
+ * TokenSpotlight — the outline pulse a hovered/focused chip draws on every element that
+ * consumes its token (RM-103, wave-4 ruling 20). Tokens only (`--ring`, `--t-fast`,
+ * `--ease-standard`); no HTML sink, no inline style — `data-token-consumer` is the only
+ * hook, added/removed by the component itself (precedent: `ambient-field.css`).
+ */
+@layer base {
+  [data-token-consumer] {
+    outline: 2px solid var(--ring);
+    outline-offset: 2px;
+    animation: brand-ui-token-consumer-pulse var(--t-fast) var(--ease-standard);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    :root:not([data-motion-pref="full"]) [data-token-consumer] {
+      animation: none;
+    }
+  }
+
+  [data-motion-pref="reduced"] [data-token-consumer] {
+    animation: none;
+  }
+
+  @keyframes brand-ui-token-consumer-pulse {
+    from {
+      outline-color: transparent;
+    }
+    to {
+      outline-color: var(--ring);
+    }
+  }
+}