@elabs-ai/components-ui 4.0.0 → 4.1.0

package/src/components/table/table.test.tsx

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
-import { render, screen } from "@testing-library/react";
+import { fireEvent, render, screen } from "@testing-library/react";
 import { Table, TableBody, TableCell, TableRow } from "./table";
+
 describe("Table", () => {
   it("renders cells", () => {
     render(
@@ -15,3 +16,143 @@ describe("Table", () => {
     expect(screen.getByText("Alpha")).toBeInTheDocument();
   });
 });
+
+/**
+ * jsdom reports 0 for every layout metric, so overflow has to be simulated —
+ * same idiom as `packages/data/src/data-table/data-table.test.tsx`. Metrics
+ * are (re-)applied and the component's own `onScroll` handler is fired so the
+ * re-measurement runs through the real code path, not by poking at state.
+ */
+function setScrollMetrics(
+  el: HTMLElement,
+  { scrollWidth, clientWidth, scrollHeight, clientHeight }: Record<string, number>,
+) {
+  Object.defineProperty(el, "scrollWidth", { configurable: true, value: scrollWidth });
+  Object.defineProperty(el, "clientWidth", { configurable: true, value: clientWidth });
+  Object.defineProperty(el, "scrollHeight", { configurable: true, value: scrollHeight });
+  Object.defineProperty(el, "clientHeight", { configurable: true, value: clientHeight });
+  fireEvent.scroll(el);
+}
+
+function scrollRegionOf(container: HTMLElement): HTMLElement {
+  const el = container.querySelector<HTMLElement>('[data-slot="table-scroll-region"]');
+  if (!el) throw new Error('no [data-slot="table-scroll-region"] in the rendered output');
+  return el;
+}
+
+describe("Table — #366 the scroll wrapper's tab stop exists only while it measurably overflows", () => {
+  it("adds NO tab stop and NO accessible name to a table that fits its container", () => {
+    const { container } = render(
+      <Table>
+        <TableBody>
+          <TableRow>
+            <TableCell>Alpha</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>,
+    );
+    const scrollRegion = scrollRegionOf(container);
+    setScrollMetrics(scrollRegion, {
+      scrollWidth: 300,
+      clientWidth: 300,
+      scrollHeight: 100,
+      clientHeight: 100,
+    });
+    // A table that doesn't scroll must not gain a focus stop that does
+    // nothing, nor announce itself as "scrollable" — axe's
+    // `scrollable-region-focusable` only fires the other way round, so this
+    // is the locking assertion for it.
+    expect(scrollRegion).not.toHaveAttribute("tabindex");
+    expect(scrollRegion).not.toHaveAttribute("aria-label");
+    expect(screen.queryByLabelText("Table contents, scrollable")).toBeNull();
+  });
+
+  it("gains the tab stop + accessible name once the region measurably overflows vertically", () => {
+    const { container } = render(
+      <Table>
+        <TableBody>
+          <TableRow>
+            <TableCell>Alpha</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>,
+    );
+    const scrollRegion = scrollRegionOf(container);
+    setScrollMetrics(scrollRegion, {
+      scrollWidth: 300,
+      clientWidth: 300,
+      scrollHeight: 800,
+      clientHeight: 200,
+    });
+    expect(scrollRegion).toHaveAttribute("tabindex", "0");
+    expect(screen.getByLabelText("Table contents, scrollable")).toBe(scrollRegion);
+  });
+
+  it("gains the tab stop + accessible name once the region measurably overflows horizontally", () => {
+    const { container } = render(
+      <Table>
+        <TableBody>
+          <TableRow>
+            <TableCell>Alpha</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>,
+    );
+    const scrollRegion = scrollRegionOf(container);
+    setScrollMetrics(scrollRegion, {
+      scrollWidth: 900,
+      clientWidth: 300,
+      scrollHeight: 100,
+      clientHeight: 100,
+    });
+    expect(scrollRegion).toHaveAttribute("tabindex", "0");
+    expect(screen.getByLabelText("Table contents, scrollable")).toBe(scrollRegion);
+  });
+
+  it("drops the tab stop again when the overflow goes away (e.g. the container grows)", () => {
+    const { container } = render(
+      <Table>
+        <TableBody>
+          <TableRow>
+            <TableCell>Alpha</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>,
+    );
+    const scrollRegion = scrollRegionOf(container);
+    setScrollMetrics(scrollRegion, {
+      scrollWidth: 300,
+      clientWidth: 300,
+      scrollHeight: 800,
+      clientHeight: 200,
+    });
+    expect(scrollRegion).toHaveAttribute("tabindex", "0");
+    setScrollMetrics(scrollRegion, {
+      scrollWidth: 300,
+      clientWidth: 300,
+      scrollHeight: 800,
+      clientHeight: 900,
+    });
+    expect(scrollRegion).not.toHaveAttribute("tabindex");
+  });
+
+  it('never adds a redundant role="region" landmark', () => {
+    const { container } = render(
+      <Table>
+        <TableBody>
+          <TableRow>
+            <TableCell>Alpha</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>,
+    );
+    const scrollRegion = scrollRegionOf(container);
+    setScrollMetrics(scrollRegion, {
+      scrollWidth: 300,
+      clientWidth: 300,
+      scrollHeight: 800,
+      clientHeight: 200,
+    });
+    expect(scrollRegion).not.toHaveAttribute("role");
+  });
+});

package/src/components/table/table.tsx

@@ -1,17 +1,76 @@
 import {
   forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
   type HTMLAttributes,
   type TdHTMLAttributes,
   type ThHTMLAttributes,
 } from "react";
 import { cn } from "../../lib/cn";
+import { useLocale } from "../locale-provider";
 
+/**
+ * `Table`'s own scroll wrapper, gated on MEASURED overflow (#366).
+ *
+ * `className`/`ref`/`...props` all land on the `<table>` — unchanged, no new
+ * prop — so this wrapper is internal plumbing, not a new public surface. It
+ * follows `DataTable`'s non-virtualized branch verbatim
+ * (`packages/data/src/data-table/data-table.tsx:1658-1695`, #330), the
+ * closest precedent: a plain `overflow-auto` box with no pinned columns, no
+ * loading overlay and no edge fade to carry along, just the keyboard
+ * affordance itself.
+ *
+ * A table that FITS must stay a byte-identical no-op: no `tabIndex`, no
+ * `aria-label`, no ring — an unconditional stop would announce "scrollable"
+ * on content that never scrolls. Only a table that measurably overflows
+ * gets the tab stop, its accessible name (WCAG 4.1.2) and the compound focus
+ * ring (`focus-ring-inset` — the wrapper's own edge is the scroll clip, so an
+ * outside ring would be cut, `.claude/rules/theming.md`). No `role="region"`:
+ * both existing precedents (`DataTable`, `SheetTable`) decided against a
+ * redundant landmark over a real `<table>`, and this wrapper adds none either.
+ */
 export const Table = forwardRef<HTMLTableElement, HTMLAttributes<HTMLTableElement>>(function Table(
   { className, ...props },
   ref,
 ) {
+  const { t } = useLocale();
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const [scrollOverflows, setScrollOverflows] = useState(false);
+
+  const updateScrollAffordance = useCallback(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    // 1px tolerance absorbs sub-pixel layout rounding, which would otherwise
+    // report a permanent 0.5px overflow on a table that visually fits.
+    setScrollOverflows(
+      el.scrollWidth > el.clientWidth + 1 || el.scrollHeight > el.clientHeight + 1,
+    );
+  }, []);
+
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    updateScrollAffordance();
+    if (typeof ResizeObserver === "undefined") return;
+    // Observe the CONTAINER (viewport changes) and the <table> inside it
+    // (content changes its intrinsic size without resizing the container).
+    const observer = new ResizeObserver(updateScrollAffordance);
+    observer.observe(el);
+    if (el.firstElementChild) observer.observe(el.firstElementChild);
+    return () => observer.disconnect();
+  }, [updateScrollAffordance]);
+
   return (
-    <div className="relative w-full overflow-auto">
+    <div
+      ref={scrollRef}
+      data-slot="table-scroll-region"
+      tabIndex={scrollOverflows ? 0 : undefined}
+      aria-label={scrollOverflows ? t("ui.table.scrollRegion") : undefined}
+      onScroll={updateScrollAffordance}
+      className="relative w-full overflow-auto focus-ring-inset"
+    >
       <table ref={ref} className={cn("w-full caption-bottom text-body", className)} {...props} />
     </div>
   );

package/src/components/tabs/tabs.tsx

@@ -142,7 +142,13 @@ export const TabsTrigger = forwardRef<
       ref={mergedRef}
       className={cn(
         "inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-sm font-medium transition-colors duration-fast",
-        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+        // `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
+        // 9); at offset 1 it is exactly 4px and the loop closes.
+        "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
         "disabled:pointer-events-none disabled:opacity-50",
         "data-[state=active]:bg-surface-elevated data-[state=active]:text-foreground data-[state=active]:shadow-sm",
         className,
@@ -160,7 +166,7 @@ export const TabsContent = forwardRef<
     <TabsPrimitive.Content
       ref={ref}
       className={cn(
-        "mt-2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+        "mt-2 focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
         "data-[state=active]:animate-in data-[state=active]:fade-in-0 data-[state=active]:slide-in-from-bottom-1 data-[state=active]:[--tw-ease:var(--ease-entrance)]",
         className,
       )}

package/src/components/tag-input/tag-input.tsx

@@ -208,7 +208,7 @@ export const TagInput = forwardRef<HTMLDivElement, TagInputProps>(function TagIn
               }}
               className={cn(
                 "rounded-full p-0.5 transition-colors",
-                "hover:bg-secondary-foreground/20 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                "hover:bg-secondary-foreground/20 focus-ring",
                 "disabled:pointer-events-none disabled:opacity-50",
               )}
             >
@@ -240,7 +240,8 @@ export const TagInput = forwardRef<HTMLDivElement, TagInputProps>(function TagIn
         />
       </InputGroup>
       {error && (
-        <p role="alert" className="text-xs text-destructive">
+        // #124: running text (the validation message) — ink rung.
+        <p role="alert" className="text-xs text-destructive-text">
           {error}
         </p>
       )}

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

@@ -12,6 +12,7 @@ import {
   DropdownMenuTrigger,
 } from "../dropdown-menu";
 import { SidebarMenu, SidebarMenuButton, SidebarMenuItem, useSidebar } from "../sidebar";
+import { useLocale } from "../locale-provider";
 import { cn } from "../../lib/cn";
 
 export type TeamSwitcherTeam = {
@@ -37,6 +38,7 @@ export interface TeamSwitcherProps {
  */
 export function TeamSwitcher({ teams, logoClassName, className }: TeamSwitcherProps) {
   const { isMobile } = useSidebar();
+  const { t } = useLocale();
   const [activeTeam, setActiveTeam] = React.useState(teams[0]);
   if (!activeTeam) return null;
   const Logo = activeTeam.logo;
@@ -48,21 +50,44 @@ export function TeamSwitcher({ teams, logoClassName, className }: TeamSwitcherPr
           <DropdownMenuTrigger asChild>
             <SidebarMenuButton
               size="lg"
+              // The name is written out rather than left to the button's own
+              // contents, because the contents cannot carry it in every state:
+              // collapsed to the 48px rail the trigger is one glyph, and the
+              // label beside it is either gone or clipped out of view by the
+              // button's `overflow-hidden` — either way axe reads a nameless
+              // button (`button-name`, critical). The string is exactly the
+              // visible label, in reading order, so WCAG 2.5.3 (label in name)
+              // holds expanded, where that label IS on screen. Verified by
+              // deleting this line and watching three dashboard stories fail
+              // `button-name` (critical).
+              aria-label={`${activeTeam.name} ${activeTeam.plan}`}
               className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground"
             >
+              {/* Collapsed, this row is ONE ICON in a 48px rail and has to sit
+                  on the same centre line as every nav entry above and below it.
+                  Measured before this fix: the 32px plate did not fit the
+                  button's 16px content box, so it overflowed (clipped by the
+                  button's own `overflow-hidden`) and its glyph landed 8px to the
+                  trailing side of every other icon in the rail. So the plate
+                  becomes the glyph's own 16px box — no fill, no radius, nothing
+                  to overflow — and the label and chevron stand down: at 48px
+                  there is no room to read them, and they are what crowds the
+                  plate. Expanded, all three come back unchanged. */}
               <div
                 className={cn(
-                  "flex aspect-square size-8 items-center justify-center rounded-lg",
+                  "flex aspect-square size-8 shrink-0 items-center justify-center rounded-lg",
                   logoClassName ?? "bg-sidebar-accent text-sidebar-accent-foreground",
+                  "group-data-[collapsible=icon]:size-4 group-data-[collapsible=icon]:rounded-none group-data-[collapsible=icon]:bg-transparent group-data-[collapsible=icon]:text-sidebar-foreground",
                 )}
               >
                 <Logo className="size-4" />
               </div>
-              <div className="grid flex-1 text-start text-sm leading-tight">
+              <div className="grid flex-1 text-start text-sm leading-tight group-data-[collapsible=icon]:hidden">
                 <span className="truncate font-semibold">{activeTeam.name}</span>
                 <span className="truncate text-xs">{activeTeam.plan}</span>
               </div>
-              <ChevronsUpDown className="ms-auto" />
+              {/* Decorative, so it simply goes. */}
+              <ChevronsUpDown className="ms-auto group-data-[collapsible=icon]:hidden" />
             </SidebarMenuButton>
           </DropdownMenuTrigger>
           <DropdownMenuContent
@@ -71,7 +96,9 @@ export function TeamSwitcher({ teams, logoClassName, className }: TeamSwitcherPr
             side={isMobile ? "bottom" : "right"}
             sideOffset={4}
           >
-            <DropdownMenuLabel className="text-xs text-muted-foreground">Teams</DropdownMenuLabel>
+            <DropdownMenuLabel className="text-xs text-muted-foreground">
+              {t("ui.teamSwitcher.label")}
+            </DropdownMenuLabel>
             {teams.map((team, index) => (
               <DropdownMenuItem
                 key={team.name}
@@ -90,7 +117,9 @@ export function TeamSwitcher({ teams, logoClassName, className }: TeamSwitcherPr
               <div className="flex size-6 items-center justify-center rounded-md border bg-transparent">
                 <Plus className="size-4" />
               </div>
-              <div className="font-medium text-muted-foreground">Add team</div>
+              <div className="font-medium text-muted-foreground">
+                {t("ui.teamSwitcher.addTeam")}
+              </div>
             </DropdownMenuItem>
           </DropdownMenuContent>
         </DropdownMenu>

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-md border border-input bg-background px-3 py-2 text-sm shadow-sm transition-[color,background-color,border-color,box-shadow] duration-fast ease-standard",
         "placeholder:text-muted-foreground",
-        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+        "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
         "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-switcher/theme-switcher.tsx

@@ -12,6 +12,7 @@ import {
   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 +108,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);
@@ -215,7 +217,7 @@ export const ThemeSwitcher = forwardRef<HTMLButtonElement, ThemeSwitcherProps>(
             {showSystem ? (
               <DropdownMenuItem onSelect={() => pickSystem()}>
                 <Monitor />
-                <span>System</span>
+                <span>{t("ui.themeSwitcher.system")}</span>
                 {isSystem ? <Check className="ml-auto" /> : null}
               </DropdownMenuItem>
             ) : null}
@@ -254,7 +256,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

@@ -17,6 +17,16 @@
  *
  * 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 +151,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-md text-sm font-medium 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: {

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/tree/tree.stories.tsx

@@ -483,7 +483,7 @@ function RevealSelectedNodeDemo() {
             key={id}
             type="button"
             onClick={() => setTarget(id)}
-            className="rounded-md border border-border-strong bg-background px-3 py-1.5 text-body font-medium text-foreground hover:bg-surface-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            className="rounded-md border border-border-strong bg-background px-3 py-1.5 text-body font-medium text-foreground hover:bg-surface-muted focus-ring"
           >
             Navigate to Node {Number(id.split("-")[1]) + 1}
           </button>
@@ -535,7 +535,7 @@ export const RevealSelectedNode: Story = {
  * (like the Sidebar itself) perceivability comes from the foreground/weight shift
  * plus `aria-selected`, not fill contrast alone.
  *
- * NOTE: cross-theme visual correctness (the three shipped themes — light,
+ * NOTE: cross-theme visual correctness (every shipped theme — light,
  * dark) requires a real render and is owed to a human reviewer;
  * the tokens are semantic so they adapt, but pixel-level confirmation cannot be
  * automated in this environment.

package/src/components/tree/tree.tsx

@@ -15,6 +15,7 @@ import { ChevronRight, AlertCircle, RotateCcw } from "lucide-react";
 import { useVirtualizer, type Virtualizer } from "@tanstack/react-virtual";
 import { cn } from "../../lib/cn";
 import { Checkbox } from "../checkbox/checkbox";
+import { useLocale } from "../locale-provider";
 import { Skeleton } from "../skeleton/skeleton";
 import { Spinner } from "../spinner/spinner";
 import { useTreeKeyboard } from "./use-tree-keyboard";
@@ -222,6 +223,7 @@ function VirtualFlatRow<T>({
   registerNodeRef,
   setActiveId,
 }: VirtualFlatRowProps<T>) {
+  const { t } = useLocale();
   const { node, level, setSize, posInSet } = row;
   const isLoading = lazyState === "loading";
   const isError = lazyState === "error";
@@ -262,7 +264,7 @@ function VirtualFlatRow<T>({
         "flex min-w-0 cursor-pointer select-none items-center gap-1.5 rounded-md px-2 py-1.5 text-body outline-none",
         "transition-colors duration-fast ease-standard motion-reduce:transition-none",
         "hover:bg-accent hover:text-accent-foreground",
-        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+        "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
         isSelected &&
           selectionMode !== "none" &&
           (surface === "sidebar"
@@ -319,9 +321,11 @@ function VirtualFlatRow<T>({
 
       {/* label */}
       {isError ? (
-        <span id={labelId} className="min-w-0 flex items-center gap-1 text-destructive">
+        // #124: running text ("Failed to load…"), not a mark — the ink rung
+        // clears >=4.5:1 and the wrapped icon inherits it fine (>=3:1 trivially).
+        <span id={labelId} className="min-w-0 flex items-center gap-1 text-destructive-text">
           <AlertCircle className="size-3.5 shrink-0" aria-hidden="true" />
-          <span className="truncate">Failed to load</span>
+          <span className="truncate">{t("ui.tree.failedToLoad")}</span>
           <button
             type="button"
             aria-label="Retry loading children"
@@ -332,7 +336,7 @@ function VirtualFlatRow<T>({
             className={cn(
               "ms-1 flex items-center gap-0.5 rounded px-1 py-0.5 text-caption",
               "text-muted-foreground hover:text-foreground",
-              "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+              "focus-ring",
             )}
           >
             <RotateCcw className="size-3" aria-hidden="true" />
@@ -392,19 +396,20 @@ function LoadingRow({ level }: { level: number }) {
 }
 
 function ErrorRow({ level, onRetry }: { level: number; onRetry: () => void }) {
+  const { t } = useLocale();
   const indentStyle = { paddingLeft: `${(level - 1) * 1}rem` };
   return (
     <div
       role="treeitem"
-      aria-label="Failed to load"
+      aria-label={t("ui.tree.failedToLoad")}
       aria-disabled="true"
       tabIndex={-1}
-      className="flex min-w-0 items-center gap-1.5 px-2 py-1.5 text-body text-destructive"
+      className="flex min-w-0 items-center gap-1.5 px-2 py-1.5 text-body text-destructive-text"
       style={indentStyle}
     >
       <span aria-hidden="true" className="size-4 shrink-0" />
       <AlertCircle className="size-3.5 shrink-0" aria-hidden="true" />
-      <span className="truncate">Failed to load</span>
+      <span className="truncate">{t("ui.tree.failedToLoad")}</span>
       <button
         type="button"
         onClick={(e) => {
@@ -414,7 +419,7 @@ function ErrorRow({ level, onRetry }: { level: number; onRetry: () => void }) {
         className={cn(
           "ms-1 flex items-center gap-0.5 rounded px-1 py-0.5 text-xs",
           "text-muted-foreground hover:text-foreground",
-          "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+          "focus-ring",
         )}
       >
         <RotateCcw className="size-3" aria-hidden="true" />
@@ -541,7 +546,7 @@ function TreeItem<T>({
           "flex min-w-0 cursor-pointer select-none items-center gap-1.5 rounded-md px-2 py-1.5 text-body outline-none",
           "transition-colors duration-fast ease-standard motion-reduce:transition-none",
           "hover:bg-accent hover:text-accent-foreground",
-          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+          "focus-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
           isSelected &&
             selectionMode !== "none" &&
             (surface === "sidebar"

package/src/components/typography/prose.tsx

@@ -119,7 +119,7 @@ export const ProseLink = forwardRef<HTMLAnchorElement, ProseLinkProps>(function
         // #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
         // 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-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        "font-medium text-primary-text underline underline-offset-4 hover:no-underline focus-ring",
         className,
       )}
       {...(isExternal ? { target: "_blank", rel: "noopener noreferrer" } : {})}