Skip to content

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

TypeScript

refactor: rename XDSTopNavTitleIcon → XDSNavIcon, update nav selected states (#313)

Cindy Zhange3e6b3cdc73b
diff --git a/apps/sandbox/src/app/pages/topnav-menu/page.tsx b/apps/sandbox/src/app/pages/topnav-menu/page.tsx
index c5cba84605..41bab4a824 100644
--- a/apps/sandbox/src/app/pages/topnav-menu/page.tsx
+++ b/apps/sandbox/src/app/pages/topnav-menu/page.tsx
@@ -7,10 +7,10 @@ import {XDSButton} from '@xds/core/Button';
import {
XDSTopNav,
XDSTopNavTitle,
- XDSTopNavTitleIcon,
XDSTopNavItem,
XDSTopNavMenu,
} from '@xds/core/TopNav';
+import {XDSNavIcon} from '@xds/core/NavIcon';
const styles = stylex.create({
container: {
@@ -117,7 +117,7 @@ export default function TopNavMenuPage() {
title={
<XDSTopNavTitle
title="Marketing"
- logo={<XDSTopNavTitleIcon icon={<LogoIcon />} size="sm" />}
+ logo={<XDSNavIcon icon={<LogoIcon />} />}
href="#"
/>
}
diff --git a/apps/storybook/stories/SideNav.stories.tsx b/apps/storybook/stories/SideNav.stories.tsx
index acee7a188c..dfa115c1e1 100644
--- a/apps/storybook/stories/SideNav.stories.tsx
+++ b/apps/storybook/stories/SideNav.stories.tsx
@@ -7,10 +7,10 @@ import {
} from '@xds/core/SideNav';
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 {XDSList, XDSListItem} from '@xds/core/List';
+import {XDSNavIcon} from '@xds/core/NavIcon';
import {XDSText} from '@xds/core/Text';
-import {XDSVStack} from '@xds/core/Stack';
import {
HomeIcon,
FolderIcon,
@@ -59,7 +59,9 @@ export const Default: Story = {
<XDSSideNav
header={
<XDSSideNavHeader
- icon={<XDSIcon icon={CubeIcon} size="lg" />}
+ icon={
+ <XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />
+ }
title="My App"
titleHref="/"
/>
@@ -97,6 +99,38 @@ export const Default: Story = {
),
};
+// =============================================================================
+// Title Without Icon
+// =============================================================================
+
+export const TitleWithoutIcon: Story = {
+ name: 'Title Without Icon',
+ render: () => (
+ <XDSSideNav header={<XDSSideNavHeader title="My App" titleHref="/" />}>
+ <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>
+ </XDSSideNav>
+ ),
+};
+
// =============================================================================
// With Header Menu
// =============================================================================
@@ -107,44 +141,42 @@ export const WithHeaderMenu: Story = {
<XDSSideNav
header={
<XDSSideNavHeader
- icon={<XDSIcon icon={CubeIcon} size="lg" />}
+ icon={
+ <XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />
+ }
title="Product Name"
subtitle="Business Account"
menu={
- <div style={{padding: 12}}>
- <XDSVStack gap="space2">
+ <XDSList
+ density="compact"
+ header={
<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>
+ }>
+ <XDSListItem
+ label="Personal Account"
+ startContent={<XDSIcon icon={UserIcon} size="sm" />}
+ href="#"
+ />
+ <XDSListItem
+ label="Acme Corp"
+ startContent={<XDSIcon icon={BuildingOfficeIcon} size="sm" />}
+ href="#"
+ />
+ <XDSListItem
+ label="Add account"
+ startContent={<XDSIcon icon={PlusIcon} size="sm" />}
+ href="#"
+ />
+ <XDSListItem
+ label="Sign out"
+ startContent={
+ <XDSIcon icon={ArrowRightStartOnRectangleIcon} size="sm" />
+ }
+ href="#"
+ />
+ </XDSList>
}
/>
}>
@@ -171,37 +203,37 @@ export const SuiteHeader: Story = {
<XDSSideNav
header={
<XDSSideNavHeader
- icon={<XDSIcon icon={CubeIcon} size="lg" />}
+ icon={
+ <XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />
+ }
supertitle="Suite Name"
supertitleHref="/suite"
title="Product Name"
titleHref="/product"
menu={
- <div style={{padding: 12}}>
- <XDSVStack gap="space1">
+ <XDSList
+ density="compact"
+ header={
<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>
+ }>
+ <XDSListItem
+ label="Analytics"
+ startContent={<XDSIcon icon={ChartBarIcon} size="sm" />}
+ href="#"
+ />
+ <XDSListItem
+ label="Commerce"
+ startContent={<XDSIcon icon={CubeIcon} size="sm" />}
+ href="#"
+ />
+ <XDSListItem
+ label="Team Hub"
+ startContent={<XDSIcon icon={UserGroupIcon} size="sm" />}
+ href="#"
+ />
+ </XDSList>
}
/>
}>
@@ -228,7 +260,9 @@ export const NestedItems: Story = {
<XDSSideNav
header={
<XDSSideNavHeader
- icon={<XDSIcon icon={CubeIcon} size="lg" />}
+ icon={
+ <XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />
+ }
title="My App"
/>
}>
@@ -262,7 +296,9 @@ export const WithFooter: Story = {
<XDSSideNav
header={
<XDSSideNavHeader
- icon={<XDSIcon icon={CubeIcon} size="lg" />}
+ icon={
+ <XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />
+ }
title="My App"
/>
}
@@ -305,7 +341,9 @@ export const DisabledItem: Story = {
<XDSSideNav
header={
<XDSSideNavHeader
- icon={<XDSIcon icon={CubeIcon} size="lg" />}
+ icon={
+ <XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />
+ }
title="My App"
/>
}>
@@ -337,7 +375,9 @@ export const HiddenSectionHeader: Story = {
<XDSSideNav
header={
<XDSSideNavHeader
- icon={<XDSIcon icon={CubeIcon} size="lg" />}
+ icon={
+ <XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />
+ }
title="My App"
/>
}>
diff --git a/apps/storybook/stories/TopNav.stories.tsx b/apps/storybook/stories/TopNav.stories.tsx
index eee7e3c069..6883d5aade 100644
--- a/apps/storybook/stories/TopNav.stories.tsx
+++ b/apps/storybook/stories/TopNav.stories.tsx
@@ -1,10 +1,6 @@
import type {Meta, StoryObj} from '@storybook/react';
-import {
- XDSTopNav,
- XDSTopNavTitle,
- XDSTopNavTitleIcon,
- XDSTopNavItem,
-} from '@xds/core/TopNav';
+import {XDSTopNav, XDSTopNavTitle, XDSTopNavItem} from '@xds/core/TopNav';
+import {XDSNavIcon} from '@xds/core/NavIcon';
import {XDSButton} from '@xds/core/Button';
import {
HomeIcon,
@@ -75,9 +71,7 @@ export const WithLogo: Story = {
<XDSTopNavTitle
title="Dashboard"
logo={
- <XDSTopNavTitleIcon
- icon={<CubeIcon style={{width: 16, height: 16}} />}
- />
+ <XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />
}
href="#"
/>
@@ -106,10 +100,7 @@ export const TitleOnly: Story = {
<XDSTopNavTitle
title="Simple App"
logo={
- <XDSTopNavTitleIcon
- icon={<HomeIcon style={{width: 16, height: 16}} />}
- size="sm"
- />
+ <XDSNavIcon icon={<HomeIcon style={{width: 16, height: 16}} />} />
}
/>
),
@@ -138,55 +129,6 @@ export const NavItemStates: Story = {
),
};
-export const TitleIconSizes: Story = {
- render: () => (
- <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
- <XDSTopNav
- label="Small icon"
- title={
- <XDSTopNavTitle
- title="Small"
- logo={
- <XDSTopNavTitleIcon
- icon={<CubeIcon style={{width: 14, height: 14}} />}
- size="sm"
- />
- }
- />
- }
- />
- <XDSTopNav
- label="Medium icon"
- title={
- <XDSTopNavTitle
- title="Medium"
- logo={
- <XDSTopNavTitleIcon
- icon={<CubeIcon style={{width: 16, height: 16}} />}
- size="md"
- />
- }
- />
- }
- />
- <XDSTopNav
- label="Large icon"
- title={
- <XDSTopNavTitle
- title="Large"
- logo={
- <XDSTopNavTitleIcon
- icon={<CubeIcon style={{width: 18, height: 18}} />}
- size="lg"
- />
- }
- />
- }
- />
- </div>
- ),
-};
-
export const CenteredNavigation: Story = {
render: () => (
<XDSTopNav
@@ -195,9 +137,7 @@ export const CenteredNavigation: Story = {
<XDSTopNavTitle
title="My App"
logo={
- <XDSTopNavTitleIcon
- icon={<CubeIcon style={{width: 16, height: 16}} />}
- />
+ <XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />
}
href="#"
/>
@@ -235,7 +175,7 @@ export const CenteredWithStartContent: Story = {
<XDSTopNavTitle
title="Dashboard"
logo={
- <XDSTopNavTitleIcon
+ <XDSNavIcon
icon={<ChartBarIcon style={{width: 16, height: 16}} />}
/>
}
@@ -298,7 +238,7 @@ export const FullExample: Story = {
<XDSTopNavTitle
title="Enterprise Dashboard"
logo={
- <XDSTopNavTitleIcon
+ <XDSNavIcon
icon={<ChartBarIcon style={{width: 16, height: 16}} />}
/>
}
diff --git a/internal/vibe-tests/src/universal-eval.ts b/internal/vibe-tests/src/universal-eval.ts
index 749a63d778..734000c022 100644
--- a/internal/vibe-tests/src/universal-eval.ts
+++ b/internal/vibe-tests/src/universal-eval.ts
@@ -141,6 +141,7 @@ function discoverXDSComponents(): Set<string> {
'XDSTopNavMenu',
'XDSTopNavTitle',
'XDSTopNavTitleIcon',
+ 'XDSNavIcon',
'XDSVStack',
'Theme',
'defaultTheme',
diff --git a/packages/core/package.json b/packages/core/package.json
index ed2c6293d8..d13a1bad81 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"
},
+ "./NavIcon": {
+ "source": "./src/NavIcon/index.ts",
+ "types": "./dist/NavIcon/index.d.ts",
+ "import": "./dist/NavIcon/index.mjs",
+ "require": "./dist/NavIcon/index.js"
+ },
"./NumberInput": {
"source": "./src/NumberInput/index.ts",
"types": "./dist/NumberInput/index.d.ts",
diff --git a/packages/core/src/NavIcon/README.md b/packages/core/src/NavIcon/README.md
new file mode 100644
index 0000000000..1dd7559134
--- /dev/null
+++ b/packages/core/src/NavIcon/README.md
@@ -0,0 +1,65 @@
+# /packages/core/src/NavIcon
+
+Circular icon container for navigation headers.
+
+<!-- SYNC: When files in this directory change, update this document. -->
+
+## Features
+
+- **Shared** — used in both XDSTopNavTitle and XDSPageNavHeader
+- **Accent background** — uses `--color-accent` with `--color-icon-on-media` contrast
+- **Fixed size** — renders at the medium (`--size-md`) design token size
+
+## Usage
+
+```tsx
+import {XDSNavIcon} from '@xds/core/NavIcon';
+import {CubeIcon} from '@heroicons/react/24/solid';
+
+// In top navigation
+<XDSTopNavTitle
+ title="My App"
+ logo={<XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />}
+/>
+
+// In side navigation
+<XDSPageNavHeader
+ icon={<XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />}
+ title="My App"
+/>
+```
+
+## Components
+
+- **XDSNavIcon** — Circular icon container with accent background
+
+## Props
+
+### XDSNavIcon
+
+| Prop | Type | Default | Description |
+| ------ | ----------- | ------- | ----------------------- |
+| `icon` | `ReactNode` | — | Icon element (required) |
+
+## Files
+
+| File | Role | Purpose |
+| --------------------- | ----- | --------------------------- |
+| `index.ts` | Entry | Exports component and types |
+| `XDSNavIcon.tsx` | Core | Circular icon container |
+| `XDSNavIcon.test.tsx` | Test | Unit tests |
+
+## Migration from XDSTopNavTitleIcon
+
+`XDSNavIcon` replaces `XDSTopNavTitleIcon`. The old component is still
+exported from `@xds/core/TopNav` as a deprecated alias.
+
+```diff
+- import {XDSTopNavTitleIcon} from '@xds/core/TopNav';
++ import {XDSNavIcon} from '@xds/core/NavIcon';
+
+- <XDSTopNavTitleIcon icon={<MyIcon />} size="md" />
++ <XDSNavIcon icon={<MyIcon />} />
+```
+
+The `size` prop has been removed — `XDSNavIcon` always renders at medium size.
diff --git a/packages/core/src/NavIcon/XDSNavIcon.test.tsx b/packages/core/src/NavIcon/XDSNavIcon.test.tsx
new file mode 100644
index 0000000000..40944eb021
--- /dev/null
+++ b/packages/core/src/NavIcon/XDSNavIcon.test.tsx
@@ -0,0 +1,30 @@
+/**
+ * @file XDSNavIcon.test.tsx
+ * @input Uses vitest, @testing-library/react, XDSNavIcon
+ * @output Unit tests for XDSNavIcon component
+ * @position Testing; validates XDSNavIcon implementation
+ *
+ * SYNC: When XDSNavIcon changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {XDSNavIcon} from './XDSNavIcon';
+
+describe('XDSNavIcon', () => {
+ it('renders icon content', () => {
+ render(<XDSNavIcon icon={<span data-testid="icon">Icon</span>} />);
+ expect(screen.getByTestId('icon')).toBeInTheDocument();
+ });
+
+ it('forwards ref correctly', () => {
+ const ref = vi.fn();
+ render(<XDSNavIcon icon={<span>Icon</span>} ref={ref} />);
+ expect(ref).toHaveBeenCalledWith(expect.any(HTMLSpanElement));
+ });
+
+ it('passes data-testid', () => {
+ render(<XDSNavIcon icon={<span>Icon</span>} data-testid="nav-icon" />);
+ expect(screen.getByTestId('nav-icon')).toBeInTheDocument();
+ });
+});
diff --git a/packages/core/src/NavIcon/XDSNavIcon.tsx b/packages/core/src/NavIcon/XDSNavIcon.tsx
new file mode 100644
index 0000000000..12d61ba3e1
--- /dev/null
+++ b/packages/core/src/NavIcon/XDSNavIcon.tsx
@@ -0,0 +1,80 @@
+/**
+ * @file XDSNavIcon.tsx
+ * @input Uses React forwardRef, HTMLAttributes, ReactNode
+ * @output Exports XDSNavIcon component and XDSNavIconProps
+ * @position Shared circular icon container for navigation headers (TopNav, PageNav)
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/NavIcon/README.md
+ * - /packages/core/src/NavIcon/XDSNavIcon.test.tsx
+ * - /packages/core/src/NavIcon/index.ts
+ * - /apps/storybook/stories/TopNav.stories.tsx
+ * - /apps/storybook/stories/PageNav.stories.tsx
+ */
+
+import {forwardRef, type HTMLAttributes, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars, sizeVars} from '../theme/tokens.stylex';
+
+/**
+ * NavIcon styles
+ */
+const styles = stylex.create({
+ base: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ borderRadius: '50%',
+ backgroundColor: colorVars['--color-accent'],
+ color: colorVars['--color-icon-on-media'],
+ flexShrink: 0,
+ width: sizeVars['--size-md'],
+ height: sizeVars['--size-md'],
+ },
+});
+
+export interface XDSNavIconProps extends Omit<
+ HTMLAttributes<HTMLSpanElement>,
+ 'style' | 'className'
+> {
+ /**
+ * The icon element to render inside the circular background.
+ * Should be an XDSIcon or similar icon component.
+ */
+ icon: ReactNode;
+}
+
+/**
+ * Circular icon container for navigation headers.
+ *
+ * Wraps an icon with a circular accent-colored background, suitable for
+ * use as a logo in top navigation or side navigation title areas.
+ *
+ * @example
+ * ```tsx
+ * import {HomeIcon} from '@heroicons/react/24/solid';
+ *
+ * // In XDSTopNavTitle
+ * <XDSTopNavTitle
+ * title="Dashboard"
+ * logo={<XDSNavIcon icon={<HomeIcon style={{width: 16, height: 16}} />} />}
+ * />
+ *
+ * // In XDSPageNavHeader
+ * <XDSPageNavHeader
+ * icon={<XDSNavIcon icon={<HomeIcon style={{width: 16, height: 16}} />} />}
+ * title="My App"
+ * />
+ * ```
+ */
+export const XDSNavIcon = forwardRef<HTMLSpanElement, XDSNavIconProps>(
+ function XDSNavIcon({icon, ...props}, ref) {
+ return (
+ <span ref={ref} {...stylex.props(styles.base)} {...props}>
+ {icon}
+ </span>
+ );
+ },
+);
+
+XDSNavIcon.displayName = 'XDSNavIcon';
diff --git a/packages/core/src/NavIcon/index.ts b/packages/core/src/NavIcon/index.ts
new file mode 100644
index 0000000000..9f69801cee
--- /dev/null
+++ b/packages/core/src/NavIcon/index.ts
@@ -0,0 +1,11 @@
+/**
+ * @file index.ts
+ * @input Imports from XDSNavIcon.tsx
+ * @output Exports XDSNavIcon component and types
+ * @position Entry point for NavIcon module
+ *
+ * SYNC: When modified, update /packages/core/src/NavIcon/README.md
+ */
+
+export {XDSNavIcon} from './XDSNavIcon';
+export type {XDSNavIconProps} from './XDSNavIcon';
diff --git a/packages/core/src/SideNav/XDSSideNavItem.tsx b/packages/core/src/SideNav/XDSSideNavItem.tsx
index 834116499e..c0d74de1d5 100644
--- a/packages/core/src/SideNav/XDSSideNavItem.tsx
+++ b/packages/core/src/SideNav/XDSSideNavItem.tsx
@@ -63,10 +63,10 @@ const styles = stylex.create({
},
},
selected: {
- backgroundColor: colorVars['--color-accent-deemphasized'],
+ backgroundColor: colorVars['--color-deemphasized'],
fontWeight: fontWeightVars['--font-weight-medium'],
':hover': {
- backgroundColor: colorVars['--color-accent-deemphasized'],
+ backgroundColor: colorVars['--color-deemphasized'],
},
},
disabled: {
@@ -201,7 +201,7 @@ export const XDSSideNavItem = forwardRef<HTMLElement, XDSSideNavItemProps>(
icon={displayIcon}
size="sm"
color={
- isSelected ? 'accent' : isDisabled ? 'disabled' : 'secondary'
+ isSelected ? 'primary' : isDisabled ? 'disabled' : 'secondary'
}
/>
)}
diff --git a/packages/core/src/TopNav/README.md b/packages/core/src/TopNav/README.md
index 1e5884c215..cef45fe54a 100644
--- a/packages/core/src/TopNav/README.md
+++ b/packages/core/src/TopNav/README.md
@@ -6,20 +6,16 @@ Top navigation bar component for application headers.
## Features
-- **Slot-based layout**: `title`, `startContent`, `centerContent`, `endContent` for flexible organization
-- **Companion components**: XDSTopNavTitle, XDSTopNavTitleIcon, XDSTopNavItem
+- **Slot-based layout**: `title`, `startContent`, `endContent` for flexible organization
+- **Companion components**: XDSTopNavTitle, XDSTopNavItem
- **Accessible**: Proper ARIA roles and keyboard navigation
- **Themeable**: Uses XDS design tokens for styling
## Usage
```tsx
-import {
- XDSTopNav,
- XDSTopNavTitle,
- XDSTopNavTitleIcon,
- XDSTopNavItem,
-} from '@xds/core/TopNav';
+import {XDSTopNav, XDSTopNavTitle, XDSTopNavItem} from '@xds/core/TopNav';
+import {XDSNavIcon} from '@xds/core/NavIcon';
import {XDSButton} from '@xds/core/Button';
import {HomeIcon, BellIcon, UserCircleIcon} from '@heroicons/react/24/outline';
@@ -28,11 +24,7 @@ import {HomeIcon, BellIcon, UserCircleIcon} from '@heroicons/react/24/outline';
title={
<XDSTopNavTitle
title="My App"
- logo={
- <XDSTopNavTitleIcon
- icon={<HomeIcon style={{width: 16, height: 16}} />}
- />
- }
+ logo={<XDSNavIcon icon={<HomeIcon style={{width: 16, height: 16}} />} />}
href="/"
/>
}
@@ -64,36 +56,29 @@ import {HomeIcon, BellIcon, UserCircleIcon} from '@heroicons/react/24/outline';
- **XDSTopNav** — Main navigation container
- **XDSTopNavTitle** — Title with logo and text
-- **XDSTopNavTitleIcon** — Circular icon container for the title
- **XDSTopNavItem** — Navigation link item
- **XDSTopNavMenu** — Navigation item with hover-triggered overflow menu
+For the circular icon container, use `XDSNavIcon` from `@xds/core/NavIcon`.
+
## Props
### XDSTopNav
-| Prop | Type | Default | Description |
-| --------------- | ----------- | ------- | ------------------------------------------------------------------ |
-| `title` | `ReactNode` | — | Title slot (logo, brand) - left aligned |
-| `startContent` | `ReactNode` | — | Start content (nav items, breadcrumbs) - left aligned |
-| `centerContent` | `ReactNode` | — | Center content (nav items) - centered; enables three-column layout |
-| `endContent` | `ReactNode` | — | End content (search, icons, profile) - right aligned |
-| `label` | `string` | — | Accessible label for navigation landmark |
+| Prop | Type | Default | Description |
+| -------------- | ----------- | ------- | ----------------------------------------------------- |
+| `title` | `ReactNode` | — | Title slot (logo, brand) - left aligned |
+| `startContent` | `ReactNode` | — | Start content (nav items, breadcrumbs) - left aligned |
+| `endContent` | `ReactNode` | — | End content (search, icons, profile) - right aligned |
+| `label` | `string` | — | Accessible label for navigation landmark |
### XDSTopNavTitle
-| Prop | Type | Default | Description |
-| ------- | ----------- | ------- | ---------------------------------------- |
-| `title` | `string` | — | Title text to display |
-| `logo` | `ReactNode` | — | Logo element (image, XDSTopNavTitleIcon) |
-| `href` | `string` | — | URL to navigate to when clicked |
-
-### XDSTopNavTitleIcon
-
-| Prop | Type | Default | Description |
-| ------ | ---------------------- | ------- | -------------------------- |
-| `icon` | `ReactNode` | — | Icon element (required) |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of circular container |
+| Prop | Type | Default | Description |
+| ------- | ----------- | ------- | -------------------------------- |
+| `title` | `string` | — | Title text to display |
+| `logo` | `ReactNode` | — | Logo element (image, XDSNavIcon) |
+| `href` | `string` | — | URL to navigate to when clicked |
### XDSTopNavItem
@@ -125,6 +110,14 @@ import {HomeIcon, BellIcon, UserCircleIcon} from '@heroicons/react/24/outline';
| `href` | `string` | URL to navigate to |
| `onClick` | `() => void` | Callback on click |
+## Selected State
+
+When `isSelected` is true, nav items show:
+
+- **Background**: `--color-accent-deemphasized` (subtle accent tint)
+- **Text**: `--color-text-primary` with semibold weight
+- **Icon**: Primary color; use `selectedIcon` for filled variants
+
## Theming
Themes can override `TopNav` styles via `ComponentStyles`:
@@ -154,7 +147,6 @@ const theme: Theme = {
| `index.ts` | Entry | Exports components and types |
| `XDSTopNav.tsx` | Core | Main navigation container |
| `XDSTopNavTitle.tsx` | Core | Title with logo and text |
-| `XDSTopNavTitleIcon.tsx` | Core | Circular icon container |
| `XDSTopNavItem.tsx` | Core | Navigation link item |
| `XDSTopNavMenu.tsx` | Core | Nav item with hover overflow menu |
| `XDSTopNav.test.tsx` | Test | Unit tests for TopNav components |
@@ -193,8 +185,6 @@ import {XDSTopNav, XDSTopNavTitle, XDSTopNavItem} from '@xds/core/TopNav';
## Slot Layout Structure
-**Standard layout** (no `centerContent`):
-
```
┌─────────────────────────────────────────────────────────────┐
│ [title] [startContent ...] [...endContent] │
@@ -223,8 +213,17 @@ left/right content widths. The right column is always rendered (even when
- Without `centerContent`: title and startContent grow to push endContent right
- With `centerContent`: switches to CSS grid (`1fr auto 1fr`) for true centering
- XDSTopNavItem supports `aria-current="page"` when `isSelected` is true
-- XDSTopNavTitleIcon uses `--color-accent` background with `--color-icon-on-media` for contrast
- Default height is 48px with 16px horizontal padding
- Uses `--color-navbar` token for background (defaults to white)
- Positioning (sticky/fixed) is handled by the layout system (e.g. XDSAppShell), not TopNav itself
- Dividers are controlled by the layout system (e.g. XDSLayoutHeader's `hasDivider`), not TopNav
+
+## Migration
+
+`XDSTopNavTitleIcon` has been renamed to `XDSNavIcon` and moved to its own module.
+The old name is still exported from `@xds/core/TopNav` as a deprecated alias.
+
+```diff
+- import {XDSTopNavTitleIcon} from '@xds/core/TopNav';
++ import {XDSNavIcon} from '@xds/core/NavIcon';
+```
diff --git a/packages/core/src/TopNav/XDSTopNav.test.tsx b/packages/core/src/TopNav/XDSTopNav.test.tsx
index 02d36d23de..3798839f89 100644
--- a/packages/core/src/TopNav/XDSTopNav.test.tsx
+++ b/packages/core/src/TopNav/XDSTopNav.test.tsx
@@ -12,7 +12,7 @@ import {render, screen} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {XDSTopNav} from './XDSTopNav';
import {XDSTopNavTitle} from './XDSTopNavTitle';
-import {XDSTopNavTitleIcon} from './XDSTopNavTitleIcon';
+import {XDSNavIcon} from '../NavIcon';
import {XDSTopNavItem} from './XDSTopNavItem';
describe('XDSTopNav', () => {
@@ -164,44 +164,15 @@ describe('XDSTopNavTitle', () => {
});
});
-describe('XDSTopNavTitleIcon', () => {
+describe('XDSNavIcon', () => {
it('renders icon content', () => {
- render(<XDSTopNavTitleIcon icon={<span data-testid="icon">Icon</span>} />);
+ render(<XDSNavIcon icon={<span data-testid="icon">Icon</span>} />);
expect(screen.getByTestId('icon')).toBeInTheDocument();
});
- it('renders with different sizes', () => {
- const {rerender} = render(
- <XDSTopNavTitleIcon
- icon={<span>Icon</span>}
- size="sm"
- data-testid="icon-wrapper"
- />,
- );
- expect(screen.getByTestId('icon-wrapper')).toBeInTheDocument();
-
- rerender(
- <XDSTopNavTitleIcon
- icon={<span>Icon</span>}
- size="md"
- data-testid="icon-wrapper"
- />,
- );
- expect(screen.getByTestId('icon-wrapper')).toBeInTheDocument();
-
- rerender(
- <XDSTopNavTitleIcon
- icon={<span>Icon</span>}
- size="lg"
- data-testid="icon-wrapper"
- />,
- );
- expect(screen.getByTestId('icon-wrapper')).toBeInTheDocument();
- });
-
it('forwards ref correctly', () => {
const ref = vi.fn();
- render(<XDSTopNavTitleIcon icon={<span>Icon</span>} ref={ref} />);
+ render(<XDSNavIcon icon={<span>Icon</span>} ref={ref} />);
expect(ref).toHaveBeenCalledWith(expect.any(HTMLSpanElement));
});
});
diff --git a/packages/core/src/TopNav/XDSTopNavItem.tsx b/packages/core/src/TopNav/XDSTopNavItem.tsx
index a6a0a5ea56..2d3b202e29 100644
--- a/packages/core/src/TopNav/XDSTopNavItem.tsx
+++ b/packages/core/src/TopNav/XDSTopNavItem.tsx
@@ -57,12 +57,12 @@ const styles = stylex.create({
},
},
selected: {
- color: colorVars['--color-accent-text'],
+ color: colorVars['--color-text-primary'],
fontWeight: fontWeightVars['--font-weight-semibold'],
backgroundColor: {
- default: colorVars['--color-accent-deemphasized'],
- ':hover': colorVars['--color-accent-deemphasized'],
- ':active': colorVars['--color-accent-deemphasized'],
+ default: colorVars['--color-deemphasized'],
+ ':hover': colorVars['--color-deemphasized'],
+ ':active': colorVars['--color-deemphasized'],
},
},
disabled: {
diff --git a/packages/core/src/TopNav/XDSTopNavTitle.tsx b/packages/core/src/TopNav/XDSTopNavTitle.tsx
index 6b92acac8f..fb1fca79f4 100644
--- a/packages/core/src/TopNav/XDSTopNavTitle.tsx
+++ b/packages/core/src/TopNav/XDSTopNavTitle.tsx
@@ -59,7 +59,7 @@ export interface XDSTopNavTitleProps extends Omit<
title?: string;
/**
* Logo element to display before the title.
- * Can be an image, XDSTopNavTitleIcon, or any ReactNode.
+ * Can be an image, XDSNavIcon, or any ReactNode.
*/
logo?: ReactNode;
/**
@@ -73,7 +73,7 @@ export interface XDSTopNavTitleProps extends Omit<
* Title component for XDSTopNav.
*
* Displays a logo and/or title text, optionally as a clickable link.
- * Use with XDSTopNavTitleIcon to create a circular icon background.
+ * Use with XDSNavIcon to create a circular icon background.
*
* @example
* ```tsx
@@ -87,7 +87,7 @@ export interface XDSTopNavTitleProps extends Omit<
* // With circular icon
* <XDSTopNavTitle
* title="Dashboard"
- * logo={<XDSTopNavTitleIcon icon={<HomeIcon />} />}
+ * logo={<XDSNavIcon icon={<HomeIcon />} />}
* />
*
* // Logo only
diff --git a/packages/core/src/TopNav/XDSTopNavTitleIcon.tsx b/packages/core/src/TopNav/XDSTopNavTitleIcon.tsx
deleted file mode 100644
index c6847579d6..0000000000
--- a/packages/core/src/TopNav/XDSTopNavTitleIcon.tsx
+++ /dev/null
@@ -1,97 +0,0 @@
-/**
- * @file XDSTopNavTitleIcon.tsx
- * @input Uses React forwardRef, HTMLAttributes, ReactNode
- * @output Exports XDSTopNavTitleIcon component and XDSTopNavTitleIconProps
- * @position Companion component for XDSTopNavTitle logo slot
- *
- * SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/TopNav/README.md
- * - /packages/core/src/TopNav/XDSTopNav.test.tsx
- * - /packages/core/src/TopNav/index.ts
- * - /apps/storybook/stories/TopNav.stories.tsx
- */
-
-import {forwardRef, type HTMLAttributes, type ReactNode} from 'react';
-import * as stylex from '@stylexjs/stylex';
-import {colorVars, sizeVars} from '../theme/tokens.stylex';
-
-/**
- * TitleIcon styles
- */
-const styles = stylex.create({
- base: {
- display: 'flex',
- alignItems: 'center',
- justifyContent: 'center',
- borderRadius: '50%',
- backgroundColor: colorVars['--color-accent'],
- color: colorVars['--color-icon-on-media'],
- flexShrink: 0,
- },
- sm: {
- width: sizeVars['--size-sm'],
- height: sizeVars['--size-sm'],
- },
- md: {
- width: sizeVars['--size-md'],
- height: sizeVars['--size-md'],
- },
- lg: {
- width: sizeVars['--size-lg'],
- height: sizeVars['--size-lg'],
- },
-});
-
-/**
- * Size variants for the title icon
- */
-export type XDSTopNavTitleIconSize = 'sm' | 'md' | 'lg';
-
-export interface XDSTopNavTitleIconProps extends Omit<
- HTMLAttributes<HTMLSpanElement>,
- 'style' | 'className'
-> {
- /**
- * The icon element to render inside the circular background.
- * Should be an XDSIcon or similar icon component.
- */
- icon: ReactNode;
- /**
- * Size of the circular icon container.
- * @default 'md'
- */
- size?: XDSTopNavTitleIconSize;
-}
-
-/**
- * Circular icon container for XDSTopNavTitle.
- *
- * Wraps an icon with a circular colored background, suitable for
- * use as a logo in the top navigation title area.
- *
- * @example
- * ```tsx
- * import {HomeIcon} from '@heroicons/react/24/solid';
- *
- * <XDSTopNavTitle
- * title="Dashboard"
- * logo={
- * <XDSTopNavTitleIcon
- * icon={<HomeIcon style={{width: 16, height: 16}} />}
- * />
- * }
- * />
- * ```
- */
-export const XDSTopNavTitleIcon = forwardRef<
- HTMLSpanElement,
- XDSTopNavTitleIconProps
->(function XDSTopNavTitleIcon({icon, size = 'md', ...props}, ref) {
- return (
- <span ref={ref} {...stylex.props(styles.base, styles[size])} {...props}>
- {icon}
- </span>
- );
-});
-
-XDSTopNavTitleIcon.displayName = 'XDSTopNavTitleIcon';
diff --git a/packages/core/src/TopNav/index.ts b/packages/core/src/TopNav/index.ts
index 345db63bcb..3f280e4070 100644
--- a/packages/core/src/TopNav/index.ts
+++ b/packages/core/src/TopNav/index.ts
@@ -13,11 +13,14 @@ export type {XDSTopNavProps} from './XDSTopNav';
export {XDSTopNavTitle} from './XDSTopNavTitle';
export type {XDSTopNavTitleProps} from './XDSTopNavTitle';
-export {XDSTopNavTitleIcon} from './XDSTopNavTitleIcon';
-export type {
- XDSTopNavTitleIconProps,
- XDSTopNavTitleIconSize,
-} from './XDSTopNavTitleIcon';
+/**
+ * @deprecated Use `XDSNavIcon` from `@xds/core/NavIcon` instead.
+ */
+export {XDSNavIcon as XDSTopNavTitleIcon} from '../NavIcon';
+/**
+ * @deprecated Use `XDSNavIconProps` from `@xds/core/NavIcon` instead.
+ */
+export type {XDSNavIconProps as XDSTopNavTitleIconProps} from '../NavIcon';
export {XDSTopNavItem} from './XDSTopNavItem';
export type {XDSTopNavItemProps} from './XDSTopNavItem';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 0fea47188a..0a8fa4ad7e 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -25,6 +25,7 @@ export * from './Divider';
export * from './EmptyState';
export * from './Link';
export * from './List';
+export * from './NavIcon';
export * from './Slider';
export * from './Stack';
export * from './Switch';