Skip to content

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

TypeScript

feat(PageNav): add XDSPageNav component with header, items, and sections (#251)

Cindy Zhangc2e3266c3855
diff --git a/apps/storybook/stories/PageNav.stories.tsx b/apps/storybook/stories/PageNav.stories.tsx
new file mode 100644
index 0000000000..57bca33983
--- /dev/null
+++ b/apps/storybook/stories/PageNav.stories.tsx
@@ -0,0 +1,356 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import {
+ XDSPageNav,
+ XDSPageNavHeader,
+ XDSPageNavItem,
+ XDSPageNavSection,
+} from '@xds/core/PageNav';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSButton} from '@xds/core/Button';
+import {XDSDivider} from '@xds/core/Divider';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSText} from '@xds/core/Text';
+import {XDSVStack} from '@xds/core/Stack';
+import {
+ HomeIcon,
+ FolderIcon,
+ Cog6ToothIcon,
+ ChartBarIcon,
+ UserGroupIcon,
+ BellIcon,
+ QuestionMarkCircleIcon,
+ DocumentTextIcon,
+ CubeIcon,
+ BuildingOfficeIcon,
+ UserIcon,
+ PlusIcon,
+ ArrowRightStartOnRectangleIcon,
+} from '@heroicons/react/24/outline';
+import {
+ HomeIcon as HomeIconSolid,
+ FolderIcon as FolderIconSolid,
+} from '@heroicons/react/24/solid';
+
+const meta: Meta<typeof XDSPageNav> = {
+ title: 'Navigation/XDSPageNav',
+ component: XDSPageNav,
+ tags: ['autodocs'],
+ parameters: {
+ layout: 'centered',
+ },
+ decorators: [
+ Story => (
+ <div style={{width: 280, height: 600, border: '1px solid #e5e7eb'}}>
+ <Story />
+ </div>
+ ),
+ ],
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSPageNav>;
+
+// =============================================================================
+// Basic
+// =============================================================================
+
+export const Default: Story = {
+ render: () => (
+ <XDSPageNav
+ header={
+ <XDSPageNavHeader
+ icon={<XDSIcon icon={CubeIcon} size="lg" />}
+ title="My App"
+ titleHref="/"
+ />
+ }>
+ <XDSPageNavSection title="Main">
+ <XDSPageNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ href="/dashboard"
+ />
+ <XDSPageNavItem
+ label="Projects"
+ icon={FolderIcon}
+ selectedIcon={FolderIconSolid}
+ href="/projects"
+ endContent={<XDSBadge label="3" />}
+ />
+ <XDSPageNavItem
+ label="Analytics"
+ icon={ChartBarIcon}
+ href="/analytics"
+ />
+ <XDSPageNavItem label="Team" icon={UserGroupIcon} href="/team" />
+ </XDSPageNavSection>
+ <XDSPageNavSection title="Documents">
+ <XDSPageNavItem
+ label="All Documents"
+ icon={DocumentTextIcon}
+ href="/documents"
+ />
+ </XDSPageNavSection>
+ </XDSPageNav>
+ ),
+};
+
+// =============================================================================
+// With Header Menu
+// =============================================================================
+
+export const WithHeaderMenu: Story = {
+ name: 'Header with Menu',
+ render: () => (
+ <XDSPageNav
+ header={
+ <XDSPageNavHeader
+ icon={<XDSIcon icon={CubeIcon} size="lg" />}
+ title="Product Name"
+ subtitle="Business Account"
+ menu={
+ <div style={{padding: 12}}>
+ <XDSVStack gap="space2">
+ <XDSText type="supporting" color="secondary">
+ Switch account
+ </XDSText>
+ <XDSButton
+ label="Personal Account"
+ icon={<XDSIcon icon={UserIcon} size="sm" />}
+ variant="ghost"
+ size="sm"
+ />
+ <XDSButton
+ label="Acme Corp"
+ icon={<XDSIcon icon={BuildingOfficeIcon} size="sm" />}
+ variant="ghost"
+ size="sm"
+ />
+ <XDSDivider />
+ <XDSButton
+ label="Add account"
+ icon={<XDSIcon icon={PlusIcon} size="sm" />}
+ variant="ghost"
+ size="sm"
+ />
+ <XDSButton
+ label="Sign out"
+ icon={
+ <XDSIcon icon={ArrowRightStartOnRectangleIcon} size="sm" />
+ }
+ variant="ghost"
+ size="sm"
+ />
+ </XDSVStack>
+ </div>
+ }
+ />
+ }>
+ <XDSPageNavSection title="Navigation">
+ <XDSPageNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ />
+ <XDSPageNavItem label="Settings" icon={Cog6ToothIcon} />
+ </XDSPageNavSection>
+ </XDSPageNav>
+ ),
+};
+
+// =============================================================================
+// Suite Header
+// =============================================================================
+
+export const SuiteHeader: Story = {
+ name: 'Suite with Independent Links',
+ render: () => (
+ <XDSPageNav
+ header={
+ <XDSPageNavHeader
+ icon={<XDSIcon icon={CubeIcon} size="lg" />}
+ supertitle="Suite Name"
+ supertitleHref="/suite"
+ title="Product Name"
+ titleHref="/product"
+ menu={
+ <div style={{padding: 12}}>
+ <XDSVStack gap="space1">
+ <XDSText type="supporting" color="secondary">
+ Switch product
+ </XDSText>
+ <XDSButton
+ label="Analytics"
+ icon={<XDSIcon icon={ChartBarIcon} size="sm" />}
+ variant="ghost"
+ size="sm"
+ />
+ <XDSButton
+ label="Commerce"
+ icon={<XDSIcon icon={CubeIcon} size="sm" />}
+ variant="ghost"
+ size="sm"
+ />
+ <XDSButton
+ label="Team Hub"
+ icon={<XDSIcon icon={UserGroupIcon} size="sm" />}
+ variant="ghost"
+ size="sm"
+ />
+ </XDSVStack>
+ </div>
+ }
+ />
+ }>
+ <XDSPageNavSection title="Main">
+ <XDSPageNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ />
+ <XDSPageNavItem label="Projects" icon={FolderIcon} />
+ </XDSPageNavSection>
+ </XDSPageNav>
+ ),
+};
+
+// =============================================================================
+// Nested Items
+// =============================================================================
+
+export const NestedItems: Story = {
+ name: 'Nested Items',
+ render: () => (
+ <XDSPageNav
+ header={
+ <XDSPageNavHeader
+ icon={<XDSIcon icon={CubeIcon} size="lg" />}
+ title="My App"
+ />
+ }>
+ <XDSPageNavSection title="Main">
+ <XDSPageNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ />
+ <XDSPageNavItem label="Settings" icon={Cog6ToothIcon}>
+ <XDSPageNavItem label="General" href="/settings/general" />
+ <XDSPageNavItem label="Security" href="/settings/security" />
+ <XDSPageNavItem
+ label="Notifications"
+ href="/settings/notifications"
+ />
+ </XDSPageNavItem>
+ </XDSPageNavSection>
+ </XDSPageNav>
+ ),
+};
+
+// =============================================================================
+// With Footer
+// =============================================================================
+
+export const WithFooter: Story = {
+ name: 'With Footer Icons',
+ render: () => (
+ <XDSPageNav
+ header={
+ <XDSPageNavHeader
+ icon={<XDSIcon icon={CubeIcon} size="lg" />}
+ title="My App"
+ />
+ }
+ footerIcons={
+ <>
+ <XDSButton
+ label="Help"
+ icon={<XDSIcon icon={QuestionMarkCircleIcon} size="md" />}
+ variant="ghost"
+ size="sm"
+ />
+ <XDSButton
+ label="Notifications"
+ icon={<XDSIcon icon={BellIcon} size="md" />}
+ variant="ghost"
+ size="sm"
+ />
+ </>
+ }>
+ <XDSPageNavSection title="Main">
+ <XDSPageNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ />
+ <XDSPageNavItem label="Projects" icon={FolderIcon} />
+ </XDSPageNavSection>
+ </XDSPageNav>
+ ),
+};
+
+// =============================================================================
+// Disabled Item
+// =============================================================================
+
+export const DisabledItem: Story = {
+ name: 'Disabled Items',
+ render: () => (
+ <XDSPageNav
+ header={
+ <XDSPageNavHeader
+ icon={<XDSIcon icon={CubeIcon} size="lg" />}
+ title="My App"
+ />
+ }>
+ <XDSPageNavSection title="Main">
+ <XDSPageNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ />
+ <XDSPageNavItem label="Projects" icon={FolderIcon} />
+ <XDSPageNavItem
+ label="Analytics (Coming Soon)"
+ icon={ChartBarIcon}
+ isDisabled
+ />
+ </XDSPageNavSection>
+ </XDSPageNav>
+ ),
+};
+
+// =============================================================================
+// Hidden Section Header
+// =============================================================================
+
+export const HiddenSectionHeader: Story = {
+ name: 'Hidden Section Header',
+ render: () => (
+ <XDSPageNav
+ header={
+ <XDSPageNavHeader
+ icon={<XDSIcon icon={CubeIcon} size="lg" />}
+ title="My App"
+ />
+ }>
+ <XDSPageNavSection title="Main navigation" isHeaderHidden>
+ <XDSPageNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ />
+ <XDSPageNavItem label="Projects" icon={FolderIcon} />
+ <XDSPageNavItem label="Analytics" icon={ChartBarIcon} />
+ </XDSPageNavSection>
+ </XDSPageNav>
+ ),
+};
diff --git a/packages/core/src/PageNav/README.md b/packages/core/src/PageNav/README.md
new file mode 100644
index 0000000000..c7269c1602
--- /dev/null
+++ b/packages/core/src/PageNav/README.md
@@ -0,0 +1,81 @@
+# PageNav
+
+Sidebar navigation component for application pages. Supports sections, nested items, selected state, icons, and responsive collapse.
+
+## Components
+
+| Component | Description |
+| ------------------- | ----------------------------------------------------------------------------------------- |
+| `XDSPageNav` | Container with five zones: header, topContent, children (scrollable), footer, footerIcons |
+| `XDSPageNavHeader` | Product/suite/account header with smart interaction boundary logic |
+| `XDSPageNavItem` | Navigation item with icon, selected state, and nesting |
+| `XDSPageNavSection` | Section grouping with optional title and end content |
+
+## Files
+
+| File | Purpose |
+| ----------------------- | ------------------------------------------ |
+| `XDSPageNav.tsx` | Container component |
+| `XDSPageNavHeader.tsx` | Header component with popover menu support |
+| `XDSPageNavItem.tsx` | Navigation item component |
+| `XDSPageNavSection.tsx` | Section grouping component |
+| `XDSPageNav.test.tsx` | Unit tests |
+| `index.ts` | Public exports |
+
+## Usage
+
+```tsx
+import {
+ XDSPageNav,
+ XDSPageNavHeader,
+ XDSPageNavItem,
+ XDSPageNavSection,
+} from '@xds/core/PageNav';
+
+<XDSPageNav
+ header={<XDSPageNavHeader icon={<AppIcon />} title="My App" titleHref="/" />}
+ topContent={<XDSButton label="Create new" variant="primary" />}
+ footerIcons={<XDSButton icon={HelpIcon} variant="ghost" label="Help" />}>
+ <XDSPageNavSection title="Main">
+ <XDSPageNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ href="/dashboard"
+ />
+ <XDSPageNavItem
+ label="Projects"
+ icon={FolderIcon}
+ href="/projects"
+ endContent={<XDSBadge label="3" />}
+ />
+ </XDSPageNavSection>
+
+ <XDSPageNavSection title="Settings">
+ <XDSPageNavItem label="General" href="/settings/general" />
+ <XDSPageNavItem label="Security" href="/settings/security" />
+ </XDSPageNavSection>
+</XDSPageNav>;
+```
+
+## Header Interaction Model
+
+| Props provided | Behavior |
+| --------------------------------------- | -------------------------------------------------------------- |
+| `titleHref` only, no menu | Whole header is one link |
+| `titleHref` + `supertitleHref`, no menu | Each text is an independent link |
+| `menu` only, no hrefs | Whole header is the popover trigger |
+| `menu` + hrefs | Links are independent `<a>`, chevron/remaining area is trigger |
+
+## Accessibility
+
+- `<nav aria-label="Page navigation">`
+- `aria-current="page"` on selected item
+- Sections: `role="group"` with `aria-labelledby`
+- Keyboard: Tab through items, Enter/Space to activate
+
+## Dependencies
+
+- `useXDSPopover` — for header menu popover
+- `XDSIcon` — for rendering icon components in nav items
diff --git a/packages/core/src/PageNav/XDSPageNav.test.tsx b/packages/core/src/PageNav/XDSPageNav.test.tsx
new file mode 100644
index 0000000000..f440e81116
--- /dev/null
+++ b/packages/core/src/PageNav/XDSPageNav.test.tsx
@@ -0,0 +1,388 @@
+/**
+ * @file XDSPageNav.test.tsx
+ * @input Uses vitest, @testing-library/react, PageNav components
+ * @output Unit tests for XDSPageNav component suite
+ * @position Testing; validates PageNav implementations
+ *
+ * SYNC: When PageNav components change, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {XDSPageNav} from './XDSPageNav';
+import {XDSPageNavHeader} from './XDSPageNavHeader';
+import {XDSPageNavItem} from './XDSPageNavItem';
+import {XDSPageNavSection} from './XDSPageNavSection';
+
+// =============================================================================
+// XDSPageNav
+// =============================================================================
+
+describe('XDSPageNav', () => {
+ it('renders with navigation role', () => {
+ render(<XDSPageNav>Content</XDSPageNav>);
+ expect(screen.getByRole('navigation')).toBeInTheDocument();
+ });
+
+ it('renders aria-label for page navigation', () => {
+ render(<XDSPageNav>Content</XDSPageNav>);
+ expect(screen.getByRole('navigation')).toHaveAttribute(
+ 'aria-label',
+ 'Page navigation',
+ );
+ });
+
+ it('renders children in scrollable area', () => {
+ render(
+ <XDSPageNav>
+ <span data-testid="nav-content">Nav items</span>
+ </XDSPageNav>,
+ );
+ expect(screen.getByTestId('nav-content')).toBeInTheDocument();
+ });
+
+ it('renders header slot', () => {
+ render(
+ <XDSPageNav header={<span data-testid="header">Header</span>}>
+ Content
+ </XDSPageNav>,
+ );
+ expect(screen.getByTestId('header')).toBeInTheDocument();
+ });
+
+ it('renders topContent slot', () => {
+ render(
+ <XDSPageNav topContent={<span data-testid="sticky">Sticky</span>}>
+ Content
+ </XDSPageNav>,
+ );
+ expect(screen.getByTestId('sticky')).toBeInTheDocument();
+ });
+
+ it('renders footer slot', () => {
+ render(
+ <XDSPageNav footer={<span data-testid="footer">Footer</span>}>
+ Content
+ </XDSPageNav>,
+ );
+ expect(screen.getByTestId('footer')).toBeInTheDocument();
+ });
+
+ it('renders footerIcons slot', () => {
+ render(
+ <XDSPageNav footerIcons={<span data-testid="footer-icons">Icons</span>}>
+ Content
+ </XDSPageNav>,
+ );
+ expect(screen.getByTestId('footer-icons')).toBeInTheDocument();
+ });
+
+ it('renders all slots together', () => {
+ render(
+ <XDSPageNav
+ header={<span data-testid="header">Header</span>}
+ topContent={<span data-testid="sticky">Sticky</span>}
+ footer={<span data-testid="footer">Footer</span>}
+ footerIcons={<span data-testid="icons">Icons</span>}>
+ <span data-testid="content">Content</span>
+ </XDSPageNav>,
+ );
+ expect(screen.getByTestId('header')).toBeInTheDocument();
+ expect(screen.getByTestId('sticky')).toBeInTheDocument();
+ expect(screen.getByTestId('content')).toBeInTheDocument();
+ expect(screen.getByTestId('footer')).toBeInTheDocument();
+ expect(screen.getByTestId('icons')).toBeInTheDocument();
+ });
+
+ it('forwards ref correctly', () => {
+ const ref = vi.fn();
+ render(<XDSPageNav ref={ref}>Content</XDSPageNav>);
+ expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));
+ });
+
+ it('passes data-testid to root', () => {
+ render(<XDSPageNav data-testid="page-nav">Content</XDSPageNav>);
+ expect(screen.getByTestId('page-nav')).toBeInTheDocument();
+ });
+});
+
+// =============================================================================
+// XDSPageNavHeader
+// =============================================================================
+
+describe('XDSPageNavHeader', () => {
+ it('renders title text', () => {
+ render(<XDSPageNavHeader title="My App" />);
+ expect(screen.getByText('My App')).toBeInTheDocument();
+ });
+
+ it('renders icon', () => {
+ render(
+ <XDSPageNavHeader
+ title="My App"
+ icon={<span data-testid="app-icon">🏠</span>}
+ />,
+ );
+ expect(screen.getByTestId('app-icon')).toBeInTheDocument();
+ });
+
+ it('renders supertitle', () => {
+ render(<XDSPageNavHeader title="Product" supertitle="Suite Name" />);
+ expect(screen.getByText('Suite Name')).toBeInTheDocument();
+ });
+
+ it('renders subtitle', () => {
+ render(<XDSPageNavHeader title="Product" subtitle="Account" />);
+ expect(screen.getByText('Account')).toBeInTheDocument();
+ });
+
+ it('renders as link when titleHref is provided without menu', () => {
+ render(<XDSPageNavHeader title="My App" titleHref="/home" />);
+ const link = screen.getByRole('link');
+ expect(link).toHaveAttribute('href', '/home');
+ expect(link).toHaveTextContent('My App');
+ });
+
+ it('renders independent links when titleHref and supertitleHref are provided', () => {
+ render(
+ <XDSPageNavHeader
+ title="Product"
+ titleHref="/product"
+ supertitle="Suite"
+ supertitleHref="/suite"
+ />,
+ );
+ const links = screen.getAllByRole('link');
+ expect(links).toHaveLength(2);
+ expect(links[0]).toHaveAttribute('href', '/suite');
+ expect(links[1]).toHaveAttribute('href', '/product');
+ });
+
+ it('shows chevron when menu is provided', () => {
+ render(<XDSPageNavHeader title="My App" menu={<div>Menu content</div>} />);
+ // The chevron SVG should be rendered
+ const button = screen.getByRole('button');
+ expect(button).toBeInTheDocument();
+ });
+
+ it('does not show chevron without menu', () => {
+ const {container} = render(<XDSPageNavHeader title="My App" />);
+ const svg = container.querySelector('svg');
+ expect(svg).not.toBeInTheDocument();
+ });
+
+ it('whole header is popover trigger when menu provided without hrefs', () => {
+ render(<XDSPageNavHeader title="My App" menu={<div>Menu</div>} />);
+ const button = screen.getByRole('button');
+ expect(button).toHaveAttribute('aria-haspopup', 'dialog');
+ expect(button).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('toggles popover on click when menu is provided', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSPageNavHeader
+ title="My App"
+ menu={<div data-testid="menu-content">Menu</div>}
+ />,
+ );
+ const button = screen.getByRole('button');
+ await user.click(button);
+ expect(button).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('renders chevron as separate trigger when menu and hrefs are provided', () => {
+ render(
+ <XDSPageNavHeader
+ title="Product"
+ titleHref="/product"
+ menu={<div>Menu</div>}
+ />,
+ );
+ const button = screen.getByRole('button', {name: 'Open menu'});
+ expect(button).toHaveAttribute('aria-haspopup', 'dialog');
+ });
+
+ it('passes data-testid', () => {
+ render(<XDSPageNavHeader title="My App" data-testid="nav-header" />);
+ expect(screen.getByTestId('nav-header')).toBeInTheDocument();
+ });
+});
+
+// =============================================================================
+// XDSPageNavItem
+// =============================================================================
+
+describe('XDSPageNavItem', () => {
+ it('renders label text', () => {
+ render(<XDSPageNavItem label="Dashboard" />);
+ expect(screen.getByText('Dashboard')).toBeInTheDocument();
+ });
+
+ it('renders as link when href is provided', () => {
+ render(<XDSPageNavItem label="Dashboard" href="/dashboard" />);
+ const link = screen.getByRole('link');
+ expect(link).toHaveAttribute('href', '/dashboard');
+ });
+
+ it('renders as button when no href', () => {
+ render(<XDSPageNavItem label="Dashboard" />);
+ expect(screen.getByRole('button')).toBeInTheDocument();
+ });
+
+ it('sets aria-current="page" when selected', () => {
+ render(<XDSPageNavItem label="Dashboard" isSelected />);
+ const button = screen.getByRole('button');
+ expect(button).toHaveAttribute('aria-current', 'page');
+ });
+
+ it('does not set aria-current when not selected', () => {
+ render(<XDSPageNavItem label="Dashboard" />);
+ const button = screen.getByRole('button');
+ expect(button).not.toHaveAttribute('aria-current');
+ });
+
+ it('disables the button when isDisabled', () => {
+ render(<XDSPageNavItem label="Dashboard" isDisabled />);
+ const button = screen.getByRole('button');
+ expect(button).toBeDisabled();
+ });
+
+ it('calls onClick handler', async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(<XDSPageNavItem label="Dashboard" onClick={handleClick} />);
+ await user.click(screen.getByRole('button'));
+ expect(handleClick).toHaveBeenCalledTimes(1);
+ });
+
+ it('renders endContent', () => {
+ render(
+ <XDSPageNavItem
+ label="Projects"
+ endContent={<span data-testid="badge">3</span>}
+ />,
+ );
+ expect(screen.getByTestId('badge')).toBeInTheDocument();
+ });
+
+ it('renders nested children', () => {
+ render(
+ <XDSPageNavItem label="Settings">
+ <XDSPageNavItem label="General" />
+ <XDSPageNavItem label="Security" />
+ </XDSPageNavItem>,
+ );
+ expect(screen.getByText('General')).toBeInTheDocument();
+ expect(screen.getByText('Security')).toBeInTheDocument();
+ });
+
+ it('passes data-testid', () => {
+ render(<XDSPageNavItem label="Dashboard" data-testid="nav-item" />);
+ expect(screen.getByTestId('nav-item')).toBeInTheDocument();
+ });
+
+ it('renders with selected link', () => {
+ render(<XDSPageNavItem label="Dashboard" href="/dashboard" isSelected />);
+ const link = screen.getByRole('link');
+ expect(link).toHaveAttribute('aria-current', 'page');
+ });
+});
+
+// =============================================================================
+// XDSPageNavSection
+// =============================================================================
+
+describe('XDSPageNavSection', () => {
+ it('renders with group role', () => {
+ render(
+ <XDSPageNavSection title="Main">
+ <XDSPageNavItem label="Dashboard" />
+ </XDSPageNavSection>,
+ );
+ expect(screen.getByRole('group')).toBeInTheDocument();
+ });
+
+ it('renders title text', () => {
+ render(
+ <XDSPageNavSection title="Main">
+ <XDSPageNavItem label="Dashboard" />
+ </XDSPageNavSection>,
+ );
+ expect(screen.getByText('Main')).toBeInTheDocument();
+ });
+
+ it('uses aria-labelledby to link title to group', () => {
+ render(
+ <XDSPageNavSection title="Main">
+ <XDSPageNavItem label="Dashboard" />
+ </XDSPageNavSection>,
+ );
+ const group = screen.getByRole('group');
+ const labelId = group.getAttribute('aria-labelledby');
+ expect(labelId).toBeTruthy();
+ const label = document.getElementById(labelId!);
+ expect(label).toHaveTextContent('Main');
+ });
+
+ it('renders subtitle', () => {
+ render(
+ <XDSPageNavSection title="Main" subtitle="Primary navigation">
+ <XDSPageNavItem label="Dashboard" />
+ </XDSPageNavSection>,
+ );
+ expect(screen.getByText('Primary navigation')).toBeInTheDocument();
+ });
+
+ it('renders endContent', () => {
+ render(
+ <XDSPageNavSection
+ title="Main"
+ endContent={<span data-testid="section-action">+</span>}>
+ <XDSPageNavItem label="Dashboard" />
+ </XDSPageNavSection>,
+ );
+ expect(screen.getByTestId('section-action')).toBeInTheDocument();
+ });
+
+ it('passes data-testid', () => {
+ render(
+ <XDSPageNavSection title="Main" data-testid="nav-section">
+ <XDSPageNavItem label="Dashboard" />
+ </XDSPageNavSection>,
+ );
+ expect(screen.getByTestId('nav-section')).toBeInTheDocument();
+ });
+});
+
+// =============================================================================
+// Integration
+// =============================================================================
+
+describe('PageNav integration', () => {
+ it('renders a complete page nav', () => {
+ render(
+ <XDSPageNav
+ header={<XDSPageNavHeader title="My App" />}
+ topContent={<button>Create</button>}
+ footer={<div data-testid="promo">Promo</div>}
+ footerIcons={<button>Help</button>}>
+ <XDSPageNavSection title="Main">
+ <XDSPageNavItem label="Dashboard" isSelected />
+ <XDSPageNavItem label="Projects" />
+ </XDSPageNavSection>
+ <XDSPageNavSection title="Settings">
+ <XDSPageNavItem label="General" />
+ </XDSPageNavSection>
+ </XDSPageNav>,
+ );
+
+ expect(screen.getByRole('navigation')).toBeInTheDocument();
+ expect(screen.getByText('My App')).toBeInTheDocument();
+ expect(screen.getByText('Dashboard')).toBeInTheDocument();
+ expect(screen.getByText('Projects')).toBeInTheDocument();
+ expect(screen.getByText('General')).toBeInTheDocument();
+ expect(screen.getByTestId('promo')).toBeInTheDocument();
+ });
+});
diff --git a/packages/core/src/PageNav/XDSPageNav.tsx b/packages/core/src/PageNav/XDSPageNav.tsx
new file mode 100644
index 0000000000..d7510286fc
--- /dev/null
+++ b/packages/core/src/PageNav/XDSPageNav.tsx
@@ -0,0 +1,210 @@
+/**
+ * @file XDSPageNav.tsx
+ * @input Uses React forwardRef, HTMLAttributes, ReactNode, StyleX
+ * @output Exports XDSPageNav component and XDSPageNavProps
+ * @position Core implementation; consumed by index.ts, tested by XDSPageNav.test.tsx
+ *
+ * Sidebar navigation container with five zones: header + topContent (sticky together),
+ * children (scrollable), footer, and footerIcons (sticky bottom).
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/PageNav/README.md
+ * - /packages/core/src/PageNav/XDSPageNav.test.tsx
+ * - /packages/core/src/PageNav/index.ts
+ * - /apps/storybook/stories/PageNav.stories.tsx
+ */
+
+'use client';
+
+import {
+ forwardRef,
+ useContext,
+ type HTMLAttributes,
+ type ReactNode,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {colorVars, spacingVars} from '../theme/tokens.stylex';
+import {ThemeContext} from '../theme/ThemeContext';
+import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ root: {
+ display: 'flex',
+ flexDirection: 'column',
+ height: '100%',
+ backgroundColor: colorVars['--color-surface'],
+ boxSizing: 'border-box',
+ overflow: 'hidden',
+ },
+ stickyTop: {
+ display: 'flex',
+ flexDirection: 'column',
+ flexShrink: 0,
+ position: 'sticky',
+ top: 0,
+ zIndex: 1,
+ backgroundColor: colorVars['--color-surface'],
+ },
+ topContent: {
+ paddingInline: spacingVars['--spacing-2'],
+ paddingBlock: spacingVars['--spacing-1'],
+ },
+ scrollable: {
+ flex: 1,
+ overflowY: 'auto',
+ overflowX: 'hidden',
+ paddingInline: spacingVars['--spacing-2'],
+ paddingBlock: spacingVars['--spacing-1'],
+ },
+ stickyBottom: {
+ flexShrink: 0,
+ marginTop: 'auto',
+ position: 'sticky',
+ bottom: 0,
+ backgroundColor: colorVars['--color-surface'],
+ },
+ footer: {
+ paddingInline: spacingVars['--spacing-2'],
+ paddingBlock: spacingVars['--spacing-2'],
+ },
+ footerIcons: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-1'],
+ paddingInline: spacingVars['--spacing-2'],
+ paddingBlock: spacingVars['--spacing-2'],
+ borderBlockStart: `1px solid ${colorVars['--color-divider']}`,
+ },
+});
+
+// =============================================================================
+// Module Augmentation
+// =============================================================================
+
+declare module '../theme/types' {
+ interface ComponentStyles {
+ pageNav?: {
+ /** Root container styles */
+ root?: ThemeStyleXStyles;
+ };
+ }
+}
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface XDSPageNavProps extends Omit<
+ HTMLAttributes<HTMLElement>,
+ 'style' | 'className'
+> {
+ /**
+ * Header area — typically XDSPageNavHeader. Sticky at top.
+ */
+ header?: ReactNode;
+ /**
+ * Content pinned below header (e.g., create button, top-level items). Sticky.
+ */
+ topContent?: ReactNode;
+ /**
+ * Navigation sections and items. Scrollable.
+ */
+ children: ReactNode;
+ /**
+ * Footer area above icon bar (e.g., promo cards).
+ */
+ footer?: ReactNode;
+ /**
+ * Footer icon bar (e.g., help, notifications, avatar).
+ */
+ footerIcons?: ReactNode;
+ /**
+ * StyleX overrides for the root container.
+ */
+ xstyle?: StyleXStyles;
+ /**
+ * Test ID for the root element.
+ */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Sidebar navigation container for application pages.
+ *
+ * Provides five zones stacked vertically: a sticky header + action area (stuck together),
+ * scrollable nav content, and a sticky bottom footer + footer icon bar.
+ *
+ * @example
+ * ```tsx
+ * <XDSPageNav
+ * header={<XDSPageNavHeader icon={<AppIcon />} title="My App" titleHref="/" />}
+ * topContent={<XDSButton label="Create new" variant="primary" />}
+ * footerIcons={<XDSButton icon={HelpIcon} variant="ghost" label="Help" />}
+ * >
+ * <XDSPageNavSection title="Main">
+ * <XDSPageNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />
+ * <XDSPageNavItem label="Projects" icon={FolderIcon} href="/projects" />
+ * </XDSPageNavSection>
+ * </XDSPageNav>
+ * ```
+ */
+export const XDSPageNav = forwardRef<HTMLElement, XDSPageNavProps>(
+ function XDSPageNav(
+ {
+ header,
+ topContent,
+ children,
+ footer,
+ footerIcons,
+ xstyle,
+ 'data-testid': testId,
+ ...props
+ },
+ ref,
+ ) {
+ const themeContext = useContext(ThemeContext);
+ const rootOverride = themeContext?.theme.components?.pageNav?.root;
+
+ const hasStickyTop = !!(header || topContent);
+ const hasStickyBottom = !!(footer || footerIcons);
+
+ return (
+ <nav
+ ref={ref}
+ role="navigation"
+ aria-label="Page navigation"
+ data-testid={testId}
+ {...stylex.props(styles.root, rootOverride, xstyle)}
+ {...props}>
+ {hasStickyTop && (
+ <div {...stylex.props(styles.stickyTop)}>
+ {header}
+ {topContent && (
+ <div {...stylex.props(styles.topContent)}>{topContent}</div>
+ )}
+ </div>
+ )}
+ <div {...stylex.props(styles.scrollable)}>{children}</div>
+ {hasStickyBottom && (
+ <div {...stylex.props(styles.stickyBottom)}>
+ {footer && <div {...stylex.props(styles.footer)}>{footer}</div>}
+ {footerIcons && (
+ <div {...stylex.props(styles.footerIcons)}>{footerIcons}</div>
+ )}
+ </div>
+ )}
+ </nav>
+ );
+ },
+);
+
+XDSPageNav.displayName = 'XDSPageNav';
diff --git a/packages/core/src/PageNav/XDSPageNavHeader.tsx b/packages/core/src/PageNav/XDSPageNavHeader.tsx
new file mode 100644
index 0000000000..796cea676d
--- /dev/null
+++ b/packages/core/src/PageNav/XDSPageNavHeader.tsx
@@ -0,0 +1,506 @@
+/**
+ * @file XDSPageNavHeader.tsx
+ * @input Uses React forwardRef, useRef, useCallback, ReactNode, StyleX, useXDSPopover
+ * @output Exports XDSPageNavHeader component and XDSPageNavHeaderProps
+ * @position Core implementation; used inside XDSPageNav header slot
+ *
+ * Product/suite/account header with smart interaction boundary logic.
+ * Composes useXDSPopover internally when menu prop is provided.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/PageNav/README.md
+ * - /packages/core/src/PageNav/XDSPageNav.test.tsx
+ * - /packages/core/src/PageNav/index.ts
+ * - /apps/storybook/stories/PageNav.stories.tsx
+ */
+
+'use client';
+
+import {forwardRef, useCallback, useRef, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ textSizeVars,
+ fontWeightVars,
+ lineHeightVars,
+ radiusVars,
+} from '../theme/tokens.stylex';
+// TODO(#264): Lazy-load useXDSPopover so the popover/layer bundle is not
+// eagerly imported when `menu` is not provided. See XDSText for an example
+// of lazy loading layer resources.
+import {useXDSPopover} from '../Layer/useXDSPopover';
+import {XDSLink} from '../Link';
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ root: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-3'],
+ paddingBlock: spacingVars['--spacing-3'],
+ boxSizing: 'border-box',
+ textDecoration: 'none',
+ color: 'inherit',
+ cursor: 'default',
+ },
+ interactive: {
+ cursor: 'pointer',
+ borderRadius: radiusVars['--radius-element'],
+ borderWidth: 0,
+ borderStyle: 'none',
+ backgroundColor: 'transparent',
+ fontFamily: 'inherit',
+ fontSize: 'inherit',
+ textAlign: 'start',
+ ':hover': {
+ backgroundColor: colorVars['--color-hover-overlay'],
+ },
+ },
+ interactiveInset: {
+ marginInline: spacingVars['--spacing-1'],
+ marginBlock: spacingVars['--spacing-1'],
+ },
+ icon: {
+ flexShrink: 0,
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ width: spacingVars['--spacing-8'],
+ height: spacingVars['--spacing-8'],
+ },
+ textContainer: {
+ display: 'flex',
+ flexDirection: 'column',
+ flex: 1,
+ minWidth: 0,
+ },
+ supertitle: {
+ fontSize: textSizeVars['--text-xsm'],
+ lineHeight: lineHeightVars['--leading-snug'],
+ color: colorVars['--color-text-secondary'],
+ textDecoration: 'none',
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ },
+ title: {
+ fontSize: textSizeVars['--text-base'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ lineHeight: lineHeightVars['--leading-snug'],
+ color: colorVars['--color-text-primary'],
+ textDecoration: 'none',
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ },
+ subtitle: {
+ fontSize: textSizeVars['--text-xsm'],
+ lineHeight: lineHeightVars['--leading-snug'],
+ color: colorVars['--color-text-secondary'],
+ textDecoration: 'none',
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ },
+ chevron: {
+ flexShrink: 0,
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ width: 16,
+ height: 16,
+ color: colorVars['--color-icon-secondary'],
+ },
+ popoverContent: {
+ borderRadius: radiusVars['--radius-element'],
+ backgroundColor: colorVars['--color-surface'],
+ boxShadow: `0 4px 12px ${colorVars['--color-shadow-elevation']}`,
+ overflow: 'hidden',
+ },
+ popover: {
+ minWidth: 'anchor-size(width)',
+ marginBlockStart: spacingVars['--spacing-1'],
+ },
+});
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface XDSPageNavHeaderProps {
+ /**
+ * Product/app icon.
+ */
+ icon?: ReactNode;
+ /**
+ * Product/app name.
+ */
+ title: string;
+ /**
+ * Link for the title (e.g., product home).
+ */
+ titleHref?: string;
+ /**
+ * Text above the title (e.g., suite name).
+ */
+ supertitle?: string;
+ /**
+ * Link for the supertitle (e.g., suite home).
+ */
+ supertitleHref?: string;
+ /**
+ * Text below the title (e.g., account context).
+ */
+ subtitle?: string;
+ /**
+ * Link for the subtitle.
+ */
+ subtitleHref?: string;
+ /**
+ * Menu content shown in a popover. When provided, the header composes
+ * useXDSPopover internally and shows a dropdown chevron. The trigger
+ * boundary is determined automatically:
+ * - No hrefs → whole header is the trigger
+ * - With hrefs → links are independent, chevron/remaining area is the trigger
+ */
+ menu?: ReactNode;
+ /**
+ * StyleX overrides.
+ */
+ xstyle?: StyleXStyles;
+ /**
+ * Test ID for the root element.
+ */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Chevron SVG
+// =============================================================================
+
+function ChevronDownIcon() {
+ return (
+ <svg
+ width="16"
+ height="16"
+ viewBox="0 0 16 16"
+ fill="none"
+ aria-hidden="true">
+ <path
+ d="M4 6L8 10L12 6"
+ stroke="currentColor"
+ strokeWidth="1.5"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ />
+ </svg>
+ );
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Product/suite/account header for XDSPageNav.
+ *
+ * Supports smart interaction boundary logic:
+ * - No hrefs + menu → whole header is the popover trigger
+ * - titleHref only, no menu → whole header is one link
+ * - titleHref + supertitleHref, no menu → each is an independent link
+ * - menu + hrefs → links are independent, chevron/remaining area is the trigger
+ *
+ * The chevron indicator is automatically shown when `menu` is provided.
+ *
+ * @example
+ * ```tsx
+ * // Single product
+ * <XDSPageNavHeader icon={<AppIcon />} title="My App" titleHref="/" />
+ *
+ * // Suite with menu
+ * <XDSPageNavHeader
+ * icon={<SuiteIcon />}
+ * supertitle="Suite Name"
+ * supertitleHref="/suite"
+ * title="Product Name"
+ * titleHref="/product"
+ * menu={<ProductSwitcher />}
+ * />
+ *
+ * // Account context with menu
+ * <XDSPageNavHeader
+ * icon={<AppIcon />}
+ * title="Product Name"
+ * subtitle="Business Account"
+ * menu={<AccountSwitcher />}
+ * />
+ * ```
+ */
+export const XDSPageNavHeader = forwardRef<
+ HTMLDivElement,
+ XDSPageNavHeaderProps
+>(function XDSPageNavHeader(
+ {
+ icon,
+ title,
+ titleHref,
+ supertitle,
+ supertitleHref,
+ subtitle,
+ subtitleHref,
+ menu,
+ xstyle,
+ 'data-testid': testId,
+ ...props
+ },
+ ref,
+) {
+ const rootRef = useRef<HTMLDivElement>(null);
+
+ const popover = useXDSPopover({
+ dialogLabel: 'Navigation menu',
+ });
+
+ const showChevron = !!menu;
+ const hasAnyHref = !!(titleHref || supertitleHref || subtitleHref);
+
+ // Determine interaction mode
+ const isWholeHeaderTrigger = !!menu && !hasAnyHref;
+ const isWholeHeaderLink =
+ !!titleHref && !menu && !supertitleHref && !subtitleHref;
+
+ const handleToggle = useCallback(() => {
+ popover.toggle();
+ }, [popover]);
+
+ // Combine refs — always anchor popover to the full header element
+ // so the popover appears in the same position regardless of whether
+ // links are present (mixed mode) or not (whole-header trigger mode).
+ const setRef = useCallback(
+ (el: HTMLDivElement | null) => {
+ (rootRef as React.MutableRefObject<HTMLDivElement | null>).current = el;
+ if (typeof ref === 'function') {
+ ref(el);
+ } else if (ref) {
+ (ref as React.MutableRefObject<HTMLDivElement | null>).current = el;
+ }
+ if (menu) {
+ popover.triggerRef(el);
+ }
+ },
+ [ref, popover, menu],
+ );
+
+ // Render text content
+ const renderTextContent = () => (
+ <span {...stylex.props(styles.textContainer)}>
+ {supertitle &&
+ (hasAnyHref && supertitleHref && menu ? (
+ <XDSLink
+ label={supertitle}
+ href={supertitleHref}
+ color="secondary"
+ size="xsm">
+ {supertitle}
+ </XDSLink>
+ ) : (
+ <span {...stylex.props(styles.supertitle)}>{supertitle}</span>
+ ))}
+ {hasAnyHref && titleHref && menu ? (
+ <XDSLink
+ label={title}
+ href={titleHref}
+ color="primary"
+ weight="semibold">
+ {title}
+ </XDSLink>
+ ) : (
+ <span {...stylex.props(styles.title)}>{title}</span>
+ )}
+ {subtitle &&
+ (hasAnyHref && subtitleHref && menu ? (
+ <XDSLink
+ label={subtitle}
+ href={subtitleHref}
+ color="secondary"
+ size="xsm">
+ {subtitle}
+ </XDSLink>
+ ) : (
+ <span {...stylex.props(styles.subtitle)}>{subtitle}</span>
+ ))}
+ </span>
+ );
+
+ const chevronElement = showChevron && (
+ <span {...stylex.props(styles.chevron)}>
+ <ChevronDownIcon />
+ </span>
+ );
+
+ // Whole header is a link (no menu, single titleHref)
+ if (isWholeHeaderLink) {
+ return (
+ <a
+ ref={ref as React.Ref<HTMLAnchorElement>}
+ href={titleHref}
+ data-testid={testId}
+ {...stylex.props(
+ styles.root,
+ styles.interactive,
+ styles.interactiveInset,
+ xstyle,
+ )}
+ {...(props as React.AnchorHTMLAttributes<HTMLAnchorElement>)}>
+ {icon && <span {...stylex.props(styles.icon)}>{icon}</span>}
+ {renderTextContent()}
+ {chevronElement}
+ </a>
+ );
+ }
+
+ // Whole header is the popover trigger (menu, no hrefs)
+ if (isWholeHeaderTrigger) {
+ return (
+ <>
+ <button
+ ref={setRef as React.Ref<HTMLButtonElement>}
+ type="button"
+ onClick={handleToggle}
+ data-testid={testId}
+ {...popover.triggerProps}
+ {...stylex.props(
+ styles.root,
+ styles.interactive,
+ styles.interactiveInset,
+ xstyle,
+ )}>
+ {icon && <span {...stylex.props(styles.icon)}>{icon}</span>}
+ {renderTextContent()}
+ {chevronElement}
+ </button>
+ {popover.render(
+ <div {...stylex.props(styles.popoverContent)}>{menu}</div>,
+ {placement: 'below', alignment: 'start', xstyle: styles.popover},
+ )}
+ </>
+ );
+ }
+
+ // Mixed mode: independent links + chevron trigger for menu
+ // Popover anchors to the full header div, not the chevron, so it
+ // appears in the same position as the no-links case.
+ if (menu && hasAnyHref) {
+ return (
+ <>
+ <div
+ ref={setRef}
+ data-testid={testId}
+ {...stylex.props(styles.root, xstyle)}>
+ {icon &&
+ (titleHref ? (
+ <a href={titleHref} {...stylex.props(styles.icon)}>
+ {icon}
+ </a>
+ ) : (
+ <span {...stylex.props(styles.icon)}>{icon}</span>
+ ))}
+ {renderTextContent()}
+ {showChevron && (
+ <button
+ type="button"
+ onClick={handleToggle}
+ aria-label="Open menu"
+ {...popover.triggerProps}
+ {...stylex.props(styles.chevron, styles.interactive)}>
+ <ChevronDownIcon />
+ </button>
+ )}
+ </div>
+ {popover.render(
+ <div {...stylex.props(styles.popoverContent)}>{menu}</div>,
+ {placement: 'below', alignment: 'start', xstyle: styles.popover},
+ )}
+ </>
+ );
+ }
+
+ // Static header with independent links (no menu)
+ if (hasAnyHref && !isWholeHeaderLink) {
+ return (
+ <div
+ ref={ref}
+ data-testid={testId}
+ {...stylex.props(styles.root, xstyle)}
+ {...props}>
+ {icon &&
+ (titleHref ? (
+ <a href={titleHref} {...stylex.props(styles.icon)}>
+ {icon}
+ </a>
+ ) : (
+ <span {...stylex.props(styles.icon)}>{icon}</span>
+ ))}
+ <span {...stylex.props(styles.textContainer)}>
+ {supertitle &&
+ (supertitleHref ? (
+ <XDSLink
+ label={supertitle}
+ href={supertitleHref}
+ color="secondary"
+ size="xsm">
+ {supertitle}
+ </XDSLink>
+ ) : (
+ <span {...stylex.props(styles.supertitle)}>{supertitle}</span>
+ ))}
+ {titleHref ? (
+ <XDSLink
+ label={title}
+ href={titleHref}
+ color="primary"
+ weight="semibold">
+ {title}
+ </XDSLink>
+ ) : (
+ <span {...stylex.props(styles.title)}>{title}</span>
+ )}
+ {subtitle &&
+ (subtitleHref ? (
+ <XDSLink
+ label={subtitle}
+ href={subtitleHref}
+ color="secondary"
+ size="xsm">
+ {subtitle}
+ </XDSLink>
+ ) : (
+ <span {...stylex.props(styles.subtitle)}>{subtitle}</span>
+ ))}
+ </span>
+ {chevronElement}
+ </div>
+ );
+ }
+
+ // Default: static header, no links, no menu
+ return (
+ <div
+ ref={ref}
+ data-testid={testId}
+ {...stylex.props(styles.root, xstyle)}
+ {...props}>
+ {icon && <span {...stylex.props(styles.icon)}>{icon}</span>}
+ {renderTextContent()}
+ {chevronElement}
+ </div>
+ );
+});
+
+XDSPageNavHeader.displayName = 'XDSPageNavHeader';
diff --git a/packages/core/src/PageNav/XDSPageNavItem.tsx b/packages/core/src/PageNav/XDSPageNavItem.tsx
new file mode 100644
index 0000000000..621292dc3b
--- /dev/null
+++ b/packages/core/src/PageNav/XDSPageNavItem.tsx
@@ -0,0 +1,270 @@
+/**
+ * @file XDSPageNavItem.tsx
+ * @input Uses React forwardRef, ReactNode, StyleX, XDSIcon, XDSIconType
+ * @output Exports XDSPageNavItem component and XDSPageNavItemProps
+ * @position Core implementation; used inside XDSPageNav children
+ *
+ * Navigation item with icon, selected state, and nesting.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/PageNav/README.md
+ * - /packages/core/src/PageNav/XDSPageNav.test.tsx
+ * - /packages/core/src/PageNav/index.ts
+ * - /apps/storybook/stories/PageNav.stories.tsx
+ */
+
+'use client';
+
+import {forwardRef, useId, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ radiusVars,
+ textSizeVars,
+ fontWeightVars,
+ lineHeightVars,
+} from '../theme/tokens.stylex';
+import {XDSIcon} from '../Icon';
+import type {XDSIconType} from '../Icon';
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ root: {
+ display: 'flex',
+ flexDirection: 'column',
+ width: '100%',
+ },
+ item: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ width: '100%',
+ paddingInline: spacingVars['--spacing-3'],
+ paddingBlock: spacingVars['--spacing-2'],
+ borderRadius: radiusVars['--radius-element'],
+ borderWidth: 0,
+ borderStyle: 'none',
+ backgroundColor: 'transparent',
+ color: colorVars['--color-text-primary'],
+ textDecoration: 'none',
+ cursor: 'pointer',
+ fontFamily: 'inherit',
+ fontSize: textSizeVars['--text-base'],
+ fontWeight: fontWeightVars['--font-weight-normal'],
+ lineHeight: lineHeightVars['--leading-base'],
+ textAlign: 'start',
+ boxSizing: 'border-box',
+ ':hover': {
+ backgroundColor: colorVars['--color-hover-overlay'],
+ },
+ },
+ selected: {
+ backgroundColor: colorVars['--color-accent-deemphasized'],
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ ':hover': {
+ backgroundColor: colorVars['--color-accent-deemphasized'],
+ },
+ },
+ disabled: {
+ color: colorVars['--color-text-disabled'],
+ cursor: 'not-allowed',
+ pointerEvents: 'none',
+ },
+ label: {
+ flex: 1,
+ minWidth: 0,
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ },
+ endContent: {
+ flexShrink: 0,
+ display: 'flex',
+ alignItems: 'center',
+ },
+ children: {
+ paddingInlineStart: spacingVars['--spacing-6'],
+ },
+});
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface XDSPageNavItemProps {
+ /**
+ * Item label.
+ */
+ label: string;
+ /**
+ * Icon (outline variant).
+ */
+ icon?: XDSIconType;
+ /**
+ * Icon when selected (filled variant).
+ */
+ selectedIcon?: XDSIconType;
+ /**
+ * Current page indicator.
+ * @default false
+ */
+ isSelected?: boolean;
+ /**
+ * Whether the item is disabled.
+ * @default false
+ */
+ isDisabled?: boolean;
+ /**
+ * Navigation URL.
+ */
+ href?: string;
+ /**
+ * Click handler.
+ */
+ onClick?: (e: React.MouseEvent) => void;
+ /**
+ * Right-side content (badges, counts).
+ */
+ endContent?: ReactNode;
+ /**
+ * Sub-items for nesting.
+ */
+ children?: ReactNode;
+ /**
+ * Test ID for the item element.
+ */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Navigation item for XDSPageNav.
+ *
+ * Supports icons, selected state, nesting, and end content like badges or counts.
+ *
+ * @example
+ * ```tsx
+ * <XDSPageNavItem
+ * label="Dashboard"
+ * icon={HomeIcon}
+ * selectedIcon={HomeIconSolid}
+ * isSelected
+ * href="/dashboard"
+ * />
+ *
+ * <XDSPageNavItem label="Settings" icon={CogIcon}>
+ * <XDSPageNavItem label="General" href="/settings/general" />
+ * <XDSPageNavItem label="Security" href="/settings/security" />
+ * </XDSPageNavItem>
+ * ```
+ */
+export const XDSPageNavItem = forwardRef<HTMLElement, XDSPageNavItemProps>(
+ function XDSPageNavItem(
+ {
+ label,
+ icon,
+ selectedIcon,
+ isSelected = false,
+ isDisabled = false,
+ href,
+ onClick,
+ endContent,
+ children,
+ 'data-testid': testId,
+ },
+ ref,
+ ) {
+ const id = useId();
+ const hasChildren = !!children;
+
+ const displayIcon = isSelected && selectedIcon ? selectedIcon : icon;
+
+ const handleClick = (e: React.MouseEvent) => {
+ if (isDisabled) {
+ e.preventDefault();
+ return;
+ }
+ onClick?.(e);
+ };
+
+ const itemContent = (
+ <>
+ {displayIcon && (
+ <XDSIcon
+ icon={displayIcon}
+ size="sm"
+ color={
+ isSelected ? 'accent' : isDisabled ? 'disabled' : 'secondary'
+ }
+ />
+ )}
+ <span {...stylex.props(styles.label)}>{label}</span>
+ {endContent && (
+ <span {...stylex.props(styles.endContent)}>{endContent}</span>
+ )}
+ </>
+ );
+
+ const ariaProps = {
+ 'aria-current': isSelected ? ('page' as const) : undefined,
+ 'aria-disabled': isDisabled || undefined,
+ 'data-testid': testId,
+ };
+
+ const itemElement =
+ href && !isDisabled ? (
+ <a
+ ref={ref as React.Ref<HTMLAnchorElement>}
+ href={href}
+ onClick={handleClick}
+ {...ariaProps}
+ {...stylex.props(
+ styles.item,
+ isSelected && styles.selected,
+ isDisabled && styles.disabled,
+ )}>
+ {itemContent}
+ </a>
+ ) : (
+ <button
+ ref={ref as React.Ref<HTMLButtonElement>}
+ type="button"
+ onClick={handleClick}
+ disabled={isDisabled}
+ {...ariaProps}
+ {...stylex.props(
+ styles.item,
+ isSelected && styles.selected,
+ isDisabled && styles.disabled,
+ )}>
+ {itemContent}
+ </button>
+ );
+
+ return (
+ <div {...stylex.props(styles.root)}>
+ {itemElement}
+ {hasChildren && (
+ <div
+ role="group"
+ aria-labelledby={`${id}-label`}
+ {...stylex.props(styles.children)}>
+ <span id={`${id}-label`} hidden>
+ {label}
+ </span>
+ {children}
+ </div>
+ )}
+ </div>
+ );
+ },
+);
+
+XDSPageNavItem.displayName = 'XDSPageNavItem';
diff --git a/packages/core/src/PageNav/XDSPageNavSection.tsx b/packages/core/src/PageNav/XDSPageNavSection.tsx
new file mode 100644
index 0000000000..d1a49da60f
--- /dev/null
+++ b/packages/core/src/PageNav/XDSPageNavSection.tsx
@@ -0,0 +1,188 @@
+/**
+ * @file XDSPageNavSection.tsx
+ * @input Uses React, StyleX
+ * @output Exports XDSPageNavSection component and XDSPageNavSectionProps
+ * @position Core implementation; used inside XDSPageNav children
+ *
+ * Section grouping for navigation items with optional title and end content.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/PageNav/README.md
+ * - /packages/core/src/PageNav/XDSPageNav.test.tsx
+ * - /packages/core/src/PageNav/index.ts
+ * - /apps/storybook/stories/PageNav.stories.tsx
+ */
+
+'use client';
+
+import {useId, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ textSizeVars,
+ fontWeightVars,
+ lineHeightVars,
+} from '../theme/tokens.stylex';
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ root: {
+ display: 'flex',
+ flexDirection: 'column',
+ paddingBlock: spacingVars['--spacing-1'],
+ },
+ header: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-3'],
+ paddingBlock: spacingVars['--spacing-1'],
+ cursor: 'default',
+ userSelect: 'none',
+ },
+
+ titleContainer: {
+ display: 'flex',
+ flexDirection: 'column',
+ flex: 1,
+ minWidth: 0,
+ },
+ title: {
+ fontSize: textSizeVars['--text-xsm'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ lineHeight: lineHeightVars['--leading-snug'],
+ color: colorVars['--color-text-secondary'],
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ },
+ subtitle: {
+ fontSize: textSizeVars['--text-xsm'],
+ lineHeight: lineHeightVars['--leading-snug'],
+ color: colorVars['--color-text-secondary'],
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ },
+ endContent: {
+ flexShrink: 0,
+ display: 'flex',
+ alignItems: 'center',
+ },
+
+ items: {
+ display: 'flex',
+ flexDirection: 'column',
+ },
+});
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface XDSPageNavSectionProps {
+ /**
+ * Section title.
+ */
+ title: string;
+ /**
+ * Section subtitle.
+ */
+ subtitle?: string;
+ /**
+ * Section items.
+ */
+ children: ReactNode;
+ /**
+ * Right-side content in the section header.
+ */
+ endContent?: ReactNode;
+ /**
+ * Whether the section header is visually hidden.
+ * The section title is still accessible to screen readers.
+ * @default false
+ */
+ isHeaderHidden?: boolean;
+ /**
+ * Test ID for the section element.
+ */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Section grouping for XDSPageNav items.
+ *
+ * Renders a labeled group of navigation items.
+ * Uses `role="group"` with `aria-labelledby` for accessibility.
+ *
+ * @example
+ * ```tsx
+ * <XDSPageNavSection title="Main">
+ * <XDSPageNavItem label="Dashboard" icon={HomeIcon} isSelected />
+ * <XDSPageNavItem label="Projects" icon={FolderIcon} />
+ * </XDSPageNavSection>
+ * ```
+ */
+export function XDSPageNavSection({
+ title,
+ subtitle,
+ children,
+ endContent,
+ isHeaderHidden = false,
+ 'data-testid': testId,
+}: XDSPageNavSectionProps) {
+ const id = useId();
+ const titleId = `${id}-title`;
+
+ const headerContent = (
+ <>
+ <span {...stylex.props(styles.titleContainer)}>
+ <span id={titleId} {...stylex.props(styles.title)}>
+ {title}
+ </span>
+ {subtitle && <span {...stylex.props(styles.subtitle)}>{subtitle}</span>}
+ </span>
+ {endContent && (
+ <span {...stylex.props(styles.endContent)}>{endContent}</span>
+ )}
+ </>
+ );
+
+ const visuallyHiddenStyle: React.CSSProperties = isHeaderHidden
+ ? {
+ position: 'absolute',
+ width: 1,
+ height: 1,
+ padding: 0,
+ margin: -1,
+ overflow: 'hidden',
+ clip: 'rect(0, 0, 0, 0)',
+ whiteSpace: 'nowrap',
+ borderWidth: 0,
+ }
+ : {};
+
+ return (
+ <div
+ role="group"
+ aria-labelledby={titleId}
+ data-testid={testId}
+ {...stylex.props(styles.root)}>
+ <div
+ style={isHeaderHidden ? visuallyHiddenStyle : undefined}
+ {...stylex.props(styles.header)}>
+ {headerContent}
+ </div>
+ <div {...stylex.props(styles.items)}>{children}</div>
+ </div>
+ );
+}
+
+XDSPageNavSection.displayName = 'XDSPageNavSection';
diff --git a/packages/core/src/PageNav/index.ts b/packages/core/src/PageNav/index.ts
new file mode 100644
index 0000000000..c8527293c9
--- /dev/null
+++ b/packages/core/src/PageNav/index.ts
@@ -0,0 +1,20 @@
+/**
+ * @file index.ts
+ * @input Imports PageNav components and types
+ * @output Exports XDSPageNav, XDSPageNavHeader, XDSPageNavItem, XDSPageNavSection
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ *
+ * SYNC: When modified, update this header and /packages/core/src/PageNav/README.md
+ */
+
+export {XDSPageNav} from './XDSPageNav';
+export type {XDSPageNavProps} from './XDSPageNav';
+
+export {XDSPageNavHeader} from './XDSPageNavHeader';
+export type {XDSPageNavHeaderProps} from './XDSPageNavHeader';
+
+export {XDSPageNavItem} from './XDSPageNavItem';
+export type {XDSPageNavItemProps} from './XDSPageNavItem';
+
+export {XDSPageNavSection} from './XDSPageNavSection';
+export type {XDSPageNavSectionProps} from './XDSPageNavSection';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index aa110e6120..1b7abeb9c5 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -44,6 +44,7 @@ export * from './Token';
export * from './Dialog';
export * from './DropdownMenu';
export * from './TopNav';
+export * from './PageNav';
export * from './ProgressBar';
// Layout utilities and components (includes XDSHStack, XDSVStack)