@elabs-ai/components-ui 4.0.0 → 4.1.0

package/src/components/sidebar/sidebar.tsx

@@ -19,6 +19,7 @@ import { useIsMobile } from "../../lib/use-mobile";
 import { Button } from "../button";
 import { useCollapsiblePanel } from "../collapsible-panel";
 import { Input } from "../input";
+import { useLocale } from "../locale-provider";
 import { Separator } from "../separator";
 import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle } from "../sheet";
 import { Skeleton } from "../skeleton";
@@ -55,12 +56,36 @@ export const SidebarProvider = forwardRef<
     defaultOpen?: boolean;
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Drives the frame's inset treatment from an ANCESTOR the whole frame can
+     * see — `SidebarInset` (#342 fix) reads it as `data-variant` on this
+     * wrapper via `group-data-[variant=inset]/sidebar-wrapper:`, which reaches
+     * regardless of DOM order (unlike the legacy `peer-*` combinator, which
+     * only matches a Sidebar that comes AFTER). Optional and unset by
+     * default, so an existing caller that only sets `variant` on `Sidebar`
+     * is unaffected.
+     */
+    variant?: "sidebar" | "floating" | "inset";
+    /**
+     * Default `"app"` — today's behaviour, byte-identical. `"nested"` is for
+     * a `SidebarProvider` a compound component (e.g. `ContextRail`, ADR 0035
+     * §4) mounts internally so `useSidebar()` reports ITS OWN state to its
+     * own parts: it still provides `SidebarContext` and the two
+     * `--sidebar-width*` custom properties (which survive `display:
+     * contents`), but renders no frame box, no `data-slot`/`data-variant`/
+     * `data-state`, registers no global `⌘B`/`Ctrl+B` listener, and writes no
+     * `sidebar_state` cookie — so a nested rail can never be mistaken for a
+     * second app frame. See the emission table in ADR 0035 §4.
+     */
+    frame?: "app" | "nested";
   }
 >(function SidebarProvider(
   {
     defaultOpen = true,
     open: openProp,
     onOpenChange: setOpenProp,
+    variant,
+    frame = "app",
     className,
     style,
     children,
@@ -68,6 +93,7 @@ export const SidebarProvider = forwardRef<
   },
   ref,
 ) {
+  const isNested = frame === "nested";
   const isMobile = useIsMobile();
   const [openMobile, setOpenMobile] = useState(false);
 
@@ -78,11 +104,14 @@ export const SidebarProvider = forwardRef<
       const openState = typeof value === "function" ? value(open) : value;
       if (setOpenProp) setOpenProp(openState);
       else _setOpen(openState);
-      if (typeof document !== "undefined") {
+      // A nested provider (ADR 0035 §4) is not the app frame, so it must not
+      // persist ITS state as if it were — only `frame="app"` (the default)
+      // owns the `sidebar_state` cookie.
+      if (!isNested && typeof document !== "undefined") {
         document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`;
       }
     },
-    [setOpenProp, open],
+    [setOpenProp, open, isNested],
   );
 
   const toggleSidebar = useCallback(() => {
@@ -90,6 +119,10 @@ export const SidebarProvider = forwardRef<
   }, [isMobile, setOpen]);
 
   useEffect(() => {
+    // Same reasoning as the cookie write above: the global keyboard shortcut
+    // belongs to the ONE app frame, not to every nested provider a compound
+    // component happens to mount.
+    if (isNested) return;
     const handleKeyDown = (event: KeyboardEvent) => {
       if (event.key === SIDEBAR_KEYBOARD_SHORTCUT && (event.metaKey || event.ctrlKey)) {
         event.preventDefault();
@@ -98,7 +131,7 @@ export const SidebarProvider = forwardRef<
     };
     window.addEventListener("keydown", handleKeyDown);
     return () => window.removeEventListener("keydown", handleKeyDown);
-  }, [toggleSidebar]);
+  }, [isNested, toggleSidebar]);
 
   const state = open ? "expanded" : "collapsed";
 
@@ -112,9 +145,26 @@ export const SidebarProvider = forwardRef<
       <TooltipProvider delayDuration={0}>
         <div
           ref={ref}
-          data-slot="sidebar-wrapper"
+          // `data-slot`/`data-variant`/`data-state`/`group/sidebar-wrapper`
+          // (in the class list below) are ADR 0035 §8 refinement 3's
+          // `frame="app"` surface. `frame="nested"` (ADR 0035 §4, Task 9A)
+          // omits all four: a nested rail's own state must never drive the
+          // outer frame's geometry through the same group name or be mistaken
+          // for a second "sidebar wrapper" by a selector/test targeting the
+          // slot. The literal string "sidebar-wrapper" stays below (as a
+          // conditional value) so `pnpm data-slot:check` still sees this
+          // module's declaration.
+          data-slot={isNested ? undefined : "sidebar-wrapper"}
+          data-variant={isNested ? undefined : variant}
+          data-state={isNested ? undefined : state}
           style={
             {
+              // These two custom properties are the ONE thing a nested
+              // provider still emits (ADR 0035 §4) — they survive `display:
+              // contents` because custom properties inherit down the DOM
+              // tree regardless of the box an element generates, which is
+              // exactly how a nested rail publishes its width to whatever it
+              // wraps. Never move them onto a child.
               "--sidebar-width": SIDEBAR_WIDTH,
               "--sidebar-width-icon": SIDEBAR_WIDTH_ICON,
               ...style,
@@ -131,7 +181,28 @@ export const SidebarProvider = forwardRef<
             // for every element that inherits its colour (outline Buttons, list
             // rows). See the chrome<canvas elevation invariant in
             // .claude/rules/styling-and-tokens.md.
-            "group/sidebar-wrapper flex min-h-svh w-full text-foreground has-data-[variant=inset]:bg-sidebar",
+            // Omitted under `frame="nested"` — a nested provider is a pure
+            // context + custom-property carrier, not a second frame box.
+            !isNested && "group/sidebar-wrapper flex min-h-svh w-full text-foreground",
+            // The frame's OWN `variant` is authoritative once set (ADR 0035 §8
+            // refinement 4): resolved in JS, not by a CSS descendant match, so
+            // a nested rail three levels down that happens to render
+            // `variant="inset"` can never repaint THIS frame's ground merely
+            // because `:has()` is depth-unlimited. `has-data-[variant=inset]`
+            // stays as the fallback ONLY while this provider's own `variant`
+            // is unset, which is exactly every existing caller (this prop
+            // didn't exist before #342) — so they render exactly as today.
+            // Also omitted under `frame="nested"`, same reasoning as above.
+            !isNested &&
+              (variant === undefined
+                ? "has-data-[variant=inset]:bg-sidebar"
+                : variant === "inset" && "bg-sidebar"),
+            // `frame="nested"` renders no box of its own: `display: contents`
+            // (the literal Tailwind class, never an inline style or a
+            // concatenated name) removes this element from layout while
+            // keeping its children — and the custom properties above —
+            // reachable.
+            isNested && "contents",
             className,
           )}
           {...props}
@@ -155,6 +226,7 @@ export const Sidebar = forwardRef<
   ref,
 ) {
   const { isMobile, openMobile, setOpenMobile, open, setOpen } = useSidebar();
+  const { t } = useLocale();
 
   // The collapse mechanism (gap spacer + fixed slide) is the canonical
   // useCollapsiblePanel hook (#190, research 09 §B.2) — Sidebar passes its
@@ -196,11 +268,11 @@ export const Sidebar = forwardRef<
           data-slot="sidebar"
           data-mobile="true"
           side={side}
-          className="w-(--sidebar-width) bg-sidebar p-0 text-sidebar-foreground [&>button]:hidden"
+          className="w-[var(--sidebar-width)] bg-sidebar p-0 text-sidebar-foreground [&>button]:hidden"
           style={{ "--sidebar-width": SIDEBAR_WIDTH_MOBILE } as CSSProperties}
         >
           <SheetHeader className="sr-only">
-            <SheetTitle>Sidebar</SheetTitle>
+            <SheetTitle>{t("ui.sidebar.title")}</SheetTitle>
             <SheetDescription>Displays the mobile sidebar.</SheetDescription>
           </SheetHeader>
           <div className="flex h-full w-full flex-col">{children}</div>
@@ -235,7 +307,16 @@ export const Sidebar = forwardRef<
           panel.containerClassName,
           variant === "floating" || variant === "inset"
             ? "p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4))+2px)]"
-            : "group-data-[collapsible=icon]:w-(--sidebar-width-icon) group-data-[side=left]:border-r group-data-[side=right]:border-l",
+            : // `border-sidebar-border`, not the inherited canvas `--border`:
+              // this edge is CHROME, so it takes the chrome edge token — the
+              // same one the `floating` variant's inner surface and
+              // `SidebarSeparator` already use. Left to the canvas token it was
+              // a near-white hairline (light: L 0.88), invisible against the
+              // page but a bright line as soon as the rail sits on a
+              // `bg-sidebar` ground — which is exactly what an `inset` frame
+              // puts behind it, measured at the dashboard shell's right-hand
+              // `ContextRail`.
+              "group-data-[collapsible=icon]:w-(--sidebar-width-icon) border-sidebar-border group-data-[side=left]:border-r group-data-[side=right]:border-l",
           className,
         )}
         {...props}
@@ -254,7 +335,12 @@ export const Sidebar = forwardRef<
 
 export const SidebarTrigger = forwardRef<HTMLButtonElement, ComponentProps<typeof Button>>(
   function SidebarTrigger({ className, onClick, ...props }, ref) {
-    const { toggleSidebar } = useSidebar();
+    const { isMobile, open, openMobile, toggleSidebar } = useSidebar();
+    // `toggleSidebar` flips `openMobile` below the mobile breakpoint and `open`
+    // above it, so the state this button EXPOSES has to be read the same way —
+    // reporting the desktop `open` on a mobile viewport would announce the
+    // opposite of what the button does.
+    const expanded = isMobile ? openMobile : open;
     return (
       <Button
         ref={ref}
@@ -262,6 +348,18 @@ export const SidebarTrigger = forwardRef<HTMLButtonElement, ComponentProps<typeo
         data-slot="sidebar-trigger"
         variant="ghost"
         size="icon"
+        // A disclosure control must EXPOSE the state it toggles (WCAG 4.1.2).
+        // This button's whole accessible name is the static "Toggle Sidebar"
+        // below, so without this attribute nothing tells a screen-reader user
+        // whether the rail is currently open — and no axe rule catches it,
+        // because a <button> has no REQUIRED expanded state.
+        //
+        // `aria-controls` is deliberately omitted, not forgotten: on mobile the
+        // sidebar renders into a `Sheet` that is not in the document while
+        // closed, so the attribute would point at an absent id — worse than
+        // leaving it off. Spread last, so a caller that really does own a
+        // stable target can still supply both.
+        aria-expanded={expanded}
         className={cn("size-7", className)}
         onClick={(event) => {
           onClick?.(event);
@@ -300,22 +398,124 @@ export const SidebarRail = forwardRef<HTMLButtonElement, ComponentProps<"button"
   },
 );
 
-export const SidebarInset = forwardRef<HTMLDivElement, ComponentProps<"main">>(
-  function SidebarInset({ className, ...props }, ref) {
-    return (
-      <main
-        ref={ref}
-        data-slot="sidebar-inset"
-        className={cn(
-          "relative flex w-full flex-1 flex-col bg-background",
-          "md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ms-0 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-sm md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ms-2",
-          className,
-        )}
-        {...props}
-      />
-    );
+/**
+ * Which sides of the floating "inset" surface get a gutter, once an ancestor
+ * drives the treatment (`SidebarProvider variant="inset"`, or the legacy
+ * immediately-preceding `Sidebar variant="inset"`).
+ *
+ * - `"auto"` (default) — today's rule, unchanged: a gutter on every side
+ *   except the leading edge (`m-2 ms-0`, because the classic layout puts the
+ *   sidebar there), plus the leading edge's gutter returns (`ms-2`) once that
+ *   sidebar collapses and its own gap closes.
+ * - `"none"` — no gutter margin (the unconditional radius/shadow below still
+ *   apply).
+ * - An object — pick sides explicitly. `{ start: true, bottom: true }` is the
+ *   "flush rail" geometry: a leading + bottom gutter only, no top, no
+ *   trailing, because the trailing edge sits flush against a rail — a tab
+ *   must touch the page it belongs to.
+ *
+ * PRECEDENCE (fix round 1, #342): a caller composing BOTH mechanisms at once
+ * — `SidebarProvider variant="inset"` AND a LEFT `Sidebar variant="inset"`,
+ * the shape a left-hand shell (e.g. the sidebar-02 rebuild) uses — never hits
+ * a class-order race, because the ancestor-scoped and legacy peer-scoped
+ * margin classes are BOTH derived from this same `gutter` value, so whenever
+ * both selectors match they emit identical declarations instead of competing
+ * ones; the resolved geometry is always exactly what `gutter` says, decided
+ * by this prop, never by the generated stylesheet's rule order.
+ */
+export type SidebarInsetGutter =
+  | "auto"
+  | "none"
+  | { top?: boolean; bottom?: boolean; start?: boolean; end?: boolean };
+
+export interface SidebarInsetProps extends ComponentProps<"main"> {
+  gutter?: SidebarInsetGutter;
+}
+
+// Each side is a COMPLETE literal utility string, one per SELECTOR SCOPE:
+// `ancestor` (`group-data-…/sidebar-wrapper:`, reaches a `SidebarProvider
+// variant="inset"` regardless of DOM order — the #342 fix) and `legacy`
+// (`peer-data-…:`, reaches a `Sidebar variant="inset"` that immediately
+// precedes this element — every caller before #342). Both scopes read the
+// SAME `gutter` value below, which is what keeps them from ever disagreeing.
+// Tailwind's content scanner only recognises literal class text in source —
+// never a name assembled by concatenation/interpolation
+// (.claude/rules/styling-and-tokens.md) — so the object form below picks
+// among these literals, it never builds one.
+const SIDEBAR_INSET_GUTTER_SIDE_CLASS = {
+  top: {
+    ancestor: "md:group-data-[variant=inset]/sidebar-wrapper:mt-2",
+    legacy: "md:peer-data-[variant=inset]:mt-2",
   },
-);
+  bottom: {
+    ancestor: "md:group-data-[variant=inset]/sidebar-wrapper:mb-2",
+    legacy: "md:peer-data-[variant=inset]:mb-2",
+  },
+  start: {
+    ancestor: "md:group-data-[variant=inset]/sidebar-wrapper:ms-2",
+    legacy: "md:peer-data-[variant=inset]:ms-2",
+  },
+  end: {
+    ancestor: "md:group-data-[variant=inset]/sidebar-wrapper:me-2",
+    legacy: "md:peer-data-[variant=inset]:me-2",
+  },
+} as const;
+
+// "auto" is its own complete literal pair, not composed from the map above,
+// because it also carries the collapsed-state clause: the sidebar's own gap
+// closes on collapse, so the inset's leading margin has to come back.
+const SIDEBAR_INSET_GUTTER_AUTO_CLASS = {
+  ancestor:
+    "md:group-data-[variant=inset]/sidebar-wrapper:m-2 md:group-data-[variant=inset]/sidebar-wrapper:ms-0 md:group-data-[variant=inset]/sidebar-wrapper:group-data-[state=collapsed]/sidebar-wrapper:ms-2",
+  legacy:
+    "md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ms-0 md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ms-2",
+} as const;
+
+function sidebarInsetGutterClassName(
+  gutter: SidebarInsetGutter,
+  scope: "ancestor" | "legacy",
+): string {
+  if (gutter === "auto") return SIDEBAR_INSET_GUTTER_AUTO_CLASS[scope];
+  if (gutter === "none") return "";
+  return cn(
+    gutter.top && SIDEBAR_INSET_GUTTER_SIDE_CLASS.top[scope],
+    gutter.bottom && SIDEBAR_INSET_GUTTER_SIDE_CLASS.bottom[scope],
+    gutter.start && SIDEBAR_INSET_GUTTER_SIDE_CLASS.start[scope],
+    gutter.end && SIDEBAR_INSET_GUTTER_SIDE_CLASS.end[scope],
+  );
+}
+
+export const SidebarInset = forwardRef<HTMLDivElement, SidebarInsetProps>(function SidebarInset(
+  { className, gutter = "auto", ...props },
+  ref,
+) {
+  return (
+    <main
+      ref={ref}
+      data-slot="sidebar-inset"
+      className={cn(
+        "relative flex w-full flex-1 flex-col bg-background",
+        // Ancestor-scoped (#342 fix): `group/sidebar-wrapper` spans the whole
+        // frame, so this reaches a right-hand or reordered `Sidebar` the old
+        // peer-* combinator could not (it only matches a sibling that comes
+        // AFTER). Reads `SidebarProvider`'s own `data-variant`/`data-state`.
+        // Radius/shadow are unconditional here — not gated by `gutter`.
+        "md:group-data-[variant=inset]/sidebar-wrapper:rounded-xl md:group-data-[variant=inset]/sidebar-wrapper:shadow-sm",
+        sidebarInsetGutterClassName(gutter, "ancestor"),
+        // Legacy peer rule — reaches a shell that sets `variant` only on
+        // `Sidebar` (every caller before #342). Radius/shadow unconditional
+        // here too; the margin is driven by the SAME `gutter` value as the
+        // ancestor rule above (fix round 1, #342), so a caller composing both
+        // mechanisms at once never hits a stylesheet-order race — whichever
+        // selector matches emits the identical declaration.
+        "md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-sm",
+        sidebarInsetGutterClassName(gutter, "legacy"),
+        className,
+      )}
+      {...props}
+    />
+  );
+});
 
 export const SidebarInput = forwardRef<HTMLInputElement, ComponentProps<typeof Input>>(
   function SidebarInput({ className, ...props }, ref) {
@@ -416,8 +616,8 @@ export const SidebarGroupLabel = forwardRef<
       data-slot="sidebar-group-label"
       data-sidebar="group-label"
       className={cn(
-        "flex h-8 shrink-0 items-center rounded-md px-2 text-meta font-medium text-sidebar-muted-foreground outline-none ring-sidebar-ring transition-[margin,opacity] duration-base ease-linear focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0",
-        "group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0",
+        "flex h-8 shrink-0 items-center rounded-md px-2 text-meta font-medium text-sidebar-muted-foreground focus-ring [--focus-ring-color:var(--sidebar-ring)] transition-[opacity] duration-base ease-linear [&>svg]:size-4 [&>svg]:shrink-0",
+        "group-data-[collapsible=icon]:hidden",
         className,
       )}
       {...props}
@@ -436,7 +636,7 @@ export const SidebarGroupAction = forwardRef<
       data-slot="sidebar-group-action"
       data-sidebar="group-action"
       className={cn(
-        "absolute end-3 top-3.5 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground outline-none ring-sidebar-ring transition-transform hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0 after:absolute after:-inset-2 md:after:hidden",
+        "absolute end-3 top-3.5 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground focus-ring [--focus-ring-color:var(--sidebar-ring)] transition-transform hover:bg-sidebar-accent hover:text-sidebar-accent-foreground [&>svg]:size-4 [&>svg]:shrink-0 after:absolute after:-inset-2 md:after:hidden",
         "group-data-[collapsible=icon]:hidden",
         className,
       )}
@@ -489,7 +689,7 @@ export const SidebarMenuItem = forwardRef<HTMLLIElement, ComponentProps<"li">>(
 );
 
 export const sidebarMenuButtonVariants = cva(
-  "peer/menu-button flex w-full items-center gap-2 overflow-hidden rounded-md p-2 text-start text-body text-sidebar-foreground outline-none ring-sidebar-ring transition-[width,height,padding] hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 group-has-data-[sidebar=menu-action]/menu-item:pe-8 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[active=true]:bg-sidebar-accent data-[active=true]:font-medium data-[active=true]:text-sidebar-accent-foreground data-[active=true]:[&>svg]:text-sidebar-primary data-[state=open]:hover:bg-sidebar-accent data-[state=open]:hover:text-sidebar-accent-foreground group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0",
+  "peer/menu-button relative flex w-full items-center gap-2 overflow-hidden rounded-md p-2 text-start text-body text-sidebar-foreground focus-ring [--focus-ring-color:var(--sidebar-ring)] transition-[width,height,padding] hover:bg-sidebar-accent hover:text-sidebar-accent-foreground active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 group-has-data-[sidebar=menu-action]/menu-item:pe-8 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[active=true]:bg-sidebar-accent data-[active=true]:font-semibold data-[active=true]:text-sidebar-accent-foreground data-[active=true]:[&>svg]:text-sidebar-primary data-[active=true]:before:pointer-events-none data-[active=true]:before:absolute data-[active=true]:before:inset-y-1.5 data-[active=true]:before:start-0 data-[active=true]:before:w-1 data-[active=true]:before:rounded-full data-[active=true]:before:bg-sidebar-primary data-[state=open]:hover:bg-sidebar-accent data-[state=open]:hover:text-sidebar-accent-foreground group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0",
   {
     variants: {
       variant: {
@@ -573,7 +773,7 @@ export const SidebarMenuAction = forwardRef<
       data-slot="sidebar-menu-action"
       data-sidebar="menu-action"
       className={cn(
-        "absolute end-1 top-1.5 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground outline-none ring-sidebar-ring transition-transform hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 peer-hover/menu-button:text-sidebar-accent-foreground [&>svg]:size-4 [&>svg]:shrink-0 after:absolute after:-inset-2 md:after:hidden",
+        "absolute end-1 top-1.5 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground focus-ring [--focus-ring-color:var(--sidebar-ring)] transition-transform hover:bg-sidebar-accent hover:text-sidebar-accent-foreground peer-hover/menu-button:text-sidebar-accent-foreground [&>svg]:size-4 [&>svg]:shrink-0 after:absolute after:-inset-2 md:after:hidden",
         "group-data-[collapsible=icon]:hidden",
         showOnHover &&
           "group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-[state=open]:opacity-100 peer-data-[active=true]/menu-button:text-sidebar-accent-foreground md:opacity-0",
@@ -617,9 +817,21 @@ export function SidebarMenuSkeleton({
       className={cn("flex h-8 items-center gap-2 rounded-md px-2", className)}
       {...props}
     >
-      {showIcon && <Skeleton className="size-4 rounded-md" data-sidebar="menu-skeleton-icon" />}
+      {/* `bg-sidebar-accent`, overriding `Skeleton`'s own `bg-muted`. `--muted`
+          is a CANVAS token: in the light theme it is a near-white
+          `oklch(0.968 …)` sitting on this sidebar's dark `oklch(0.3 …)` ground,
+          which measures 12.42:1 — the placeholder becomes the loudest thing on
+          a screen that has nothing loaded yet. The sidebar's own quiet rung
+          measures 1.26:1 on light and 1.29:1 on dark, i.e. a placeholder in
+          both themes instead of an inversion in one. */}
+      {showIcon && (
+        <Skeleton
+          className="size-4 rounded-md bg-sidebar-accent"
+          data-sidebar="menu-skeleton-icon"
+        />
+      )}
       <Skeleton
-        className="h-4 max-w-(--skeleton-width) flex-1"
+        className="h-4 max-w-(--skeleton-width) flex-1 bg-sidebar-accent"
         data-sidebar="menu-skeleton-text"
         style={{ "--skeleton-width": width } as CSSProperties}
       />
@@ -675,8 +887,8 @@ export const SidebarMenuSubButton = forwardRef<
       data-size={size}
       data-active={isActive}
       className={cn(
-        "flex h-7 min-w-0 -translate-x-px items-center gap-2 overflow-hidden rounded-md px-2 text-sidebar-foreground outline-none ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0 [&>svg]:text-sidebar-accent-foreground",
-        "data-[active=true]:bg-sidebar-accent data-[active=true]:text-sidebar-accent-foreground",
+        "relative flex h-7 min-w-0 -translate-x-px items-center gap-2 overflow-hidden rounded-md px-2 text-sidebar-foreground focus-ring [--focus-ring-color:var(--sidebar-ring)] hover:bg-sidebar-accent hover:text-sidebar-accent-foreground active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0 [&>svg]:text-sidebar-accent-foreground",
+        "data-[active=true]:bg-sidebar-accent data-[active=true]:font-semibold data-[active=true]:text-sidebar-accent-foreground data-[active=true]:before:pointer-events-none data-[active=true]:before:absolute data-[active=true]:before:inset-y-1.5 data-[active=true]:before:start-0 data-[active=true]:before:w-1 data-[active=true]:before:rounded-full data-[active=true]:before:bg-sidebar-primary",
         size === "sm" && "text-meta",
         size === "md" && "text-body",
         "group-data-[collapsible=icon]:hidden",

package/src/components/skip-link/index.ts

@@ -0,0 +1 @@
+export * from "./skip-link";

package/src/components/skip-link/skip-link.stories.tsx

@@ -0,0 +1,106 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent } from "storybook/test";
+import { CommandTrigger } from "../command-trigger";
+import { SkipLink } from "./skip-link";
+
+const meta = {
+  title: "Navigation/SkipLink",
+  component: SkipLink,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'The first focusable element of an application. Invisible until it receives focus, then a pill in the top-start corner that jumps past the whole nav rail to the page\'s `<main>`. Give the target `id="main-content"` and `tabIndex={-1}` so focus lands there rather than merely scrolling.',
+      },
+    },
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof SkipLink>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Press Tab: the link appears. It is the only way a keyboard user skips the rail. */
+export const Default: Story = {
+  render: () => (
+    <div>
+      <SkipLink />
+      <nav aria-label="Primary" className="p-4 text-body text-muted-foreground">
+        nav links live here
+      </nav>
+      <main id="main-content" tabIndex={-1} className="p-4 text-body">
+        Main content
+      </main>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    await userEvent.tab();
+    const link = canvasElement.querySelector('[data-slot="skip-link"]') as HTMLElement;
+    await expect(link).toHaveFocus();
+    // Not-sr-only when focused: it has real painted size.
+    await expect(link.getBoundingClientRect().width).toBeGreaterThan(40);
+  },
+};
+
+/**
+ * Finding 3 (task-11f-brief.md): the `Default` story above has no competing
+ * focusable furniture, so its own "the link comes first" assertion is
+ * vacuous — it would pass on a page with the link anywhere in the tab order,
+ * because there is nothing else to come before. This story composes the
+ * link inside a realistic shell — a `CommandTrigger` plus real nav
+ * `<a>`/`<button>` elements genuinely competing for first place — and a real
+ * `<main id="main-content" tabIndex={-1}>` target. It proves the tab-order
+ * claim for real: tabbing from a blurred page lands on the skip link ahead of
+ * every one of those competing controls. The second claim — that ACTIVATING
+ * the link moves real focus rather than merely scrolling — is only checked at
+ * the precondition level here (see the comment in the play function); this
+ * harness cannot exercise the activation itself.
+ */
+export const RealisticShell: Story = {
+  render: () => (
+    <div>
+      <SkipLink />
+      <header className="flex items-center justify-between gap-4 border-b border-border p-4">
+        <nav aria-label="Primary" className="flex items-center gap-4">
+          <a href="#dashboard" className="text-body text-foreground">
+            Dashboard
+          </a>
+          <a href="#reports" className="text-body text-foreground">
+            Reports
+          </a>
+          <button type="button" className="text-body text-foreground">
+            Settings
+          </button>
+        </nav>
+        <CommandTrigger />
+      </header>
+      <main id="main-content" tabIndex={-1} className="p-4 text-body">
+        Main content
+      </main>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    // Start from a blurred page so Tab lands on whatever is genuinely FIRST
+    // in the DOM's tab order — not on whatever the previous story left
+    // focused.
+    (document.activeElement as HTMLElement | null)?.blur();
+    await userEvent.tab();
+    const link = canvasElement.querySelector('[data-slot="skip-link"]') as HTMLElement;
+    await expect(link).toHaveFocus();
+
+    // PRECONDITIONS only, not proof: activating the link really moving focus
+    // to the main landmark cannot be exercised in this harness — Playwright's
+    // pointer-driven `.click()` on a same-document `href="#…"` anchor makes
+    // this `@vitest/browser` composed-story runner tear down the page and
+    // report its own WebSocket connection as closed, even though the
+    // navigation itself is ordinary. So this locks the two things the
+    // focus-move mechanism depends on instead: the href fragment targets the
+    // right id, and that id is programmatically focusable.
+    const main = canvasElement.querySelector("#main-content") as HTMLElement;
+    await expect(link.getAttribute("href")).toBe(`#${main.id}`);
+    // Assert the ATTRIBUTE, not the `tabIndex` IDL property: for a
+    // non-interactive element the property getter returns -1 whether or not
+    // the attribute is present, so it cannot detect a missing attribute —
+    // the one thing this precondition exists to catch.
+    await expect(main.getAttribute("tabindex")).toBe("-1");
+  },
+};

package/src/components/skip-link/skip-link.test.tsx

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { SkipLink } from "./skip-link";
+
+describe("SkipLink", () => {
+  it("points at the main landmark and is reachable by keyboard", () => {
+    render(<SkipLink />);
+    const link = screen.getByRole("link", { name: "Skip to main content" });
+    expect(link).toHaveAttribute("href", "#main-content");
+    expect(link).not.toHaveAttribute("tabindex", "-1");
+  });
+
+  it("accepts a different target", () => {
+    render(<SkipLink targetId="reading-pane">Skip to the message</SkipLink>);
+    expect(screen.getByRole("link", { name: "Skip to the message" })).toHaveAttribute(
+      "href",
+      "#reading-pane",
+    );
+  });
+});

package/src/components/skip-link/skip-link.tsx

@@ -0,0 +1,34 @@
+import { forwardRef, type ComponentProps } from "react";
+import { cn } from "../../lib/cn";
+
+export interface SkipLinkProps extends ComponentProps<"a"> {
+  /** The id of the landmark to jump to. Defaults to "main-content". */
+  targetId?: string;
+}
+
+/**
+ * The first focusable element of an application: invisible until focused, then a
+ * token-styled pill pinned to the top-start corner. Give the target element
+ * `id={targetId}` and `tabIndex={-1}` so focus actually lands there.
+ */
+export const SkipLink = forwardRef<HTMLAnchorElement, SkipLinkProps>(function SkipLink(
+  { targetId = "main-content", className, children, ...props },
+  ref,
+) {
+  return (
+    <a
+      ref={ref}
+      data-slot="skip-link"
+      href={`#${targetId}`}
+      className={cn(
+        "sr-only focus-visible:not-sr-only focus-visible:absolute focus-visible:start-4 focus-visible:top-4 focus-visible:z-50",
+        "focus-visible:rounded-md focus-visible:bg-card focus-visible:px-3 focus-visible:py-2 focus-visible:text-body focus-visible:text-foreground focus-visible:shadow-ring-md",
+        "focus-ring",
+        className,
+      )}
+      {...props}
+    >
+      {children ?? "Skip to main content"}
+    </a>
+  );
+});

package/src/components/slider/slider.tsx

@@ -124,7 +124,7 @@ export const Slider = forwardRef<ElementRef<typeof SliderPrimitive.Root>, Slider
               aria-valuetext={ariaValueText}
               {...safeThumbProps}
               className={cn(
-                "block size-4 rounded-full border border-primary/50 bg-background shadow transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
+                "block size-4 rounded-full border border-primary/50 bg-background shadow transition-colors focus-ring disabled:pointer-events-none disabled:opacity-50",
                 safeThumbProps?.className,
               )}
             />

package/src/components/split-panel/index.ts

@@ -1 +1,6 @@
-export { SplitPanel, type SplitPanelProps, type SplitPanelTone } from "./split-panel";
+export {
+  SplitPanel,
+  splitPaneVariants,
+  type SplitPanelProps,
+  type SplitPanelTone,
+} from "./split-panel";

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

@@ -4,7 +4,23 @@ import { SplitPanel } from "./split-panel";
 const meta = {
   title: "Layout/SplitPanel",
   component: SplitPanel,
-  parameters: { layout: "fullscreen" },
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "A fixed two-pane layout with per-pane surface tones — panes the user can drag to " +
+          "resize are `Layout/Resizable`, see " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). " +
+          '`SplitPanel` sizes the start pane with a CSS grid track (`startSize`, e.g. `"320px"`, ' +
+          '`"40%"`, `"1fr"`) rather than a percentage, so layout is predictable in tests and SSR ' +
+          "with no client-side measurement. The three-tone `plain`/`muted`/`card` ground-offset " +
+          "system on `startTone`/`endTone` is exported as `splitPaneVariants` — apply it to a " +
+          "`ResizablePanel` for the identical tiering on a draggable layout.",
+      },
+    },
+  },
 } satisfies Meta<typeof SplitPanel>;
 export default meta;
 type Story = StoryObj<typeof meta>;
@@ -28,7 +44,7 @@ export const MasterDetail: Story = {
  * the page itself is recessed below white; see research/structural-design 08 §H). A
  * `muted` list well is a light-theme-only enhancement (in dark, `--surface-muted` reads
  * lighter than `--card`), so this demo keeps the list `plain` to read correctly across
- * all three themes.
+ * every theme.
  */
 export const Tiered: Story = {
   render: () => (