@lessly/ui 3.0.0 → 4.0.0

package/dist/router.d.ts

@@ -54,28 +54,38 @@ interface SidebarNavProps {
     isItemActive?: (item: NavItem, pathname: string) => boolean;
     className?: string;
 }
+/**
+ * The rail's rows, and the part of it that reads the router: it takes `useLocation`, marks the row
+ * whose path is open, and renders each through `LinkComponent`. That import is why it and
+ * `AppSidebar` ship from `@lessly/ui/router` rather than the main barrel.
+ *
+ * **Beside `AppSidebar`.** `AppSidebar` is the rail itself — the identity slot above the rows, the
+ * collapse toggle at the foot, the dividers and the two widths — and it renders this component for
+ * the rows in the middle. Take `AppSidebar` for the console's rail; take `SidebarNav`
+ * when the surrounding chrome is yours and only the rows and their active-path rule are not, or
+ * when one rail carries a second list. Either way the row is `NavRow`, so the two cannot drift.
+ */
 declare function SidebarNav({ items, collapsed, basePath, LinkComponent, isItemActive, className, }: SidebarNavProps): React.JSX.Element;
 
 interface AppSidebarProps {
     items: NavItem[];
-    /** Expanded-slot mark/wordmark, rendered when `header` is absent. Also the collapsed-rail
-     *  fallback when `logoCollapsed` isn't given, on a rail that isn't `collapsible` — see
-     *  `logoCollapsed`. */
+    /** Expanded-slot mark/wordmark, rendered when `header` is absent. Also the narrow rail's fallback
+     *  when `logoCollapsed` isn't given. */
     logo?: React.ReactNode;
-    /** Collapsed-rail identity — a small mark, for a rail that cannot be expanded from inside it.
-     *  A `collapsible` rail shows the pin here instead and never reads this: the 52px rail holds
-     *  one box, and the way back to expanded is what it holds. */
+    /** Narrow-rail identity — a small mark, for the width where `header` has no room to be read.
+     *  Falls back to `logo`. */
     logoCollapsed?: React.ReactNode;
     /** Identity slot above the rail — e.g. an <OrgProductSwitcher/> (#266). Falls back to `logo`.
-     *  Expanded-only: rendering it in the 52px collapsed rail would overflow, so the collapsed
-     *  branch never reads it. What stands in depends on `collapsible` — the pin when it is set,
-     *  `logoCollapsed ?? logo` when it is not. */
+     *  Expanded-only: `logoCollapsed ?? logo` stands in it at the narrow width, because a switcher
+     *  clipped to the rail's own width reads as a tile with a severed word beside it. */
     header?: React.ReactNode;
-    /** Account slot below the rail — e.g. a <UserMenu/>. Its divider renders only with it. */
-    footer?: React.ReactNode;
-    /** Render the built-in collapse pin. Off by default: the shipped rail has none.
-     *  `collapsed` is still honoured without it, for consumers driving collapse themselves. */
-    collapsible?: boolean;
+    /** Top of the rail — e.g. a <QuickSearchRow/>. It sits between the header's rule and the rows,
+     *  and it is pinned: outside the scroll region, so it holds one place while the rows below it
+     *  scroll. No rule of its own — what is above it belongs to the organization and what is below
+     *  is the rail, while this is the rail's own first row, and a line would file it elsewhere.
+     *  Unlike `header` it is drawn at both widths, so it takes a function to read `collapsed` with —
+     *  the state a caller has no other way to reach when the rail drives its own collapse. */
+    railTop?: React.ReactNode | ((collapsed: boolean) => React.ReactNode);
     collapsed?: boolean;
     defaultCollapsed?: boolean;
     onCollapsedChange?: (collapsed: boolean) => void;
@@ -84,11 +94,11 @@ interface AppSidebarProps {
     isItemActive?: (item: NavItem, pathname: string) => boolean;
     className?: string;
 }
-declare function AppSidebar({ items, logo, logoCollapsed, header, footer, collapsible, collapsed: controlled, defaultCollapsed, onCollapsedChange, basePath, LinkComponent, isItemActive, className, }: AppSidebarProps): React.JSX.Element;
+declare function AppSidebar({ items, logo, logoCollapsed, header, railTop, collapsed: controlled, defaultCollapsed, onCollapsedChange, basePath, LinkComponent, isItemActive, className, }: AppSidebarProps): React.JSX.Element;
 
 interface AppShellProps {
-    /** The sidebar, typically an <AppSidebar/>. Rendered in the desktop rail and,
-     *  on mobile, inside a Sheet (force-expanded via cloneElement collapsed=false). */
+    /** The sidebar, typically an <AppSidebar/>. Rendered in the desktop rail and, on mobile, inside a
+     *  Sheet — where an <AppSidebar/> at any depth draws the drawer's shape rather than the rail's. */
     sidebar: React.ReactNode;
     topBar?: React.ReactNode;
     children?: React.ReactNode;

package/dist/router.js

@@ -1,6 +1,8 @@
 import {
   Button,
   NavRow,
+  RAIL_COLUMN_BOX,
+  RailToggle,
   Sheet,
   SheetContent,
   SheetDescription,
@@ -13,7 +15,7 @@ import {
   cn,
   useIsMobile,
   useSidebar
-} from "./chunk-CEXND5YW.js";
+} from "./chunk-DYHP7W3X.js";
 
 // src/components/extension-link.tsx
 import { Link } from "react-router";
@@ -52,7 +54,7 @@ function SidebarNavLink({
       label: item.label,
       hideLabel: collapsed,
       icon: Icon ? /* @__PURE__ */ jsx2(Icon, { "aria-hidden": "true" }) : void 0,
-      className: cn(collapsed && "size-9 justify-center px-0 py-0", className),
+      className,
       asChild: true,
       children: /* @__PURE__ */ jsx2(Comp, { to, "aria-current": active ? "page" : void 0 })
     }
@@ -72,57 +74,47 @@ function SidebarNav({
   className
 }) {
   const { pathname } = useLocation();
-  const nav = /* @__PURE__ */ jsx2(
-    "nav",
-    {
-      className: cn(
-        "flex flex-col gap-2",
-        collapsed && "items-center",
-        className
-      ),
-      children: items.map((item) => {
-        const full = `${basePath}${item.href}`;
-        const active = isItemActive ? isItemActive(item, pathname) : isActivePath(pathname, full, item.exact);
-        return /* @__PURE__ */ jsx2(
-          SidebarNavLink,
-          {
-            item,
-            active,
-            collapsed,
-            basePath,
-            LinkComponent
-          },
-          item.href
-        );
-      })
-    }
+  const nav = (
+    // One layout at both widths. A row is `w-full` and its glyph sits at the row's own left
+    // padding, so the column a mark stands on is a fact about the rail around these rows and not
+    // about their width — a narrow box of their own is what took the glyph off that column.
+    /* @__PURE__ */ jsx2("nav", { className: cn("flex flex-col gap-2", className), children: items.map((item) => {
+      const full = `${basePath}${item.href}`;
+      const active = isItemActive ? isItemActive(item, pathname) : isActivePath(pathname, full, item.exact);
+      return /* @__PURE__ */ jsx2(
+        SidebarNavLink,
+        {
+          item,
+          active,
+          collapsed,
+          basePath,
+          LinkComponent
+        },
+        item.href
+      );
+    }) })
   );
   return collapsed ? /* @__PURE__ */ jsx2(TooltipProvider, { children: nav }) : nav;
 }
 
 // src/components/app-sidebar.tsx
-import { PanelLeft } from "lucide-react";
+import * as React from "react";
 import { Fragment, jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
-function Divider({ collapsed, testId, className }) {
-  return /* @__PURE__ */ jsx3(
-    "div",
-    {
-      "data-testid": testId,
-      className: cn(
-        "h-px shrink-0 bg-border-subtle",
-        collapsed ? "ml-[6px] w-[40px]" : "ml-[14px] w-[220px]",
-        className
-      )
-    }
-  );
+var SidebarDrawerContext = React.createContext(false);
+function SidebarDrawer({ children }) {
+  return /* @__PURE__ */ jsx3(SidebarDrawerContext.Provider, { value: true, children });
+}
+function Divider({ testId, className }) {
+  return /* @__PURE__ */ jsx3("div", { "data-testid": testId, className: cn("h-px shrink-0 bg-border-subtle", className) });
 }
+var RAIL_WIDE = "w-[248px]";
+var RAIL_NARROW = "w-[64px]";
 function AppSidebar({
   items,
   logo,
   logoCollapsed,
   header,
-  footer,
-  collapsible = false,
+  railTop,
   collapsed: controlled,
   defaultCollapsed,
   onCollapsedChange,
@@ -131,89 +123,69 @@ function AppSidebar({
   isItemActive,
   className
 }) {
-  const { collapsed, toggle } = useSidebar({
+  const drawer = React.useContext(SidebarDrawerContext);
+  const { collapsed: railCollapsed, toggle } = useSidebar({
     collapsed: controlled,
     defaultCollapsed,
     onCollapsedChange
   });
-  const pin = collapsible ? /* @__PURE__ */ jsx3(
-    "button",
-    {
-      type: "button",
-      onClick: toggle,
-      "aria-label": collapsed ? "Expand sidebar" : "Collapse sidebar",
-      "aria-expanded": !collapsed,
-      className: "flex size-6 shrink-0 items-center justify-center rounded-md text-text-secondary transition-colors duration-fast hover:bg-[var(--hov-bg)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-border-focus",
-      children: /* @__PURE__ */ jsx3(PanelLeft, { className: "size-4", "aria-hidden": "true" })
-    }
-  ) : null;
-  return /* @__PURE__ */ jsxs2(
+  const collapsed = drawer ? false : railCollapsed;
+  const railTopNode = typeof railTop === "function" ? railTop(collapsed) : railTop;
+  return /* @__PURE__ */ jsx3(
     "aside",
     {
       "data-collapsed": collapsed,
       className: cn(
-        "flex h-full shrink-0 flex-col overflow-hidden transition-[width] duration-200 ease-in-out",
-        collapsed ? "w-[52px]" : "w-[248px]",
+        "flex h-full shrink-0 flex-col overflow-hidden motion-rail-collapse",
+        // A nav row drops its own label at the narrow width. What this fades is a label whatever
+        // stands in `railTop` keeps mounted at both — QuickSearchRow's, for one — so the closing
+        // edge slides over the words instead of cutting through them.
+        "[&_[data-slot=nav-row-label]]:transition-opacity [&_[data-slot=nav-row-label]]:duration-fast",
+        collapsed ? RAIL_NARROW : RAIL_WIDE,
+        collapsed && "[&_[data-slot=nav-row-label]]:opacity-0",
         className
       ),
-      children: [
-        /* @__PURE__ */ jsx3("div", { className: cn("flex h-14 items-center gap-2", collapsed ? "justify-center px-1" : "px-3"), children: collapsed ? collapsible ? (
-          /* The 52px rail holds one 32px box, and the way back to expanded is what it holds.
-             The logo has the expanded band and the top bar; the pin has nowhere else, and a
-             pin hidden behind the mark is no pin at all on a device that cannot hover. */
-          /* @__PURE__ */ jsx3(
-            "button",
-            {
-              type: "button",
-              onClick: toggle,
-              "aria-label": "Expand sidebar",
-              "aria-expanded": false,
-              className: "flex size-8 shrink-0 items-center justify-center rounded-md text-text-secondary transition-colors duration-fast hover:bg-[var(--hov-bg)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-border-focus",
-              children: /* @__PURE__ */ jsx3(PanelLeft, { className: "size-4", "aria-hidden": "true" })
-            }
-          )
-        ) : logoCollapsed ?? logo : /* @__PURE__ */ jsxs2(Fragment, { children: [
-          header ?? logo,
-          pin
-        ] }) }),
-        /* @__PURE__ */ jsx3(Divider, { collapsed, testId: "sidebar-divider-header" }),
+      children: /* @__PURE__ */ jsxs2("div", { className: cn("flex h-full shrink-0 flex-col", RAIL_WIDE), children: [
+        /* @__PURE__ */ jsx3("div", { className: cn("flex h-14 shrink-0 items-center gap-2", drawer ? "pl-3 pr-10" : "px-3"), children: collapsed ? /* @__PURE__ */ jsx3("div", { className: RAIL_COLUMN_BOX, children: logoCollapsed ?? logo }) : header ?? logo }),
+        /* @__PURE__ */ jsx3(Divider, { testId: "sidebar-divider-header" }),
+        railTopNode && /* @__PURE__ */ jsx3("div", { "data-testid": "sidebar-rail-top", className: "shrink-0 px-3 pt-3", children: railTopNode }),
         /* @__PURE__ */ jsx3(
           "div",
           {
             "data-testid": "sidebar-scroll",
             className: cn(
-              "min-h-0 flex-1 overflow-y-auto overflow-x-hidden pt-3 pb-2",
-              collapsed ? "px-1" : "px-3"
+              "min-h-0 flex-1 overflow-y-auto overflow-x-hidden px-3 pb-2",
+              railTopNode ? "pt-2" : "pt-3"
             ),
             children: /* @__PURE__ */ jsx3(SidebarNav, { items, collapsed, basePath, LinkComponent, isItemActive })
           }
         ),
-        footer && /* @__PURE__ */ jsxs2(Fragment, { children: [
-          /* @__PURE__ */ jsx3(Divider, { collapsed, testId: "sidebar-divider-account" }),
-          /* @__PURE__ */ jsx3("div", { className: cn("py-2", collapsed ? "px-1" : "px-3"), children: footer })
+        !drawer && /* @__PURE__ */ jsxs2(Fragment, { children: [
+          /* @__PURE__ */ jsx3(Divider, { testId: "sidebar-divider-foot" }),
+          /* @__PURE__ */ jsx3("div", { className: "flex shrink-0 px-3 py-2", children: /* @__PURE__ */ jsx3(RailToggle, { collapsed, onClick: toggle }) })
         ] })
-      ]
+      ] })
     }
   );
 }
 
 // src/components/app-shell.tsx
-import * as React from "react";
+import * as React2 from "react";
 import { Menu } from "lucide-react";
 import { useLocation as useLocation2 } from "react-router";
-import { jsx as jsx4, jsxs as jsxs3 } from "react/jsx-runtime";
+import { Fragment as Fragment2, jsx as jsx4, jsxs as jsxs3 } from "react/jsx-runtime";
 function expandedSidebar(sidebar) {
-  return React.isValidElement(sidebar) ? React.cloneElement(sidebar, { collapsed: false }) : sidebar;
+  return React2.isValidElement(sidebar) ? React2.cloneElement(sidebar, { collapsed: false }) : sidebar;
 }
 function AppShell({ sidebar, topBar, children, className }) {
   const { pathname } = useLocation2();
-  const [mobileOpen, setMobileOpen] = React.useState(false);
-  React.useEffect(() => {
+  const [mobileOpen, setMobileOpen] = React2.useState(false);
+  React2.useEffect(() => {
     setMobileOpen(false);
   }, [pathname]);
   const isMobile = useIsMobile();
   if (isMobile) {
-    return /* @__PURE__ */ jsx4(TooltipProvider, { children: /* @__PURE__ */ jsxs3("div", { className: cn("flex min-h-screen flex-col bg-bg-surface", className), children: [
+    return /* @__PURE__ */ jsx4(TooltipProvider, { children: /* @__PURE__ */ jsxs3("div", { className: cn("flex min-h-screen flex-col bg-bg-primary", className), children: [
       /* @__PURE__ */ jsxs3(
         "header",
         {
@@ -222,10 +194,10 @@ function AppShell({ sidebar, topBar, children, className }) {
           children: [
             /* @__PURE__ */ jsxs3(Sheet, { open: mobileOpen, onOpenChange: setMobileOpen, children: [
               /* @__PURE__ */ jsx4(SheetTrigger, { asChild: true, children: /* @__PURE__ */ jsx4(Button, { variant: "ghost", size: "icon", className: "size-8 text-text-secondary", "aria-label": "Open navigation", children: /* @__PURE__ */ jsx4(Menu, { className: "size-5" }) }) }),
-              /* @__PURE__ */ jsxs3(SheetContent, { side: "left", className: "w-[248px] bg-bg-surface p-0", children: [
+              /* @__PURE__ */ jsxs3(SheetContent, { side: "left", className: "w-[248px] bg-bg-primary p-0", children: [
                 /* @__PURE__ */ jsx4(SheetTitle, { className: "sr-only", children: "Navigation" }),
                 /* @__PURE__ */ jsx4(SheetDescription, { className: "sr-only", children: "Application navigation menu" }),
-                expandedSidebar(sidebar)
+                /* @__PURE__ */ jsx4(SidebarDrawer, { children: expandedSidebar(sidebar) })
               ] })
             ] }),
             /* @__PURE__ */ jsx4("div", { className: "flex items-center gap-2", children: topBar })
@@ -235,10 +207,13 @@ function AppShell({ sidebar, topBar, children, className }) {
       /* @__PURE__ */ jsx4("main", { className: "flex-1 overflow-auto px-4", children })
     ] }) });
   }
-  return /* @__PURE__ */ jsx4(TooltipProvider, { children: /* @__PURE__ */ jsxs3("div", { className: cn("flex min-h-screen gap-3 bg-bg-surface p-4", className), children: [
-    /* @__PURE__ */ jsx4("div", { className: "sticky top-4 h-[calc(100vh-32px)] shrink-0", children: sidebar }),
+  return /* @__PURE__ */ jsx4(TooltipProvider, { children: /* @__PURE__ */ jsxs3("div", { className: cn("flex min-h-screen bg-bg-primary", className), children: [
+    /* @__PURE__ */ jsx4("div", { className: "sticky top-0 h-screen shrink-0 border-r border-border-subtle", children: sidebar }),
     /* @__PURE__ */ jsxs3("div", { className: "flex min-w-0 flex-1 flex-col overflow-hidden", children: [
-      topBar && /* @__PURE__ */ jsx4("div", { "data-slot": "app-shell-topbar", className: "flex h-14 shrink-0 items-center gap-2 px-6", children: topBar }),
+      topBar && /* @__PURE__ */ jsxs3(Fragment2, { children: [
+        /* @__PURE__ */ jsx4("div", { "data-slot": "app-shell-topbar", className: "flex h-14 shrink-0 items-center gap-2 px-6", children: topBar }),
+        /* @__PURE__ */ jsx4("div", { "data-slot": "app-shell-topbar-rule", className: "h-px shrink-0 bg-border-subtle" })
+      ] }),
       /* @__PURE__ */ jsx4("main", { className: "flex-1 overflow-y-auto px-6", children })
     ] })
   ] }) });

package/dist/styles-federated.css

@@ -535,8 +535,8 @@
   /* A semantic token is a whole colour with no `<alpha-value>` placeholder, so `bg-bg-secondary/50`
      compiles to nothing on Tailwind 3 while Tailwind 4 answers it with color-mix. These are the
      three alphas the kit writes, as variables the preset maps a colour name onto so both majors
-     and both consumption paths resolve them. Like --hov-bg below, the inner var() resolves at the
-     element that paints, so `.light` needs no override. Delete each the release @lessly/tokens
+     and both consumption paths resolve them. The inner var() resolves on the element `:root` and
+     `.light` both match, so `.light` needs no override. Delete each the release @lessly/tokens
      publishes its semantic colours with an `<alpha-value>` placeholder. */
   --bg-secondary-a50: color-mix(in oklab, var(--bg-secondary) 50%, transparent);
   --bg-secondary-a80: color-mix(in oklab, var(--bg-secondary) 80%, transparent);
@@ -545,8 +545,32 @@
   /* === Nav / menu surfaces (0.3.0 sidebar) === */
   /* The floating surface sits on the package's overlay pair: --menu-bg on
      --bg-overlay, --menu-shadow on --shadow-overlay. theme.css re-resolves both
-     per theme, so `.light` needs no override for either. */
-  --hov-bg: color-mix(in srgb, var(--text-primary) 7%, transparent);
+     per theme, so `.light` needs no override for either.
+
+     The pointer contrasts with whatever it lands on, and the direction flips by itself: this is a
+     wash of --text-primary, which is light ink in dark and dark ink in light, so one declaration
+     lightens on a dark ground and darkens on a light one. A wash rather than a rung because it is
+     ground-relative by construction — the same 4% reads on the page, a rail, a card, a menu and a
+     nested card alike, where every opaque step fails on at least one of them (--bg-secondary is a
+     nested card's own fill, so a hover painted with it disappears there). Measured: dark 1.099:1
+     up from the page and 1.117:1 from a card; light 1.083:1 down from the page and 1.090:1 from a
+     card (Guidelines/Look/Surface tone).
+
+     --current-bg is the plate a resting selection takes, and it is the end of the ladder the ink
+     points at: the wash above travels in the ink's direction, so the current row is the last rung
+     that way and the four states of a rail row read as one walk. Dark ink is light, so the top,
+     --bg-overlay, 1.184:1 up from the page. Light ink is dark, so the bottom, --bg-sunken,
+     1.208:1 down. Two declarations because the two ends are two different tokens, not because the
+     rule differs.
+
+     --hov-current is what the pointer paints on the row that already holds that plate, and the 4%
+     cap is why it has to exist: in dark the whole gap between the page and the plate is 1.184:1,
+     so a hover step big enough to be seen ON the plate would overshoot it on the ground. Same
+     rule, one layer up — the wash taken over --current-bg rather than over the ground, which is
+     also what carries the pointer past a rung the ladder has no successor for. */
+  --hov-bg: color-mix(in srgb, var(--text-primary) 4%, transparent);
+  --current-bg: var(--bg-overlay);
+  --hov-current: color-mix(in srgb, var(--text-primary) 4%, var(--current-bg));
   --menu-bg: var(--bg-overlay);
   --menu-shadow: var(--shadow-overlay);
   --menu-hov: var(--hov-bg);
@@ -565,11 +589,10 @@
 }
 
 :where(.light) {
-  /* Light keeps opaque hover plates: a translucent text-mix would vanish on a
-     white menu. Pinned 0.3.0-prototype literals — the package has no hover-surface
-     roles yet, so these can't move onto tokens the way --menu-bg did. */
-  --hov-bg: #ffffff;
-  --menu-hov: #f2f4f7;
+
+  /* The other end of the ladder — see --current-bg in :root above. --hov-current is declared once
+     and reads this, so the pointer's step off the plate follows without a second copy. */
+  --current-bg: var(--bg-sunken);
 
   /* Auth screen — see :root above. */
   --auth-glow-a: rgba(11, 76, 213, 0.09);
@@ -604,6 +627,19 @@
   transition-timing-function: var(--motion-easing-standard);
 }
 
+/* Backs AppSidebar's collapse: the rail's width, and the bar in the toggle's mark that crosses the
+   frame as it travels. One class on both, so the mark cannot be retuned away from the edge it
+   answers for — the same reason two carets read one `caretMotion`. `transform` is here rather than
+   in a class of its own because the bar is that edge said in miniature: retune one and the two stop
+   arriving together. A real class for the reason the two above are, and
+   token-driven because a Tailwind `duration-200` is a literal 200ms: under prefers-reduced-motion
+   the rail kept sliding for its full 200ms while every token-driven motion beside it went instant. */
+.motion-rail-collapse {
+  transition-property: width, transform;
+  transition-duration: var(--motion-duration-normal);
+  transition-timing-function: var(--motion-easing-standard);
+}
+
 /* Backs the `useFreshHighlight` hook: a freshly-created row gets a brief background wash that fades
    back to the resting surface, so the eye lands on the thing you just made. The tint is driven by
    --fresh-tint (default the amber wash — closest to GitHub's yellow flash, chosen over the

package/dist/styles.css

@@ -576,8 +576,8 @@
   /* A semantic token is a whole colour with no `<alpha-value>` placeholder, so `bg-bg-secondary/50`
      compiles to nothing on Tailwind 3 while Tailwind 4 answers it with color-mix. These are the
      three alphas the kit writes, as variables the preset maps a colour name onto so both majors
-     and both consumption paths resolve them. Like --hov-bg below, the inner var() resolves at the
-     element that paints, so `.light` needs no override. Delete each the release @lessly/tokens
+     and both consumption paths resolve them. The inner var() resolves on the element `:root` and
+     `.light` both match, so `.light` needs no override. Delete each the release @lessly/tokens
      publishes its semantic colours with an `<alpha-value>` placeholder. */
   --bg-secondary-a50: color-mix(in oklab, var(--bg-secondary) 50%, transparent);
   --bg-secondary-a80: color-mix(in oklab, var(--bg-secondary) 80%, transparent);
@@ -586,8 +586,32 @@
   /* === Nav / menu surfaces (0.3.0 sidebar) === */
   /* The floating surface sits on the package's overlay pair: --menu-bg on
      --bg-overlay, --menu-shadow on --shadow-overlay. theme.css re-resolves both
-     per theme, so `.light` needs no override for either. */
-  --hov-bg: color-mix(in srgb, var(--text-primary) 7%, transparent);
+     per theme, so `.light` needs no override for either.
+
+     The pointer contrasts with whatever it lands on, and the direction flips by itself: this is a
+     wash of --text-primary, which is light ink in dark and dark ink in light, so one declaration
+     lightens on a dark ground and darkens on a light one. A wash rather than a rung because it is
+     ground-relative by construction — the same 4% reads on the page, a rail, a card, a menu and a
+     nested card alike, where every opaque step fails on at least one of them (--bg-secondary is a
+     nested card's own fill, so a hover painted with it disappears there). Measured: dark 1.099:1
+     up from the page and 1.117:1 from a card; light 1.083:1 down from the page and 1.090:1 from a
+     card (Guidelines/Look/Surface tone).
+
+     --current-bg is the plate a resting selection takes, and it is the end of the ladder the ink
+     points at: the wash above travels in the ink's direction, so the current row is the last rung
+     that way and the four states of a rail row read as one walk. Dark ink is light, so the top,
+     --bg-overlay, 1.184:1 up from the page. Light ink is dark, so the bottom, --bg-sunken,
+     1.208:1 down. Two declarations because the two ends are two different tokens, not because the
+     rule differs.
+
+     --hov-current is what the pointer paints on the row that already holds that plate, and the 4%
+     cap is why it has to exist: in dark the whole gap between the page and the plate is 1.184:1,
+     so a hover step big enough to be seen ON the plate would overshoot it on the ground. Same
+     rule, one layer up — the wash taken over --current-bg rather than over the ground, which is
+     also what carries the pointer past a rung the ladder has no successor for. */
+  --hov-bg: color-mix(in srgb, var(--text-primary) 4%, transparent);
+  --current-bg: var(--bg-overlay);
+  --hov-current: color-mix(in srgb, var(--text-primary) 4%, var(--current-bg));
   --menu-bg: var(--bg-overlay);
   --menu-shadow: var(--shadow-overlay);
   --menu-hov: var(--hov-bg);
@@ -606,11 +630,10 @@
 }
 
 .light {
-  /* Light keeps opaque hover plates: a translucent text-mix would vanish on a
-     white menu. Pinned 0.3.0-prototype literals — the package has no hover-surface
-     roles yet, so these can't move onto tokens the way --menu-bg did. */
-  --hov-bg: #ffffff;
-  --menu-hov: #f2f4f7;
+
+  /* The other end of the ladder — see --current-bg in :root above. --hov-current is declared once
+     and reads this, so the pointer's step off the plate follows without a second copy. */
+  --current-bg: var(--bg-sunken);
 
   /* Auth screen — see :root above. */
   --auth-glow-a: rgba(11, 76, 213, 0.09);
@@ -651,6 +674,19 @@
   transition-timing-function: var(--motion-easing-standard);
 }
 
+/* Backs AppSidebar's collapse: the rail's width, and the bar in the toggle's mark that crosses the
+   frame as it travels. One class on both, so the mark cannot be retuned away from the edge it
+   answers for — the same reason two carets read one `caretMotion`. `transform` is here rather than
+   in a class of its own because the bar is that edge said in miniature: retune one and the two stop
+   arriving together. A real class for the reason the two above are, and
+   token-driven because a Tailwind `duration-200` is a literal 200ms: under prefers-reduced-motion
+   the rail kept sliding for its full 200ms while every token-driven motion beside it went instant. */
+.motion-rail-collapse {
+  transition-property: width, transform;
+  transition-duration: var(--motion-duration-normal);
+  transition-timing-function: var(--motion-easing-standard);
+}
+
 /* Backs the `useFreshHighlight` hook: a freshly-created row gets a brief background wash that fades
    back to the resting surface, so the eye lands on the thing you just made. The tint is driven by
    --fresh-tint (default the amber wash — closest to GitHub's yellow flash, chosen over the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessly/ui",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Lessly design system — shared UI primitives, tokens, and theme",
   "type": "module",
   "packageManager": "pnpm@10.30.3",
@@ -34,24 +34,25 @@
   },
   "scripts": {
     "build": "tsup && node scripts/build-styles.mjs",
-    "prepare": "pnpm build",
-    "test": "vitest run",
-    "type-check": "tsc --noEmit",
-    "lint": "eslint .",
-    "prepublishOnly": "pnpm build && pnpm test && node scripts/check-package-contract.mjs",
-    "storybook": "storybook dev -p 6006 --no-open",
+    "build-site": "pnpm build && vite build --config site/vite.config.ts",
     "build-storybook": "storybook build",
+    "build:current-emails": "tsx scripts/build-current-emails.mts",
+    "build:email-logo": "tsx scripts/build-email-logo.mts",
     "changeset": "changeset",
-    "release:version": "changeset version && node scripts/stamp-changelog-date.mjs && pnpm gen-changelog",
+    "dev-css-stale": "node scripts/dev-css-stale.mjs",
+    "dev-site": "vite --config site/vite.config.ts",
+    "gen-changelog": "node site/scripts/gen-changelog.mjs",
+    "lint": "eslint .",
+    "prepare": "pnpm build",
+    "prepublishOnly": "pnpm build && pnpm test && node scripts/check-package-contract.mjs",
     "release:publish": "node scripts/release-publish.mjs",
     "release:tag": "changeset tag",
-    "dev-site": "vite --config site/vite.config.ts",
-    "dev-css-stale": "node scripts/dev-css-stale.mjs",
-    "build-site": "pnpm build && vite build --config site/vite.config.ts",
+    "release:version": "changeset version && node scripts/stamp-changelog-date.mjs && pnpm gen-changelog",
+    "storybook": "storybook dev -p 6006 --no-open",
+    "test": "vitest run",
     "test-site": "node --test site/*.test.mjs",
     "test-site-app": "vitest run --config site/vitest.config.ts",
-    "gen-changelog": "node site/scripts/gen-changelog.mjs",
-    "build:email-logo": "tsx scripts/build-email-logo.mts"
+    "type-check": "tsc --noEmit"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",