[Brand Refactor] Update SubdomainNavBar

[danielguillan]

Summary

Updates SubdomainNavBar with the new brand refactor styles and expands its content, search, and responsive navigation capabilities.

Towards https://github.com/github/brand-experience/issues/223

List of notable changes:

• Updates the default SubdomainNavBar styling with the new gridline design.
• Adds leadingComponent and trailingComponent content slots.
• Adds an input search type trigger on desktop, configurable keyboard shortcuts, grouped results, and localized labels.
• Adds imperative openSearch() and closeSearch() methods.
• Improves desktop link overflow and focus management.
• Refines responsive and mobile menu behavior.
• Updates navigation link hover, focus, current-page, and expanded states.
• Updates component documentation, tests, stories, and visual snapshots.

What should reviewers focus on?

• Verify the visual treatment across constrained and full-width layouts, light and dark modes, and open menu and search states.
• Verify spacing and alignment across desktop, tablet, and mobile.
• Verify links move into and out of the More menu in order as the available width changes.
• Verify custom content slots render in the expected position across viewport sizes.
• Verify search behavior, includin keyboard shortcuts, grouped results, localization, and focus management.
• Verify keyboard and assistive technology navigation when links overflow or the mobile menu contains only custom slot content.
• Review the new APIs and confirm they cover the expected use cases.

Steps to test:

1. Open the SubdomainNavBar stories in the Storybook preview.
2. Review the default, playground, leading and trailing component, input search, grouped results, keyboard shortcut, imperative search API, overflow menu, and mobile stories.
3. Resize the viewport and verify links move into and out of the More menu in order.
4. Verify overflowed links are not exposed to keyboard or assistive technology navigation.
5. Interact with navigation and search using a mouse and keyboard, including opening and closing menus and dialogs, navigating results, and returning focus to the trigger.
6. Toggle light and dark modes and verify hover, focus, current-page, and expanded states.
7. Open the docs preview and verify the updated examples and API documentation.

Contributor checklist:

• All new and existing CI checks pass
• Tests prove that the feature works and covers both happy and unhappy paths
• Any drop in coverage, breaking changes or regressions have been documented above
• UI Changes contain new visual snapshots (generated by adding update snapshots label to the PR)
• All developer debugging and non-functional logging has been removed
• Related issues have been referenced in the PR description

Reviewer checklist:

• Check that pull request and proposed changes adhere to our contribution guidelines and code of conduct
• Check that tests prove the feature works and covers both happy and unhappy paths
• Check that there aren't other open Pull Requests for the same update/change

Screenshots:

Desktop navigation

Before	After

Search

Before	After

Mobile menu

Before	After

[changeset-bot]

🦋 Changeset detected

Latest commit: f2995a4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@primer/react-brand	Minor
@primer/brand-primitives	Minor
@primer/brand-docs	Minor
@primer/brand-css	Minor
@primer/brand-e2e	Minor
@primer/brand-fonts	Minor
@primer/brand-mcp	Minor
@primer/brand-config	Minor
@primer/brand-storybook	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

🔍 Design token changes found

View CSS variable changes

+ --brand-SubdomainNavBar-color-link-bgColor: var(--base-color-scale-gray-1);

+ --brand-SubdomainNavBar-searchDialog-shadowColor: rgba(0, 0, 0, 0.1);

+ --brand-SubdomainNavBar-searchDialog-backdropColor: rgba(0, 0, 0, 0.2);

+ --brand-SubdomainNavBar-color-link-bgColor: var(--base-color-scale-gray-6);

+ --brand-SubdomainNavBar-searchDialog-shadowColor: rgba(0, 0, 0, 0.1);

+ --brand-SubdomainNavBar-searchDialog-backdropColor: rgba(0, 0, 0, 0.2);

[github-actions]

🟢 Bundle size report

Check	Main	Branch	Change
UMD — full bundle (JS)	101.76 kB	104.15 kB	⬆️ +2.39 kB (+2.4%)
UMD — full bundle (CSS)	67.57 kB	69.63 kB	⬆️ +2.06 kB (+3.1%)
ESM — full bundle (JS + CSS)	1.59 MB	1.61 MB	⬆️ +21.63 kB (+1.3%)
ESM — tree-shaken simple (Button)	70.86 kB	72.94 kB	⬆️ +2.08 kB (+2.9%)
ESM — tree-shaken complex (ActionMenu)	79.82 kB	81.90 kB	⬆️ +2.08 kB (+2.6%)

[github-actions]

🟢 Unit test coverage changes found

Unit test coverage has been updated through this PR.

Changes: 0 new tests, 0 removed tests, 1 improved, 0 decreased

Component/Hook	Statements	Functions	Branches	Change
SubdomainNavBar	71.9% 84.7%	79.4% 94.2%	66.7% 79.3%	+14.8%

[github-actions]

🟢 No visual differences found

Our visual comparison tests did not find any differences in the UI.

[Copilot]

Pull request overview

Updates SubdomainNavBar to the brand-refactor visual style while expanding layout, search, and responsive navigation capabilities in the @primer/react-brand component library.

Changes:

• Refactors layout/styling (gridline design), adds leadingComponent/trailingComponent, and introduces an imperative search ref API.
• Reworks search UX (input-style trigger, keyboard shortcut config, grouped results, localized labels) and desktop overflow behavior (More menu + focus management).
• Updates supporting assets: docs, stories, unit tests, visual tests, E2E snapshot generation, and design tokens.

Show a summary per file

File	Description
packages/react/src/SubdomainNavBar/useVisibilityObserver.ts	Replaces IntersectionObserver-based link visibility with measurement + ResizeObserver logic.
packages/react/src/SubdomainNavBar/SubdomainNavBarLinkContext.ts	Adds context for overflow state and link-click handling across visible/overflow menus.
packages/react/src/SubdomainNavBar/SubdomainNavBar.visual.spec.ts	Expands visual coverage for new stories and states (overflow, grouped results, mobile slot-only menu).
packages/react/src/SubdomainNavBar/SubdomainNavBar.tsx	Main component refactor: new slots, search API/UX, overflow accessibility behavior, and responsive updates.
packages/react/src/SubdomainNavBar/SubdomainNavBar.test.tsx	Adds extensive unit coverage for new behaviors (overflow, keyboard shortcuts, ref API, slots, dialog behavior).
packages/react/src/SubdomainNavBar/SubdomainNavBar.stories.tsx	Adds/updates Storybook stories to demonstrate new APIs and responsive behaviors.
packages/react/src/SubdomainNavBar/SubdomainNavBar.module.css.d.ts	Updates CSS module typings for new/removed classnames.
packages/react/src/SubdomainNavBar/SubdomainNavBar.module.css	Major style updates for gridline design, responsive layout, overflow menu, and search dialog.
packages/react/src/SubdomainNavBar/NavigationVisbilityObserver.tsx	Reworks desktop overflow measurement and introduces anchored overflow menu positioning and focus handling.
packages/e2e/scripts/playwright/playwright.generate-tests.ts	Adds per-story viewport/timeout/before-screenshot hooks for more reliable visual snapshots.
packages/design-tokens/src/tokens/functional/components/subdomain-nav-bar/colors.js	Adds token values for search dialog shadow/backdrop colors.
apps/next-docs/content/components/SubdomainNavBar/index.mdx	Updates documentation to match new props, search model, and accessibility guidance.
.changeset/tasty-cameras-search.md	Minor changeset documenting new slots, search APIs, and overflow behavior + token changes.
.changeset/quiet-pills-align.md	Patch changeset for desktop navigation pill state styling updates.

Review details

• Files reviewed: 13/42 changed files
• Comments generated: 4
• Review effort level: Lite