@elabs-ai/components-ui 4.0.0 → 4.2.0

package/src/components/state-panel/state-panel.tsx

@@ -1,7 +1,11 @@
-import { type ReactNode } from "react";
+"use client";
+
+import { type CSSProperties, type ReactNode } from "react";
 import { CircleAlert } from "lucide-react";
 import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../../lib/cn";
+import { ILLUSTRATION_ACCENT_VAR } from "../../illustrations/illustration-base";
+import { useLocale } from "../locale-provider";
 
 // ─── Variants ────────────────────────────────────────────────────────────────
 
@@ -14,11 +18,22 @@ export const statePanelVariants = cva(
     variants: {
       kind: {
         empty: "border border-dashed bg-surface",
-        // error: primary cue is color (destructive bg/border); structural cue
-        // (border-s-4 + border-border-strong top strip) survives monochrome /
-        // a monochrome palette so the panel is distinguishable from empty/loading even
-        // without hue. border-border-strong satisfies WCAG 1.4.11 non-text contrast.
-        error: "border border-destructive/30 bg-destructive/5 border-s-4 border-s-border-strong",
+        // error: the non-color, monochrome-survivable cue is the rail's WIDTH
+        // (border-s-4, 4px, vs the 1px hairline on the other three edges) —
+        // not its hue (per styling-and-tokens.md's border/border-strong
+        // decision test: "if I deleted this line, could a sighted user still
+        // tell the two regions apart?" here it's the thickness that answers
+        // yes). So the rail's COLOR should stay in the destructive family
+        // like the rest of the panel, not fall back to the neutral
+        // `border-strong` rung — a 4px grey rail beside three red hairlines
+        // read as a CSS-specificity bug, not a deliberate accent (#71).
+        // `border-s-destructive` is the FILL rung (styling-and-tokens.md
+        // "which status rung a graphical MARK reaches for") — guaranteed
+        // >=3:1 against --card/--background in every theme, so it still
+        // satisfies the WCAG 1.4.11 non-text-contrast guarantee the old
+        // `border-border-strong` comment claimed. The icon (:87-91) and the
+        // eyebrow (:148-152 below) are the third and fourth non-color cues.
+        error: "border border-destructive/30 bg-destructive/5 border-s-4 border-s-destructive",
         loading: "",
       },
     },
@@ -41,11 +56,29 @@ export interface StatePanelProps extends VariantProps<typeof statePanelVariants>
   /** Supporting description below the title. */
   description?: ReactNode;
   /**
-   * Icon or illustration shown above the title.
-   * For `"error"` defaults to a built-in warning triangle.
-   * For `"loading"` defaults to an animated spinner.
+   * Icon shown above the title, clamped to a uniform 40×40 so mismatched
+   * glyphs stay tidy. For `"error"` defaults to a built-in warning triangle.
+   * For `"loading"` defaults to an animated spinner. Ignored when
+   * `illustration` is also provided — see `illustration`.
    */
   icon?: ReactNode;
+  /**
+   * A larger illustration (one of `@elabs-ai/components-ui`'s shipped
+   * `*Illustration` components, or a consumer's own `ReactNode`) shown above
+   * the title instead of `icon`. Unlike `icon`, it is **not** clamped to
+   * 40×40 — an illustration governs its own size (see each illustration's
+   * `size` prop, `rem`-based, ~64px–160px). Takes precedence over `icon`
+   * when both are given.
+   */
+  illustration?: ReactNode;
+  /**
+   * Heading level for the panel's title (#328 convention). Set this to the
+   * level that correctly follows whatever heading precedes this panel in
+   * the document outline — e.g. `"h3"` inside a `ChartCard` whose own title
+   * is an `<h2>`.
+   * @default "h3"
+   */
+  titleAs?: "div" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
   /** Accessible label for the spinner in loading state. @default "Loading…" */
   loadingLabel?: string;
   /** Spinner size (loading kind only). @default "md" */
@@ -91,13 +124,17 @@ export function StatePanel({
   title,
   description,
   icon,
-  loadingLabel = "Loading…",
+  illustration,
+  titleAs: Tag = "h3",
+  loadingLabel,
   size = "md",
   actions,
   className,
 }: StatePanelProps) {
+  const { t } = useLocale();
   const isLoading = kind === "loading";
   const isError = kind === "error";
+  const resolvedLoadingLabel = loadingLabel ?? t("loading");
 
   // Role: loading → status + live region; error → alert; empty → (none needed).
   const roleProps = isLoading
@@ -107,9 +144,9 @@ export function StatePanel({
       : {};
 
   // Default title / description fallbacks for error state (mirroring old ErrorState).
-  const resolvedTitle = title ?? (isError ? "Something went wrong" : undefined);
+  const resolvedTitle = title ?? (isError ? t("ui.statePanel.errorTitle") : undefined);
   const resolvedDescription =
-    description ?? (isError ? "An unexpected error occurred. Please try again." : undefined);
+    description ?? (isError ? t("ui.statePanel.errorDescription") : undefined);
 
   // Resolve displayed icon.
   let resolvedIcon: ReactNode;
@@ -124,17 +161,48 @@ export function StatePanel({
   return (
     <div data-kind={kind} className={cn(statePanelVariants({ kind }), className)} {...roleProps}>
       {/* Error eyebrow: "Error" label shown above the icon so the panel reads
-          as an error structurally even in monochrome themes. The
-          eyebrow uses text-destructive which resolves to a drawable
-          foreground at high decoration — combined with the thick left border from
-          statePanelVariants it gives two non-color structural cues. */}
+          as an error structurally even in monochrome themes. This is running
+          TEXT, not a mark, so it takes the ink rung `text-destructive-text`
+          (>= 4.5:1, gated in themes-contrast.test.ts) — not the fill rung
+          `text-destructive`, whose contract is only the 3:1 mark bar (see
+          "Which status rung a graphical MARK reaches for", styling-and-tokens.md
+          #381). Combined with the thick left border from statePanelVariants it
+          gives two non-color structural cues. The icon below deliberately
+          KEEPS text-destructive: an icon is a mark, so the fill rung is
+          correct there — do not "tidy" it onto -text too. */}
       {isError && (
-        <span className="text-xs font-semibold uppercase tracking-widest text-destructive">
-          Error
+        <span className="text-meta font-semibold uppercase tracking-widest text-destructive-text">
+          {t("ui.statePanel.errorEyebrow")}
         </span>
       )}
 
-      {resolvedIcon ? (
+      {illustration ? (
+        // Illustration wins over `icon` when both are given. No `[&_svg]:size-10`
+        // clamp here — an illustration governs its own (rem-based) size, unlike
+        // the fixed-size icon slot below. For `kind="error"` this also sets the
+        // `--illustration-accent` custom property every illustration's accent
+        // ink reads through, so ANY illustration (not just `ErrorIllustration`)
+        // retints its accent to `--destructive-text` instead of staying pinned
+        // to its default hue inside a red-tinted slot (#24 fix round 1, P0-2).
+        // TEXT rung, not the FILL token below: the wrapper's `text-destructive`
+        // class already puts the SUBJECT (silhouette) on the fill rung, so an
+        // accent override reading the same `--destructive` token collapsed
+        // onto it and disappeared (#48 finding 2) — `--destructive-text` is a
+        // deliberately distinct, deeper rung (matches the fallback every
+        // other illustration's own accent already uses: `--primary-text`,
+        // `--success-text`) so the accent stays visible against the retinted
+        // silhouette.
+        <div
+          className={cn(isError ? "text-destructive" : "text-muted-foreground")}
+          style={
+            isError
+              ? ({ [ILLUSTRATION_ACCENT_VAR]: "var(--destructive-text)" } as CSSProperties)
+              : undefined
+          }
+        >
+          {illustration}
+        </div>
+      ) : resolvedIcon ? (
         // Error icon keeps text-destructive (not muted) so it stays visible even
         // when rendered at low contrast. In monochrome themes the icon shape
         // (CircleAlert) carries the cue; the color is supplemental.
@@ -146,19 +214,37 @@ export function StatePanel({
       ) : null}
 
       {(resolvedTitle || resolvedDescription) && (
-        <div className="space-y-1">
+        // A 112px+ illustration (default `size="7rem"`) needs a heavier title
+        // to group with, and more air between the artwork and the copy than
+        // between the title and its own description — otherwise the caption
+        // reads as an afterthought under the artwork instead of one grouped
+        // unit (#47). `mt-2` (on top of the root's `gap-3`) only fires on the
+        // illustration path; the plain `icon` path (a fixed 40x40 glyph) is
+        // untouched. The title/description gap stays the tight `space-y-1`
+        // either way — that's the "one visually distinct unit" the two lines
+        // read as.
+        <div className={cn("space-y-1", illustration && "mt-2")}>
           {resolvedTitle && (
-            <h3 className="text-sm font-semibold text-foreground">{resolvedTitle}</h3>
+            <Tag
+              className={cn(
+                "font-semibold text-foreground",
+                illustration ? "text-subtitle" : "text-body",
+              )}
+            >
+              {resolvedTitle}
+            </Tag>
           )}
           {resolvedDescription && (
-            <p className="mx-auto max-w-sm text-sm text-muted-foreground">{resolvedDescription}</p>
+            <p className="mx-auto max-w-sm text-body text-muted-foreground">
+              {resolvedDescription}
+            </p>
           )}
         </div>
       )}
 
       {/* Loading label (visually shown as supporting text; also the live-region content). */}
-      {isLoading && loadingLabel && (
-        <span className="text-sm text-muted-foreground">{loadingLabel}</span>
+      {isLoading && resolvedLoadingLabel && (
+        <span className="text-body text-muted-foreground">{resolvedLoadingLabel}</span>
       )}
 
       {actions ? <div className="mt-1 flex items-center gap-2">{actions}</div> : null}

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

@@ -6,6 +6,14 @@ const meta = {
   title: "Core/StatusBadge",
   component: StatusBadge,
   tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The closed seven-state execution-status vocabulary, each state carrying its own icon as well as its own tone so two states are still tellable apart in greyscale. A neutral label or count with no state semantics is `Core/Badge`; see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs).",
+      },
+    },
+  },
   args: { status: "complete" },
   argTypes: {
     status: {

package/src/components/switch/switch.tsx

@@ -9,9 +9,10 @@ export const Switch = forwardRef<
   return (
     <SwitchPrimitive.Root
       ref={ref}
+      data-slot="switch"
       className={cn(
         "peer inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent shadow-sm transition-colors duration-fast ease-standard",
-        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+        "focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
         "disabled:cursor-not-allowed disabled:opacity-50",
         "data-[state=checked]:bg-primary data-[state=unchecked]:bg-input",
         className,
@@ -19,6 +20,7 @@ export const Switch = forwardRef<
       {...props}
     >
       <SwitchPrimitive.Thumb
+        data-slot="switch-thumb"
         className={cn(
           "pointer-events-none block size-4 rounded-full bg-background shadow-xs ring-0 transition-transform duration-fast ease-standard",
           "data-[state=checked]:translate-x-4 data-[state=unchecked]:translate-x-0",

package/src/components/table/table.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor } from "storybook/test";
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "./table";
 const meta = {
   title: "Data/Table",
@@ -8,6 +9,9 @@ const meta = {
     docs: {
       description: {
         component:
+          "The STATIC table markup you lay out yourself; the interactive grid is " +
+          "`Data/DataTable` — see " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). " +
           "Low-level static table primitives (header/body/row/cell styling). For sorting, filtering, " +
           "pagination, virtualization, row selection and column management, use the TanStack-powered " +
           "DataTable (see Data/DataTable, @elabs-ai/components-data) instead.",
@@ -51,3 +55,63 @@ export const Default: Story = {
     </Table>
   ),
 };
+
+// ─── Scrolling (#366) ───────────────────────────────────────────────────────
+
+/**
+ * A fixed-height container with more rows than fit — `Table`'s own scroll
+ * wrapper is genuinely `overflow-auto` here, and that is exactly what no
+ * `Table` story ever exercised before #366: the wrapper's own keyboard
+ * affordance (WCAG 2.1.1 / axe `scrollable-region-focusable`) shipped
+ * unguarded on this package's own turf, only incidentally covered elsewhere.
+ * `Tab` reaches the region, and it carries the accessible name naming it a
+ * scrollable region — see `table.test.tsx` for the fitting-table negative.
+ */
+export const Scrolling: Story = {
+  render: () => (
+    // `Table`'s own scroll wrapper has no explicit height of its own — like any
+    // block box it grows to fit its content unless something makes it a flex
+    // item with a bounded main-axis size. A plain `<div style={{height:160}}>`
+    // ancestor does NOT do that (block children ignore a parent's height), so
+    // this outer div is a column flex container: its one child (the wrapper,
+    // which already carries `overflow-auto`) gets an automatic flex-basis
+    // minimum size of 0 per the flexbox spec's overflow carve-out, letting it
+    // shrink to the 160px bound instead of growing to its ~750px content.
+    <div style={{ height: 160, display: "flex", flexDirection: "column" }}>
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Service</TableHead>
+            <TableHead>Status</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {Array.from({ length: 20 }, (_, i) => (
+            <TableRow key={i}>
+              <TableCell>service-{i}</TableCell>
+              <TableCell>{i % 2 === 0 ? "healthy" : "degraded"}</TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  ),
+  play: async ({ canvasElement, userEvent }) => {
+    const scrollRegion = await waitFor(() => {
+      const el = canvasElement.querySelector<HTMLElement>('[data-slot="table-scroll-region"]');
+      if (!el || el.scrollHeight <= el.clientHeight) throw new Error("not overflowing yet");
+      return el;
+    });
+    await expect(scrollRegion).toHaveAttribute("tabindex", "0");
+    await expect(scrollRegion).toHaveAccessibleName("Table contents, scrollable");
+    // A named, non-landmark stop: `group`, never `region` (a landmark per
+    // overflowing table collides under axe `landmark-unique`).
+    await expect(scrollRegion).toHaveAttribute("role", "group");
+
+    // The region is the only focusable element the story renders, so a
+    // single Tab from nothing focused reaches it — the real WCAG 2.1.1
+    // reproduction from the issue ("press Tab from the top").
+    await userEvent.tab();
+    await waitFor(() => expect(document.activeElement).toBe(scrollRegion));
+  },
+};

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,150 @@ 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('adds role="group" once it overflows — a named, non-landmark stop', () => {
+    const { container } = render(
+      <Table>
+        <TableBody>
+          <TableRow>
+            <TableCell>Alpha</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>,
+    );
+    const scrollRegion = scrollRegionOf(container);
+    // `aria-label` on a plain `<div>` (role `generic`) is not guaranteed to
+    // produce an accessible name at all, so the overflowing stop needs a
+    // naming-capable role — `group`, never the `region` landmark, which would
+    // collide (axe `landmark-unique`) as soon as two tables overflow on a page.
+    expect(scrollRegion).not.toHaveAttribute("role");
+    setScrollMetrics(scrollRegion, {
+      scrollWidth: 300,
+      clientWidth: 300,
+      scrollHeight: 800,
+      clientHeight: 200,
+    });
+    expect(scrollRegion).toHaveAttribute("role", "group");
+    expect(screen.queryByRole("region")).toBeNull();
+    expect(screen.getByRole("group", { name: "Table contents, scrollable" })).toBe(scrollRegion);
+  });
+});

package/src/components/table/table.tsx

@@ -1,17 +1,86 @@
+"use client";
+
 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 `role`, 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`).
+ *
+ * A naming-capable role is REQUIRED alongside that `aria-label`: `aria-label`
+ * on a plain `<div>` (role `generic`) is prohibited by ARIA 1.2 and not
+ * guaranteed to compute into a name, so `tabIndex={0}` alone would make an
+ * UNNAMED stop. That role is `group`, NOT `region`: `region` is a landmark,
+ * and every overflowing table on a page would add one more landmark with the
+ * same name (axe `landmark-unique`) over a real `<table>` that already has
+ * its own semantics. `group` names the stop without joining landmark
+ * navigation — the no-redundant-landmark call `DataTable` made first (#330).
+ */
 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}
+      role={scrollOverflows ? "group" : 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>
   );
@@ -79,7 +148,7 @@ export const TableHead = forwardRef<HTMLTableCellElement, ThHTMLAttributes<HTMLT
       <th
         ref={ref}
         className={cn(
-          "h-10 px-3 text-start align-middle font-medium text-muted-foreground",
+          "h-10 px-3 text-start align-middle font-table-header text-muted-foreground",
           className,
         )}
         {...props}

package/src/components/tabs/index.ts

@@ -1 +1,10 @@
-export { Tabs, TabsList, TabsTrigger, TabsContent } from "./tabs";
+export {
+  Tabs,
+  TabsList,
+  TabsTrigger,
+  TabsContent,
+  tabsListVariants,
+  tabsTriggerVariants,
+  type TabsListProps,
+  type TabsVariant,
+} from "./tabs";

package/src/components/tabs/tabs.stories.tsx

@@ -265,3 +265,51 @@ export const ProgrammaticActivation: Story = {
     await expect(window.scrollY).toBe(0);
   },
 };
+
+/**
+ * `variant="underline"` — line tabs: a transparent row over a 1px rule, the
+ * active tab marked by a 2px `--primary` underline and foreground ink. Label
+ * weight follows the theme's `--control-weight`. Keyboard behaviour is Radix's,
+ * identical to the segmented default.
+ */
+export const Underline: Story = {
+  render: () => (
+    <Tabs defaultValue="overview" className="w-[28rem]">
+      <TabsList variant="underline">
+        <TabsTrigger value="overview">Overview</TabsTrigger>
+        <TabsTrigger value="activity">Activity</TabsTrigger>
+        <TabsTrigger value="settings">Settings</TabsTrigger>
+      </TabsList>
+      <TabsContent value="overview" className="text-body text-muted-foreground">
+        Overview panel.
+      </TabsContent>
+      <TabsContent value="activity" className="text-body text-muted-foreground">
+        Activity panel.
+      </TabsContent>
+      <TabsContent value="settings" className="text-body text-muted-foreground">
+        Settings panel.
+      </TabsContent>
+    </Tabs>
+  ),
+  play: async ({ canvas, userEvent }) => {
+    const overview = canvas.getByRole("tab", { name: "Overview" });
+    const activity = canvas.getByRole("tab", { name: "Activity" });
+
+    // The underline is a 2px border on every trigger (transparent at rest), so
+    // activating a tab never changes its box.
+    await expect(getComputedStyle(activity).borderBottomWidth).toBe("2px");
+    await expect(getComputedStyle(overview).borderBottomColor).not.toBe(
+      getComputedStyle(activity).borderBottomColor,
+    );
+    const restingHeight = activity.getBoundingClientRect().height;
+
+    await userEvent.click(overview);
+    await userEvent.keyboard("{ArrowRight}");
+    await expect(activity).toHaveFocus();
+    await expect(activity).toHaveAttribute("aria-selected", "true");
+    await expect(activity.getBoundingClientRect().height).toBe(restingHeight);
+    // The panel mounts on switch and fades in (gated entrance) — wait for it to settle.
+    const panel = await canvas.findByText("Activity panel.");
+    await waitFor(() => expect(panel).toBeVisible());
+  },
+};