@elabs-ai/components-ui 4.1.0 → 5.0.0

package/src/components/tree/use-tree-keyboard.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { TreeNode } from "./tree";
 
 /**
@@ -125,6 +125,31 @@ export function useTreeKeyboard<T>(options: UseTreeKeyboardOptions<T>): UseTreeK
     }
   }, []);
 
+  // Memoised O(1) lookups — rebuilt only when the tree shape / expansion
+  // actually changes, not on every keypress (a full re-flatten + `indexOf`/
+  // `findNode` walk per arrow key is O(n) on a large tree).
+  const visible = useMemo(
+    () => (virtualize && flatNodeIds ? flatNodeIds : flattenVisible(nodes, expandedIds)),
+    [virtualize, flatNodeIds, nodes, expandedIds],
+  );
+  const visibleIndexById = useMemo(() => {
+    const map = new Map<string, number>();
+    visible.forEach((id, i) => map.set(id, i));
+    return map;
+  }, [visible]);
+  const nodeById = useMemo(() => {
+    const map = new Map<string, TreeNode<T>>();
+    function walk(list: TreeNode<T>[]) {
+      for (const node of list) {
+        map.set(node.id, node);
+        if (node.children?.length) walk(node.children);
+      }
+    }
+    walk(nodes);
+    return map;
+  }, [nodes]);
+  const parentMapMemo = useMemo(() => buildParentMap(nodes), [nodes]);
+
   // Typeahead buffer
   const typeaheadBuffer = useRef<string>("");
   const typeaheadTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -156,8 +181,7 @@ export function useTreeKeyboard<T>(options: UseTreeKeyboardOptions<T>): UseTreeK
 
       // Element not mounted — happens when it's scrolled out of the virtual window.
       if (virtualize && scrollToVirtualIndex && pendingFocusIdRef) {
-        const ids = flatNodeIds ?? [];
-        const index = ids.indexOf(id);
+        const index = visibleIndexById.get(id) ?? -1;
         if (index >= 0) {
           pendingFocusIdRef.current = id;
           scrollToVirtualIndex(index);
@@ -165,18 +189,16 @@ export function useTreeKeyboard<T>(options: UseTreeKeyboardOptions<T>): UseTreeK
         }
       }
     },
-    [virtualize, flatNodeIds, pendingFocusIdRef, scrollToVirtualIndex],
+    [virtualize, visibleIndexById, pendingFocusIdRef, scrollToVirtualIndex],
   );
 
   const onKeyDown = useCallback(
     (e: React.KeyboardEvent<HTMLElement>) => {
       if (!activeId) return;
 
-      // In virtual mode use the pre-computed flat list so we don't re-flatten
-      const visible = virtualize && flatNodeIds ? flatNodeIds : flattenVisible(nodes, expandedIds);
-      const currentIndex = visible.indexOf(activeId);
-      const currentNode = findNode(nodes, activeId);
-      const parentMap = buildParentMap(nodes);
+      const currentIndex = visibleIndexById.get(activeId) ?? -1;
+      const currentNode = nodeById.get(activeId);
+      const parentMap = parentMapMemo;
 
       const moveTo = (id: string) => {
         e.preventDefault();
@@ -185,7 +207,7 @@ export function useTreeKeyboard<T>(options: UseTreeKeyboardOptions<T>): UseTreeK
 
       const selectNode = (id: string) => {
         if (selectionMode === "none") return;
-        const node = findNode(nodes, id);
+        const node = nodeById.get(id);
         if (node?.disabled) return;
         if (selectionMode === "single") {
           onSelectionChange(new Set([id]));
@@ -282,7 +304,7 @@ export function useTreeKeyboard<T>(options: UseTreeKeyboardOptions<T>): UseTreeK
               ...visible.slice(0, currentIndex + 1),
             ];
             for (const id of searchList) {
-              const node = findNode(nodes, id);
+              const node = nodeById.get(id);
               if (!node) continue;
               // only string labels are searchable
               if (typeof node.label !== "string") continue;
@@ -298,15 +320,16 @@ export function useTreeKeyboard<T>(options: UseTreeKeyboardOptions<T>): UseTreeK
     },
     [
       activeId,
-      nodes,
+      visible,
+      visibleIndexById,
+      nodeById,
+      parentMapMemo,
       expandedIds,
       onExpandedChange,
       selectionMode,
       selectedIds,
       onSelectionChange,
       setActiveId,
-      virtualize,
-      flatNodeIds,
     ],
   );
 

package/src/components/tree-select/tree-select.stories.tsx

@@ -51,6 +51,15 @@ const meta = {
   title: "Forms/TreeSelect",
   component: TreeSelect,
   tags: ["autodocs"],
+  // The trigger fills its container by default (no hard-fixed width) — cap
+  // the docs canvas to a realistic form-field width.
+  decorators: [
+    (Story) => (
+      <div className="w-72">
+        <Story />
+      </div>
+    ),
+  ],
   argTypes: {
     nodes: {
       description: "Hierarchical tree data (`TreeNode[]`).",

package/src/components/tree-select/tree-select.test.tsx

@@ -37,4 +37,9 @@ describe("TreeSelect", () => {
     render(<TreeSelect nodes={nodes} multiple value={["apple", "banana", "carrot"]} />);
     expect(screen.getByText("+1")).toBeInTheDocument();
   });
+
+  it("does not hard-fix the trigger width — fills its container by default", () => {
+    render(<TreeSelect nodes={nodes} />);
+    expect(screen.getByRole("combobox").className).not.toMatch(/\bw-64\b/);
+  });
 });

package/src/components/tree-select/tree-select.tsx

@@ -7,6 +7,7 @@ import { cn } from "../../lib/cn";
 import { Badge } from "../badge";
 import { Button } from "../button";
 import { Popover, PopoverContent, PopoverTrigger } from "../popover";
+import { useLocale } from "../locale-provider";
 import { Tree, type TreeNode } from "../tree";
 
 export interface TreeSelectProps<T = unknown> extends Omit<
@@ -47,18 +48,11 @@ function findLabel<T>(nodes: TreeNode<T>[], id: string): ReactNode | undefined {
  * selection; composes `Tree` for all keyboard/SR behaviour.
  */
 export const TreeSelect = forwardRef<HTMLButtonElement, TreeSelectProps>(function TreeSelect(
-  {
-    nodes,
-    value,
-    defaultValue,
-    onValueChange,
-    multiple = false,
-    placeholder = "Select…",
-    className,
-    ...props
-  },
+  { nodes, value, defaultValue, onValueChange, multiple = false, placeholder, className, ...props },
   ref,
 ) {
+  const { t } = useLocale();
+  const resolvedPlaceholder = placeholder ?? t("ui.treeSelect.placeholder");
   const [open, setOpen] = useState(false);
   const treeId = useId();
   const isControlled = value !== undefined;
@@ -88,12 +82,12 @@ export const TreeSelect = forwardRef<HTMLButtonElement, TreeSelectProps>(functio
           aria-haspopup="tree"
           aria-expanded={open}
           aria-controls={treeId}
-          className={cn("h-auto min-h-9 w-64 justify-between font-normal", className)}
+          className={cn("h-auto min-h-9 w-full justify-between font-normal", className)}
           {...props}
         >
           <span className="flex min-w-0 flex-1 flex-wrap items-center gap-1 text-start">
             {labels.length === 0 ? (
-              <span className="text-muted-foreground">{placeholder}</span>
+              <span className="text-muted-foreground">{resolvedPlaceholder}</span>
             ) : multiple ? (
               <>
                 {labels.slice(0, 2).map((l) => (
@@ -106,7 +100,10 @@ export const TreeSelect = forwardRef<HTMLButtonElement, TreeSelectProps>(functio
                   </Badge>
                 ))}
                 {labels.length > 2 ? (
-                  <Badge variant="secondary" aria-label={`and ${labels.length - 2} more selected`}>
+                  <Badge
+                    variant="secondary"
+                    aria-label={t("ui.treeSelect.moreSelected", { count: labels.length - 2 })}
+                  >
                     +{labels.length - 2}
                   </Badge>
                 ) : null}
@@ -118,7 +115,7 @@ export const TreeSelect = forwardRef<HTMLButtonElement, TreeSelectProps>(functio
           <ChevronsUpDown className="ms-2 size-4 shrink-0 opacity-50" aria-hidden="true" />
         </Button>
       </PopoverTrigger>
-      <PopoverContent className="w-64 p-1" align="start">
+      <PopoverContent className="w-[var(--radix-popover-trigger-width)] min-w-64 p-1" align="start">
         <Tree
           id={treeId}
           nodes={nodes}

package/src/components/typography/prose.test.tsx

@@ -20,12 +20,13 @@ import { ProseLink } from "./prose";
 afterEach(cleanup);
 
 describe("ProseLink — #399 on-surface brand-accent rung", () => {
-  it("renders text-primary-text, never the text-primary fill rung", () => {
+  // `text-link` reads `--link`, which the reference themes alias to `--primary-text`.
+  it("renders the link ink, never the text-primary fill rung", () => {
     render(<ProseLink href="https://example.com">docs</ProseLink>);
 
     const link = screen.getByRole("link", { name: "docs" });
     const classes = link.className.split(/\s+/);
-    expect(classes).toContain("text-primary-text");
+    expect(classes).toContain("text-link");
     expect(classes).not.toContain("text-primary");
   });
 

package/src/components/typography/prose.tsx

@@ -116,10 +116,10 @@ export const ProseLink = forwardRef<HTMLAnchorElement, ProseLinkProps>(function
       ref={ref}
       href={href}
       className={cn(
-        // #399 — `text-primary-text`, not the `text-primary` FILL rung: a prose
-        // link is ordinary body text and owes WCAG 1.4.3 AA (4.5:1), which the
+        // #399 — `text-link` (defaults to `--primary-text`), not the `text-primary`
+        // FILL rung: a prose link is ordinary body text and owes WCAG 1.4.3 AA (4.5:1), which the
         // fill only guarantees at the 1.4.11 mark bar (3:1).
-        "font-medium text-primary-text underline underline-offset-4 hover:no-underline focus-ring",
+        "font-medium text-link underline underline-offset-4 hover:no-underline focus-ring",
         className,
       )}
       {...(isExternal ? { target: "_blank", rel: "noopener noreferrer" } : {})}

package/src/components/typography/typography.stories.tsx

@@ -51,8 +51,10 @@ export const TextVariants: Story = {
       <Text variant="lead">Lead — a lead paragraph: the subtitle rung at body weight.</Text>
       <Text variant="body">Body — default reading text for app surfaces.</Text>
       <Text variant="caption">Caption — secondary / supporting body.</Text>
-      <Text variant="meta">Meta — metadata, eyebrows, timestamps.</Text>
+      <Text variant="meta">Meta — metadata, timestamps.</Text>
+      <Text variant="eyebrow">Eyebrow — an uppercase tracked label</Text>
       <Text variant="kpi">12,480</Text>
+      <Text variant="kpi-sm">1,284 — kpi-sm, a tile or satellite value</Text>
       <Text variant="code">pnpm --filter @elabs-ai/components-ui test</Text>
     </div>
   ),
@@ -84,6 +86,9 @@ export const Headings: Story = {
 export const HeadingSizeOverride: Story = {
   render: () => (
     <div className="space-y-3">
+      <Heading level={1} size="display-lg">
+        An h1 that reads as display-lg — a hero or deck headline
+      </Heading>
       <Heading level={2} size="display">
         An h2 that reads as display
       </Heading>
@@ -385,7 +390,7 @@ function CjkPanel({ sample }: { sample: CjkSample }) {
 }
 
 export const CJKFontAndLineBreaking: Story = {
-  name: "CJK font fallback + line-breaking (#15)",
+  name: "CJK font fallback + line-breaking",
   parameters: {
     docs: {
       description: {

package/src/components/typography/typography.tsx

@@ -27,6 +27,8 @@ export const TEXT_ROLE_REM = {
   meta: 0.75,
   kpi: 2,
   code: 0.8125,
+  "kpi-sm": 1.5,
+  "display-lg": 3,
 } as const;
 
 export type TextRole = keyof typeof TEXT_ROLE_REM;
@@ -41,6 +43,10 @@ export const textVariants = cva("", {
       meta: "text-meta",
       /** KPI values pair with tabular figures (interaction-guidelines). */
       kpi: "text-kpi tabular-nums",
+      /** A tile/satellite value — the rung between title and kpi. */
+      "kpi-sm": "text-kpi-sm tabular-nums",
+      /** An uppercase tracked label above a title or a column header. */
+      eyebrow: "text-eyebrow uppercase",
       /** Inline/block code pairs with the `--font-mono` seam. */
       code: "text-code font-mono",
     },
@@ -79,6 +85,8 @@ export const headingVariants = cva("text-balance text-foreground", {
   variants: {
     size: {
       /** display + title carry the `--font-display` brand seam (research 07 §E.5). */
+      /** A hero/deck headline — the rung above display. */
+      "display-lg": "font-display text-display-lg",
       display: "font-display text-display",
       title: "font-display text-title",
       subtitle: "text-subtitle",

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

@@ -16,7 +16,7 @@ const meta = {
     docs: {
       description: {
         component:
-          "The row above a list, table or board — filters and context on the left, actions on the right. Its controls are ordinary tab stops on purpose: a dense secondary control row that should cost ONE tab stop with arrow-key roving is `Layout/Toolbar`, the component that actually claims the `toolbar` ARIA role. See [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs) and [Docs / View Toolbar Contract](?path=/docs/docs-view-toolbar-contract--docs) (rule R10) for the filter-chip, result-count and control-height rules of this row.",
+          "The row above a list, table or board — filters and context on the left, actions on the right. Its controls are ordinary tab stops on purpose: a dense secondary control row that should cost ONE tab stop with arrow-key roving is `Layout/Toolbar`, the component that actually claims the `toolbar` ARIA role. See [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs) and [ViewToolbar → Contract](?path=/docs/layout-viewtoolbar--contract) (rule R10) for the filter-chip, result-count and control-height rules of this row.",
       },
     },
   },
@@ -369,6 +369,7 @@ export const DarkTheme: Story = {
 
 /** The same row at decoration 10 — drawn, not filled. */
 export const HighDecoration: Story = {
+  tags: ["!dev"],
   globals: { decoration: "10" },
   render: () => (
     <ViewToolbar info={VIEW_INFO} actions={<ViewActions />} className="w-full max-w-4xl">

package/src/components/view-toolbar/view-toolbar.tsx

@@ -21,7 +21,7 @@
  *
  * - **No `cva`.** None of the four parts has a second visual axis today, and the
  *   rules forbid dead variants. A sticky/bounded bar is a caller `className`
- *   recipe (documented in `Docs/View Toolbar Contract`), not a variant.
+ *   recipe (documented in `Layout/ViewToolbar → Contract`), not a variant.
  * - **No `role="toolbar"` on the root.** That role promises roving-tabindex
  *   arrow-key navigation, which this row does not implement; claiming it would
  *   mislead assistive tech. Every control is an ordinary tab stop instead, and
@@ -65,7 +65,7 @@ export interface ViewToolbarProps extends HTMLAttributes<HTMLDivElement> {
    * focus but deliberately NOT on tap (and Radix suppresses the focus-open when
    * focus arrived from a pointer), so on a touch device this text is
    * unreachable. Treat `info` as progressive enhancement: never put something a
-   * phone user cannot do without in it. See `Docs/View Toolbar Contract`.
+   * phone user cannot do without in it. See `Layout/ViewToolbar → Contract`.
    */
   info?: ReactNode;
   /** Left cluster — status/context, `ViewToolbarFilters`, `ResultCount`. */

package/src/components/virtual-select/virtual-select.stories.tsx

@@ -58,6 +58,15 @@ const meta = {
       },
     },
   },
+  // The trigger fills its container by default (no hard-fixed width) — cap
+  // the docs canvas to a realistic form-field width.
+  decorators: [
+    (Story) => (
+      <div className="w-72">
+        <Story />
+      </div>
+    ),
+  ],
   argTypes: {
     options: {
       description:

package/src/components/virtual-select/virtual-select.test.tsx

@@ -12,8 +12,8 @@
  *   - Virtualizer scroll behavior with 10,000 options
  *   - Cross-theme visual correctness
  */
-import { describe, expect, it } from "vitest";
-import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
 import { VirtualSelect } from "./virtual-select";
 import type { VirtualSelectOption } from "./virtual-select";
 
@@ -104,3 +104,29 @@ describe("VirtualSelect defaultValue (uncontrolled)", () => {
     expect(screen.getByText("Gamma")).toBeInTheDocument();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Deferred autofocus timer — cancelled on unmount (#reviewed)
+// ---------------------------------------------------------------------------
+
+describe("VirtualSelect autofocus timer cleanup", () => {
+  it("cancels the pending search-input autofocus timeout when unmounted before it fires", () => {
+    vi.useFakeTimers();
+    try {
+      const { unmount } = render(<VirtualSelect options={OPTIONS} />);
+      const trigger = screen.getByRole("combobox");
+      // Opening schedules a deferred `searchRef.current?.focus()`.
+      fireEvent.click(trigger);
+      const pendingBeforeUnmount = vi.getTimerCount();
+      expect(pendingBeforeUnmount).toBeGreaterThan(0);
+
+      unmount();
+
+      // The pending timer must be cancelled on unmount — left uncancelled, it
+      // stays scheduled and fires later against a torn-down `searchRef`.
+      expect(vi.getTimerCount()).toBeLessThan(pendingBeforeUnmount);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/components/virtual-select/virtual-select.tsx

@@ -19,6 +19,7 @@ import { Badge } from "../badge";
 import { Button } from "../button";
 import { Input } from "../input";
 import { Popover, PopoverContent, PopoverTrigger } from "../popover";
+import { useLocale } from "../locale-provider";
 import { type VirtualSelectOption, useVirtualListbox } from "./use-virtual-listbox";
 
 export type { VirtualSelectOption };
@@ -85,9 +86,9 @@ export const VirtualSelect = forwardRef<HTMLButtonElement, VirtualSelectProps>(
       value,
       defaultValue,
       onValueChange,
-      placeholder = "Select…",
-      searchPlaceholder = "Search…",
-      emptyText = "No results.",
+      placeholder,
+      searchPlaceholder,
+      emptyText,
       estimateOptionHeight = 32,
       maxListHeight = "18rem",
       className,
@@ -95,6 +96,11 @@ export const VirtualSelect = forwardRef<HTMLButtonElement, VirtualSelectProps>(
     },
     ref,
   ) {
+    const { t } = useLocale();
+    const resolvedPlaceholder = placeholder ?? t("ui.virtualSelect.placeholder");
+    const resolvedSearchPlaceholder = searchPlaceholder ?? t("ui.virtualSelect.searchPlaceholder");
+    const resolvedEmptyText = emptyText ?? t("noResults");
+
     // ------------------------------------------------------------------
     // Controlled / uncontrolled
     // ------------------------------------------------------------------
@@ -135,6 +141,15 @@ export const VirtualSelect = forwardRef<HTMLButtonElement, VirtualSelectProps>(
       [options, query],
     );
 
+    // O(1) label lookup for the trigger's selected chips — `selected.map(find)`
+    // is O(selected.length * options.length) and options lists here can be
+    // large (that's the whole point of virtualizing).
+    const optionByValue = useMemo(() => {
+      const map = new Map<string, VirtualSelectOption>();
+      for (const o of options) map.set(o.value, o);
+      return map;
+    }, [options]);
+
     // ------------------------------------------------------------------
     // Virtualizer
     // ------------------------------------------------------------------
@@ -184,26 +199,45 @@ export const VirtualSelect = forwardRef<HTMLButtonElement, VirtualSelectProps>(
     const listboxId = `${uid}-listbox`;
     const optionId = (index: number) => `${uid}-option-${index}`;
 
-    // Focus the search input when the popover opens
+    // Focus the search input when the popover opens. The timeout id is
+    // tracked so it can be cancelled on unmount (or a rapid re-close) —
+    // otherwise it fires after the component (and `searchRef`'s DOM node)
+    // is gone, or focuses a NEW popover's input on a fast toggle.
+    const focusTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+    useEffect(
+      () => () => {
+        if (focusTimeoutRef.current != null) clearTimeout(focusTimeoutRef.current);
+      },
+      [],
+    );
+
     const handleOpenChange = useCallback((next: boolean) => {
       setOpen(next);
+      if (focusTimeoutRef.current != null) {
+        clearTimeout(focusTimeoutRef.current);
+        focusTimeoutRef.current = null;
+      }
       if (next) {
         // Defer one frame so Radix has mounted the portal
-        setTimeout(() => searchRef.current?.focus(), 0);
+        focusTimeoutRef.current = setTimeout(() => {
+          focusTimeoutRef.current = null;
+          searchRef.current?.focus();
+        }, 0);
       }
     }, []);
 
     // ------------------------------------------------------------------
     // Trigger label
     // ------------------------------------------------------------------
-    const selectedLabels = selected.map((v) => {
-      const opt = options.find((o) => o.value === v);
-      return { value: v, label: opt?.label ?? v };
-    });
+    const selectedLabels = selected.map((v) => ({
+      value: v,
+      label: optionByValue.get(v)?.label ?? v,
+    }));
 
     const triggerContent =
       selectedLabels.length === 0 ? (
-        <span className="text-muted-foreground">{placeholder}</span>
+        <span className="text-muted-foreground">{resolvedPlaceholder}</span>
       ) : multiple ? (
         <>
           {selectedLabels.slice(0, 2).map((l) => (
@@ -247,7 +281,7 @@ export const VirtualSelect = forwardRef<HTMLButtonElement, VirtualSelectProps>(
             aria-expanded={open}
             aria-haspopup="listbox"
             aria-controls={listboxId}
-            className={cn("h-auto min-h-9 w-64 justify-between font-normal", className)}
+            className={cn("h-auto min-h-9 w-full justify-between font-normal", className)}
             {...props}
           >
             <span className="flex min-w-0 flex-1 flex-wrap items-center gap-1 text-start">
@@ -258,7 +292,7 @@ export const VirtualSelect = forwardRef<HTMLButtonElement, VirtualSelectProps>(
         </PopoverTrigger>
 
         <PopoverContent
-          className="w-64 p-0"
+          className="w-[var(--radix-popover-trigger-width)] min-w-64 p-0"
           align="start"
           // Prevent Radix from stealing focus so it can go to the input
           onOpenAutoFocus={(e) => e.preventDefault()}
@@ -270,17 +304,21 @@ export const VirtualSelect = forwardRef<HTMLButtonElement, VirtualSelectProps>(
               type="text"
               autoComplete="off"
               spellCheck={false}
-              placeholder={searchPlaceholder}
+              placeholder={resolvedSearchPlaceholder}
               value={query}
               onChange={(e) => setQuery(e.target.value)}
               onKeyDown={(e: KeyboardEvent<HTMLInputElement>) => onInputKeyDown(e)}
-              aria-label={searchPlaceholder}
+              aria-label={resolvedSearchPlaceholder}
               aria-autocomplete="list"
               aria-controls={listboxId}
               aria-activedescendant={
                 activeIndex >= 0 && activeMounted ? optionId(activeIndex) : undefined
               }
-              className="h-8 border-0 shadow-none focus-visible:ring-0 focus-visible:ring-offset-0"
+              // Border/shadow removed (sits inside the popover's own bordered
+              // header strip) but the base `Input` focus-ring is kept — no
+              // compound ring lives elsewhere on this control, so silencing it
+              // would leave a re-focused search box with no visible indicator.
+              className="h-8 border-0 shadow-none"
             />
           </div>
 
@@ -318,7 +356,7 @@ export const VirtualSelect = forwardRef<HTMLButtonElement, VirtualSelectProps>(
                         transform: `translateY(${virtualRow.start}px)`,
                       }}
                       className={cn(
-                        "flex cursor-pointer select-none items-center rounded-sm px-2 text-sm outline-none",
+                        "flex cursor-pointer select-none items-center rounded-sm px-2 text-body outline-none",
                         "transition-colors duration-fast motion-reduce:transition-none",
                         isActive && "bg-accent text-accent-foreground",
                         !isActive && "hover:bg-accent hover:text-accent-foreground",
@@ -349,9 +387,9 @@ export const VirtualSelect = forwardRef<HTMLButtonElement, VirtualSelectProps>(
             <div
               role="status"
               aria-live="polite"
-              className="px-2 py-6 text-center text-sm text-muted-foreground"
+              className="px-2 py-6 text-center text-body text-muted-foreground"
             >
-              {emptyText}
+              {resolvedEmptyText}
             </div>
           ) : null}
         </PopoverContent>

package/src/components/wizard/wizard.test.tsx

@@ -64,4 +64,13 @@ describe("Wizard", () => {
     await user.click(screen.getByRole("button", { name: "Next" }));
     await waitFor(() => expect(screen.getByRole("button", { name: "Finish" })).toBeInTheDocument());
   });
+
+  it("names the completed-step indicator button — it renders only an icon", async () => {
+    const user = userEvent.setup();
+    renderWizard();
+    await user.click(screen.getByRole("button", { name: "Next" }));
+    // The first step's indicator now shows a checkmark glyph with no text
+    // content — without an accessible name it would be an unlabelled button.
+    expect(screen.getByRole("button", { name: "Account — completed" })).toBeInTheDocument();
+  });
 });

package/src/components/wizard/wizard.tsx

@@ -232,8 +232,12 @@ export const WizardSteps = forwardRef<HTMLOListElement, WizardStepsProps>(functi
               type="button"
               disabled={!isClickable}
               onClick={() => goTo(index)}
+              // The completed state renders only a checkmark glyph (hidden
+              // from AT below) — with no text content, the button would
+              // otherwise have no accessible name at all.
+              aria-label={isComplete ? `${meta.title} — completed` : undefined}
               className={cn(
-                "flex size-7 shrink-0 items-center justify-center rounded-full border text-xs font-medium tabular-nums",
+                "flex size-7 shrink-0 items-center justify-center rounded-full border text-meta font-medium tabular-nums",
                 "focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
                 isActive && "border-primary bg-primary text-primary-foreground",
                 // #399 — the step NUMBER is text on a `/10` wash, not plate ink
@@ -248,14 +252,14 @@ export const WizardSteps = forwardRef<HTMLOListElement, WizardStepsProps>(functi
             <span className="flex min-w-0 flex-col">
               <span
                 className={cn(
-                  "truncate text-sm font-medium",
+                  "truncate text-body font-medium",
                   isActive ? "text-foreground" : "text-muted-foreground",
                 )}
               >
                 {meta.title}
               </span>
               {meta.description && (
-                <span className="truncate text-xs text-muted-foreground">{meta.description}</span>
+                <span className="truncate text-meta text-muted-foreground">{meta.description}</span>
               )}
             </span>
           </li>
@@ -309,7 +313,11 @@ export const WizardStep = forwardRef<HTMLDivElement, WizardStepProps>(function W
       role="group"
       aria-labelledby={`${baseId}-step-${step}`}
       tabIndex={-1}
-      className={cn("min-w-0 flex-1 focus-visible:outline-none", className)}
+      // Programmatically focused on step change (`regionRef.current?.focus()`
+      // above) — `focus-ring` gives that a visible indicator instead of
+      // silently discarding the browser's default outline (mirrors
+      // `DialogBody`'s same tabIndex={-1}-container precedent).
+      className={cn("min-w-0 flex-1 focus-ring", className)}
       {...props}
     >
       {children}