@elabs-ai/components-ui 4.0.0 → 4.2.0

package/src/components/sidebar/sidebar.tsx

@@ -7,6 +7,7 @@ import {
   useContext,
   useEffect,
   useMemo,
+  useRef,
   useState,
   type ComponentProps,
   type CSSProperties,
@@ -19,6 +20,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 +57,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 +94,7 @@ export const SidebarProvider = forwardRef<
   },
   ref,
 ) {
+  const isNested = frame === "nested";
   const isMobile = useIsMobile();
   const [openMobile, setOpenMobile] = useState(false);
 
@@ -78,27 +105,45 @@ 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(() => {
     return isMobile ? setOpenMobile((o) => !o) : setOpen((o) => !o);
   }, [isMobile, setOpen]);
 
+  // `toggleSidebar` is a NEW function on every `open` change (it closes over
+  // `setOpen`, which itself closes over `open`) — a `useEffect` depending on
+  // it directly would tear down and re-add the global `keydown` listener on
+  // every single toggle. A ref holding the latest callback keeps the listener
+  // registration stable across toggles; only `isNested` (which never changes
+  // after mount) re-runs the effect.
+  const toggleSidebarRef = useRef(toggleSidebar);
   useEffect(() => {
+    toggleSidebarRef.current = toggleSidebar;
+  }, [toggleSidebar]);
+
+  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();
-        toggleSidebar();
+        toggleSidebarRef.current();
       }
     };
     window.addEventListener("keydown", handleKeyDown);
     return () => window.removeEventListener("keydown", handleKeyDown);
-  }, [toggleSidebar]);
+  }, [isNested]);
 
   const state = open ? "expanded" : "collapsed";
 
@@ -112,9 +157,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 +193,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 +238,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,12 +280,12 @@ 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>
-            <SheetDescription>Displays the mobile sidebar.</SheetDescription>
+            <SheetTitle>{t("ui.sidebar.title")}</SheetTitle>
+            <SheetDescription>{t("ui.sidebar.mobileDescription")}</SheetDescription>
           </SheetHeader>
           <div className="flex h-full w-full flex-col">{children}</div>
         </SheetContent>
@@ -235,7 +319,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 +347,13 @@ export const Sidebar = forwardRef<
 
 export const SidebarTrigger = forwardRef<HTMLButtonElement, ComponentProps<typeof Button>>(
   function SidebarTrigger({ className, onClick, ...props }, ref) {
-    const { toggleSidebar } = useSidebar();
+    const { t } = useLocale();
+    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 +361,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);
@@ -270,7 +381,7 @@ export const SidebarTrigger = forwardRef<HTMLButtonElement, ComponentProps<typeo
         {...props}
       >
         <PanelLeftIcon />
-        <span className="sr-only">Toggle Sidebar</span>
+        <span className="sr-only">{t("ui.sidebar.toggle")}</span>
       </Button>
     );
   },
@@ -278,16 +389,17 @@ export const SidebarTrigger = forwardRef<HTMLButtonElement, ComponentProps<typeo
 
 export const SidebarRail = forwardRef<HTMLButtonElement, ComponentProps<"button">>(
   function SidebarRail({ className, ...props }, ref) {
+    const { t } = useLocale();
     const { toggleSidebar } = useSidebar();
     return (
       <button
         ref={ref}
         data-sidebar="rail"
         data-slot="sidebar-rail"
-        aria-label="Toggle Sidebar"
+        aria-label={t("ui.sidebar.toggle")}
         tabIndex={-1}
         onClick={toggleSidebar}
-        title="Toggle Sidebar"
+        title={t("ui.sidebar.toggle")}
         className={cn(
           "absolute inset-y-0 z-20 hidden w-4 -translate-x-1/2 transition-all ease-linear group-data-[side=left]:-right-4 group-data-[side=right]:left-0 after:absolute after:inset-y-0 after:left-1/2 after:w-[2px] hover:after:bg-sidebar-border sm:flex",
           "in-data-[side=left]:cursor-w-resize in-data-[side=right]:cursor-e-resize",
@@ -300,22 +412,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 +630,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 +650,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 +703,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 +787,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 +831,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 +901,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/skeleton/skeleton.tsx

@@ -7,6 +7,7 @@ export type SkeletonProps = HTMLAttributes<HTMLDivElement>;
 export function Skeleton({ className, ...props }: SkeletonProps) {
   return (
     <div
+      data-slot="skeleton"
       className={cn("animate-pulse rounded-md bg-muted", className)}
       aria-hidden="true"
       {...props}

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",
+    );
+  });
+});