@flamingo-stack/openframe-frontend-core 0.0.498 → 0.0.499-snapshot.20260730180712

package/src/components/navigation/app-header.tsx

@@ -50,8 +50,57 @@ export interface AppHeaderProps {
    * EXCEPT the mobile burger menu toggle, which remains interactive.
    */
   disabled?: boolean;
+  /**
+   * Draw placeholder cells instead of the live controls.
+   *
+   * Solves a problem this header cannot solve on its own: its mobile/desktop split
+   * is decided by `useMdUp()`, which answers `undefined` until an effect has run —
+   * and `?? false` turns that into "mobile". The first render is therefore always
+   * the phone header (burger + wordmark, no side actions), which on a desktop load
+   * is a visible flash before the real layout appears. It is also what a host has
+   * to show while the user and the action flags are still loading.
+   *
+   * The placeholder decides mobile vs desktop in CSS instead, so it is correct at
+   * every width on the very first paint, server-rendered included.
+   */
+  loading?: boolean;
+  /**
+   * Shape of the trailing action cells `loading` reserves.
+   *
+   * Needed because the `show*` props are usually the very thing the host is still
+   * waiting on — they are typically driven by feature flags or permissions, so during
+   * `loading` they all read `false` and the placeholder collapses to whatever is
+   * hardcoded on (often just the avatar), which looks nothing like the loaded header.
+   *
+   * Pass the cells the header settles on, in order — see `HeaderLoadingCell` for the
+   * footprints. A bare number is accepted as shorthand for all-`'icon'`.
+   *
+   * Unlike the sidebar's rows, a cell that turns out not to exist is cheap here: the
+   * cells are a right-aligned cluster in otherwise empty space, so one disappearing
+   * shifts nothing else on the page.
+   *
+   * Defaults to the shape implied by the `show*` props, which is right for a host whose
+   * header composition is known up front.
+   */
+  loadingActionCells?: number | ReadonlyArray<HeaderLoadingCell>;
 }
 
+/**
+ * A trailing header cell's footprint while loading — see `loadingActionCells`.
+ *
+ * The breakpoint-scoped members exist because several live cells are themselves
+ * responsive, and a placeholder that ignores that is wider than the header it hands
+ * off to on exactly the viewports where the cluster is tightest:
+ *
+ * - `'icon'` — a fixed 48/56px cell at every width (time tracker, notifications).
+ * - `'icon-md'` — the same cell, from md only (the avatar: `isMdUp && showUser`).
+ * - `'icon-lg'` — the same cell, from lg only (the organization filter, which the
+ *   live header renders `hidden lg:flex`).
+ * - `'wide'` — the Mingo launcher: a 48px square below md, where the live button is
+ *   `iconOnly`, and the fixed 140px labelled cell from md.
+ */
+export type HeaderLoadingCell = 'icon' | 'icon-md' | 'icon-lg' | 'wide';
+
 export const AppHeader = React.memo(function AppHeader({
   showSearch,
   onSearch,
@@ -75,9 +124,36 @@ export const AppHeader = React.memo(function AppHeader({
   isMobileMenuOpen,
   onToggleMobileMenu,
   disabled = false,
+  loading = false,
+  loadingActionCells,
 }: AppHeaderProps) {
   const isMdUp = useMdUp() ?? false;
 
+  // After the only hook above, so the hook order is identical in both branches.
+  if (loading) {
+    return (
+      <AppHeaderSkeleton
+        showSearch={showSearch}
+        actionCells={
+          loadingActionCells ??
+          // Fallback: what the `show*` props imply, in the order the live cells are
+          // mounted below. Only correct for a host that knows its header composition
+          // before it starts loading. The cell types carry each control's own
+          // breakpoint — the organization filter is `hidden lg:flex`, the avatar is
+          // gated on `isMdUp`, and Mingo is `iconOnly` below md.
+          ([
+            showOrganizations && 'icon-lg',
+            showTimeTracker && 'icon',
+            showNotifications && 'icon',
+            showUser && 'icon-md',
+            showMingoAI && 'wide',
+          ].filter(Boolean) as HeaderLoadingCell[])
+        }
+        className={className}
+      />
+    );
+  }
+
   const dimmedClass = disabled ? 'pointer-events-none opacity-50' : '';
   // Cells carry their own dividers in the unified TopNavigation model
   // (the shell no longer applies divide-x).
@@ -268,3 +344,105 @@ function NotificationsHeaderButton({ fallbackUnreadCount, disabled, dimmedClass
 }
 
 export default AppHeader;
+
+// Literal class strings — Tailwind's scanner needs to see them spelled out.
+const CELL_VISIBILITY: Record<Exclude<HeaderLoadingCell, 'wide'>, string | undefined> = {
+  icon: undefined,
+  'icon-md': 'hidden md:flex',
+  'icon-lg': 'hidden lg:flex',
+};
+
+/** One trailing action cell placeholder — mirrors the live cells' 48/56px box. */
+function HeaderCellSkeleton({ className }: { className?: string }) {
+  return (
+    <div
+      className={cn(
+        'flex h-full w-12 shrink-0 items-center justify-center border-l border-ods-border md:w-14',
+        className,
+      )}
+    >
+      <div className="h-4 w-4 animate-pulse rounded bg-ods-border md:h-6 md:w-6" />
+    </div>
+  );
+}
+
+/**
+ * Wide cell placeholder — mirrors `HeaderMingoButton` at both widths, which are
+ * two different shapes: the live button gets `iconOnly={!isMdUp}`, so below md it
+ * drops its wordmark and collapses to the same 48px square as any other cell, and
+ * from md it is the fixed 140px labelled cell. Reserving 140px-worth of icon,
+ * label, gap and padding on a phone would make the placeholder cluster ~70px
+ * wider than the header it hands off to.
+ */
+function HeaderWideCellSkeleton() {
+  return (
+    <div className="flex h-full w-12 shrink-0 items-center justify-center gap-2 border-l border-ods-border md:w-[140px] md:px-4">
+      <div className="h-4 w-4 shrink-0 animate-pulse rounded bg-ods-border md:h-6 md:w-6" />
+      <div className="hidden h-5 animate-pulse rounded bg-ods-border md:block md:w-[72px]" />
+    </div>
+  );
+}
+
+/**
+ * `AppHeader`'s loading state — see `AppHeaderProps.loading`.
+ *
+ * Keep in sync with `AppHeader` above; a diverging placeholder makes the handoff
+ * jump. Every breakpoint decision here is a Tailwind variant on purpose: this is the
+ * one thing the live header cannot do (its split runs through `useMdUp()`), and it
+ * is the whole reason this branch exists.
+ */
+function AppHeaderSkeleton({
+  showSearch,
+  actionCells,
+  className,
+}: {
+  showSearch?: boolean;
+  actionCells: number | ReadonlyArray<HeaderLoadingCell>;
+  className?: string;
+}) {
+  const cells: ReadonlyArray<HeaderLoadingCell> =
+    typeof actionCells === 'number'
+      ? Array.from({ length: Math.max(0, actionCells) }, () => 'icon' as const)
+      : actionCells;
+  return (
+    <TopNavigation
+      className={cn('sticky top-0 z-40', className)}
+      centerBreakpoint="md"
+      aria-busy="true"
+      leading={
+        // Burger cell: mobile only, in CSS.
+        <div className="flex h-full w-12 shrink-0 items-center justify-center border-r border-ods-border md:hidden">
+          <div className="h-4 w-4 animate-pulse rounded bg-ods-border" />
+        </div>
+      }
+      logo={
+        <>
+          <div className="h-6 w-6 shrink-0 animate-pulse rounded bg-ods-border" />
+          <div className="h-4 w-24 animate-pulse rounded bg-ods-border" />
+        </>
+      }
+      // `md:hidden` belongs on the WRAPPER, not the placeholder inside it:
+      // `TopNavigation` builds its padded logo zone whenever `logo` is truthy, and
+      // that padding runs to 24px at md and 80px at lg. The live header passes
+      // `false` here from md up, so the zone does not exist at all — leaving the
+      // wrapper visible would inset the search field by 80px on desktop and shift
+      // it back on handoff, which is the exact jump this branch removes.
+      logoClassName="gap-2 md:hidden"
+      // `TopNavigation` already hides the center zone below `centerBreakpoint`.
+      center={showSearch ? <div className="h-10 w-full animate-pulse rounded-md bg-ods-border" /> : undefined}
+      sideActions={
+        <>
+          {/* Mobile-only search trigger; from md the search lives in the center zone. */}
+          {showSearch && <HeaderCellSkeleton className="md:hidden" />}
+          {cells.map((cell, i) =>
+            cell === 'wide' ? (
+              <HeaderWideCellSkeleton key={i} />
+            ) : (
+              <HeaderCellSkeleton key={i} className={CELL_VISIBILITY[cell]} />
+            ),
+          )}
+        </>
+      }
+    />
+  );
+}

package/src/components/navigation/header-mingo-button.tsx

@@ -39,6 +39,11 @@ export function HeaderMingoButton({
       aria-pressed={isActive}
       className={cn(
         'flex items-center shrink-0 h-full gap-2 px-4',
+        // Fixed 140px cell from md, so the header's right-hand cluster has a
+        // known width and a loading placeholder can reserve it exactly
+        // (`AppHeaderProps.loadingActionCells` → `'wide'`). Content-width below
+        // md, and in `iconOnly` mode, where the control is a square affordance.
+        !iconOnly && 'md:w-[140px] md:justify-center',
         'transition-colors duration-200',
         'focus:outline-none focus-visible:ring-2 focus-visible:ring-ods-accent',
         // Transparent at rest so the cell inherits the bar's background

package/src/components/navigation/index.ts

@@ -22,11 +22,11 @@ export type { SlidingSidebarProps } from './sliding-sidebar'
 export { StickySectionNav, useSectionNavigation } from './sticky-section-nav'
 export type { StickyNavSection } from './sticky-section-nav'
 
-export { NavigationSidebar } from './navigation-sidebar'
+export { NAVIGATION_SIDEBAR_WIDTH_VAR, NavigationSidebar } from './navigation-sidebar'
 export type { NavigationSidebarProps } from './navigation-sidebar'
 
 export { AppHeader } from './app-header'
-export type { AppHeaderProps } from './app-header'
+export type { AppHeaderProps, HeaderLoadingCell } from './app-header'
 
 export { AppLayout, useAppLayoutDrawerContainer } from './app-layout'
 export type { AppLayoutProps } from './app-layout'

package/src/components/navigation/navigation-sidebar-item.tsx

@@ -130,3 +130,25 @@ export const NavigationSidebarItemButton = memo(function NavigationSidebarItemBu
     </Link>
   )
 })
+
+/**
+ * One placeholder entry, for `NavigationSidebarConfig.loading`.
+ *
+ * Deliberately in this file, beside `NavigationSidebarItemButton`: the two must
+ * agree on `h-14`, the `p-[var(--spacing-system-m)]` inset, the 24px icon box and
+ * the label column, or the nav resizes on the handoff. Same reason
+ * `header-skeleton.tsx` sits beside `header.tsx`.
+ *
+ * `showLabel` is the sidebar's own minimized state, so the caller passes what it
+ * already passes the real row — no separate width handling.
+ */
+export function NavigationSidebarItemSkeleton({ showLabel }: { showLabel: boolean }) {
+  return (
+    <div className="w-full flex items-center justify-start h-14 p-[var(--spacing-system-m)]" aria-hidden="true">
+      <div className="relative flex items-center justify-center flex-shrink-0">
+        <div className="h-6 w-6 animate-pulse rounded bg-ods-border" />
+      </div>
+      {showLabel && <div className="h-4 flex-1 ml-[var(--spacing-system-xs)] animate-pulse rounded bg-ods-border" />}
+    </div>
+  )
+}

package/src/components/navigation/navigation-sidebar-toggle.tsx

@@ -30,12 +30,16 @@ export function NavigationSidebarToggle({
         aria-label={"Hide Menu"}
       >
         <div className="flex items-center justify-center flex-shrink-0">
-          <Chevrons03LeftIcon
-            className={cn(
-              "text-ods-text-secondary w-6 h-6 transition-transform duration-300",
-              minimized && "rotate-180",
-            )}
-          />
+          {/* Direction follows the rail's measured width (the `of-nav-sidebar`
+              container declared in `navigation-sidebar.tsx`), not `minimized`:
+              before hydration that prop can only carry the server's answer, and
+              a chevron pointing the wrong way in a 56px rail is the one piece of
+              sidebar state a user actually notices arriving late.
+
+              Collapsed is the default because container queries are min-width —
+              the rail is narrower than every threshold, so it needs no query of
+              its own. */}
+          <Chevrons03LeftIcon className="rotate-180 @[140px]/of-nav-sidebar:rotate-0 text-ods-text-secondary w-6 h-6 transition-transform duration-300" />
         </div>
 
         <span

package/src/components/navigation/navigation-sidebar.tsx

@@ -1,18 +1,115 @@
 "use client"
 
-import { useCallback, useEffect, useLayoutEffect, useMemo, useState } from 'react'
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { useIsomorphicLayoutEffect } from '../../hooks/ui/use-isomorphic-layout-effect'
 import { useLocalStorage } from '../../hooks/ui/use-local-storage'
 import { useLgUp, useMdUp } from '../../hooks/ui/use-media-query'
 import { NavigationSidebarConfig, NavigationSidebarItem } from '../../types/navigation'
 import { cn } from '../../utils'
 import { NavigationSidebarHeader } from './navigation-sidebar-header'
-import { NavigationSidebarItemButton } from './navigation-sidebar-item'
+import { NavigationSidebarItemButton, NavigationSidebarItemSkeleton } from './navigation-sidebar-item'
 import { NavigationSidebarToggle } from './navigation-sidebar-toggle'
 
 const MINIMIZED_WIDTH = 56 // 3.5rem = 56px
 const EXPANDED_WIDTH = 224 // 14rem = 224px
 const STORAGE_KEY = 'of.navigationSidebar.minimized'
 
+/**
+ * The desktop width, as a custom property on `:root`. Read by the `lg:` rule in
+ * {@link SIDEBAR_GEOMETRY_CLASSES} and written by this component whenever the
+ * user toggles — but NEVER during render.
+ *
+ * It has to be a global variable rather than an inline style because of WHEN the
+ * value is knowable. The width follows a preference in `localStorage`, which the
+ * server cannot read: any markup derived from it differs between the server's
+ * HTML and the client's hydration render, and React tears the tree down and
+ * regenerates it. Seeding this property from a tiny script in `<head>` moves the
+ * preference OUT of React's rendered output — the markup becomes identical on
+ * both sides, while the width is already correct on the very first paint.
+ *
+ * Consumers are expected to seed it before first paint; unseeded, the fallback
+ * in the class below paints the expanded width until this component's effect
+ * catches up, which is the flash the seed exists to remove.
+ */
+export const NAVIGATION_SIDEBAR_WIDTH_VAR = '--of-navigation-sidebar-width'
+
+/**
+ * The rail as a query container, so the parts of the sidebar that follow its
+ * collapsed state can read that state off the rail's own width — currently the
+ * collapse chevron's direction, in `navigation-sidebar-toggle.tsx`.
+ *
+ * There is no second source of truth for "is it collapsed", and that is the
+ * point: the width already has to be correct on the first paint and at every
+ * breakpoint, so anything derived from it is too — the seeded desktop
+ * preference, the tablet rail and an overlay opened on tablet all come along for
+ * free. A parallel copy would have to be kept in step with each of the three
+ * separately, and the custom property that used to live here fell out of step on
+ * the last one: it could not see the tablet rail, so that case got its own media
+ * query, which in turn could not see an open overlay and pointed the chevron
+ * backwards under it.
+ *
+ * Queried as `@[140px]/of-nav-sidebar:` — 140px is the midpoint between the 56px
+ * rail and the 224px expanded sidebar, so the width only crosses it mid-toggle.
+ * Container queries are min-width, so a follower styles its COLLAPSED look as the
+ * default and lets the query take it back. Written out literally at each use
+ * rather than interpolated from a constant: Tailwind scans source text, and a
+ * class it cannot see spelled out is a class it never generates.
+ */
+const SIDEBAR_CONTAINER = '@container/of-nav-sidebar'
+
+/**
+ * Where the sidebar sits and how wide it is, per breakpoint — as literal classes,
+ * because this cannot be decided in JavaScript in time.
+ *
+ * `useMdUp`/`useLgUp` answer `undefined` until an effect has run, so `isTablet`
+ * is false on the first render — the SERVER's render included. A tablet
+ * therefore received the desktop branch in its HTML (`relative`, `width:224px`,
+ * an inline style no class could outrank) and only snapped to the 56px rail once
+ * hydration and an effect had both completed. That is the wide sidebar that
+ * flashed on every load, and no amount of JS could fix it: the server has no
+ * viewport to consult, so the answer has to be deferred to the one consumer that
+ * always knows — the browser's own media evaluation.
+ *
+ * The state that a viewport CANNOT determine still lives outside the render: the
+ * persisted desktop preference reaches the `lg:` rule through
+ * {@link NAVIGATION_SIDEBAR_WIDTH_VAR}. An inline width would be simpler than a
+ * custom property, but it would also override the tablet rail on the very first
+ * paint, which is the bug being fixed.
+ *
+ * The tablet WIDTH is deliberately not here — see {@link SIDEBAR_TABLET_WIDTH}.
+ *
+ * Widths are `w-14`/`w-56` — the class equivalents of `MINIMIZED_WIDTH` and
+ * `EXPANDED_WIDTH`, as is the `14rem` fallback below. Keep them in step; a class
+ * string cannot interpolate a constant.
+ */
+const SIDEBAR_GEOMETRY_CLASSES = [
+  // Tablet: float over the content, anchored to the layout row (`absolute`
+  // within AppLayout's `relative` row) — NOT the viewport — so an optional
+  // `topBar` above the row is not overlapped. With no topBar the row spans the
+  // full viewport, so this is visually identical to a viewport-fixed sidebar.
+  'md:absolute md:inset-y-0 md:left-0 md:z-[45]',
+  // Desktop: back in the flex flow, width from the persisted preference. The
+  // fallback IS the default, so the property needs no global declaration and an
+  // unseeded consumer gets the full sidebar rather than a rail with no labels.
+  'lg:relative lg:inset-auto lg:z-auto lg:h-full lg:w-[var(--of-navigation-sidebar-width,14rem)]',
+].join(' ')
+
+/**
+ * The tablet width, as ONE `md:` class rather than a rail plus an override.
+ *
+ * Tablet is a 56px rail by design and only widens for an overlay the user has
+ * opened — state no viewport can imply, so it has to come from JS. Written as
+ * `md:w-14` + `max-lg:w-56` the two rules both match between md and lg at equal
+ * specificity, and Tailwind emits the `max-lg` block BEFORE the `md` one, so
+ * source order hands the tablet straight back to the rail. Picking one class
+ * removes the contest instead of trying to win it — and keeps the `!important`
+ * that winning it would need out of the tree.
+ *
+ * `lg:` still governs desktop either way: it is emitted after `md:`, so an
+ * overlay left open while the window widens does not leak into the desktop width.
+ */
+const SIDEBAR_TABLET_WIDTH = { rail: 'md:w-14', overlay: 'md:w-56' } as const
+
 /** A click the browser will resolve itself — new tab, new window, middle button. */
 const isModifiedClick = (event?: React.MouseEvent): boolean =>
   !!event && (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || event.button !== 0)
@@ -47,7 +144,22 @@ export function NavigationSidebar({ config, disabled = false }: NavigationSideba
     if (isTablet) setTabletMinimized(true)
   }, [isTablet])
 
-  const minimized = isTablet ? tabletMinimized : desktopMinimized
+  // `useLocalStorage` reads the store SYNCHRONOUSLY in its initializer, so on the
+  // hydration render it already knows a preference the server could not. Anything
+  // derived from it — labels, `aria-hidden`, the chevron, the placeholder rows —
+  // then differs from the server's HTML, and React throws out the whole tree and
+  // regenerates it. So until hydration is done, this renders the server's answer
+  // and nothing else.
+  //
+  // That costs nothing visually. The width is already correct at that point (it
+  // comes from the seeded CSS var, not from here), and at the minimized width
+  // every label is a `flex-1` in a rail with no room to give — zero-wide whatever
+  // this says. What flips on the next commit is opacity and margin on boxes that
+  // were never visible.
+  const [hydrated, setHydrated] = useState(false)
+  useEffect(() => setHydrated(true), [])
+
+  const minimized = hydrated ? (isTablet ? tabletMinimized : desktopMinimized) : (config.minimized ?? false)
 
   // Enable transitions only after the correct width is painted
   const [transitionsEnabled, setTransitionsEnabled] = useState(false)
@@ -147,11 +259,35 @@ export function NavigationSidebar({ config, disabled = false }: NavigationSideba
     secondaryItems: config.items.filter(item => item.section === 'secondary'),
   }), [config.items])
 
+  // Placeholder rows while the host cannot know its entries yet — see
+  // `NavigationSidebarConfig.loading`. Only the ROWS are stood in for: the header,
+  // the collapse toggle, the widths and the tablet overlay all behave exactly as
+  // when loaded, so this is the loaded rail with unknown contents rather than a
+  // separate skeleton sidebar to keep in sync.
+  const loadingRows = useMemo(() => {
+    if (!config.loading) return null
+    const primary = config.loadingRows?.primary ?? 7
+    const secondary = config.loadingRows?.secondary ?? 2
+    return {
+      primary: Array.from({ length: Math.max(0, primary) }, (_, i) => `primary-${i}`),
+      secondary: Array.from({ length: Math.max(0, secondary) }, (_, i) => `secondary-${i}`),
+    }
+  }, [config.loading, config.loadingRows?.primary, config.loadingRows?.secondary])
+
   const sidebarWidth = useMemo(
     () => (minimized ? `${MINIMIZED_WIDTH}px` : `${EXPANDED_WIDTH}px`),
     [minimized],
   )
 
+  // Published to CSS from an EFFECT, never from render. Before hydration the
+  // width belongs to whatever seeded `NAVIGATION_SIDEBAR_WIDTH_VAR` in `<head>`
+  // — put it in the markup instead and it becomes part of what React hydrates,
+  // which is precisely what cannot agree across the server boundary. Afterwards
+  // this is what a toggle moves.
+  useIsomorphicLayoutEffect(() => {
+    document.documentElement.style.setProperty(NAVIGATION_SIDEBAR_WIDTH_VAR, sidebarWidth)
+  }, [sidebarWidth])
+
   // There used to be an `isHydrated` gate here — `isMdUp !== undefined && ...`
   // — meant to hold the sidebar's contents back until the media queries
   // resolved. It could never be false: the `?? false` above had already
@@ -159,7 +295,7 @@ export function NavigationSidebar({ config, disabled = false }: NavigationSideba
   // because repairing it would be the regression: the contents are server-
   // rendered today, and gating them behind a client-only media query would
   // trade a first paint of the real navigation for an empty rail.
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     if (!transitionsEnabled) {
       const id = requestAnimationFrame(() => {
         setTransitionsEnabled(true)
@@ -183,61 +319,68 @@ export function NavigationSidebar({ config, disabled = false }: NavigationSideba
       />
 
       {/* Flex-flow placeholder — reserves the collapsed 56px slot on tablet so
-          the main content keeps its position while the sidebar floats above it */}
-      {isTablet && (
-        <div
-          className="h-full hidden md:block flex-shrink-0"
-          style={{ width: `${MINIMIZED_WIDTH}px` }}
-          aria-hidden="true"
-        />
-      )}
+          the main content keeps its position while the sidebar floats above it.
+          Rendered unconditionally and scoped by classes for the same reason the
+          geometry is: gated on `isTablet`, it was missing from the server HTML
+          and from the first client paint — exactly when the sidebar it
+          compensates for has already gone `absolute`. */}
+      <div className="h-full hidden md:block lg:hidden w-14 flex-shrink-0" aria-hidden="true" />
 
       <aside
         className={cn(
+          SIDEBAR_CONTAINER,
           "flex-col hidden md:flex flex-shrink-0",
           "bg-ods-card border-r border-ods-border",
-          // Tablet: float the sidebar over content. Anchored to the layout row
-          // (`absolute` within AppLayout's `relative` row) — NOT the viewport —
-          // so an optional `topBar` above the row is not overlapped. With no
-          // topBar the row spans the full viewport, so this is visually
-          // identical to a viewport-fixed sidebar.
-          isTablet ? "absolute inset-y-0 left-0 z-[45]" : "relative h-full",
+          SIDEBAR_GEOMETRY_CLASSES,
+          // The one width a viewport cannot imply: an overlay the user opened on
+          // tablet. Only ever true after a click, so the first paint always gets
+          // the rail.
+          isOverlayOpen ? SIDEBAR_TABLET_WIDTH.overlay : SIDEBAR_TABLET_WIDTH.rail,
           transitionsEnabled && "transition-[width] duration-300",
           config.className,
         )}
-        style={{ width: sidebarWidth }}
         aria-label="Main navigation sidebar"
       >
         <NavigationSidebarHeader minimized={minimized} />
 
         <div className="flex-1 flex flex-col justify-between py-4 overflow-y-auto">
-          <nav className="flex flex-col" aria-label="Primary navigation">
-            {primaryItems.map(item => (
-              <NavigationSidebarItemButton
-                key={item.id}
-                item={item}
-                isActive={item.id === committedActiveId}
-                isPending={item.id === pendingItemId}
-                showLabel={showLabel}
-                disabled={disabled}
-                onClick={handleItemClick}
-              />
-            ))}
+          {/* `aria-busy` on the nav, not the rows: the region is what is loading,
+              and each placeholder row is already `aria-hidden`. */}
+          <nav className="flex flex-col" aria-label="Primary navigation" aria-busy={!!loadingRows}>
+            {loadingRows
+              ? loadingRows.primary.map(key => (
+                  <NavigationSidebarItemSkeleton key={key} showLabel={showLabel} />
+                ))
+              : primaryItems.map(item => (
+                  <NavigationSidebarItemButton
+                    key={item.id}
+                    item={item}
+                    isActive={item.id === committedActiveId}
+                    isPending={item.id === pendingItemId}
+                    showLabel={showLabel}
+                    disabled={disabled}
+                    onClick={handleItemClick}
+                  />
+                ))}
           </nav>
 
-          {secondaryItems.length > 0 && (
-            <nav className="flex flex-col" aria-label="Secondary navigation">
-              {secondaryItems.map(item => (
-                <NavigationSidebarItemButton
-                  key={item.id}
-                  item={item}
-                  isActive={item.id === committedActiveId}
-                isPending={item.id === pendingItemId}
-                  showLabel={showLabel}
-                  disabled={disabled}
-                  onClick={handleItemClick}
-                />
-              ))}
+          {(loadingRows ? loadingRows.secondary.length > 0 : secondaryItems.length > 0) && (
+            <nav className="flex flex-col" aria-label="Secondary navigation" aria-busy={!!loadingRows}>
+              {loadingRows
+                ? loadingRows.secondary.map(key => (
+                    <NavigationSidebarItemSkeleton key={key} showLabel={showLabel} />
+                  ))
+                : secondaryItems.map(item => (
+                    <NavigationSidebarItemButton
+                      key={item.id}
+                      item={item}
+                      isActive={item.id === committedActiveId}
+                      isPending={item.id === pendingItemId}
+                      showLabel={showLabel}
+                      disabled={disabled}
+                      onClick={handleItemClick}
+                    />
+                  ))}
             </nav>
           )}
         </div>

package/src/components/ui/button/button-styles.ts

@@ -32,6 +32,17 @@ export const buttonSurfaceClasses = {
 export const outlineBorderClasses =
   "border border-ods-border hover:border-ods-border-hover active:border-ods-border-active disabled:border-ods-border aria-disabled:border-ods-border"
 
+// Glyph scale for the split-layout button family: 16px below md, 24px from md.
+//
+// Shared because the same page-header action renders through EITHER of the two
+// split layouts depending on its shape — `SplitButton` for two click targets, and
+// `Button` + `splitIcon` for one with a decorative trailing glyph — and the two sit
+// side by side in the same row. They used to disagree: `SplitButton` carried this
+// responsive scale while the `Button` split slots re-declared a flat 20px, so a
+// "submenu" action's icons rendered 4px smaller than its neighbour's on desktop.
+// `Button`'s own flat `[&_svg]:h-5` stays as it is for ordinary (non-split) buttons.
+export const splitGlyphSizeClasses = "[&_svg]:h-4 [&_svg]:w-4 md:[&_svg]:h-6 md:[&_svg]:w-6"
+
 // Color of the vertical seam between the main and icon halves (split layouts).
 export const splitDividerColorClasses = {
   accent: "border-ods-accent-active",

package/src/components/ui/button/button.tsx

@@ -6,7 +6,7 @@ import Link from "../../../embed-shims/next-link"
 import React from "react"
 
 import { cn } from "../../../utils/cn"
-import { buttonSurfaceClasses, outlineBorderClasses, splitDividerColorClasses } from "./button-styles"
+import { buttonSurfaceClasses, outlineBorderClasses, splitDividerColorClasses, splitGlyphSizeClasses } from "./button-styles"
 
 // Default layout: centered single content area, padding/gap on the button itself.
 const buttonVariants = cva(
@@ -104,14 +104,17 @@ const splitShellVariants = cva(
 )
 
 const splitSlotVariants = cva(
-  ["inline-flex items-center justify-center", "[&_svg]:shrink-0 [&_svg]:h-5 [&_svg]:w-5"],
+  // Glyph size lives per-size, not in the base: cva concatenates base + variant
+  // without tailwind-merge, so a base `[&_svg]:h-5` and a variant `[&_svg]:h-4`
+  // would both ship and the winner would come down to stylesheet order.
+  ["inline-flex items-center justify-center", "[&_svg]:shrink-0"],
   {
     variants: {
       slot: {
         main: "gap-[var(--spacing-system-xsf)]",
         icon: "border-l",
       },
-      size: { default: "", small: "[&_svg]:h-4 [&_svg]:w-4" },
+      size: { default: splitGlyphSizeClasses, small: "[&_svg]:h-4 [&_svg]:w-4" },
       variant: { accent: "", outline: "", transparent: "", destructive: "", warning: "" },
     },
     compoundVariants: [

package/src/components/ui/button/split-button.tsx

@@ -5,7 +5,7 @@ import Link from "../../../embed-shims/next-link"
 import React from "react"
 
 import { cn } from "../../../utils/cn"
-import { buttonSurfaceClasses, splitDividerColorClasses } from "./button-styles"
+import { buttonSurfaceClasses, splitDividerColorClasses, splitGlyphSizeClasses } from "./button-styles"
 
 // Two independent interactive halves: each a `<button>` or `<a>`. The seam is
 // a 1px border on the left edge of the icon half, colored per variant. For a
@@ -29,7 +29,7 @@ const splitHalfVariants = cva(splitHalfBase, {
       warning: buttonSurfaceClasses.warning,
     },
     size: {
-      default: "h-10 md:h-12 px-[var(--spacing-system-m)] py-[var(--spacing-system-sf)] text-h3 [&_svg]:h-4 [&_svg]:w-4 md:[&_svg]:h-6 md:[&_svg]:w-6",
+      default: `h-10 md:h-12 px-[var(--spacing-system-m)] py-[var(--spacing-system-sf)] text-h3 ${splitGlyphSizeClasses}`,
       small: "h-6 md:h-8 px-[var(--spacing-system-xs)] text-h5 [&_svg]:h-3 [&_svg]:w-3 md:[&_svg]:h-4 md:[&_svg]:w-4",
     },
     side: { main: "", icon: "" },