@elabs-ai/components-ui 4.0.0 → 4.2.0

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

@@ -7,6 +7,7 @@ import {
   BUILT_IN_THEME_DEFINITIONS,
   defineTheme,
   ThemeProvider,
+  useTheme,
 } from "@elabs-ai/components-tokens";
 
 import { ThemeSwitcher } from "./theme-switcher";
@@ -251,3 +252,184 @@ describe("ThemeSwitcher — consumer themes (ADR 0029)", () => {
     );
   });
 });
+
+describe("ThemeSwitcher — theme families (ADR 0036)", () => {
+  const oceanLight = defineTheme({
+    value: "ocean-light",
+    label: "Ocean light",
+    dark: false,
+    family: "ocean",
+    familyLabel: "Ocean",
+  });
+  const oceanDark = defineTheme({
+    value: "ocean-dark",
+    label: "Ocean dark",
+    dark: true,
+    family: "ocean",
+  });
+  const dusk = defineTheme({
+    value: "dusk",
+    label: "Dusk",
+    dark: true,
+    family: "dusk",
+    familyLabel: "Dusk",
+  });
+  const midnight = defineTheme({ value: "midnight", label: "Midnight", dark: true });
+  const daylight = defineTheme({ value: "daylight", label: "Daylight", dark: false });
+  const REGISTRY = [...BUILT_IN_THEME_DEFINITIONS, oceanLight, oceanDark, dusk];
+
+  async function openMenu() {
+    await userEvent.click(screen.getByRole("button", { name: "Theme" }));
+    return screen.findByRole("menu");
+  }
+
+  it("BACKWARD COMPAT: the default provider still renders the cycle toggle", () => {
+    setup(<ThemeSwitcher />);
+    expect(screen.getByRole("button", { name: /theme:/i })).toBeInTheDocument();
+  });
+
+  it("BACKWARD COMPAT: built-ins plus one undeclared theme stays a flat dropdown", async () => {
+    render(
+      <ThemeProvider themes={[...BUILT_IN_THEME_DEFINITIONS, midnight]}>
+        <ThemeSwitcher />
+      </ThemeProvider>,
+    );
+    const menu = await openMenu();
+    expect(within(menu).queryAllByRole("menuitemradio")).toHaveLength(0);
+    expect(within(menu).getByText("Midnight")).toBeInTheDocument();
+  });
+
+  it("BACKWARD COMPAT: an undeclared two-theme pair stays a light/dark toggle", () => {
+    render(
+      <ThemeProvider themes={[daylight, midnight]} defaultTheme="daylight">
+        <ThemeSwitcher showSystem={false} />
+      </ThemeProvider>,
+    );
+    expect(screen.getByRole("button", { name: /theme:/i })).toHaveAccessibleName(
+      "Theme: Daylight. Activate to switch to Midnight.",
+    );
+  });
+
+  it("offers families and a separate mode group once two families are declared", async () => {
+    render(
+      <ThemeProvider themes={REGISTRY} defaultTheme="light">
+        <ThemeSwitcher />
+      </ThemeProvider>,
+    );
+    const menu = await openMenu();
+    const radios = within(menu).getAllByRole("menuitemradio");
+    expect(radios.map((r) => r.textContent)).toEqual([
+      "Default",
+      "Ocean",
+      "Dusk",
+      "Light",
+      "Dark",
+      "System",
+    ]);
+    expect(within(menu).getByRole("menuitemradio", { name: "Default" })).toBeChecked();
+    expect(within(menu).getByRole("menuitemradio", { name: "Light" })).toBeChecked();
+  });
+
+  it("switching family keeps the chosen mode", async () => {
+    render(
+      <ThemeProvider themes={REGISTRY} defaultTheme="dark">
+        <ThemeSwitcher />
+      </ThemeProvider>,
+    );
+    await openMenu();
+    await userEvent.click(screen.getByRole("menuitemradio", { name: "Ocean" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("ocean-dark");
+  });
+
+  it("switching mode stays within the family", async () => {
+    render(
+      <ThemeProvider themes={REGISTRY} defaultTheme="ocean-light">
+        <ThemeSwitcher />
+      </ThemeProvider>,
+    );
+    await openMenu();
+    await userEvent.click(screen.getByRole("menuitemradio", { name: "Dark" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("ocean-dark");
+  });
+
+  it("hides the mode group for a single-mode family", async () => {
+    render(
+      <ThemeProvider themes={REGISTRY} defaultTheme="dusk">
+        <ThemeSwitcher />
+      </ThemeProvider>,
+    );
+    const menu = await openMenu();
+    expect(within(menu).queryByRole("menuitemradio", { name: "Light" })).not.toBeInTheDocument();
+    expect(within(menu).queryByText("Mode")).not.toBeInTheDocument();
+  });
+
+  it("remembers dark across a light-only family", async () => {
+    const sand = defineTheme({ value: "sand", label: "Sand", dark: false, family: "sand" });
+    render(
+      <ThemeProvider themes={[...REGISTRY, sand]} defaultTheme="dark">
+        <ThemeSwitcher />
+      </ThemeProvider>,
+    );
+    await openMenu();
+    await userEvent.click(screen.getByRole("menuitemradio", { name: "sand" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("sand");
+    await openMenu();
+    await userEvent.click(screen.getByRole("menuitemradio", { name: "Ocean" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("ocean-dark");
+  });
+
+  it("checks the right family when a second same-scheme variant is active", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const oceanDeep = defineTheme({
+      value: "ocean-deep",
+      label: "Ocean deep",
+      dark: true,
+      family: "ocean",
+    });
+    render(
+      <ThemeProvider themes={[...REGISTRY, oceanDeep]} defaultTheme="ocean-deep">
+        <ThemeSwitcher />
+      </ThemeProvider>,
+    );
+    const menu = await openMenu();
+    expect(within(menu).getByRole("menuitemradio", { name: "Ocean" })).toBeChecked();
+    expect(within(menu).getByRole("menuitemradio", { name: "Default" })).not.toBeChecked();
+    warn.mockRestore();
+  });
+
+  it("forgets a remembered mode once another control changes the theme", async () => {
+    function ExternalLight() {
+      const { setTheme } = useTheme();
+      return (
+        <button type="button" onClick={() => setTheme("light")}>
+          External light
+        </button>
+      );
+    }
+    render(
+      <ThemeProvider themes={REGISTRY} defaultTheme="light">
+        <ThemeSwitcher />
+        <ExternalLight />
+      </ThemeProvider>,
+    );
+    await openMenu();
+    await userEvent.click(screen.getByRole("menuitemradio", { name: "Dark" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("dark");
+    await userEvent.click(screen.getByRole("button", { name: "External light" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("light");
+    await openMenu();
+    await userEvent.click(screen.getByRole("menuitemradio", { name: "Ocean" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("ocean-light");
+  });
+
+  it("forced dropdown mode keeps the flat list even with families", async () => {
+    render(
+      <ThemeProvider themes={REGISTRY}>
+        <ThemeSwitcher mode="dropdown" />
+      </ThemeProvider>,
+    );
+    const menu = await openMenu();
+    expect(within(menu).queryAllByRole("menuitemradio")).toHaveLength(0);
+    expect(within(menu).getByText("Ocean dark")).toBeInTheDocument();
+  });
+});

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

@@ -1,17 +1,31 @@
 "use client";
 
-import { forwardRef, useCallback, useEffect, useState, type HTMLAttributes } from "react";
+import { forwardRef, useCallback, useEffect, useRef, useState, type HTMLAttributes } from "react";
 import { Check, Monitor, Moon, Sun } from "lucide-react";
-import { useTheme, type ThemeDefinition, type ThemeName } from "@elabs-ai/components-tokens";
+import {
+  groupThemeFamilies,
+  resolveThemeVariant,
+  themeFamilyIdOf,
+  themeSchemeOf,
+  useTheme,
+  type ThemeDefinition,
+  type ThemeName,
+  type ThemeScheme,
+} from "@elabs-ai/components-tokens";
 
 import { Button } from "../button";
 import {
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "../dropdown-menu";
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "../tooltip";
+import { useLocale } from "../locale-provider";
 import { useThemeTransition, type ThemeTransitionEffect } from "./use-theme-transition";
 
 const SYSTEM_STORAGE_KEY = "brand-ui-theme-system";
@@ -107,6 +121,7 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
     ref,
   ) {
     const { theme, themeDefinitions, setTheme } = useTheme();
+    const { t } = useLocale();
     const switchTheme = useThemeTransition(effect);
     const isControlled = preference !== undefined;
     const [uncontrolledIsSystem, setUncontrolledIsSystem] = useState(false);
@@ -127,16 +142,43 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
     const labelOf = (name: ThemeName) => offered.find((d) => d.value === name)?.label ?? name;
     const isDark = (name: ThemeName) => offered.find((d) => d.value === name)?.dark ?? false;
 
-    // `?? theme` (the active theme), never a "light"/"dark" literal: with an open
-    // registry those names may not exist at all in this app.
-    const lightTheme: ThemeName = pickByDarkness(offered, false) ?? theme;
-    const darkTheme: ThemeName = pickByDarkness(offered, true) ?? theme;
-
     // The concrete theme to DISPLAY as current: the controlled preference when
     // it names one, otherwise the theme actually applied via the provider.
     const resolvedTheme: ThemeName =
       isControlled && preference !== undefined && preference !== "system" ? preference : theme;
 
+    // ADR 0036 — the family layout is OPT-IN: only when the offered list (not the
+    // provider's `families`, so the `themes` prop still narrows) holds two or
+    // more DECLARED families. An undeclared `[daylight, midnight]` pair keeps
+    // today's toggle byte-for-byte.
+    const families = groupThemeFamilies(offered);
+    const useFamilies = mode === "auto" && families.filter((f) => f.declared).length >= 2;
+    // Match by the active definition's declared family, not the retained
+    // light/dark slots: a second same-scheme variant is still reachable via
+    // `setTheme` but is not in either slot.
+    const activeDefinition = offered.find((d) => d.value === resolvedTheme);
+    const activeFamily = useFamilies
+      ? ((activeDefinition && families.find((f) => f.id === themeFamilyIdOf(activeDefinition))) ??
+        families[0])
+      : undefined;
+    // "System" is scoped to the active family in the family layout.
+    const scope: readonly ThemeDefinition[] = activeFamily
+      ? [activeFamily.light, activeFamily.dark].filter((d): d is ThemeDefinition => d !== undefined)
+      : offered;
+
+    // `?? theme` (the active theme), never a "light"/"dark" literal: with an open
+    // registry those names may not exist at all in this app.
+    const lightTheme: ThemeName = pickByDarkness(scope, false) ?? theme;
+    const darkTheme: ThemeName = pickByDarkness(scope, true) ?? theme;
+
+    // The scheme the user last chose, so dark → a light-only family → a
+    // two-scheme family lands on dark again (mirrors the provider's `setFamily`).
+    // Remembered together with the theme it produced: once something else changes
+    // the theme (another control calling `setTheme`), the memory no longer applies.
+    const intendedSchemeRef = useRef<{ scheme: ThemeScheme; theme: ThemeName } | undefined>(
+      undefined,
+    );
+
     // Hydrate the "system" choice from localStorage and apply it on mount —
     // uncontrolled mode only. Controlled mode's "system" state comes from the
     // `preference` prop and never touches this component's own storage key.
@@ -193,6 +235,90 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
     }, [switchTheme, darkTheme, lightTheme, isControlled, onPreferenceChange]);
 
     const TriggerIcon = isSystem ? Monitor : isDark(resolvedTheme) ? Moon : Sun;
+
+    // ---- Family layout (≥2 declared families): family group + scheme group ----
+    if (activeFamily) {
+      const activeScheme = activeDefinition;
+      const remembered = intendedSchemeRef.current;
+      const intended =
+        remembered && remembered.theme === resolvedTheme
+          ? remembered.scheme
+          : activeScheme
+            ? themeSchemeOf(activeScheme)
+            : "light";
+      const pickFamily = (familyId: string) => {
+        // System re-resolves against the OS immediately on a family change
+        // instead of waiting for the next `change` event.
+        const scheme: ThemeScheme = isSystem ? (prefersDark() ? "dark" : "light") : intended;
+        const next = resolveThemeVariant(families, familyId, scheme);
+        if (next === undefined) return;
+        intendedSchemeRef.current = { scheme: intended, theme: next };
+        if (isSystem) switchTheme(next);
+        else pickTheme(next);
+      };
+      const pickScheme = (value: string) => {
+        if (value === "system") {
+          pickSystem();
+          return;
+        }
+        const scheme = value as ThemeScheme;
+        const next = activeFamily[scheme]?.value;
+        if (next === undefined) return;
+        intendedSchemeRef.current = { scheme, theme: next };
+        pickTheme(next);
+      };
+      const schemeValue = isSystem ? "system" : activeScheme ? themeSchemeOf(activeScheme) : "";
+
+      return (
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              ref={ref}
+              variant="outline"
+              size={ICON_SIZE[size]}
+              aria-label={t("ui.themeSwitcher.theme")}
+              className={className}
+              {...props}
+            >
+              <TriggerIcon />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuLabel>{t("ui.themeSwitcher.theme")}</DropdownMenuLabel>
+            <DropdownMenuRadioGroup value={activeFamily.id} onValueChange={pickFamily}>
+              {families.map((f) => (
+                <DropdownMenuRadioItem key={f.id} value={f.id}>
+                  {f.label}
+                </DropdownMenuRadioItem>
+              ))}
+            </DropdownMenuRadioGroup>
+            {activeFamily.schemes.length === 2 ? (
+              <>
+                <DropdownMenuSeparator />
+                <DropdownMenuLabel>{t("ui.themeSwitcher.mode")}</DropdownMenuLabel>
+                <DropdownMenuRadioGroup value={schemeValue} onValueChange={pickScheme}>
+                  <DropdownMenuRadioItem value="light">
+                    <Sun aria-hidden="true" />
+                    {t("ui.themeSwitcher.light")}
+                  </DropdownMenuRadioItem>
+                  <DropdownMenuRadioItem value="dark">
+                    <Moon aria-hidden="true" />
+                    {t("ui.themeSwitcher.dark")}
+                  </DropdownMenuRadioItem>
+                  {showSystem ? (
+                    <DropdownMenuRadioItem value="system">
+                      <Monitor aria-hidden="true" />
+                      {t("ui.themeSwitcher.system")}
+                    </DropdownMenuRadioItem>
+                  ) : null}
+                </DropdownMenuRadioGroup>
+              </>
+            ) : null}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      );
+    }
+
     const useDropdown = mode === "dropdown" || (mode === "auto" && safeThemes.length > 2);
 
     // ---- Dropdown mode (>2 themes) ----
@@ -204,7 +330,7 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
               ref={ref}
               variant="outline"
               size={ICON_SIZE[size]}
-              aria-label="Theme"
+              aria-label={t("ui.themeSwitcher.theme")}
               className={className}
               {...props}
             >
@@ -215,15 +341,15 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
             {showSystem ? (
               <DropdownMenuItem onSelect={() => pickSystem()}>
                 <Monitor />
-                <span>System</span>
-                {isSystem ? <Check className="ml-auto" /> : null}
+                <span>{t("ui.themeSwitcher.system")}</span>
+                {isSystem ? <Check className="ms-auto" /> : null}
               </DropdownMenuItem>
             ) : null}
             {offered.map((d) => (
               <DropdownMenuItem key={d.value} onSelect={() => pickTheme(d.value)}>
                 {d.dark ? <Moon /> : <Sun />}
                 <span>{d.label}</span>
-                {!isSystem && resolvedTheme === d.value ? <Check className="ml-auto" /> : null}
+                {!isSystem && resolvedTheme === d.value ? <Check className="ms-auto" /> : null}
               </DropdownMenuItem>
             ))}
           </DropdownMenuContent>
@@ -254,7 +380,9 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
     // `role` is optional only because `order[i]` is an indexed read under
     // `noUncheckedIndexedAccess`; the modulo above makes it always present.
     const roleLabel = (role: "light" | "dark" | "system" | undefined) =>
-      role === "system" ? "System" : labelOf(role === "dark" ? darkTheme : lightTheme);
+      role === "system"
+        ? t("ui.themeSwitcher.system")
+        : labelOf(role === "dark" ? darkTheme : lightTheme);
 
     return (
       <TooltipProvider>

package/src/components/theme-switcher/use-theme-transition.ts

@@ -15,8 +15,8 @@ type ViewTransitionDocument = Document & {
  * Transitions API (the chanhdai.com "theme toggle effect", adapted to brand-ui).
  *
  * - Direction-aware: sets `data-vt="to-dark|to-light"` on `<html>` from the
- *   target theme's `dark` flag, so the clip-path wipes the right way for ANY of
- *   the three themes (not just light/dark).
+ *   target theme's `dark` flag, so the clip-path wipes the right way for ANY
+ *   theme (not just light/dark).
  * - `data-vt-effect` selects the reveal shape (default "polygon").
  * - Motion-aware: under `useReducedMotion()` (OS or in-app preference) — or when
  *   the browser lacks `startViewTransition` — it falls back to an instant,

package/src/components/timeline/timeline.stories.tsx

@@ -11,6 +11,9 @@ const meta = {
     docs: {
       description: {
         component:
+          "The GENERIC ordered-steps rail; an agent execution trace is `AI/AgentTimeline` " +
+          "and git history is `Data/RevisionTimeline` — see " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). " +
           "Ordered steps with a vertical connector and status-colored nodes — THE shared " +
           "rail spine (#190). Two front doors over one rail: the array `items` API (the " +
           "editor's `:::timeline` target, `done|active|pending`) and the compound " +
@@ -78,6 +81,30 @@ export const Compound: Story = {
   },
 };
 
+export const TabularTimestamps: Story = {
+  // #386 — a right-aligned timestamp column of differing digit widths
+  // ("09:14" vs "11:47" vs "9:02") must not jitter: the span needs
+  // `tabular-nums` so every digit occupies equal width.
+  args: { items: [] },
+  render: () => (
+    <TimelineRoot aria-label="Run with numeric timestamps">
+      <TimelineItem status="complete" timestamp="09:14">
+        Searched financial filings
+      </TimelineItem>
+      <TimelineItem status="complete" timestamp="11:47">
+        Queried finance.revenue
+      </TimelineItem>
+      <TimelineItem status="pending" timestamp="9:02">
+        Draft the board note
+      </TimelineItem>
+    </TimelineRoot>
+  ),
+  play: async ({ canvas }) => {
+    const timestamp = await waitFor(() => canvas.getByText("09:14"));
+    await expect(getComputedStyle(timestamp).fontVariantNumeric).toContain("tabular-nums");
+  },
+};
+
 export const CanonicalStatuses: Story = {
   args: { items: [] },
   render: () => (

package/src/components/timeline/timeline.tsx

@@ -15,8 +15,15 @@
  *     parts. Keeps the editor-facing `done|active|pending` API unchanged by
  *     mapping in via `fromTimelineStatus` at the boundary.
  *
- * Fork-prevention: a Timeline re-implementation outside this folder fails
- * `pnpm timeline-fork:check` (scripts/check-timeline-fork.mjs).
+ * Deliberately NOT on this rail (a different grammar, not an oversight —
+ * RM-014, #133): `RevisionTimeline` (@elabs-ai/components-ui). Its rail is a
+ * multi-lane commit DAG whose node colour is LANE IDENTITY (the chart ramp),
+ * not `Status`, and whose fork/merge joins are cross-row beziers living in one
+ * SVG coordinate space spanning the whole list — neither of which a
+ * status-keyed node or an item-local `w-px` connector can express. Carrying
+ * both grammars here would cost ~5 opt-in props, four of them switching this
+ * rail's own node/connector/geometry/status announcement off. The four-point
+ * reason is in that component's docblock; reopen #133 before converging them.
  */
 import { forwardRef, type HTMLAttributes, type LiHTMLAttributes, type ReactNode } from "react";
 import { cn } from "../../lib/cn";
@@ -141,7 +148,7 @@ export const TimelineItem = forwardRef<HTMLLIElement, TimelineItemProps>(functio
           {children}
         </span>
         {timestamp ? (
-          <span className="shrink-0 text-meta text-muted-foreground">{timestamp}</span>
+          <span className="shrink-0 text-meta text-muted-foreground tabular-nums">{timestamp}</span>
         ) : null}
       </div>
       {description ? <p className="mt-0.5 text-body text-muted-foreground">{description}</p> : null}

package/src/components/toggle/toggle.tsx

@@ -21,7 +21,7 @@ export const toggleVariants = cva(
   // asChild wrapper overwrites data-state="on" with "closed" — aria-pressed
   // (Toggle) and aria-checked (ToggleGroupItem) are set by the toggle primitive
   // alone and survive the merge. (#214)
-  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium transition-colors duration-fast ease-standard hover:bg-muted hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground data-[state=on]:font-semibold aria-pressed:bg-accent aria-pressed:text-accent-foreground aria-pressed:font-semibold aria-checked:bg-accent aria-checked:text-accent-foreground aria-checked:font-semibold [&_svg]:size-4 [&_svg]:shrink-0",
+  "inline-flex items-center justify-center gap-2 rounded-control text-body font-control transition-colors duration-fast ease-standard hover:bg-muted hover:text-muted-foreground focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground data-[state=on]:font-semibold aria-pressed:bg-accent aria-pressed:text-accent-foreground aria-pressed:font-semibold aria-checked:bg-accent aria-checked:text-accent-foreground aria-checked:font-semibold [&_svg]:size-4 [&_svg]:shrink-0",
   {
     variants: {
       variant: {
@@ -44,7 +44,11 @@ export const toggleVariants = cva(
         segmented:
           "border-0 bg-transparent text-muted-foreground hover:bg-transparent hover:text-foreground aria-checked:bg-surface-elevated aria-checked:text-foreground aria-checked:font-medium aria-checked:shadow-sm aria-pressed:bg-surface-elevated aria-pressed:text-foreground aria-pressed:font-medium aria-pressed:shadow-sm data-[state=on]:bg-surface-elevated data-[state=on]:text-foreground data-[state=on]:font-medium data-[state=on]:shadow-sm",
       },
-      size: { default: "h-9 px-2.5 min-w-9", sm: "h-8 px-2 min-w-8", lg: "h-10 px-3 min-w-10" },
+      size: {
+        default: "h-control px-2.5 min-w-control",
+        sm: "h-control-sm px-2 min-w-control-sm",
+        lg: "h-control-lg px-3 min-w-control-lg",
+      },
     },
     defaultVariants: { variant: "default", size: "default" },
   },
@@ -57,6 +61,7 @@ export const Toggle = forwardRef<
   return (
     <TogglePrimitive.Root
       ref={ref}
+      data-slot="toggle"
       className={cn(toggleVariants({ variant, size }), className)}
       {...props}
     />

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

@@ -1,3 +1,5 @@
+"use client";
+
 import {
   createContext,
   forwardRef,

package/src/components/toolbar/toolbar.stories.tsx

@@ -28,10 +28,18 @@ import {
  * expect there.
  */
 const meta = {
-  title: "Foundation/Toolbar",
+  title: "Layout/Toolbar",
   component: Toolbar,
   tags: ["autodocs"],
-  parameters: { layout: "padded" },
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The one row that genuinely claims the `toolbar` ARIA role: Radix delegates a roving tabindex to it, so ten controls cost one tab stop instead of ten. The row above a list, table or board — filters left, actions right — is `Layout/ViewToolbar`, which deliberately does NOT claim that role because its controls are ordinary tab stops. See [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs).",
+      },
+    },
+  },
   args: { "aria-label": "Formatting" },
 } satisfies Meta<typeof Toolbar>;
 

package/src/components/tooltip/tooltip.tsx

@@ -14,9 +14,10 @@ export const TooltipContent = forwardRef<
     <TooltipPrimitive.Portal>
       <TooltipPrimitive.Content
         ref={ref}
+        data-slot="tooltip-content"
         sideOffset={sideOffset}
         className={cn(
-          "z-50 overflow-hidden rounded-md bg-foreground px-2.5 py-1.5 text-xs text-background shadow-md",
+          "z-50 overflow-hidden rounded-md bg-foreground px-2.5 py-1.5 text-meta text-background shadow-md",
           "data-[state=delayed-open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95",
           className,
         )}

package/src/components/top-nav/top-nav.tsx

@@ -17,7 +17,7 @@ export const TopNav = forwardRef<HTMLElement, TopNavProps>(function TopNav(
     <header
       ref={ref}
       className={cn(
-        "sticky top-0 z-30 flex h-14 items-center gap-4 border-b bg-surface-elevated/80 px-4 backdrop-blur",
+        "sticky top-0 z-30 flex h-header items-center gap-4 border-b bg-surface-elevated/80 px-4 backdrop-blur",
         className,
       )}
       {...props}