@elabs-ai/components-ui 4.0.0 → 4.2.0

package/src/__contract__/workspace-picker.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for WorkspacePicker (`packages/ui/src/components/workspace-picker/workspace-picker.tsx`), derived from its
+ * `Default` story (packages/ui/src/components/workspace-picker/workspace-picker.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../components/workspace-picker/workspace-picker.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `core-workspacepicker--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("WorkspacePicker contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="workspace-picker" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="workspace-picker"]')).not.toBeNull();
+  });
+});

package/src/_peer-deps.test.ts

@@ -0,0 +1,59 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Regression guard for issue #26 — `react-hook-form` / `@hookform/resolvers`
+ * are used ONLY by the RHF-bound `Form` family
+ * (`packages/ui/src/components/form/form.tsx`); `FieldRow` and every other
+ * component in this package render from plain props and never import either.
+ *
+ * A consumer who never imports `Form` should not be forced to install (or
+ * have their bundler resolve) react-hook-form. Declaring both as
+ * `dependencies` defeats that — npm/pnpm install them unconditionally for
+ * every consumer of `@elabs-ai/components-ui`, regardless of whether `Form`
+ * is ever imported. This test locks the fix: both packages are declared as
+ * OPTIONAL peers, and neither reappears as a hard `dependency`.
+ *
+ * `zod` is used only inside `form.stories.tsx` (the `zodResolver` demo) and
+ * never in shipped runtime source — it belongs in `devDependencies`, never as
+ * a runtime `dependency` or a peer a consumer must install.
+ */
+const PACKAGE_JSON_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+
+function readPackageJson(): {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+} {
+  return JSON.parse(readFileSync(PACKAGE_JSON_PATH, "utf8"));
+}
+
+describe("packages/ui/package.json — react-hook-form is an optional peer, not a hard dependency", () => {
+  const pkg = readPackageJson();
+
+  it.each(["react-hook-form", "@hookform/resolvers"])(
+    "declares %s as an OPTIONAL peerDependency",
+    (name) => {
+      expect(pkg.dependencies?.[name]).toBeUndefined();
+      expect(pkg.peerDependencies?.[name]).toBeTruthy();
+      expect(pkg.peerDependenciesMeta?.[name]?.optional).toBe(true);
+    },
+  );
+
+  it("still lists react-hook-form + @hookform/resolvers as devDependencies for the workspace's own build/test", () => {
+    // The package's own `Form` tests/stories (and `form.tsx` itself) need the
+    // real library to typecheck/run inside this workspace — peer alone does
+    // not guarantee resolution here, only for an external consumer.
+    expect(pkg.devDependencies?.["react-hook-form"]).toBeTruthy();
+    expect(pkg.devDependencies?.["@hookform/resolvers"]).toBeTruthy();
+  });
+
+  it("declares zod as a devDependency only — never a runtime dependency or peer", () => {
+    expect(pkg.dependencies?.zod).toBeUndefined();
+    expect(pkg.peerDependencies?.zod).toBeUndefined();
+    expect(pkg.devDependencies?.zod).toBeTruthy();
+  });
+});

package/src/blocks-comparison-table.stories.tsx

@@ -7,7 +7,7 @@
  * cells, a price row, and a per-plan CTA row. Reuses brand-ui's strongest
  * assets — Table + Badge + Button — and stays token-only.
  *
- * Reads in all three themes. Verify with globals=theme:<slug>.
+ * Reads in every theme. Verify with globals=theme:<slug>.
  */
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { Check, Minus } from "lucide-react";
@@ -152,7 +152,7 @@ const meta = {
     docs: {
       description: {
         component:
-          "The canonical plan/feature comparison matrix (brand-ui's Compare gap): a header with one featured column (badge + recessed wash), feature rows with check / dash / value cells, a price row, and a per-plan CTA row. Composes Table + Badge + Button; semantic tokens only; reads in all three themes.",
+          "The canonical plan/feature comparison matrix (brand-ui's Compare gap): a header with one featured column (badge + recessed wash), feature rows with check / dash / value cells, a price row, and a per-plan CTA row. Composes Table + Badge + Button; semantic tokens only; reads in every theme.",
       },
     },
   },

package/src/components/accordion/accordion.tsx

@@ -9,7 +9,14 @@ export const AccordionItem = forwardRef<
   ElementRef<typeof AccordionPrimitive.Item>,
   ComponentPropsWithoutRef<typeof AccordionPrimitive.Item>
 >(function AccordionItem({ className, ...props }, ref) {
-  return <AccordionPrimitive.Item ref={ref} className={cn("border-b", className)} {...props} />;
+  return (
+    <AccordionPrimitive.Item
+      ref={ref}
+      data-slot="accordion-item"
+      className={cn("border-b", className)}
+      {...props}
+    />
+  );
 });
 
 export const AccordionTrigger = forwardRef<
@@ -17,11 +24,12 @@ export const AccordionTrigger = forwardRef<
   ComponentPropsWithoutRef<typeof AccordionPrimitive.Trigger>
 >(function AccordionTrigger({ className, children, ...props }, ref) {
   return (
-    <AccordionPrimitive.Header className="flex">
+    <AccordionPrimitive.Header className="flex" data-slot="accordion-header">
       <AccordionPrimitive.Trigger
         ref={ref}
+        data-slot="accordion-trigger"
         className={cn(
-          "flex flex-1 items-center justify-between py-4 text-sm font-medium transition-all hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring [&[data-state=open]>svg]:rotate-180",
+          "flex flex-1 items-center justify-between py-4 text-body font-medium transition-all hover:underline focus-ring [&[data-state=open]>svg]:rotate-180",
           className,
         )}
         {...props}
@@ -40,7 +48,8 @@ export const AccordionContent = forwardRef<
   return (
     <AccordionPrimitive.Content
       ref={ref}
-      className="overflow-hidden text-sm data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down"
+      data-slot="accordion-content"
+      className="overflow-hidden text-body data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down"
       {...props}
     >
       <div className={cn("pb-4 pt-0 text-muted-foreground", className)}>{children}</div>

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

@@ -85,7 +85,7 @@ export function AdvancedGroup({
     >
       <CollapsibleTrigger
         data-slot="advanced-group-trigger"
-        className="group -mx-2 flex items-center gap-2 rounded-md px-2 py-1.5 text-body font-medium hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        className="group -mx-2 flex items-center gap-2 rounded-md px-2 py-1.5 text-body font-medium hover:bg-accent hover:text-accent-foreground focus-ring"
       >
         <ChevronDown
           aria-hidden="true"

package/src/components/alert/alert.tsx

@@ -3,7 +3,7 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../../lib/cn";
 
 export const alertVariants = cva(
-  "relative w-full rounded-lg border px-4 py-3 text-sm [&>svg]:absolute [&>svg]:start-4 [&>svg]:top-4 [&>svg]:size-4 [&>svg]:text-current [&>svg~*]:ps-7",
+  "relative w-full rounded-lg border px-4 py-3 text-body [&>svg]:absolute [&>svg]:start-4 [&>svg]:top-4 [&>svg]:size-4 [&>svg]:text-current [&>svg~*]:ps-7",
   {
     variants: {
       variant: {
@@ -11,8 +11,11 @@ export const alertVariants = cva(
         info: "border-info/40 bg-info/10 text-foreground",
         success: "border-success/40 bg-success/10 text-foreground",
         warning: "border-warning/50 bg-warning/10 text-foreground",
+        // #124: the bare `text-destructive` set the ambient colour for the
+        // Title/Description running text — ink rung. `[&>svg]:text-destructive`
+        // (the icon mark) is unchanged.
         destructive:
-          "border-destructive/40 bg-destructive/10 text-destructive [&>svg]:text-destructive",
+          "border-destructive/40 bg-destructive/10 text-destructive-text [&>svg]:text-destructive",
       },
     },
     defaultVariants: { variant: "default" },
@@ -31,7 +34,13 @@ export const Alert = forwardRef<
   ref,
 ) {
   return (
-    <div ref={ref} role={role} className={cn(alertVariants({ variant }), className)} {...props} />
+    <div
+      ref={ref}
+      role={role}
+      data-slot="alert"
+      className={cn(alertVariants({ variant }), className)}
+      {...props}
+    />
   );
 });
 
@@ -53,6 +62,7 @@ export const AlertTitle = forwardRef<HTMLHeadingElement, AlertTitleProps>(functi
   return (
     <Tag
       ref={ref}
+      data-slot="alert-title"
       className={cn("mb-1 font-medium leading-none tracking-tight", className)}
       {...props}
     />
@@ -79,8 +89,9 @@ export const AlertDescription = forwardRef<HTMLParagraphElement, AlertDescriptio
     return (
       <div
         ref={ref}
+        data-slot="alert-description"
         className={cn(
-          "text-sm [&_p]:leading-relaxed text-muted-foreground",
+          "text-body [&_p]:leading-relaxed text-muted-foreground",
           measure && "max-w-prose",
           className,
         )}

package/src/components/alert-dialog/alert-dialog.test.tsx

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import {
+  AlertDialog,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "./alert-dialog";
+
+describe("AlertDialogContent overflow", () => {
+  it("caps height and scrolls a long body instead of overflowing the viewport", () => {
+    render(
+      <AlertDialog open>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Title</AlertDialogTitle>
+            <AlertDialogDescription>Description</AlertDialogDescription>
+          </AlertDialogHeader>
+          Body
+        </AlertDialogContent>
+      </AlertDialog>,
+    );
+    const content = screen.getByRole("alertdialog");
+    // Without a height ceiling + `overflow-y-auto`, a body longer than the
+    // viewport overflows past both edges — and the `-translate-y-1/2`
+    // centring pushes its top half off-screen, unreachable even by scrolling
+    // the page.
+    expect(content.className).toContain("max-h-[85dvh]");
+    expect(content.className).toContain("overflow-y-auto");
+  });
+});

package/src/components/alert-dialog/alert-dialog.tsx

@@ -19,8 +19,9 @@ const AlertDialogOverlay = forwardRef<
   return (
     <AlertDialogPrimitive.Overlay
       ref={ref}
+      data-slot="alert-dialog-overlay"
       className={cn(
-        "fixed inset-0 z-50 bg-foreground/50 backdrop-blur-sm data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+        "fixed inset-0 z-50 bg-overlay backdrop-blur-overlay data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
         className,
       )}
       {...props}
@@ -37,8 +38,13 @@ export const AlertDialogContent = forwardRef<
       <AlertDialogOverlay />
       <AlertDialogPrimitive.Content
         ref={ref}
+        data-slot="alert-dialog-content"
         className={cn(
-          "fixed left-1/2 top-1/2 z-50 grid w-full max-w-lg -translate-x-1/2 -translate-y-1/2 gap-4 rounded-xl bg-card p-6 text-card-foreground shadow-ring-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
+          // `max-h` + `overflow-y-auto`: without a height ceiling, a long body
+          // (a big diff, a long list of items to confirm) overflows past both
+          // viewport edges with its actions unreachable — the `-translate-y-1/2`
+          // centring only makes this worse by pushing the top half off-screen.
+          "fixed left-1/2 top-1/2 z-50 grid max-h-[85dvh] w-full max-w-lg -translate-x-1/2 -translate-y-1/2 gap-4 overflow-y-auto rounded-xl bg-card p-6 text-card-foreground shadow-ring-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
           className,
         )}
         {...props}
@@ -48,11 +54,18 @@ export const AlertDialogContent = forwardRef<
 });
 
 export function AlertDialogHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn("flex flex-col gap-1.5 text-start", className)} {...props} />;
+  return (
+    <div
+      data-slot="alert-dialog-header"
+      className={cn("flex flex-col gap-1.5 text-start", className)}
+      {...props}
+    />
+  );
 }
 export function AlertDialogFooter({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
   return (
     <div
+      data-slot="alert-dialog-footer"
       className={cn("flex flex-col-reverse gap-2 sm:flex-row sm:justify-end", className)}
       {...props}
     />
@@ -63,9 +76,11 @@ export const AlertDialogTitle = forwardRef<
   ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Title>
 >(function AlertDialogTitle({ className, ...props }, ref) {
   return (
+    // `text-title`, matching `DialogTitle` (#286) — was `text-lg font-semibold`.
     <AlertDialogPrimitive.Title
       ref={ref}
-      className={cn("text-lg font-semibold", className)}
+      data-slot="alert-dialog-title"
+      className={cn("text-title leading-none", className)}
       {...props}
     />
   );
@@ -77,7 +92,8 @@ export const AlertDialogDescription = forwardRef<
   return (
     <AlertDialogPrimitive.Description
       ref={ref}
-      className={cn("text-sm text-muted-foreground", className)}
+      data-slot="alert-dialog-description"
+      className={cn("text-body text-muted-foreground", className)}
       {...props}
     />
   );
@@ -87,7 +103,12 @@ export const AlertDialogAction = forwardRef<
   ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Action>
 >(function AlertDialogAction({ className, ...props }, ref) {
   return (
-    <AlertDialogPrimitive.Action ref={ref} className={cn(buttonVariants(), className)} {...props} />
+    <AlertDialogPrimitive.Action
+      ref={ref}
+      data-slot="alert-dialog-action"
+      className={cn(buttonVariants(), className)}
+      {...props}
+    />
   );
 });
 export const AlertDialogCancel = forwardRef<
@@ -97,6 +118,7 @@ export const AlertDialogCancel = forwardRef<
   return (
     <AlertDialogPrimitive.Cancel
       ref={ref}
+      data-slot="alert-dialog-cancel"
       className={cn(buttonVariants({ variant: "outline" }), className)}
       {...props}
     />

package/src/components/app-shell/app-shell.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
 import { AppShell } from "./app-shell";
 import { TopNav } from "../top-nav";
 import { PageShell } from "../page-shell";
@@ -6,7 +7,7 @@ import { SectionHeader } from "../section-header";
 import { Button } from "../button";
 
 const meta = {
-  title: "Layout/App Shell/Basic",
+  title: "Layout/App Shell/Minimal",
   component: AppShell,
   parameters: { layout: "fullscreen" },
 } satisfies Meta<typeof AppShell>;
@@ -46,8 +47,10 @@ export const Default: Story = {
         <PageShell
           header={
             <SectionHeader
+              // The page's own title, so it owns the document outline root.
+              as="h1"
               title="Overview"
-              description="A lightweight generic shell. For full sidebar behavior use the Sidebar primitive."
+              description="A minimal, unstyled two-region shell — the honest answer for a simple layout. For full sidebar behavior use the Sidebar primitive; for a fully wired enterprise console see Layout/App Shell/Flagship."
             />
           }
         >
@@ -58,4 +61,43 @@ export const Default: Story = {
       </AppShell>
     </div>
   ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // The shell ships a skip link, so a keyboard user can pass the nav rail
+    // instead of tabbing through it on every route (WCAG 2.4.1). Resolve the
+    // TARGET FROM THE LINK, never from a hard-coded `#main-content`: querying
+    // the id directly stays green when the link and the target are deleted
+    // together.
+    const skip = canvas.getByRole("link", { name: "Skip to main content" });
+    const targetId = (skip.getAttribute("href") ?? "").replace(/^#/, "");
+    await expect(targetId).not.toBe("");
+    const target = canvasElement.querySelector(`#${CSS.escape(targetId)}`) as HTMLElement;
+    await expect(target).toBeVisible();
+    await expect(target.tagName).toBe("MAIN");
+    await expect(canvas.getByRole("main")).toBe(target);
+
+    // …and here <main> IS the scroll port (in the registry blocks the skip
+    // target and the port are separate elements), so it takes a REAL tab stop,
+    // not the `-1` a pure skip target would carry: a region that scrolls has to
+    // be keyboard-operable even when nothing inside it is focusable (WCAG
+    // 2.1.1, axe `scrollable-region-focusable`). Read as an ATTRIBUTE — the
+    // `tabIndex` IDL getter answers -1 for any non-focusable element whether or
+    // not anyone set it, so it cannot tell "-1 was set" from "nothing was set".
+    await expect(target).toHaveAttribute("tabindex", "0");
+    await expect(getComputedStyle(target).overflowY).toBe("auto");
+    // The INSET rung: the shell root above carries `overflow-hidden`, which
+    // clips both layers of the plain `focus-ring`. Asserting only that
+    // `focus-ring-inset` is present would still pass with both classes on the
+    // element — and then the clipped one is what paints.
+    await expect(target.classList.contains("focus-ring-inset")).toBe(true);
+    await expect(target.classList.contains("focus-ring")).toBe(false);
+
+    // The outline has a root. axe cannot catch its absence here:
+    // `page-has-heading-one` is a best-practice rule outside the wcag2a/wcag2aa
+    // tag set, and `heading-order` passes happily on levels that start at 2.
+    const h1s = canvasElement.querySelectorAll("h1");
+    await expect(h1s.length).toBe(1);
+    await expect(canvas.getByRole("heading", { level: 1 })).toHaveTextContent("Overview");
+  },
 };

package/src/components/app-shell/app-shell.test.tsx

@@ -0,0 +1,99 @@
+import { createRef } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { AppShell } from "./app-shell";
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarProvider,
+  SidebarTrigger,
+} from "../sidebar";
+
+describe("AppShell", () => {
+  it("forwards a ref to the root element", () => {
+    const ref = createRef<HTMLDivElement>();
+    render(
+      <AppShell ref={ref} mainId="main">
+        Content
+      </AppShell>,
+    );
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+    // The forwarded node IS the shell root — the flex/overflow box that
+    // establishes the fixed-height viewport, not some inner wrapper.
+    expect(ref.current?.className).toContain("h-dvh");
+  });
+});
+
+describe("AppShell — mobile navigation (#review 2.1: sidebar disappears below md)", () => {
+  const originalInnerWidth = window.innerWidth;
+
+  afterEach(() => {
+    Object.defineProperty(window, "innerWidth", {
+      writable: true,
+      configurable: true,
+      value: originalInnerWidth,
+    });
+  });
+
+  /**
+   * The `sidebar` slot is `hidden md:flex` with no fallback of its own (see
+   * `app-shell.tsx`'s module doc comment) — by design, because `<Sidebar>`
+   * already renders its own off-canvas `Sheet` below the mobile breakpoint,
+   * through a Radix portal that mounts into `document.body`, entirely
+   * unaffected by AppShell's `hidden md:flex` wrapper (a portal is not a
+   * descendant of that wrapper's DOM subtree). Composing `<AppShell>` with
+   * the real `<Sidebar>` primitive (not a bare custom `<nav>`) and placing a
+   * `<SidebarTrigger>` in `topNav` — both wrapped in ONE shared
+   * `<SidebarProvider>`, which is a plain React context and so is never
+   * blocked by AppShell's internal wrapper `<div>` — is therefore ALREADY a
+   * working mobile nav path with no AppShell code change: this test locks
+   * that composition rather than reworking AppShell into owning a second,
+   * competing `Sheet` (which would have to unmount `<Sidebar>` whenever ITS
+   * own drawer closes — see the doc comment for why that is a regression,
+   * not a fix). A consumer who instead passes a bare nav node still needs to
+   * bring its own responsive fallback, exactly as documented.
+   */
+  it("reaches sidebar navigation through Sidebar's own Sheet fallback at a mobile width", async () => {
+    Object.defineProperty(window, "innerWidth", {
+      writable: true,
+      configurable: true,
+      value: 500,
+    });
+    const user = userEvent.setup();
+    render(
+      <SidebarProvider>
+        <AppShell
+          mainId="main"
+          topNav={<SidebarTrigger />}
+          sidebar={
+            <Sidebar>
+              <SidebarContent>
+                <SidebarMenu>
+                  <SidebarMenuItem>
+                    <SidebarMenuButton>Dashboard</SidebarMenuButton>
+                  </SidebarMenuItem>
+                </SidebarMenu>
+              </SidebarContent>
+            </Sidebar>
+          }
+        >
+          Main content
+        </AppShell>
+      </SidebarProvider>,
+    );
+
+    // Below `md`, the desktop sidebar branch renders nothing (it is inside
+    // AppShell's `hidden md:flex` slot AND `<Sidebar>` itself renders `null`
+    // desktop markup on mobile) — the nav item is reachable only once the
+    // trigger opens the portal-rendered Sheet.
+    expect(screen.queryByRole("button", { name: "Dashboard" })).not.toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "Toggle Sidebar" }));
+
+    expect(await screen.findByRole("button", { name: "Dashboard" })).toBeInTheDocument();
+  });
+});

package/src/components/app-shell/app-shell.tsx

@@ -1,5 +1,6 @@
-import { type ReactNode } from "react";
+import { forwardRef, type ReactNode } from "react";
 import { cn } from "../../lib/cn";
+import { SkipLink } from "../skip-link";
 
 export interface AppShellProps {
   /** Persistent left navigation (often a <Sidebar />). */
@@ -10,22 +11,73 @@ export interface AppShellProps {
   className?: string;
   /** Class for the scrolling main content region. */
   mainClassName?: string;
+  /**
+   * The `<main>` region's id, and the skip link's target. Override it when a
+   * page mounts more than one shell — two elements sharing `main-content`
+   * would make the skip link ambiguous. @default "main-content"
+   */
+  mainId?: string;
 }
 
 /**
  * App-first layout: fixed-height viewport with an optional sidebar, a top bar,
  * and a scrollable main region. Pure layout — bring your own nav components.
+ *
+ * The `sidebar` slot is hidden below `md` with no fallback of its own: this
+ * shell does not know whether `sidebar` already manages its own responsive
+ * behavior. `<Sidebar>` (`../sidebar`) does — it renders as an offcanvas
+ * `Sheet` below the mobile breakpoint entirely on its own, through a Radix
+ * portal that is unaffected by this wrapper's `hidden md:flex` (a portal
+ * mounts into `document.body`, not into this DOM subtree) — pair it with a
+ * `<SidebarTrigger>` inside `topNav` for full mobile navigation. Wrapping an
+ * arbitrary `sidebar` node in a SECOND, shell-owned `Sheet` here would look
+ * like a fix but silently break that exact pattern: a Radix `Sheet`/`Dialog`
+ * only mounts its content while open, so `<Sidebar>` would be unmounted
+ * (not just hidden) whenever the shell's own drawer is closed — and with it,
+ * the very trigger a caller uses to open ITS mobile view. A bare nav node
+ * (no built-in responsive behavior of its own) has no such fallback; give it
+ * one explicitly, e.g. by rendering a `<Sheet>` alongside `topNav` in the
+ * consuming app.
+ *
+ * The `SidebarProvider` + `Sidebar` + `SidebarTrigger` composition above is
+ * regression-locked in `app-shell.test.tsx` at a mobile viewport width: no
+ * AppShell code change is needed to reach navigation below `md`, because
+ * `SidebarProvider` is a plain React context and is never blocked by this
+ * component's internal wrapper `<div>`.
  */
-export function AppShell({ sidebar, topNav, children, className, mainClassName }: AppShellProps) {
+export const AppShell = forwardRef<HTMLDivElement, AppShellProps>(function AppShell(
+  { sidebar, topNav, children, className, mainClassName, mainId = "main-content" },
+  ref,
+) {
   return (
     <div
+      ref={ref}
       className={cn("flex h-dvh w-full overflow-hidden bg-background text-foreground", className)}
     >
+      {/* The first focusable element of the shell, so a keyboard user can pass
+          the nav rail instead of tabbing through it on every route (WCAG 2.4.1).
+          All four registry app-shell blocks ship one; the primitive they sit
+          beside must not be the exception, and it is the surface with the widest
+          reach — it is imported, not copy-owned. */}
+      <SkipLink targetId={mainId} />
       {sidebar ? <div className="hidden md:flex">{sidebar}</div> : null}
       <div className="flex min-w-0 flex-1 flex-col">
         {topNav}
-        <main className={cn("min-h-0 flex-1 overflow-y-auto", mainClassName)}>{children}</main>
+        {/* `<main>` IS the scroll port here (in the blocks the skip target and
+            the scroll port are separate elements), so it takes `tabIndex={0}`
+            rather than `{-1}`: a region that scrolls has to be keyboard-operable
+            even when the content inside it is not focusable (WCAG 2.1.1, axe
+            `scrollable-region-focusable`). `focus-ring-inset`, not `focus-ring`
+            — the root above carries `overflow-hidden`, which clips both layers
+            of the plain rung. */}
+        <main
+          id={mainId}
+          tabIndex={0}
+          className={cn("min-h-0 flex-1 overflow-y-auto focus-ring-inset", mainClassName)}
+        >
+          {children}
+        </main>
       </div>
     </div>
   );
-}
+});

package/src/components/app-sidebar/app-sidebar.stories.tsx

@@ -17,7 +17,15 @@ const meta = {
   title: "Layout/AppSidebar",
   component: AppSidebar,
   tags: ["autodocs"],
-  parameters: { layout: "fullscreen" },
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "The opinionated application sidebar — the raw primitive set it composes is `Layout/Sidebar`; see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). `AppSidebar` wraps the `Sidebar` → `SidebarHeader` → `SidebarContent` → `SidebarFooter` skeleton behind typed `header` / `footer` slots with the navigation as `children`, and forwards every `Sidebar` prop. The registry’s sidebar blocks import this rather than rebuilding the skeleton.",
+      },
+    },
+  },
   decorators: [
     (Story) => (
       <SidebarProvider>

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

@@ -1,3 +1,5 @@
+"use client";
+
 import { forwardRef, useId, useMemo, type HTMLAttributes } from "react";
 import { cn } from "../../lib/cn";
 import { Badge } from "../badge";
@@ -74,7 +76,7 @@ function AttributionItem({ item, requiredLabel }: { item: Attribution; requiredL
             href={item.url}
             target="_blank"
             rel="noopener noreferrer"
-            className="text-body font-medium underline underline-offset-2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-xs"
+            className="text-body font-medium underline underline-offset-2 focus-ring rounded-xs"
           >
             {item.name}
           </a>