@elabs-ai/components-ui 4.0.0 → 4.1.0

package/src/components/split-panel/split-panel.test.tsx

@@ -19,6 +19,26 @@ describe("SplitPanel", () => {
     expect(endPane.className).toMatch(/border-s/);
   });
 
+  // Issue #163 — WCAG 1.4.11: with both tones "plain" (the shipped default),
+  // the hairline is the ONLY cue between the two panes (no fill/elevation
+  // difference), so it must be the strong, ≥3:1 rung — `border-strong ≥ 3:1
+  // on --card/--background` is proven for every theme in
+  // `@elabs-ai/components-tokens`'s `themes-contrast.test.ts`; this test locks
+  // that `SplitPanel` actually reaches for that token in this configuration,
+  // not just the bare `border-s`/`border-t` class the previous assertion
+  // above already passed on the unfixed code.
+  it("plain/plain divider uses the strong (≥3:1) border rung, not the subtle default", () => {
+    const { getByText } = render(<SplitPanel start={<>List</>} end={<>Detail</>} />);
+    expect(getByText("Detail").className).toMatch(/border-border-strong/);
+  });
+
+  it("muted/card tones keep the subtle divider rung — the fill difference already carries the boundary", () => {
+    const { getByText } = render(
+      <SplitPanel startTone="muted" endTone="card" start={<>List</>} end={<>Detail</>} />,
+    );
+    expect(getByText("Detail").className).not.toMatch(/border-border-strong/);
+  });
+
   it("applies the ground-offset tones: muted well + raised card", () => {
     const { getByText } = render(
       <SplitPanel

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

@@ -5,15 +5,20 @@ import { cn } from "../../lib/cn";
 /**
  * Per-pane surface tone — the ground-offset tiering axis (research 08 §H, #193).
  * `plain` keeps the ambient ground (default; non-breaking). `card` RAISES the pane as
- * a white `bg-card` + `shadow-sm` and is robust across all three themes — a card is
+ * a white `bg-card` + `shadow-sm` and is robust across every theme — a card is
  * lighter than the page ground in BOTH light and dark, so it always reads as raised.
  * `muted` (`bg-surface-muted`) reads as a recessed well ONLY in light themes; in dark
  * themes `--surface-muted` is lighter than `--card`, so a `muted` pane reads as a faint
  * raised tint, not a recess (dark-mode layering only goes UP — there is no surface below
  * the page ground). For a guaranteed cross-theme raise/recess contrast, raise the focus
  * pane with `card` and leave the other `plain`.
+ *
+ * Exported so the same tone system reaches a `Layout/Resizable` pane — a draggable
+ * `ResizablePanel` composes `splitPaneVariants({ tone })` for the identical ground-offset
+ * tiering `SplitPanel` gives its `startTone`/`endTone`, instead of a hand-rolled second
+ * copy of these three classes. See `Layout/Resizable`'s `Tiered` story.
  */
-const paneToneVariants = cva("min-h-0 min-w-0 overflow-auto", {
+export const splitPaneVariants = cva("min-h-0 min-w-0 overflow-auto", {
   variants: {
     tone: {
       plain: "",
@@ -24,7 +29,7 @@ const paneToneVariants = cva("min-h-0 min-w-0 overflow-auto", {
   defaultVariants: { tone: "plain" },
 });
 
-export type SplitPanelTone = NonNullable<VariantProps<typeof paneToneVariants>["tone"]>;
+export type SplitPanelTone = NonNullable<VariantProps<typeof splitPaneVariants>["tone"]>;
 
 export interface SplitPanelProps {
   start: ReactNode;
@@ -49,8 +54,12 @@ export interface SplitPanelProps {
 
 /**
  * Two-pane layout for master/detail, editor/preview and inspector workflows.
- * Static sizing by design (predictable in tests/SSR); for drag-to-resize wrap
- * with a resize hook or compose `react-resizable-panels` at the app level.
+ * Static sizing by design (predictable in tests/SSR) — `startSize` is a CSS grid
+ * track (`"320px"`, `"40%"`, `"1fr"`), not a percentage. For panes the user can
+ * drag to resize, reach for `Layout/Resizable`'s `ResizablePanelGroup`/
+ * `ResizablePanel`/`ResizableHandle` instead and apply `splitPaneVariants({ tone })`
+ * to a panel for the same ground-offset tiering. See
+ * [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs).
  *
  * For a master/detail surface where the detail should read as a raised card on a
  * recessed list, use `startTone="muted" endTone="card"` (ground-offset tiering).
@@ -80,11 +89,22 @@ export function SplitPanel({
       )}
       style={style}
     >
-      <div className={cn(paneToneVariants({ tone: startTone }), startClassName)}>{start}</div>
+      <div className={cn(splitPaneVariants({ tone: startTone }), startClassName)}>{start}</div>
       <div
         className={cn(
-          paneToneVariants({ tone: endTone }),
-          divider && (isHorizontal ? "border-s" : "border-t"),
+          splitPaneVariants({ tone: endTone }),
+          divider &&
+            (isHorizontal ? "border-s" : "border-t") +
+              // #163 — with both panes "plain" there is no fill/elevation
+              // difference between them, so the hairline is the ONLY cue and
+              // must clear the 3:1 non-text bar (WCAG 1.4.11):
+              // `border-border-strong` (`border-strong ≥ 3:1 on --card/
+              // --background` is proven for every theme in
+              // @elabs-ai/components-tokens's themes-contrast.test.ts).
+              // With either tone "muted"/"card" the fill change already
+              // carries the boundary, so the subtle default rung stays —
+              // the redundant-cue exemption in styling-and-tokens.md.
+              (startTone === "plain" && endTone === "plain" ? " border-border-strong" : ""),
           endClassName,
         )}
       >

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

@@ -1,6 +1,11 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { Button } from "../button";
 import { StatePanel } from "./state-panel";
+import {
+  EmptyListIllustration,
+  NoAccessIllustration,
+  ErrorIllustration,
+} from "../../illustrations";
 
 const meta = {
   title: "States/StatePanel",
@@ -78,3 +83,50 @@ export const EmptyNoIcon: Story = {
     description: "Items will appear here once available.",
   },
 };
+
+export const WithIllustration: Story = {
+  name: "Empty (with illustration, #24)",
+  args: {
+    kind: "empty",
+    title: "No projects yet",
+    description: "Create your first project to get started.",
+    illustration: <EmptyListIllustration />,
+    actions: <Button size="sm">New project</Button>,
+  },
+};
+
+export const NoAccess: Story = {
+  name: "Empty (no-access illustration)",
+  args: {
+    // "No access" is a blocked/informational state, not a system failure —
+    // kind stays "empty" (no alarm-red "Error" eyebrow) rather than "error".
+    kind: "empty",
+    title: "You don’t have access",
+    description: "Ask a workspace admin to grant you permission.",
+    illustration: <NoAccessIllustration />,
+    actions: (
+      <Button size="sm" variant="outline">
+        Request access
+      </Button>
+    ),
+  },
+};
+
+export const ErrorWithIllustration: Story = {
+  name: "Error (with illustration, #24 P0-2)",
+  args: {
+    // The one panel `kind` that re-tints the illustration slot (`text-destructive`)
+    // — pairing it with an illustration is what surfaces whether the accent
+    // follows the tint or clashes against it. See P0-2 in the fix-round review:
+    // no shipped story previously rendered an illustration inside `kind="error"`.
+    kind: "error",
+    title: "Failed to load data",
+    description: "The server returned an unexpected response.",
+    illustration: <ErrorIllustration />,
+    actions: (
+      <Button size="sm" variant="outline">
+        Try again
+      </Button>
+    ),
+  },
+};

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

@@ -1,6 +1,11 @@
 import { describe, expect, it } from "vitest";
 import { render, screen } from "@testing-library/react";
 import { StatePanel } from "./state-panel";
+import {
+  EmptyListIllustration,
+  ErrorIllustration,
+  ILLUSTRATION_ACCENT_VAR,
+} from "../../illustrations";
 
 describe("StatePanel", () => {
   it("renders empty kind with title and description", () => {
@@ -24,6 +29,48 @@ describe("StatePanel", () => {
     expect(alert).toHaveAttribute("data-kind", "error");
   });
 
+  it("error eyebrow uses the destructive INK rung, not the fill rung (#40)", () => {
+    // The eyebrow is running TEXT on the panel's own `bg-destructive/5` wash, so
+    // it must reach for `text-destructive-text` (>= 4.5:1, the text-rung
+    // contract) — never the bare `text-destructive` fill rung, whose contract
+    // is only the 3:1 mark bar. See styling-and-tokens.md "Which status rung a
+    // graphical MARK reaches for" (#381).
+    render(<StatePanel kind="error" />);
+    const eyebrow = screen.getByText("Error");
+    expect(eyebrow.className).toContain("text-destructive-text");
+    expect(eyebrow.className).not.toMatch(/(?<!-)\btext-destructive\b(?!-)/);
+  });
+
+  it("error icon keeps the destructive FILL rung (a mark, not text)", () => {
+    // Inverse of the eyebrow lock above: an icon IS a mark, so it correctly
+    // stays on the fill rung — the fix must not "tidy" it onto -text too.
+    const { container } = render(<StatePanel kind="error" />);
+    const iconWrapper = container.querySelector("svg")?.parentElement;
+    expect(iconWrapper?.className ?? "").toMatch(/\btext-destructive\b/);
+    expect(iconWrapper?.className ?? "").not.toContain("text-destructive-text");
+  });
+
+  it("error rail carries the width cue (border-s-4) AND a destructive-family colour, not the neutral border-strong grey (#71)", () => {
+    // The rail's WIDTH (4px vs 1px) is the monochrome-survivable structural
+    // cue (per styling-and-tokens.md's border/border-strong decision test);
+    // its HUE should match the rest of the destructive family, not fall back
+    // to the neutral `border-strong` rung — that reads as a CSS-specificity
+    // bug, a 4px grey rail beside three red hairlines, not a deliberate
+    // accent (#71).
+    const { container } = render(<StatePanel kind="error" />);
+    const root = container.firstChild as HTMLElement;
+    expect(root.className).toMatch(/\bborder-s-4\b/);
+    expect(root.className).toMatch(/\bborder-s-destructive\b/);
+    expect(root.className).not.toMatch(/\bborder-s-border-strong\b/);
+  });
+
+  it("empty kind's rail carries neither the error width nor its destructive colour", () => {
+    const { container } = render(<StatePanel kind="empty" />);
+    const root = container.firstChild as HTMLElement;
+    expect(root.className).not.toMatch(/\bborder-s-4\b/);
+    expect(root.className).not.toMatch(/\bborder-s-destructive\b/);
+  });
+
   it("renders error kind with custom title", () => {
     render(<StatePanel kind="error" title="Custom error" description="Custom description" />);
     expect(screen.getByRole("alert")).toBeInTheDocument();
@@ -61,4 +108,82 @@ describe("StatePanel", () => {
     );
     expect(screen.getByTestId("custom-icon")).toBeInTheDocument();
   });
+
+  it("renders an illustration without the size-10 icon clamp, decoratively (#24)", () => {
+    const { container } = render(
+      <StatePanel kind="empty" title="No items" illustration={<EmptyListIllustration />} />,
+    );
+    const svg = container.querySelector("svg");
+    expect(svg).not.toBeNull();
+    expect(svg).toHaveAttribute("aria-hidden", "true");
+    // The illustration's own wrapper must NOT carry the `[&_svg]:size-10`
+    // clamp the default icon slot uses — its rem sizing governs instead.
+    const wrapper = svg?.parentElement;
+    expect(wrapper?.className ?? "").not.toContain("size-10");
+  });
+
+  it("illustration path renders the title at the subtitle role, distinct from the icon path's text-sm (#47)", () => {
+    // A 112px+ illustration needs a heavier title to group with — bumping the
+    // title to `text-subtitle` (styling-and-tokens.md's typography-scale
+    // roles) only on the illustration path, so the plain `icon` path (a
+    // fixed 40x40 glyph) stays byte-identical to before.
+    const { container: withIllustration } = render(
+      <StatePanel kind="empty" title="No items" illustration={<EmptyListIllustration />} />,
+    );
+    const titleWithIllustration = withIllustration.querySelector("h3");
+    expect(titleWithIllustration?.className ?? "").toContain("text-subtitle");
+    expect(titleWithIllustration?.className ?? "").not.toMatch(/\btext-sm\b/);
+
+    const { container: withIcon } = render(
+      <StatePanel kind="empty" title="No items" icon={<span data-testid="i" />} />,
+    );
+    const titleWithIcon = withIcon.querySelector("h3");
+    expect(titleWithIcon?.className ?? "").toMatch(/\btext-sm\b/);
+    expect(titleWithIcon?.className ?? "").not.toContain("text-subtitle");
+  });
+
+  it("error-kind illustration retints the accent to the TEXT rung, distinct from the retinted subject's FILL rung (#48)", () => {
+    // StatePanel wraps the illustration slot in `text-destructive` (the FILL
+    // rung — a mark, per styling-and-tokens.md "which status rung a
+    // graphical MARK reaches for") for kind="error". If the ambient
+    // `--illustration-accent` override it sets ALSO resolved to
+    // `--destructive`, the accent would collapse onto the subject the moment
+    // both read the same token (#48 finding 2). It must resolve to the TEXT
+    // rung instead — matching the convention every other illustration's own
+    // default fallback already uses (`--primary-text`, `--success-text`).
+    const { container } = render(<StatePanel kind="error" illustration={<ErrorIllustration />} />);
+    const svg = container.querySelector("svg");
+    const wrapper = svg?.parentElement as HTMLElement;
+    expect(wrapper.className).toMatch(/\btext-destructive\b/);
+    expect(wrapper.style.getPropertyValue(ILLUSTRATION_ACCENT_VAR)).toBe("var(--destructive-text)");
+    // Sanity: ErrorIllustration's own fallback (used when no ambient override
+    // is set) also reaches for the TEXT rung, not the FILL token the subject
+    // above just read.
+    const accentRect = container.querySelector("rect");
+    expect(accentRect?.getAttribute("style") ?? "").toContain("--destructive-text");
+  });
+
+  it("prefers illustration over icon when both are given", () => {
+    render(
+      <StatePanel
+        kind="empty"
+        title="Both given"
+        icon={<span data-testid="custom-icon">icon</span>}
+        illustration={<EmptyListIllustration />}
+      />,
+    );
+    expect(screen.queryByTestId("custom-icon")).toBeNull();
+  });
+
+  it("titleAs renders the requested heading level (#385)", () => {
+    render(<StatePanel kind="empty" title="No data" titleAs="h2" />);
+    const heading = screen.getByRole("heading", { level: 2, name: "No data" });
+    expect(heading.tagName).toBe("H2");
+  });
+
+  it("default titleAs is still h3 — unchanged output for every existing caller (#385)", () => {
+    render(<StatePanel kind="empty" title="No data" />);
+    const heading = screen.getByRole("heading", { level: 3, name: "No data" });
+    expect(heading.tagName).toBe("H3");
+  });
 });

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

@@ -1,7 +1,8 @@
-import { type ReactNode } from "react";
+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";
 
 // ─── Variants ────────────────────────────────────────────────────────────────
 
@@ -14,11 +15,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 +53,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,6 +121,8 @@ export function StatePanel({
   title,
   description,
   icon,
+  illustration,
+  titleAs: Tag = "h3",
   loadingLabel = "Loading…",
   size = "md",
   actions,
@@ -124,17 +156,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">
+        <span className="text-meta font-semibold uppercase tracking-widest text-destructive-text">
           Error
         </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,9 +209,25 @@ 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-sm",
+              )}
+            >
+              {resolvedTitle}
+            </Tag>
           )}
           {resolvedDescription && (
             <p className="mx-auto max-w-sm text-sm text-muted-foreground">{resolvedDescription}</p>

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

@@ -11,7 +11,7 @@ export const Switch = forwardRef<
       ref={ref}
       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,

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,61 @@ 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");
+    await expect(scrollRegion).not.toHaveAttribute("role");
+
+    // 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));
+  },
+};