@usefragments/ui 1.6.0 → 2.0.0

package/src/components/Header/Header.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Header",
-  "description": "Composable header with slots for brand, navigation, search, and actions. Supports dropdown nav groups via Header.NavMenu. Designed for use within AppShell with responsive mobile support.",
-  "category": "navigation",
-  "tags": [
-    "header",
-    "navigation",
-    "navbar",
-    "brand",
-    "layout",
-    "dropdown"
-  ],
+  "description": "Composes brand, navigation, search, and actions into one responsive app bar.",
+  "category": "layout",
+  "tags": ["header", "navigation", "navbar", "brand", "layout", "dropdown"],
   "status": "stable",
   "sourcePath": "src/components/Header/index.tsx",
   "exportName": "Header",
@@ -41,11 +34,7 @@
       "description": "Position behavior (usually controlled by AppShell)",
       "default": "static",
       "required": false,
-      "values": [
-        "static",
-        "fixed",
-        "sticky"
-      ]
+      "values": ["static", "fixed", "sticky"]
     },
     "elevatedOnScroll": {
       "type": "boolean|object",
@@ -80,37 +69,22 @@
   },
   "usage": {
     "when": [
-      "Primary site or app header inside AppShell",
-      "Navigation bar with branding (default layout)",
-      "Search and actions bar (sidebar layout)",
-      "Header with responsive mobile menu trigger",
-      "Grouping related nav items under a dropdown menu"
+      "Top-level navigation for an app or site",
+      "Inside AppShell.Header",
+      "Anywhere brand, nav, and actions share one row"
     ],
     "whenNot": [
-      "Simple page titles (use heading elements)",
-      "Footer navigation (use Footer component)",
-      "Standalone sidebar navigation (use Sidebar directly)"
+      "Section headings inside a page (use a heading)",
+      "Toolbars scoped to one panel (use Toolbar)",
+      "Sidebar-only navigation (use Sidebar)"
     ],
     "guidelines": [
-      "Use Header.SkipLink for accessibility (skip to main content)",
-      "In default layout: include Header.Brand for logo",
-      "In sidebar layout: omit Header.Brand (logo in sidebar)",
-      "Header.Trigger integrates with SidebarProvider for mobile menus",
-      "Header.Trigger composes your onClick handler with sidebar toggle behavior",
-      "Header.Nav is hidden on mobile; use sidebar for mobile navigation",
-      "Use Header.Spacer to push items apart",
-      "Use Header.NavMenu to group related nav items under a dropdown",
-      "Use Header.NavMenuItem inside Header.NavMenu for dropdown items",
-      "Header sub-components forward DOM props (id, aria-*, data-*, handlers) to their rendered elements",
-      "Header.Brand asChild composes custom link components while preserving canonical brand styling",
-      "Header.NavItem asChild composes click handlers instead of overwriting the child handler",
-      "Use elevatedOnScroll on sticky marketing headers that need a boundary after scrolling",
-      "Use navAlign=\"center\" when navigation must stay centered independently of brand and actions",
-      "Use container=\"page\" when the header should share a bounded page gutter",
-      "Use Header.MobileNavActions for the primary action row inside Header.MobileNav",
-      "Use the Header icons prop to replace internal mobile trigger and dropdown chevron icons with any icon package",
-      "For rich dropdown content (titles, descriptions, icons), use NavigationMenu instead of Header.Nav",
-      "NavigationMenu also provides an automatic mobile drawer, replacing Header.Trigger + Sidebar for mobile nav"
+      "Header.Spacer pushes the actions cluster to the right",
+      "Omit Header.Brand when the sidebar already shows the logo",
+      "container=\"page\" caps the content at page width for marketing bars",
+      "elevatedOnScroll adds a bottom border once the page scrolls",
+      "Pair Header.Trigger with Header.MobileNav for small screens",
+      "Header.SkipLink should be the first child"
     ],
     "accessibility": [
       "Include Header.SkipLink for keyboard users",
@@ -123,43 +97,38 @@
   "examples": [
     {
       "name": "For Default Layout",
-      "description": "Header with brand, nav, and actions. Use with AppShell layout=\"default\".",
-      "code": "<ThemeProvider defaultMode=\"light\">\n  <Header>\n    <Header.SkipLink />\n    <Header.Trigger />\n    <Header.Brand href=\"/\">MyApp</Header.Brand>\n    <Header.Nav>\n      <Header.NavItem href=\"/dashboard\" active>Dashboard</Header.NavItem>\n      <Header.NavItem href=\"/projects\">Projects</Header.NavItem>\n      <Header.NavItem href=\"/settings\">Settings</Header.NavItem>\n    </Header.Nav>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n      <Button variant=\"secondary\" size=\"sm\">Sign In</Button>\n    </Header.Actions>\n  </Header>\n</ThemeProvider>"
+      "description": "Brand, nav, and actions for AppShell layout=\"default\".",
+      "code": "import { Box } from '@/components/Box';\nimport { Button } from '@/components/Button';\nimport { Header } from '@/components/Header';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box width=\"100%\" border rounded=\"md\" overflow=\"hidden\">\n  <Header>\n    <Header.SkipLink />\n    <Header.Trigger />\n    <Header.Brand href=\"/\">MyApp</Header.Brand>\n    <Header.Nav>\n      <Header.NavItem href=\"/dashboard\" active>Dashboard</Header.NavItem>\n      <Header.NavItem href=\"/projects\">Projects</Header.NavItem>\n      <Header.NavItem href=\"/settings\">Settings</Header.NavItem>\n    </Header.Nav>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n      <Button variant=\"soft\" size=\"sm\">Sign In</Button>\n    </Header.Actions>\n  </Header>\n</Box>"
     },
     {
       "name": "Marketing Header",
-      "description": "Sticky, page-width marketing header with centered navigation, scroll elevation, custom link composition, and mobile actions.",
-      "code": "<Header position=\"sticky\" elevatedOnScroll navAlign=\"center\" container=\"page\">\n  <Header.SkipLink href=\"#main-content\" />\n  <Header.Brand asChild>\n    <a href=\"/\" aria-label=\"Home\">Logo</a>\n  </Header.Brand>\n  <Header.Nav aria-label=\"Main navigation\">\n    <Header.NavItem href=\"/docs\">Docs</Header.NavItem>\n  </Header.Nav>\n  <Header.Actions>\n    <Button size=\"sm\">Start free</Button>\n  </Header.Actions>\n  <Header.Trigger />\n  <Header.MobileNav>\n    <Header.MobileNavLink href=\"/docs\">Docs</Header.MobileNavLink>\n    <Header.MobileNavActions>\n      <Button size=\"sm\">Start free</Button>\n    </Header.MobileNavActions>\n  </Header.MobileNav>\n</Header>"
+      "description": "Sticky page-width bar that gains a border on scroll, with a mobile drawer.",
+      "code": "import { Box } from '@/components/Box';\nimport { Button } from '@/components/Button';\nimport { Header } from '@/components/Header';\n\n<Box width=\"100%\" border rounded=\"md\" overflow=\"hidden\">\n  <Header position=\"sticky\" elevatedOnScroll navAlign=\"center\" container=\"page\">\n    <Header.SkipLink href=\"#main-content\" />\n    <Header.Brand asChild>\n      <a href=\"/\" aria-label=\"Home\">Logo</a>\n    </Header.Brand>\n    <Header.Nav aria-label=\"Main navigation\">\n      <Header.NavItem href=\"/docs\">Docs</Header.NavItem>\n      <Header.NavItem href=\"/pricing\">Pricing</Header.NavItem>\n    </Header.Nav>\n    <Header.Actions>\n      <Button size=\"sm\">Start free</Button>\n    </Header.Actions>\n    <Header.Trigger />\n    <Header.MobileNav>\n      <Header.MobileNavLink href=\"/docs\">Docs</Header.MobileNavLink>\n      <Header.MobileNavLink href=\"/pricing\">Pricing</Header.MobileNavLink>\n      <Header.MobileNavActions>\n        <Button size=\"sm\">Start free</Button>\n      </Header.MobileNavActions>\n    </Header.MobileNav>\n  </Header>\n</Box>"
     },
     {
       "name": "With Dropdown Nav",
-      "description": "Header with a dropdown menu grouping related navigation links.",
-      "code": "<ThemeProvider defaultMode=\"light\">\n  <Header>\n    <Header.Brand href=\"/\">MyApp</Header.Brand>\n    <Header.Nav>\n      <Header.NavItem href=\"/components\" active>Components</Header.NavItem>\n      <Header.NavItem href=\"/blocks\">Blocks</Header.NavItem>\n      <Header.NavMenu label=\"Docs\">\n        <Header.NavMenuItem href=\"/getting-started\">Getting Started</Header.NavMenuItem>\n        <Header.NavMenuItem href=\"/cli\">CLI Reference</Header.NavMenuItem>\n        <Header.NavMenuItem href=\"/mcp\">MCP Tools</Header.NavMenuItem>\n      </Header.NavMenu>\n      <Header.NavItem href=\"/blog\">Blog</Header.NavItem>\n    </Header.Nav>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n    </Header.Actions>\n  </Header>\n</ThemeProvider>"
+      "description": "Header.NavMenu groups related links behind one trigger.",
+      "code": "import { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box width=\"100%\" border rounded=\"md\" overflow=\"hidden\">\n  <Header>\n    <Header.Brand href=\"/\">MyApp</Header.Brand>\n    <Header.Nav>\n      <Header.NavItem href=\"/components\" active>Components</Header.NavItem>\n      <Header.NavItem href=\"/blocks\">Blocks</Header.NavItem>\n      <Header.NavMenu label=\"Docs\">\n        <Header.NavMenuItem href=\"/getting-started\">Getting Started</Header.NavMenuItem>\n        <Header.NavMenuItem href=\"/cli\">CLI Reference</Header.NavMenuItem>\n        <Header.NavMenuItem href=\"/mcp\">MCP Tools</Header.NavMenuItem>\n      </Header.NavMenu>\n      <Header.NavItem href=\"/blog\">Blog</Header.NavItem>\n    </Header.Nav>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n    </Header.Actions>\n  </Header>\n</Box>"
     },
     {
       "name": "For Sidebar Layout",
-      "description": "Header without brand (logo is in sidebar). Use with AppShell layout=\"sidebar\" or \"sidebar-floating\".",
-      "code": "<ThemeProvider defaultMode=\"light\">\n  <Header>\n    <Header.SkipLink />\n    <Header.Trigger />\n    <Header.Search>\n      <Input placeholder=\"Search...\" style={{ width: '240px' }} />\n    </Header.Search>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n    </Header.Actions>\n  </Header>\n</ThemeProvider>"
+      "description": "No brand — the logo lives in the sidebar instead.",
+      "code": "import { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\nimport { Input } from '@/components/Input';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box width=\"100%\" border rounded=\"md\" overflow=\"hidden\">\n  <Header>\n    <Header.SkipLink />\n    <Header.Trigger />\n    <Header.Search>\n      <Input placeholder=\"Search...\" style={{ width: '240px' }} />\n    </Header.Search>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n    </Header.Actions>\n  </Header>\n</Box>"
     },
     {
       "name": "Minimal",
-      "description": "Clean header with just trigger and actions",
-      "code": "<ThemeProvider defaultMode=\"light\">\n  <Header>\n    <Header.Trigger />\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n    </Header.Actions>\n  </Header>\n</ThemeProvider>"
-    },
-    {
-      "name": "With Search",
-      "description": "Header featuring a prominent search input",
-      "code": "<ThemeProvider defaultMode=\"light\">\n  <Header>\n    <Header.Brand>Docs</Header.Brand>\n    <Header.Search>\n      <div style={{\n        display: 'flex',\n        alignItems: 'center',\n        gap: '8px',\n        padding: '8px 12px',\n        background: 'var(--fui-bg-secondary)',\n        borderRadius: '6px',\n        color: 'var(--fui-text-tertiary)',\n        fontSize: '14px',\n        width: '280px'\n      }}>\n        <MagnifyingGlass size={16} /> Search documentation...\n      </div>\n    </Header.Search>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n    </Header.Actions>\n  </Header>\n</ThemeProvider>"
+      "description": "Just the drawer trigger and actions.",
+      "code": "import { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box width=\"100%\" border rounded=\"md\" overflow=\"hidden\">\n  <Header>\n    <Header.Trigger />\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n    </Header.Actions>\n  </Header>\n</Box>"
     },
     {
       "name": "With Skip Link",
-      "description": "Accessible header with skip link for keyboard navigation",
-      "code": "<Header>\n  <Header.SkipLink href=\"#main-content\">Skip to content</Header.SkipLink>\n  <Header.Brand>Accessible App</Header.Brand>\n  <Header.Nav>\n    <Header.NavItem href=\"/\" active>Home</Header.NavItem>\n    <Header.NavItem href=\"/about\">About</Header.NavItem>\n  </Header.Nav>\n</Header>"
+      "description": "Header.SkipLink gives keyboard users a jump to main content.",
+      "code": "import { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\n\n<Box width=\"100%\" border rounded=\"md\" overflow=\"hidden\">\n  <Header>\n    <Header.SkipLink href=\"#main-content\">Skip to content</Header.SkipLink>\n    <Header.Brand>Accessible App</Header.Brand>\n    <Header.Nav>\n      <Header.NavItem href=\"/\" active>Home</Header.NavItem>\n      <Header.NavItem href=\"/about\">About</Header.NavItem>\n    </Header.Nav>\n  </Header>\n</Box>"
     },
     {
       "name": "With NavigationMenu",
-      "description": "Header using NavigationMenu for rich dropdown content panels with titles, descriptions, and automatic mobile drawer.",
-      "code": "<ThemeProvider defaultMode=\"light\">\n  <Header>\n    <Header.Brand href=\"/\">MyApp</Header.Brand>\n    <NavigationMenu aria-label=\"Site navigation\">\n      <NavigationMenu.List>\n        <NavigationMenu.Item value=\"products\">\n          <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>\n          <NavigationMenu.Content>\n            <div style={{ display: 'flex', flexDirection: 'column', padding: '4px', minWidth: '200px' }}>\n              <NavigationMenu.Link href=\"/analytics\" title=\"Analytics\" description=\"Track your metrics.\" />\n              <NavigationMenu.Link href=\"/automation\" title=\"Automation\" description=\"Automate workflows.\" />\n            </div>\n          </NavigationMenu.Content>\n        </NavigationMenu.Item>\n        <NavigationMenu.Item>\n          <NavigationMenu.Link href=\"/pricing\">Pricing</NavigationMenu.Link>\n        </NavigationMenu.Item>\n      </NavigationMenu.List>\n      <NavigationMenu.Viewport />\n    </NavigationMenu>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n      <Button variant=\"primary\" size=\"sm\">Sign Up</Button>\n    </Header.Actions>\n  </Header>\n</ThemeProvider>"
+      "description": "Rich dropdown panels with titles and descriptions.",
+      "code": "import { Box } from '@/components/Box';\nimport { Button } from '@/components/Button';\nimport { Header } from '@/components/Header';\nimport { NavigationMenu } from '@/components/NavigationMenu';\nimport { Stack } from '@/components/Stack';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box width=\"100%\" border rounded=\"md\" overflow=\"hidden\">\n  <Header>\n    <Header.Brand href=\"/\">MyApp</Header.Brand>\n    <Header.Nav>\n      <NavigationMenu aria-label=\"Site navigation\">\n        <NavigationMenu.List>\n          <NavigationMenu.Item value=\"products\">\n            <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>\n            <NavigationMenu.Content>\n              <Box padding=\"xs\" style={{ minWidth: '200px' }}>\n                <Stack gap=\"none\">\n                  <NavigationMenu.Link href=\"/analytics\" title=\"Analytics\" description=\"Track your metrics.\" />\n                  <NavigationMenu.Link href=\"/automation\" title=\"Automation\" description=\"Automate workflows.\" />\n                </Stack>\n              </Box>\n            </NavigationMenu.Content>\n          </NavigationMenu.Item>\n          <NavigationMenu.Item>\n            <NavigationMenu.Link href=\"/pricing\">Pricing</NavigationMenu.Link>\n          </NavigationMenu.Item>\n        </NavigationMenu.List>\n        <NavigationMenu.Viewport />\n      </NavigationMenu>\n    </Header.Nav>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n      <Button variant=\"solid\" size=\"sm\">Sign Up</Button>\n    </Header.Actions>\n  </Header>\n</Box>"
     }
   ],
   "relations": [
@@ -197,12 +166,7 @@
       "Header.NavMenu provides dropdown groups via Base UI Menu",
       "Header.MobileNavActions provides an action row inside the mobile drawer"
     ],
-    "a11yRules": [
-      "A11Y_HEADER_LANDMARK",
-      "A11Y_NAV_LABEL",
-      "A11Y_SKIP_LINK",
-      "A11Y_BUTTON_LABEL"
-    ]
+    "a11yRules": ["A11Y_HEADER_LANDMARK", "A11Y_NAV_LABEL", "A11Y_SKIP_LINK", "A11Y_BUTTON_LABEL"]
   },
   "ai": {
     "compositionPattern": "compound",

package/src/components/Header/Header.module.scss

@@ -1,9 +1,11 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
-@use '../../recipes/action' as action;
-@use '../../recipes/layout' as layout;
-@use '../../recipes/navigation' as navigation;
-@use '../../recipes/popup' as popup;
+@use "../../tokens/variables" as *;
+@use "../../tokens/measurements.generated" as measurements;
+@use "../../tokens/mixins" as *;
+@use "../../recipes/action" as action;
+@use "../../recipes/layout" as layout;
+@use "../../recipes/navigation" as navigation;
+@use "../../recipes/overlay" as overlay;
+@use "../../recipes/popup" as popup;
 
 // ============================================
 // Header Root
@@ -16,9 +18,12 @@
 
   display: flex;
   align-items: center;
+  // A header always spans its container. Without this it collapses to
+  // min-content when placed inside a flex/grid parent that centers its items.
+  width: 100%;
   height: var(--header-height, var(--fui-appshell-header-height, $fui-appshell-header-height));
   min-height: var(--header-height, var(--fui-appshell-header-height, $fui-appshell-header-height));
-  background-color: var(--fui-bg-primary, $fui-bg-primary);
+  background-color: var(--fui-app-main-bg, var(--fui-main-bg, #{$fui-main-bg}));
   padding: 0 var(--fui-space-4, $fui-space-4);
   z-index: var(--fui-header-z-index, $fui-header-z-index);
 }
@@ -36,7 +41,7 @@
 }
 
 .elevatedOnScroll {
-  border-bottom: var(--fui-space-px, $fui-space-px) solid transparent;
+  border-bottom: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid transparent;
   transition: border-color var(--fui-transition-fast, $fui-transition-fast);
 }
 
@@ -124,8 +129,8 @@
   align-items: center;
   gap: var(--fui-space-1, $fui-space-1);
   list-style: none;
-  margin: 0;
-  padding: 0;
+  margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
+  padding: var(--fui-raw-space-0, #{measurements.raw-space(0)});
 }
 
 .navItem {
@@ -152,14 +157,16 @@
 }
 
 .navItemActive {
-  // Match sidebar active state: secondary surface + primary text
+  // Persistent navigation selection shares the same neutral role as Sidebar
+  // and Tabs. Do not use --fui-bg-active here: that token is for the brief
+  // pointer-down state.
   color: var(--fui-text-primary, $fui-text-primary);
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
-  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  background-color: var(--fui-control-selected-bg, var(--fui-bg-active, $fui-bg-active));
 
   &.navItem:hover,
   &.navItem:active {
-    background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+    background-color: var(--fui-control-selected-bg, var(--fui-bg-active, $fui-bg-active));
     color: var(--fui-text-primary, $fui-text-primary);
   }
 }
@@ -187,7 +194,7 @@
 // ============================================
 
 .navMenuPositioner {
-  z-index: 52;
+  z-index: var(--fui-overlay-layer-anchored, #{$fui-overlay-layer-anchored});
   outline: none;
 }
 
@@ -195,7 +202,6 @@
   @include popup.container;
 
   min-width: layout.measure("field-minimum");
-  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
 
   opacity: 0;
   transform: scale(0.95);
@@ -236,13 +242,13 @@
 }
 
 .navMenuItemActive {
-  // Match active nav item treatment in both light and dark themes
-  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  // Match the persistent navigation treatment in both light and dark themes.
+  background-color: var(--fui-control-selected-bg, var(--fui-bg-active, $fui-bg-active));
   color: var(--fui-text-primary, $fui-text-primary);
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
 
   &[data-highlighted] {
-    background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+    background-color: var(--fui-control-selected-bg, var(--fui-bg-active, $fui-bg-active));
     color: var(--fui-text-primary, $fui-text-primary);
   }
 }
@@ -269,6 +275,8 @@
 
 .search {
   display: none;
+  background-color: var(--fui-header-search-bg, var(--fui-bg-subtle, #{$fui-bg-subtle}));
+  border-radius: var(--fui-button-radius, var(--fui-radius-lg, #{$fui-radius-lg}));
 
   // Show search when header has enough space
   @include container-min($fui-breakpoint-md, fui-header) {
@@ -331,25 +339,16 @@
 // ============================================
 
 .mobileNavBackdrop {
-  position: fixed;
-  inset: 0;
-  z-index: 98;
-  background: var(--fui-backdrop, $fui-backdrop);
-  animation: mobileNavFadeIn var(--fui-transition-normal, $fui-transition-normal) ease;
+  @include overlay.backdrop;
+
+  animation: mobileNavFadeIn var(--fui-transition-normal, $fui-transition-normal);
 }
 
+// The mobile nav is the Drawer surface: same frame, width, layer and chrome.
 .mobileNavDrawer {
-  position: fixed;
-  top: 0;
-  right: 0;
-  bottom: 0;
-  z-index: 99;
-  width: min(320px, 85vw);
-  background-color: var(--fui-bg-primary, $fui-bg-primary);
-  border-left: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
-  display: flex;
-  flex-direction: column;
-  animation: mobileNavSlideIn var(--fui-transition-normal, $fui-transition-normal) ease;
+  @include overlay.side-panel("end");
+
+  animation: mobileNavSlideIn var(--fui-transition-normal, $fui-transition-normal);
 }
 
 .mobileNavHeader {
@@ -357,7 +356,8 @@
   align-items: center;
   justify-content: flex-end;
   padding: var(--fui-space-3, $fui-space-3) var(--fui-space-4, $fui-space-4);
-  border-bottom: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
+  border-bottom: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
+    var(--fui-border, $fui-border);
 }
 
 .mobileNavClose {
@@ -381,30 +381,23 @@
 .mobileNavBody {
   flex: 1;
   overflow-y: auto;
-  padding: var(--fui-space-3, $fui-space-3) var(--fui-space-4, $fui-space-4);
+  // Same gutter as NavigationMenu.drawerBody so both mobile navs inset their
+  // rows identically (UIR-D42).
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-navigation-gutter, #{navigation.gutter()});
 }
 
 .mobileNavLink {
   @include button-reset;
   @include navigation.row;
+  @include navigation.link-states;
 
   display: flex;
   align-items: center;
   width: 100%;
-  border-radius: var(--fui-radius-md, $fui-radius-md);
-  color: var(--fui-text-secondary, $fui-text-secondary);
-  text-decoration: none;
-  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
-
-  &:hover {
-    background-color: var(--fui-bg-hover, $fui-bg-hover);
-    color: var(--fui-text-primary, $fui-text-primary);
-  }
 }
 
 .mobileNavLinkActive {
-  color: var(--fui-text-primary, $fui-text-primary);
-  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  @include navigation.link-active;
 }
 
 .mobileNavActions {
@@ -415,13 +408,21 @@
 }
 
 @keyframes mobileNavFadeIn {
-  from { opacity: 0; }
-  to { opacity: 1; }
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
 }
 
 @keyframes mobileNavSlideIn {
-  from { transform: translateX(100%); }
-  to { transform: translateX(0); }
+  from {
+    transform: translateX(overlay.side-panel-offscreen("end"));
+  }
+  to {
+    transform: translateX(0);
+  }
 }
 
 @media (prefers-reduced-motion: reduce) {
@@ -441,11 +442,13 @@
   position: absolute;
   top: var(--fui-space-2, $fui-space-2);
   left: var(--fui-space-2, $fui-space-2);
-  z-index: 100;
+  // Top of the layer scale: a skip link must win over every overlay.
+  z-index: var(--fui-overlay-layer-tooltip, #{$fui-overlay-layer-tooltip});
   padding: var(--fui-space-2, $fui-space-2) var(--fui-space-4, $fui-space-4);
   background-color: var(--fui-bg-primary, $fui-bg-primary);
   color: var(--fui-text-primary, $fui-text-primary);
-  border: var(--fui-stroke-default, 2px) solid var(--fui-color-accent, $fui-color-accent);
+  border: var(--fui-stroke-default, #{$fui-stroke-default}) solid
+    var(--fui-color-accent, $fui-color-accent);
   border-radius: var(--fui-radius-md, $fui-radius-md);
   text-decoration: none;
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
@@ -456,7 +459,7 @@
     height: auto;
     clip: auto;
     white-space: normal;
-    margin: 0;
+    margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
     padding: var(--fui-space-2, $fui-space-2) var(--fui-space-4, $fui-space-4);
     overflow: visible;