Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(MobileNav): add XDSMobileNav drawer, useMediaQuery hook, and menu icon (#341)

Cindy Zhang904e6f7eba66
diff --git a/apps/storybook/stories/AppShell.stories.tsx b/apps/storybook/stories/AppShell.stories.tsx
index 2183ef8f40..cb146eacd1 100644
--- a/apps/storybook/stories/AppShell.stories.tsx
+++ b/apps/storybook/stories/AppShell.stories.tsx
@@ -6,6 +6,7 @@ import {XDSBadge} from '@xds/core/Badge';
import {XDSButton} from '@xds/core/Button';
import {XDSIcon} from '@xds/core/Icon';
import {XDSText} from '@xds/core/Text';
+import {XDSMobileNav} from '@xds/core/MobileNav';
import {XDSTopNav, XDSTopNavTitle, XDSTopNavItem} from '@xds/core/TopNav';
import {XDSNavIcon} from '@xds/core/NavIcon';
import {
@@ -14,6 +15,7 @@ import {
XDSSideNavItem,
XDSSideNavSection,
} from '@xds/core/SideNav';
+import {useMediaQuery} from '@xds/core/hooks';
import * as stylex from '@stylexjs/stylex';
import {spacingVars} from '@xds/core/theme/tokens.stylex';
import {
@@ -479,3 +481,127 @@ export const WithBanner: Story = {
</XDSAppShell>
),
};
+
+/**
+ * Responsive layout with mobile navigation drawer. Shows the recommended
+ * pattern for apps that need to work across desktop and mobile:
+ *
+ * - Desktop (>768px): Standard AppShell with TopNav + inline SideNav
+ * - Mobile (≤768px): SideNav hides, TopNav shows a hamburger button that
+ * opens the `mobileNav` drawer (an XDSMobileNav rendered by AppShell)
+ *
+ * The nav sections are defined once and shared between `sideNav` and
+ * `mobileNav`. AppShell handles rendering the XDSMobileNav internally —
+ * you just pass the content and control open/close state.
+ *
+ * Resize the viewport or use Storybook's viewport addon to see the
+ * transition between layouts.
+ */
+export const WithMobileNav: Story = {
+ name: 'With Mobile Nav',
+ render: function WithMobileNavStory() {
+ const isMobile = useMediaQuery('(max-width: 768px)');
+ const [mobileNavOpen, setMobileNavOpen] = useState(false);
+
+ const navSections = (
+ <>
+ <XDSSideNavSection title="Main" isHeaderHidden>
+ <XDSSideNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ href="#"
+ />
+ <XDSSideNavItem
+ label="Analytics"
+ icon={ChartBarIcon}
+ selectedIcon={ChartBarIconSolid}
+ href="#"
+ />
+ <XDSSideNavItem
+ label="Projects"
+ icon={FolderIcon}
+ selectedIcon={FolderIconSolid}
+ href="#"
+ endContent={<XDSBadge>12</XDSBadge>}
+ />
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Organization">
+ <XDSSideNavItem
+ label="Team"
+ icon={UserGroupIcon}
+ selectedIcon={UserGroupIconSolid}
+ href="#"
+ />
+ <XDSSideNavItem
+ label="Settings"
+ icon={Cog6ToothIcon}
+ selectedIcon={Cog6ToothIconSolid}
+ href="#"
+ />
+ </XDSSideNavSection>
+ </>
+ );
+
+ return (
+ <XDSAppShell
+ topNav={
+ <XDSTopNav
+ label="Main navigation"
+ title={
+ <XDSTopNavTitle
+ title="Acme App"
+ logo={
+ <XDSNavIcon
+ icon={<CubeIcon style={{width: 16, height: 16}} />}
+ />
+ }
+ />
+ }
+ startContent={
+ isMobile ? (
+ <XDSButton
+ label="Menu"
+ variant="ghost"
+ icon={<XDSIcon icon="menu" color="inherit" />}
+ onClick={() => setMobileNavOpen(true)}
+ />
+ ) : (
+ <>
+ <XDSTopNavItem label="Home" href="#" isSelected />
+ <XDSTopNavItem label="Products" href="#" />
+ <XDSTopNavItem label="Docs" href="#" />
+ </>
+ )
+ }
+ endContent={
+ <>
+ <XDSButton
+ label="Notifications"
+ variant="ghost"
+ icon={<BellIcon style={{width: 16, height: 16}} />}
+ />
+ <XDSButton
+ label="Profile"
+ variant="ghost"
+ icon={<UserCircleIcon style={{width: 16, height: 16}} />}
+ />
+ </>
+ }
+ />
+ }
+ sideNav={<XDSSideNav>{navSections}</XDSSideNav>}
+ mobileNav={
+ <XDSMobileNav
+ isOpen={mobileNavOpen}
+ onClose={() => setMobileNavOpen(false)}
+ title="Acme App">
+ {navSections}
+ </XDSMobileNav>
+ }>
+ <MockContent />
+ </XDSAppShell>
+ );
+ },
+};
diff --git a/apps/storybook/stories/MobileNav.stories.tsx b/apps/storybook/stories/MobileNav.stories.tsx
new file mode 100644
index 0000000000..50b273d102
--- /dev/null
+++ b/apps/storybook/stories/MobileNav.stories.tsx
@@ -0,0 +1,334 @@
+import {useState} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSMobileNav} from '@xds/core/MobileNav';
+import {
+ XDSSideNav,
+ XDSSideNavHeader,
+ XDSSideNavItem,
+ XDSSideNavSection,
+} from '@xds/core/SideNav';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSNavIcon} from '@xds/core/NavIcon';
+import {useMediaQuery} from '@xds/core/hooks';
+import {
+ HomeIcon,
+ FolderIcon,
+ Cog6ToothIcon,
+ ChartBarIcon,
+ UserGroupIcon,
+ CubeIcon,
+} from '@heroicons/react/24/outline';
+import {
+ HomeIcon as HomeIconSolid,
+ FolderIcon as FolderIconSolid,
+} from '@heroicons/react/24/solid';
+
+// =============================================================================
+// Meta
+// =============================================================================
+
+const meta: Meta<typeof XDSMobileNav> = {
+ title: 'Navigation/XDSMobileNav',
+ component: XDSMobileNav,
+ tags: ['autodocs'],
+ parameters: {
+ layout: 'centered',
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSMobileNav>;
+
+// =============================================================================
+// Default
+// =============================================================================
+
+export const Default: Story = {
+ render: () => {
+ const [isOpen, setIsOpen] = useState(false);
+ return (
+ <>
+ <XDSButton
+ label="Open Navigation"
+ icon={<XDSIcon icon="menu" color="inherit" />}
+ variant="ghost"
+ onClick={() => setIsOpen(true)}
+ />
+ <XDSMobileNav
+ isOpen={isOpen}
+ onClose={() => setIsOpen(false)}
+ title="Navigation">
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ href="/dashboard"
+ />
+ <XDSSideNavItem
+ label="Projects"
+ icon={FolderIcon}
+ selectedIcon={FolderIconSolid}
+ href="/projects"
+ />
+ <XDSSideNavItem
+ label="Analytics"
+ icon={ChartBarIcon}
+ href="/analytics"
+ />
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Settings">
+ <XDSSideNavItem
+ label="General"
+ icon={Cog6ToothIcon}
+ href="/settings"
+ />
+ <XDSSideNavItem label="Team" icon={UserGroupIcon} href="/team" />
+ </XDSSideNavSection>
+ </XDSMobileNav>
+ </>
+ );
+ },
+};
+
+// =============================================================================
+// With SideNav Children
+// =============================================================================
+
+export const WithSideNavChildren: Story = {
+ name: 'With SideNav Children',
+ render: () => {
+ const [isOpen, setIsOpen] = useState(false);
+
+ const navSections = (
+ <>
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ href="/dashboard"
+ />
+ <XDSSideNavItem
+ label="Projects"
+ icon={FolderIcon}
+ selectedIcon={FolderIconSolid}
+ href="/projects"
+ />
+ <XDSSideNavItem
+ label="Analytics"
+ icon={ChartBarIcon}
+ href="/analytics"
+ />
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Settings">
+ <XDSSideNavItem
+ label="General"
+ icon={Cog6ToothIcon}
+ href="/settings"
+ />
+ </XDSSideNavSection>
+ </>
+ );
+
+ return (
+ <>
+ <XDSButton label="Open Drawer" onClick={() => setIsOpen(true)} />
+ <XDSMobileNav
+ isOpen={isOpen}
+ onClose={() => setIsOpen(false)}
+ title="My App">
+ {navSections}
+ </XDSMobileNav>
+ </>
+ );
+ },
+};
+
+// =============================================================================
+// Responsive Pattern
+// =============================================================================
+
+export const ResponsivePattern: Story = {
+ name: 'Responsive Pattern',
+ render: () => {
+ const isMobile = useMediaQuery('(max-width: 768px)');
+ const [drawerOpen, setDrawerOpen] = useState(false);
+
+ const navSections = (
+ <>
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ href="/"
+ />
+ <XDSSideNavItem
+ label="Projects"
+ icon={FolderIcon}
+ selectedIcon={FolderIconSolid}
+ href="/projects"
+ />
+ <XDSSideNavItem
+ label="Analytics"
+ icon={ChartBarIcon}
+ href="/analytics"
+ />
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Settings">
+ <XDSSideNavItem
+ label="General"
+ icon={Cog6ToothIcon}
+ href="/settings"
+ />
+ <XDSSideNavItem label="Team" icon={UserGroupIcon} href="/team" />
+ </XDSSideNavSection>
+ </>
+ );
+
+ if (isMobile) {
+ return (
+ <>
+ <XDSButton
+ label="Menu"
+ icon={<XDSIcon icon="menu" color="inherit" />}
+ variant="ghost"
+ onClick={() => setDrawerOpen(true)}
+ />
+ <XDSMobileNav
+ isOpen={drawerOpen}
+ onClose={() => setDrawerOpen(false)}
+ title="My App">
+ {navSections}
+ </XDSMobileNav>
+ </>
+ );
+ }
+
+ return (
+ <div style={{width: 280, height: 600, border: '1px solid #e5e7eb'}}>
+ <XDSSideNav
+ header={
+ <XDSSideNavHeader
+ icon={
+ <XDSNavIcon
+ icon={<CubeIcon style={{width: 16, height: 16}} />}
+ />
+ }
+ title="My App"
+ titleHref="/"
+ />
+ }>
+ {navSections}
+ </XDSSideNav>
+ </div>
+ );
+ },
+};
+
+// =============================================================================
+// End Side
+// =============================================================================
+
+export const EndSide: Story = {
+ name: 'End Side',
+ render: () => {
+ const [isOpen, setIsOpen] = useState(false);
+ return (
+ <>
+ <XDSButton label="Open from Right" onClick={() => setIsOpen(true)} />
+ <XDSMobileNav
+ isOpen={isOpen}
+ onClose={() => setIsOpen(false)}
+ title="Settings"
+ side="end">
+ <XDSSideNavSection title="Settings">
+ <XDSSideNavItem
+ label="General"
+ icon={Cog6ToothIcon}
+ href="/settings"
+ />
+ <XDSSideNavItem label="Team" icon={UserGroupIcon} href="/team" />
+ </XDSSideNavSection>
+ </XDSMobileNav>
+ </>
+ );
+ },
+};
+
+// =============================================================================
+// Custom Width
+// =============================================================================
+
+export const CustomWidth: Story = {
+ name: 'Custom Width',
+ render: () => {
+ const [isOpen, setIsOpen] = useState(false);
+ return (
+ <>
+ <XDSButton label="Open Wide Drawer" onClick={() => setIsOpen(true)} />
+ <XDSMobileNav
+ isOpen={isOpen}
+ onClose={() => setIsOpen(false)}
+ title="Wide Navigation"
+ width={360}>
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ href="/dashboard"
+ />
+ <XDSSideNavItem
+ label="Projects"
+ icon={FolderIcon}
+ href="/projects"
+ />
+ </XDSSideNavSection>
+ </XDSMobileNav>
+ </>
+ );
+ },
+};
+
+// =============================================================================
+// Without Title
+// =============================================================================
+
+export const WithoutTitle: Story = {
+ name: 'Without Title',
+ render: () => {
+ const [isOpen, setIsOpen] = useState(false);
+ return (
+ <>
+ <XDSButton
+ label="Open Navigation"
+ icon={<XDSIcon icon="menu" color="inherit" />}
+ variant="ghost"
+ onClick={() => setIsOpen(true)}
+ />
+ <XDSMobileNav isOpen={isOpen} onClose={() => setIsOpen(false)}>
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ isSelected
+ href="/dashboard"
+ />
+ <XDSSideNavItem
+ label="Projects"
+ icon={FolderIcon}
+ href="/projects"
+ />
+ </XDSSideNavSection>
+ </XDSMobileNav>
+ </>
+ );
+ },
+};
diff --git a/packages/core/package.json b/packages/core/package.json
index 2e3b000e57..d957dfc75f 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -172,6 +172,12 @@
"import": "./dist/List/index.mjs",
"require": "./dist/List/index.js"
},
+ "./MobileNav": {
+ "source": "./src/MobileNav/index.ts",
+ "types": "./dist/MobileNav/index.d.ts",
+ "import": "./dist/MobileNav/index.mjs",
+ "require": "./dist/MobileNav/index.js"
+ },
"./NavIcon": {
"source": "./src/NavIcon/index.ts",
"types": "./dist/NavIcon/index.d.ts",
diff --git a/packages/core/src/AppShell/README.md b/packages/core/src/AppShell/README.md
index a0da331086..46f41aa524 100644
--- a/packages/core/src/AppShell/README.md
+++ b/packages/core/src/AppShell/README.md
@@ -107,6 +107,52 @@ For landing pages or simple apps that don't need secondary navigation.
</XDSAppShell>
```
+### Responsive: SideNav + MobileNav
+
+For apps that need both desktop and mobile layouts, use the `mobileNav` slot.
+On desktop the SideNav renders inline; on mobile AppShell hides the SideNav
+(via `sideNavBreakpoint`) and the consumer shows an XDSMobileNav drawer instead.
+
+Pass a fully composed `<XDSMobileNav>` — AppShell just renders it, same as
+every other slot. All drawer props (`isOpen`, `onClose`, `title`) stay on
+XDSMobileNav where they belong.
+
+```tsx
+const [mobileOpen, setMobileOpen] = useState(false);
+const isMobile = useMediaQuery('(max-width: 768px)');
+
+<XDSAppShell
+ topNav={
+ <XDSTopNav
+ label="Navigation"
+ title={<XDSTopNavTitle title="My App" />}
+ startContent={
+ isMobile ? (
+ <XDSButton
+ label="Menu"
+ icon={<XDSIcon icon="menu" color="inherit" />}
+ variant="ghost"
+ onClick={() => setMobileOpen(true)}
+ />
+ ) : (
+ <XDSTopNavItem label="Home" href="/" isSelected />
+ )
+ }
+ />
+ }
+ sideNav={<XDSSideNav>{navSections}</XDSSideNav>}
+ mobileNav={
+ <XDSMobileNav
+ isOpen={mobileOpen}
+ onClose={() => setMobileOpen(false)}
+ title="My App">
+ {navSections}
+ </XDSMobileNav>
+ }>
+ <Content />
+</XDSAppShell>;
+```
+
### Pattern Summary
| Layout | TopNav | SideNav Header | When to use |
@@ -150,6 +196,7 @@ For landing pages or simple apps that don't need secondary navigation.
| `height` | `'fill' \| 'auto'` | `'fill'` | Height behavior |
| `isSideNavCollapsed` | `boolean` | — | Whether sideNav is collapsed (controlled) |
| `initialIsSideNavCollapsed` | `boolean` | `false` | Initial collapsed state (uncontrolled) |
+| `mobileNav` | `ReactNode` | — | Mobile navigation (typically XDSMobileNav) |
| `onSideNavCollapsedChange` | `(isCollapsed: boolean) => void` | — | Collapse change callback |
| `sideNavBreakpoint` | `'sm' \| 'md' \| 'lg' \| 'none'` | `'md'` | Breakpoint for auto-collapse |
| `sideNavWidth` | `number` | `260` | SideNav width in pixels |
diff --git a/packages/core/src/AppShell/XDSAppShell.test.tsx b/packages/core/src/AppShell/XDSAppShell.test.tsx
index 46c02b06cb..fa75e406da 100644
--- a/packages/core/src/AppShell/XDSAppShell.test.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.test.tsx
@@ -7,9 +7,32 @@
* SYNC: When XDSAppShell.tsx changes, update tests to match new behavior
*/
-import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {
+ describe,
+ it,
+ expect,
+ vi,
+ beforeAll,
+ beforeEach,
+ afterEach,
+} from 'vitest';
import {render, screen, fireEvent, act} from '@testing-library/react';
import {XDSAppShell} from './XDSAppShell';
+import {XDSMobileNav} from '../MobileNav';
+
+// jsdom doesn't implement showModal/close on <dialog>, so we mock them
+beforeAll(() => {
+ HTMLDialogElement.prototype.showModal =
+ HTMLDialogElement.prototype.showModal ||
+ function (this: HTMLDialogElement) {
+ this.setAttribute('open', '');
+ };
+ HTMLDialogElement.prototype.close =
+ HTMLDialogElement.prototype.close ||
+ function (this: HTMLDialogElement) {
+ this.removeAttribute('open');
+ };
+});
// Mock ResizeObserver
class MockResizeObserver {
@@ -270,10 +293,10 @@ describe('XDSAppShell', () => {
});
// ===========================================================================
- // Mobile overlay
+ // Mobile overlay (default XDSMobileNav wrapping sideNav)
// ===========================================================================
- it('shows overlay sideNav when below breakpoint and not collapsed', () => {
+ it('shows default mobile nav when below breakpoint and not collapsed', () => {
// Start below breakpoint with sideNav expanded
mockMql = createMockMatchMedia(true);
vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
@@ -287,13 +310,13 @@ describe('XDSAppShell', () => {
</XDSAppShell>,
);
- // Should show backdrop
- expect(screen.getByTestId('sidenav-backdrop')).toBeInTheDocument();
- // Should show nav in overlay
+ // Should show default mobile nav (XDSMobileNav wrapping sideNav)
+ expect(screen.getByTestId('sidenav-mobile')).toBeInTheDocument();
+ // Should show nav content inside the mobile nav
expect(screen.getByText('Nav Items')).toBeInTheDocument();
});
- it('clicking backdrop calls onSideNavCollapsedChange', () => {
+ it('default mobile nav calls onSideNavCollapsedChange on close', () => {
mockMql = createMockMatchMedia(true);
vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
@@ -307,25 +330,9 @@ describe('XDSAppShell', () => {
</XDSAppShell>,
);
- fireEvent.click(screen.getByTestId('sidenav-backdrop'));
- expect(onChange).toHaveBeenCalledWith(true);
- });
-
- it('pressing Escape closes mobile overlay', () => {
- mockMql = createMockMatchMedia(true);
- vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
-
- const onChange = vi.fn();
- render(
- <XDSAppShell
- sideNav={<div>Nav</div>}
- isSideNavCollapsed={false}
- onSideNavCollapsedChange={onChange}>
- <div>Content</div>
- </XDSAppShell>,
- );
-
- fireEvent.keyDown(document, {key: 'Escape'});
+ // Click the close button inside the default mobile nav
+ const closeButton = screen.getByRole('button', {name: /close/i});
+ fireEvent.click(closeButton);
expect(onChange).toHaveBeenCalledWith(true);
});
@@ -459,6 +466,85 @@ describe('XDSAppShell', () => {
expect(observeSpy).not.toHaveBeenCalled();
});
+ // ===========================================================================
+ // Mobile nav slot
+ // ===========================================================================
+
+ it('renders mobileNav slot content', () => {
+ render(
+ <XDSAppShell
+ sideNav={<div>Side Nav</div>}
+ mobileNav={
+ <XDSMobileNav
+ isOpen={true}
+ onClose={() => {}}
+ title="Test App"
+ data-testid="appshell-mobile-nav">
+ <div>Mobile Nav Content</div>
+ </XDSMobileNav>
+ }>
+ <div>Content</div>
+ </XDSAppShell>,
+ );
+ expect(screen.getByTestId('appshell-mobile-nav')).toBeInTheDocument();
+ expect(screen.getByText('Mobile Nav Content')).toBeInTheDocument();
+ });
+
+ it('does not render mobileNav when not provided', () => {
+ render(
+ <XDSAppShell sideNav={<div>Side Nav</div>}>
+ <div>Content</div>
+ </XDSAppShell>,
+ );
+ expect(screen.queryByTestId('appshell-mobile-nav')).not.toBeInTheDocument();
+ });
+
+ it('uses explicit mobileNav instead of default when provided', () => {
+ mockMql = createMockMatchMedia(true);
+ vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+
+ render(
+ <XDSAppShell
+ sideNav={<div>Side Nav</div>}
+ mobileNav={
+ <XDSMobileNav
+ isOpen={false}
+ onClose={() => {}}
+ data-testid="appshell-mobile-nav">
+ <div>Mobile Nav</div>
+ </XDSMobileNav>
+ }
+ isSideNavCollapsed={false}
+ onSideNavCollapsedChange={() => {}}>
+ <div>Content</div>
+ </XDSAppShell>,
+ );
+ // Default mobile nav should NOT appear
+ expect(screen.queryByTestId('sidenav-mobile')).not.toBeInTheDocument();
+ // Explicit mobileNav slot should be rendered
+ expect(screen.getByTestId('appshell-mobile-nav')).toBeInTheDocument();
+ });
+
+ it('mobileNav onClose is called when close button is clicked', () => {
+ const onClose = vi.fn();
+ render(
+ <XDSAppShell
+ sideNav={<div>Side Nav</div>}
+ mobileNav={
+ <XDSMobileNav isOpen={true} onClose={onClose} title="Nav">
+ <div>Mobile Nav</div>
+ </XDSMobileNav>
+ }>
+ <div>Content</div>
+ </XDSAppShell>,
+ );
+ const closeButton = screen.getByRole('button', {
+ name: /close/i,
+ });
+ fireEvent.click(closeButton);
+ expect(onClose).toHaveBeenCalled();
+ });
+
// ===========================================================================
// Ref forwarding
// ===========================================================================
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index cc296679f9..cae887c8fa 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -28,6 +28,7 @@ import {XDSLayout} from '../Layout/XDSLayout';
import {XDSLayoutHeader} from '../Layout/XDSLayoutHeader';
import {XDSLayoutPanel} from '../Layout/XDSLayoutPanel';
import {XDSLayoutContent} from '../Layout/XDSLayoutContent';
+import {XDSMobileNav} from '../MobileNav/XDSMobileNav';
// =============================================================================
// Constants
@@ -101,6 +102,18 @@ export interface XDSAppShellProps {
*/
isSideNavCollapsed?: boolean;
+ /**
+ * Mobile navigation — typically an XDSMobileNav.
+ *
+ * When provided, replaces the default mobile drawer that AppShell renders
+ * for sideNav below the breakpoint. The consumer owns the XDSMobileNav
+ * element and its open/close state, just like topNav and sideNav.
+ *
+ * When not provided, AppShell automatically wraps sideNav in an
+ * XDSMobileNav for the mobile breakpoint.
+ */
+ mobileNav?: ReactNode;
+
/**
* Callback when side nav collapsed state changes.
*/
@@ -211,29 +224,6 @@ const styles = stylex.create({
banner: {
flexShrink: 0,
},
- // Mobile overlay sideNav
- overlay: {
- position: 'fixed',
- inset: 0,
- zIndex: 100,
- display: 'flex',
- },
- backdrop: {
- position: 'fixed',
- inset: 0,
- backgroundColor: colorVars['--color-overlay'],
- zIndex: 100,
- },
- overlaySideNav: {
- position: 'relative',
- zIndex: 101,
- backgroundColor: colorVars['--color-surface'],
- overflow: 'auto',
- height: '100%',
- borderInlineEndWidth: 1,
- borderInlineEndStyle: 'solid',
- borderInlineEndColor: colorVars['--color-divider'],
- },
hidden: {
display: 'none',
},
@@ -252,12 +242,6 @@ const styles = stylex.create({
},
});
-const dynamicStyles = stylex.create({
- sideNavWidth: (width: number) => ({
- width,
- }),
-});
-
// =============================================================================
// Component
// =============================================================================
@@ -274,16 +258,14 @@ const dynamicStyles = stylex.create({
* ```
* <XDSAppShell
* topNav={<XDSTopNav label="Navigation" title={<XDSTopNavTitle title="My App" />} />}
- * sideNav={
- * <XDSSideNav>
- * <XDSSideNavSection title="Main" isHeaderHidden>
- * <XDSSideNavItem label="Dashboard" isSelected href="/dashboard" />
- * <XDSSideNavItem label="Analytics" href="/analytics" />
- * </XDSSideNavSection>
- * </XDSSideNav>
+ * sideNav={<XDSSideNav>{navSections}</XDSSideNav>}
+ * mobileNav={
+ * <XDSMobileNav isOpen={mobileOpen} onClose={() => setMobileOpen(false)} title="My App">
+ * {navSections}
+ * </XDSMobileNav>
* }
* >
- * <DashboardContent />
+ * <Content />
* </XDSAppShell>
* ```
*/
@@ -297,6 +279,7 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(
height = 'fill',
initialIsSideNavCollapsed = false,
isSideNavCollapsed: controlledCollapsed,
+ mobileNav,
onSideNavCollapsedChange,
sideNav,
sideNavBreakpoint = 'md',
@@ -323,6 +306,7 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(
const isFill = height === 'fill';
const isAuto = height === 'auto';
const hasSideNav = sideNav != null;
+ const hasMobileNav = mobileNav != null;
const hasTopNav = topNav != null;
const hasBanner = banner != null;
@@ -408,28 +392,15 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(
onSideNavCollapsedChange?.(newValue);
}, [isCollapsed, isControlled, onSideNavCollapsedChange]);
- // =========================================================================
- // Close mobile sideNav on Escape
- // =========================================================================
- useEffect(() => {
- if (!isBelowBreakpoint || isCollapsed) return;
-
- const handleKeyDown = (e: KeyboardEvent) => {
- if (e.key === 'Escape') {
- e.preventDefault();
- handleToggleCollapse();
- }
- };
-
- document.addEventListener('keydown', handleKeyDown);
- return () => document.removeEventListener('keydown', handleKeyDown);
- }, [isBelowBreakpoint, isCollapsed, handleToggleCollapse]);
-
// =========================================================================
// Determine if sideNav should show as overlay (mobile) or inline
// =========================================================================
const showSideNavInline = hasSideNav && !isCollapsed && !isBelowBreakpoint;
- const showSideNavOverlay = hasSideNav && !isCollapsed && isBelowBreakpoint;
+ // Default mobile nav: when no explicit mobileNav is provided, AppShell
+ // internally renders an XDSMobileNav wrapping the sideNav content.
+ // This shares the same <dialog>-based behavior as explicit mobileNav.
+ const useDefaultMobileNav =
+ hasSideNav && !hasMobileNav && isBelowBreakpoint;
// =========================================================================
// Build header content (topNav + banner)
@@ -525,24 +496,16 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(
content={mainContent}
/>
- {/* Mobile overlay sideNav */}
- {showSideNavOverlay && (
- <>
- <div
- {...stylex.props(styles.backdrop)}
- onClick={handleToggleCollapse}
- data-testid="sidenav-backdrop"
- aria-hidden="true"
- />
- <nav
- aria-label="Application navigation"
- {...stylex.props(
- styles.overlaySideNav,
- dynamicStyles.sideNavWidth(sideNavWidth),
- )}>
- {sideNav}
- </nav>
- </>
+ {/* Mobile nav — either explicit mobileNav or default wrapping sideNav */}
+ {mobileNav}
+ {useDefaultMobileNav && (
+ <XDSMobileNav
+ isOpen={!isCollapsed}
+ onClose={handleToggleCollapse}
+ width={sideNavWidth}
+ data-testid="sidenav-mobile">
+ {sideNav}
+ </XDSMobileNav>
)}
</div>
);
diff --git a/packages/core/src/Icon/IconRegistry.tsx b/packages/core/src/Icon/IconRegistry.tsx
index 62e8693038..2549c6d36d 100644
--- a/packages/core/src/Icon/IconRegistry.tsx
+++ b/packages/core/src/Icon/IconRegistry.tsx
@@ -37,7 +37,8 @@ export type XDSIconName =
| 'info'
| 'calendar'
| 'clock'
- | 'externalLink';
+ | 'externalLink'
+ | 'menu';
/**
* Icon registry mapping semantic names to React nodes.
diff --git a/packages/core/src/Icon/defaultIcons.tsx b/packages/core/src/Icon/defaultIcons.tsx
index ac40819e66..ab4ae4c61e 100644
--- a/packages/core/src/Icon/defaultIcons.tsx
+++ b/packages/core/src/Icon/defaultIcons.tsx
@@ -153,4 +153,11 @@ export const defaultIcons: XDSIconRegistry = {
<path d="M10 14L21 3" />
</svg>
),
+
+ /** ☰ — hamburger menu (three horizontal lines) */
+ menu: (
+ <svg {...svgProps} strokeWidth={2}>
+ <path d="M4 6h16M4 12h16M4 18h16" />
+ </svg>
+ ),
};
diff --git a/packages/core/src/MobileNav/README.md b/packages/core/src/MobileNav/README.md
new file mode 100644
index 0000000000..f125770b24
--- /dev/null
+++ b/packages/core/src/MobileNav/README.md
@@ -0,0 +1,170 @@
+# MobileNav
+
+Slide-out drawer overlay for mobile navigation. The mobile counterpart to `XDSSideNav` — accepts the same children (`XDSSideNavSection`, `XDSSideNavItem`, or any ReactNode).
+
+## Components
+
+| Component | Description |
+| -------------- | ----------------------------------------------------------------- |
+| `XDSMobileNav` | Full-height drawer overlay with backdrop, close button, and title |
+
+## Files
+
+| File | Purpose |
+| ----------------------- | ---------------- |
+| `XDSMobileNav.tsx` | Drawer component |
+| `XDSMobileNav.test.tsx` | Unit tests |
+| `index.ts` | Public exports |
+
+## Usage
+
+```tsx
+import {XDSMobileNav} from '@xds/core/MobileNav';
+```
+
+### Basic — hamburger menu with nav links
+
+```tsx
+const [isOpen, setIsOpen] = useState(false);
+
+<XDSButton
+ label="Menu"
+ icon={<MenuIcon />}
+ variant="ghost"
+ onClick={() => setIsOpen(true)}
+/>
+
+<XDSMobileNav
+ isOpen={isOpen}
+ onClose={() => setIsOpen(false)}
+ title="Navigation"
+>
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem label="Dashboard" href="/dashboard" isSelected />
+ <XDSSideNavItem label="Analytics" href="/analytics" />
+ <XDSSideNavItem label="Settings" href="/settings" />
+ </XDSSideNavSection>
+</XDSMobileNav>
+```
+
+### Responsive — sidebar on desktop, drawer on mobile
+
+Use a media query to show `XDSSideNav` on desktop and `XDSMobileNav` on mobile. The same nav items work in both:
+
+```tsx
+const isMobile = useMediaQuery('(max-width: 768px)');
+const [drawerOpen, setDrawerOpen] = useState(false);
+
+const navSections = (
+ <>
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem label="Dashboard" href="/" isSelected />
+ <XDSSideNavItem label="Projects" href="/projects" />
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Settings">
+ <XDSSideNavItem label="General" href="/settings" />
+ <XDSSideNavItem label="Security" href="/security" />
+ </XDSSideNavSection>
+ </>
+);
+
+{
+ isMobile ? (
+ <>
+ <XDSButton
+ label="Menu"
+ icon={<MenuIcon />}
+ variant="ghost"
+ onClick={() => setDrawerOpen(true)}
+ />
+ <XDSMobileNav
+ isOpen={drawerOpen}
+ onClose={() => setDrawerOpen(false)}
+ title="My App">
+ {navSections}
+ </XDSMobileNav>
+ </>
+ ) : (
+ <XDSSideNav>{navSections}</XDSSideNav>
+ );
+}
+```
+
+### With top nav items moving to drawer
+
+When top nav items need to collapse into the mobile drawer:
+
+```tsx
+const isMobile = useMediaQuery('(max-width: 768px)');
+const [drawerOpen, setDrawerOpen] = useState(false);
+
+<XDSTopNav
+ title={<XDSTopNavTitle title="My App" />}
+ startContent={
+ isMobile ? (
+ <XDSButton
+ label="Menu"
+ icon={<MenuIcon />}
+ variant="ghost"
+ onClick={() => setDrawerOpen(true)}
+ />
+ ) : (
+ <>
+ <XDSTopNavItem label="Home" href="/" isSelected />
+ <XDSTopNavItem label="Products" href="/products" />
+ <XDSTopNavItem label="Docs" href="/docs" />
+ </>
+ )
+ }
+/>
+
+<XDSMobileNav isOpen={drawerOpen} onClose={() => setDrawerOpen(false)}>
+ <XDSSideNavSection title="Navigation">
+ <XDSSideNavItem label="Home" href="/" isSelected />
+ <XDSSideNavItem label="Products" href="/products" />
+ <XDSSideNavItem label="Docs" href="/docs" />
+ </XDSSideNavSection>
+</XDSMobileNav>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ------------- | ------------------ | ------- | ------------------------------------------------- |
+| `isOpen` | `boolean` | — | Whether the drawer is open (required) |
+| `onClose` | `() => void` | — | Called on backdrop click, escape, or close button |
+| `children` | `ReactNode` | — | Drawer content (XDSSideNavSection, items, etc.) |
+| `title` | `string` | — | Optional title at the top of the drawer |
+| `width` | `number` | `280` | Drawer width in pixels (capped at 85vw) |
+| `side` | `'start' \| 'end'` | `start` | Which side the drawer slides from |
+| `data-testid` | `string` | — | Test ID for the root element |
+
+## Accessibility
+
+Uses the native `<dialog>` element with `showModal()` for top-layer rendering. The browser provides focus trapping, body scroll lock, and `::backdrop` — no manual z-index needed.
+
+- Native `<dialog>` in top layer (no z-index stacking issues)
+- `aria-label` set to title or "Navigation"
+- Focus trapping via `showModal()` (browser-native)
+- Escape key closes via native `cancel` event
+- Backdrop click closes
+- Body scroll locked while modal is open
+
+## Composition with XDSSideNav
+
+`XDSMobileNav` and `XDSSideNav` are designed to share children. Extract your nav sections into a variable and render them in both:
+
+```tsx
+const sections = (
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem label="Home" href="/" />
+ <XDSSideNavItem label="Settings" href="/settings" />
+ </XDSSideNavSection>
+);
+
+// Desktop: sidebar
+<XDSSideNav>{sections}</XDSSideNav>
+
+// Mobile: drawer
+<XDSMobileNav isOpen={open} onClose={close}>{sections}</XDSMobileNav>
+```
diff --git a/packages/core/src/MobileNav/XDSMobileNav.test.tsx b/packages/core/src/MobileNav/XDSMobileNav.test.tsx
new file mode 100644
index 0000000000..0cee3c26e0
--- /dev/null
+++ b/packages/core/src/MobileNav/XDSMobileNav.test.tsx
@@ -0,0 +1,191 @@
+/**
+ * @file XDSMobileNav.test.tsx
+ * @input Uses vitest, @testing-library/react, XDSMobileNav component
+ * @output Unit tests for XDSMobileNav component behavior
+ * @position Testing; validates XDSMobileNav.tsx implementation
+ *
+ * SYNC: When XDSMobileNav.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi, beforeAll} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {XDSMobileNav} from './XDSMobileNav';
+
+// jsdom doesn't implement showModal/close on <dialog>, so we mock them
+beforeAll(() => {
+ HTMLDialogElement.prototype.showModal =
+ HTMLDialogElement.prototype.showModal ||
+ function (this: HTMLDialogElement) {
+ this.setAttribute('open', '');
+ };
+ HTMLDialogElement.prototype.close =
+ HTMLDialogElement.prototype.close ||
+ function (this: HTMLDialogElement) {
+ this.removeAttribute('open');
+ };
+});
+
+describe('XDSMobileNav', () => {
+ it('renders when isOpen is true', () => {
+ render(
+ <XDSMobileNav isOpen={true} onClose={() => {}}>
+ <span>Nav content</span>
+ </XDSMobileNav>,
+ );
+ expect(screen.getByRole('dialog')).toBeInTheDocument();
+ expect(screen.getByText('Nav content')).toBeInTheDocument();
+ });
+
+ it('does not show dialog as open when isOpen is false', () => {
+ render(
+ <XDSMobileNav isOpen={false} onClose={() => {}} data-testid="mobile-nav">
+ <span>Nav content</span>
+ </XDSMobileNav>,
+ );
+ // The dialog element exists but is not open
+ const dialog = screen.getByTestId('mobile-nav');
+ expect(dialog).toBeInTheDocument();
+ expect(dialog).not.toHaveAttribute('open');
+ });
+
+ it('calls onClose on native cancel event (Escape)', () => {
+ const handleClose = vi.fn();
+ render(
+ <XDSMobileNav isOpen={true} onClose={handleClose}>
+ <span>Content</span>
+ </XDSMobileNav>,
+ );
+
+ // Native <dialog> fires a cancel event on Escape
+ const dialog = screen.getByRole('dialog');
+ const cancelEvent = new Event('cancel', {bubbles: false, cancelable: true});
+ fireEvent(dialog, cancelEvent);
+ expect(handleClose).toHaveBeenCalledTimes(1);
+ });
+
+ it('calls onClose on backdrop click (click on dialog itself)', () => {
+ const handleClose = vi.fn();
+ render(
+ <XDSMobileNav
+ isOpen={true}
+ onClose={handleClose}
+ data-testid="mobile-nav">
+ <span>Content</span>
+ </XDSMobileNav>,
+ );
+
+ // Click directly on the dialog element (the transparent overlay area)
+ const dialog = screen.getByTestId('mobile-nav');
+ fireEvent.click(dialog);
+ expect(handleClose).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not close on drawer content click', () => {
+ const handleClose = vi.fn();
+ render(
+ <XDSMobileNav isOpen={true} onClose={handleClose}>
+ <span>Content</span>
+ </XDSMobileNav>,
+ );
+
+ fireEvent.click(screen.getByText('Content'));
+ expect(handleClose).not.toHaveBeenCalled();
+ });
+
+ it('renders close button', () => {
+ render(
+ <XDSMobileNav isOpen={true} onClose={() => {}}>
+ <span>Content</span>
+ </XDSMobileNav>,
+ );
+
+ const closeButton = screen.getByRole('button', {name: /close/i});
+ expect(closeButton).toBeInTheDocument();
+ });
+
+ it('calls onClose when close button is clicked', () => {
+ const handleClose = vi.fn();
+ render(
+ <XDSMobileNav isOpen={true} onClose={handleClose}>
+ <span>Content</span>
+ </XDSMobileNav>,
+ );
+
+ const closeButton = screen.getByRole('button', {name: /close/i});
+ fireEvent.click(closeButton);
+ expect(handleClose).toHaveBeenCalledTimes(1);
+ });
+
+ it('renders title when provided', () => {
+ render(
+ <XDSMobileNav isOpen={true} onClose={() => {}} title="Navigation">
+ <span>Content</span>
+ </XDSMobileNav>,
+ );
+
+ expect(screen.getByText('Navigation')).toBeInTheDocument();
+ });
+
+ it('forwards data-testid', () => {
+ render(
+ <XDSMobileNav isOpen={true} onClose={() => {}} data-testid="custom-nav">
+ <span>Content</span>
+ </XDSMobileNav>,
+ );
+
+ expect(screen.getByTestId('custom-nav')).toBeInTheDocument();
+ });
+
+ it('uses native dialog element', () => {
+ render(
+ <XDSMobileNav isOpen={true} onClose={() => {}} data-testid="mobile-nav">
+ <span>Content</span>
+ </XDSMobileNav>,
+ );
+
+ const dialog = screen.getByTestId('mobile-nav');
+ expect(dialog.tagName).toBe('DIALOG');
+ });
+
+ it('sets aria-label from title', () => {
+ render(
+ <XDSMobileNav isOpen={true} onClose={() => {}} title="My Nav">
+ <span>Content</span>
+ </XDSMobileNav>,
+ );
+
+ expect(screen.getByRole('dialog')).toHaveAttribute('aria-label', 'My Nav');
+ });
+
+ it('defaults aria-label to Navigation when no title', () => {
+ render(
+ <XDSMobileNav isOpen={true} onClose={() => {}}>
+ <span>Content</span>
+ </XDSMobileNav>,
+ );
+
+ expect(screen.getByRole('dialog')).toHaveAttribute(
+ 'aria-label',
+ 'Navigation',
+ );
+ });
+
+ it('opens dialog via showModal when isOpen becomes true', () => {
+ const {rerender} = render(
+ <XDSMobileNav isOpen={false} onClose={() => {}} data-testid="mobile-nav">
+ <span>Content</span>
+ </XDSMobileNav>,
+ );
+
+ const dialog = screen.getByTestId('mobile-nav');
+ expect(dialog).not.toHaveAttribute('open');
+
+ rerender(
+ <XDSMobileNav isOpen={true} onClose={() => {}} data-testid="mobile-nav">
+ <span>Content</span>
+ </XDSMobileNav>,
+ );
+
+ expect(dialog).toHaveAttribute('open');
+ });
+});
diff --git a/packages/core/src/MobileNav/XDSMobileNav.tsx b/packages/core/src/MobileNav/XDSMobileNav.tsx
new file mode 100644
index 0000000000..66c4555750
--- /dev/null
+++ b/packages/core/src/MobileNav/XDSMobileNav.tsx
@@ -0,0 +1,371 @@
+/**
+ * @file XDSMobileNav.tsx
+ * @input Uses React forwardRef, useEffect, useRef, useCallback, ReactNode, StyleX
+ * @output Exports XDSMobileNav component and XDSMobileNavProps
+ * @position Core implementation; consumed by index.ts
+ *
+ * Full-height slide-out drawer overlay for mobile navigation.
+ * The mobile counterpart to XDSSideNav — accepts the same children
+ * (XDSSideNavSection, XDSSideNavItem, or any ReactNode).
+ *
+ * Uses the native `<dialog>` element with `showModal()` for top-layer rendering.
+ * This eliminates z-index stacking issues — the drawer renders above everything
+ * without manual z-index management. The browser provides:
+ * - Top layer promotion (no z-index needed)
+ * - `::backdrop` pseudo-element
+ * - Body scroll lock
+ * - Focus trapping
+ * - Escape key handling via `cancel` event
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/MobileNav/index.ts (exports if types change)
+ */
+
+'use client';
+
+import {
+ forwardRef,
+ useCallback,
+ useContext,
+ useEffect,
+ useRef,
+ type ReactNode,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars, spacingVars} from '../theme/tokens.stylex';
+import {ThemeContext} from '../theme/ThemeContext';
+import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {XDSButton} from '../Button';
+import {XDSIcon} from '../Icon';
+import {XDSHeading} from '../Text/XDSHeading';
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const SLIDE_DURATION = '0.25s';
+const SLIDE_EASING = 'cubic-bezier(0.4, 0, 0.2, 1)';
+
+const styles = stylex.create({
+ dialog: {
+ // Reset native <dialog> defaults
+ position: 'fixed',
+ margin: 0,
+ padding: 0,
+ border: 'none',
+ maxWidth: 'none',
+ maxHeight: 'none',
+ // Full viewport overlay — the dialog itself is the full-screen container
+ inset: 0,
+ width: '100vw',
+ height: '100dvh',
+ backgroundColor: 'transparent',
+ overflow: 'hidden',
+ outline: 'none',
+ // Native <dialog> uses display:none when closed — we preserve that
+ // by only setting display when [open] via :where() selector.
+ // This prevents the dialog from blocking pointer events when closed.
+ display: {
+ default: 'none',
+ ':where([open])': 'flex',
+ },
+ },
+ // ::backdrop is provided by the browser's top layer
+ backdrop: {
+ '::backdrop': {
+ backgroundColor: colorVars['--color-overlay'],
+ opacity: 0,
+ transition: `opacity ${SLIDE_DURATION} ${SLIDE_EASING}`,
+ },
+ '@media (prefers-reduced-motion: reduce)': {
+ '::backdrop': {
+ transitionDuration: '0.01s',
+ },
+ },
+ },
+ backdropOpen: {
+ '::backdrop': {
+ opacity: 1,
+ },
+ },
+ drawer: {
+ position: 'absolute',
+ top: 0,
+ bottom: 0,
+ display: 'flex',
+ flexDirection: 'column',
+ backgroundColor: colorVars['--color-surface'],
+ boxSizing: 'border-box',
+ overflow: 'hidden',
+ transition: `transform ${SLIDE_DURATION} ${SLIDE_EASING}`,
+ outline: 'none',
+ '@media (prefers-reduced-motion: reduce)': {
+ transitionDuration: '0.01s',
+ },
+ },
+ drawerStart: {
+ insetInlineStart: 0,
+ borderInlineEndWidth: 1,
+ borderInlineEndStyle: 'solid',
+ borderInlineEndColor: colorVars['--color-divider'],
+ transform: {
+ default: 'translateX(-100%)',
+ ':is([dir="rtl"] *)': 'translateX(100%)',
+ },
+ },
+ drawerStartOpen: {
+ transform: 'translateX(0)',
+ },
+ drawerEnd: {
+ insetInlineEnd: 0,
+ borderInlineStartWidth: 1,
+ borderInlineStartStyle: 'solid',
+ borderInlineStartColor: colorVars['--color-divider'],
+ transform: {
+ default: 'translateX(100%)',
+ ':is([dir="rtl"] *)': 'translateX(-100%)',
+ },
+ },
+ drawerEndOpen: {
+ transform: 'translateX(0)',
+ },
+ header: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'space-between',
+ paddingInline: spacingVars['--spacing-2'],
+ paddingBlock: spacingVars['--spacing-2'],
+ flexShrink: 0,
+ borderBlockEndWidth: 1,
+ borderBlockEndStyle: 'solid',
+ borderBlockEndColor: colorVars['--color-divider'],
+ },
+ headerNoTitle: {
+ justifyContent: 'flex-end',
+ },
+ content: {
+ flex: 1,
+ overflowY: 'auto',
+ overflowX: 'hidden',
+ paddingInline: spacingVars['--spacing-2'],
+ paddingBlock: spacingVars['--spacing-1'],
+ },
+});
+
+const dynamicStyles = stylex.create({
+ width: (w: number) => ({
+ width: `${w}px`,
+ maxWidth: '85vw',
+ }),
+});
+
+// =============================================================================
+// Module Augmentation
+// =============================================================================
+
+declare module '../theme/types' {
+ interface ComponentStyles {
+ mobileNav?: {
+ /** Root dialog styles */
+ root?: ThemeStyleXStyles;
+ /** Drawer panel styles */
+ drawer?: ThemeStyleXStyles;
+ };
+ }
+}
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface XDSMobileNavProps {
+ /**
+ * Whether the drawer is open.
+ */
+ isOpen: boolean;
+
+ /**
+ * Called when the drawer should close (backdrop click, escape, close button).
+ */
+ onClose: () => void;
+
+ /**
+ * Drawer content — typically XDSSideNavSection/XDSSideNavItem, or any ReactNode.
+ */
+ children: ReactNode;
+
+ /**
+ * Optional title shown at the top of the drawer.
+ */
+ title?: string;
+
+ /**
+ * Width of the drawer in pixels.
+ * @default 280
+ */
+ width?: number;
+
+ /**
+ * Which side the drawer slides from.
+ * @default 'start'
+ */
+ side?: 'start' | 'end';
+
+ /**
+ * Test ID for the root element.
+ */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * A slide-out drawer overlay for mobile navigation.
+ *
+ * The mobile counterpart to XDSSideNav. Renders a full-height drawer that slides
+ * in from the start (left in LTR) or end (right in LTR) edge of the viewport,
+ * with a semi-transparent backdrop behind it.
+ *
+ * Uses the native `<dialog>` element with `showModal()` for top-layer rendering,
+ * which provides built-in focus trapping, body scroll lock, and `::backdrop`.
+ * No manual z-index needed — the browser's top layer handles stacking.
+ *
+ * @example
+ * ```tsx
+ * const [isOpen, setIsOpen] = useState(false);
+ *
+ * <XDSButton label="Menu" onClick={() => setIsOpen(true)} />
+ *
+ * <XDSMobileNav
+ * isOpen={isOpen}
+ * onClose={() => setIsOpen(false)}
+ * title="Navigation"
+ * >
+ * <XDSSideNavSection title="Main">
+ * <XDSSideNavItem label="Home" icon={HomeIcon} isSelected href="/" />
+ * <XDSSideNavItem label="Settings" icon={SettingsIcon} href="/settings" />
+ * </XDSSideNavSection>
+ * </XDSMobileNav>
+ * ```
+ */
+export const XDSMobileNav = forwardRef<HTMLDialogElement, XDSMobileNavProps>(
+ function XDSMobileNav(
+ {
+ isOpen,
+ onClose,
+ children,
+ title,
+ width = 280,
+ side = 'start',
+ 'data-testid': testId,
+ },
+ ref,
+ ) {
+ const dialogRef = useRef<HTMLDialogElement>(null);
+
+ // Merge refs
+ const setRefs = useCallback(
+ (element: HTMLDialogElement | null) => {
+ (
+ dialogRef as React.MutableRefObject<HTMLDialogElement | null>
+ ).current = element;
+ if (typeof ref === 'function') {
+ ref(element);
+ } else if (ref) {
+ ref.current = element;
+ }
+ },
+ [ref],
+ );
+
+ // Open/close the dialog via showModal()/close()
+ useEffect(() => {
+ const dialog = dialogRef.current;
+ if (!dialog) return;
+
+ if (isOpen) {
+ if (!dialog.open) {
+ dialog.showModal();
+ }
+ } else {
+ if (dialog.open) {
+ dialog.close();
+ }
+ }
+ }, [isOpen]);
+
+ // Handle native cancel event (Escape key) — prevent default and route through onClose
+ const handleCancel = useCallback(
+ (event: React.SyntheticEvent<HTMLDialogElement>) => {
+ event.preventDefault();
+ onClose();
+ },
+ [onClose],
+ );
+
+ // Handle clicks on the dialog backdrop area (outside the drawer)
+ const handleDialogClick = useCallback(
+ (event: React.MouseEvent<HTMLDialogElement>) => {
+ // Only close if click was directly on the dialog element (the transparent overlay),
+ // not on the drawer or its children
+ if (event.target === event.currentTarget) {
+ onClose();
+ }
+ },
+ [onClose],
+ );
+
+ // Get theme context for component-level overrides
+ const themeContext = useContext(ThemeContext);
+ const rootOverride = themeContext?.theme.components?.mobileNav?.root;
+ const drawerOverride = themeContext?.theme.components?.mobileNav?.drawer;
+
+ const isStart = side === 'start';
+
+ return (
+ <dialog
+ ref={setRefs}
+ data-testid={testId}
+ aria-label={title ?? 'Navigation'}
+ onClick={handleDialogClick}
+ onCancel={handleCancel}
+ {...stylex.props(
+ styles.dialog,
+ styles.backdrop,
+ isOpen && styles.backdropOpen,
+ rootOverride,
+ )}>
+ {/* Drawer panel */}
+ <div
+ {...stylex.props(
+ styles.drawer,
+ dynamicStyles.width(width),
+ isStart && styles.drawerStart,
+ isStart && isOpen && styles.drawerStartOpen,
+ !isStart && styles.drawerEnd,
+ !isStart && isOpen && styles.drawerEndOpen,
+ drawerOverride,
+ )}>
+ {/* Header with optional title and close button */}
+ <div {...stylex.props(styles.header, !title && styles.headerNoTitle)}>
+ {title && <XDSHeading level={2}>{title}</XDSHeading>}
+ <XDSButton
+ variant="ghost"
+ label="Close navigation"
+ tooltip="Close"
+ icon={<XDSIcon icon="close" color="inherit" />}
+ onClick={onClose}
+ />
+ </div>
+
+ {/* Scrollable content */}
+ <div {...stylex.props(styles.content)}>{children}</div>
+ </div>
+ </dialog>
+ );
+ },
+);
+
+XDSMobileNav.displayName = 'XDSMobileNav';
diff --git a/packages/core/src/MobileNav/index.ts b/packages/core/src/MobileNav/index.ts
new file mode 100644
index 0000000000..1b01e7f7a7
--- /dev/null
+++ b/packages/core/src/MobileNav/index.ts
@@ -0,0 +1,9 @@
+/**
+ * @file index.ts
+ * @input Imports from XDSMobileNav.tsx
+ * @output Re-exports XDSMobileNav component and XDSMobileNavProps type
+ * @position Barrel export; consumed by packages/core/src/index.ts
+ */
+
+export {XDSMobileNav} from './XDSMobileNav';
+export type {XDSMobileNavProps} from './XDSMobileNav';
diff --git a/packages/core/src/hooks/index.ts b/packages/core/src/hooks/index.ts
index bb6bd9d9b4..0de3772e86 100644
--- a/packages/core/src/hooks/index.ts
+++ b/packages/core/src/hooks/index.ts
@@ -15,3 +15,5 @@ export type {UseGridFocusOptions, UseGridFocusReturn} from './useGridFocus';
export {useListFocus} from './useListFocus';
export type {UseListFocusOptions, UseListFocusReturn} from './useListFocus';
+
+export {useMediaQuery} from './useMediaQuery';
diff --git a/packages/core/src/hooks/useMediaQuery.test.ts b/packages/core/src/hooks/useMediaQuery.test.ts
new file mode 100644
index 0000000000..5e89c662a0
--- /dev/null
+++ b/packages/core/src/hooks/useMediaQuery.test.ts
@@ -0,0 +1,116 @@
+/**
+ * @file useMediaQuery.test.ts
+ * @input Uses vitest, @testing-library/react, useMediaQuery hook
+ * @output Unit tests for useMediaQuery hook
+ * @position Testing; validates useMediaQuery.ts implementation
+ *
+ * SYNC: When useMediaQuery.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {renderHook, act} from '@testing-library/react';
+import {useMediaQuery} from './useMediaQuery';
+
+// Mock matchMedia
+function createMockMatchMedia(matches: boolean) {
+ const listeners: Array<(e: MediaQueryListEvent) => void> = [];
+ return {
+ matches,
+ media: '',
+ onchange: null,
+ addEventListener: vi.fn(
+ (_event: string, handler: (e: MediaQueryListEvent) => void) => {
+ listeners.push(handler);
+ },
+ ),
+ removeEventListener: vi.fn(
+ (_event: string, handler: (e: MediaQueryListEvent) => void) => {
+ const index = listeners.indexOf(handler);
+ if (index > -1) listeners.splice(index, 1);
+ },
+ ),
+ dispatchEvent: vi.fn(),
+ // Helper to simulate media query change
+ _triggerChange(newMatches: boolean) {
+ this.matches = newMatches;
+ listeners.forEach(fn => fn({matches: newMatches} as MediaQueryListEvent));
+ },
+ _listeners: listeners,
+ };
+}
+
+describe('useMediaQuery', () => {
+ let mockMql: ReturnType<typeof createMockMatchMedia>;
+
+ beforeEach(() => {
+ mockMql = createMockMatchMedia(false);
+ vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+ });
+
+ it('returns false on initial render (SSR-safe)', () => {
+ const {result} = renderHook(() => useMediaQuery('(max-width: 768px)'));
+ // Before the effect runs, should be false
+ expect(result.current).toBe(false);
+ });
+
+ it('syncs with matchMedia on mount', () => {
+ mockMql = createMockMatchMedia(true);
+ vi.stubGlobal('matchMedia', vi.fn().mockReturnValue(mockMql));
+
+ const {result} = renderHook(() => useMediaQuery('(max-width: 768px)'));
+ // After effect, should match the mql state
+ expect(result.current).toBe(true);
+ });
+
+ it('updates when media query changes', () => {
+ const {result} = renderHook(() => useMediaQuery('(max-width: 768px)'));
+ expect(result.current).toBe(false);
+
+ act(() => {
+ mockMql._triggerChange(true);
+ });
+ expect(result.current).toBe(true);
+
+ act(() => {
+ mockMql._triggerChange(false);
+ });
+ expect(result.current).toBe(false);
+ });
+
+ it('passes the query string to matchMedia', () => {
+ renderHook(() => useMediaQuery('(min-width: 1024px)'));
+ expect(window.matchMedia).toHaveBeenCalledWith('(min-width: 1024px)');
+ });
+
+ it('cleans up event listener on unmount', () => {
+ const {unmount} = renderHook(() => useMediaQuery('(max-width: 768px)'));
+ expect(mockMql.addEventListener).toHaveBeenCalledWith(
+ 'change',
+ expect.any(Function),
+ );
+
+ unmount();
+ expect(mockMql.removeEventListener).toHaveBeenCalledWith(
+ 'change',
+ expect.any(Function),
+ );
+ });
+
+ it('re-subscribes when query changes', () => {
+ const mockMql2 = createMockMatchMedia(true);
+ const matchMediaFn = vi.fn().mockReturnValue(mockMql);
+ vi.stubGlobal('matchMedia', matchMediaFn);
+
+ const {result, rerender} = renderHook(
+ ({query}: {query: string}) => useMediaQuery(query),
+ {initialProps: {query: '(max-width: 768px)'}},
+ );
+ expect(result.current).toBe(false);
+
+ // Change query
+ matchMediaFn.mockReturnValue(mockMql2);
+ rerender({query: '(max-width: 1024px)'});
+ expect(result.current).toBe(true);
+ expect(matchMediaFn).toHaveBeenCalledWith('(max-width: 1024px)');
+ });
+});
diff --git a/packages/core/src/hooks/useMediaQuery.ts b/packages/core/src/hooks/useMediaQuery.ts
new file mode 100644
index 0000000000..500595f120
--- /dev/null
+++ b/packages/core/src/hooks/useMediaQuery.ts
@@ -0,0 +1,37 @@
+/**
+ * @file useMediaQuery.ts
+ * @input Uses React useState, useEffect
+ * @output Exports useMediaQuery hook for responsive breakpoint detection
+ * @position Core hook; used by consumers for responsive patterns
+ *
+ * SSR-safe media query hook that subscribes to window.matchMedia changes.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ */
+
+import {useState, useEffect} from 'react';
+
+/**
+ * SSR-safe media query hook.
+ * Returns whether the given media query matches.
+ *
+ * @example
+ * ```tsx
+ * const isMobile = useMediaQuery('(max-width: 768px)');
+ * const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
+ * ```
+ */
+export function useMediaQuery(query: string): boolean {
+ const [matches, setMatches] = useState(false); // Always false on first render (SSR-safe)
+
+ useEffect(() => {
+ const mql = window.matchMedia(query);
+ setMatches(mql.matches); // Sync on mount
+ const handler = (e: MediaQueryListEvent) => setMatches(e.matches);
+ mql.addEventListener('change', handler);
+ return () => mql.removeEventListener('change', handler);
+ }, [query]);
+
+ return matches;
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 47e747d718..b171d9d86f 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -48,6 +48,7 @@ export * from './Dialog';
export * from './DropdownMenu';
export * from './TopNav';
export * from './SideNav';
+export * from './MobileNav';
export * from './ProgressBar';
// Layout utilities and components (includes XDSHStack, XDSVStack)
diff --git a/packages/themes/default/src/icons.tsx b/packages/themes/default/src/icons.tsx
index 8849c85f3c..ca6e286100 100644
--- a/packages/themes/default/src/icons.tsx
+++ b/packages/themes/default/src/icons.tsx
@@ -20,6 +20,7 @@ import {
CalendarDaysIcon,
ClockIcon,
InformationCircleIcon,
+ Bars3Icon,
} from '@heroicons/react/24/outline';
import {
@@ -48,4 +49,5 @@ export const defaultIconRegistry: XDSIconRegistry = {
calendar: <CalendarDaysIcon {...iconProps} />,
clock: <ClockIcon {...iconProps} />,
externalLink: <ArrowTopRightOnSquareIcon {...iconProps} />,
+ menu: <Bars3Icon {...iconProps} />,
};
diff --git a/packages/themes/neutral/src/icons.tsx b/packages/themes/neutral/src/icons.tsx
index b9d3eb702f..eb7d65d1b9 100644
--- a/packages/themes/neutral/src/icons.tsx
+++ b/packages/themes/neutral/src/icons.tsx
@@ -24,6 +24,7 @@ import {
Calendar,
Clock,
ExternalLink,
+ Menu,
} from 'lucide-react';
const iconProps = {
@@ -44,4 +45,5 @@ export const neutralIconRegistry: XDSIconRegistry = {
calendar: <Calendar {...iconProps} />,
clock: <Clock {...iconProps} />,
externalLink: <ExternalLink {...iconProps} />,
+ menu: <Menu {...iconProps} />,
};