Fix separator rendering bug in SubNav

[rezrah]

Summary

Resolves https://github.com/github/primer/issues/5548

Fixes a layout shift problem that occurs in certain SSR environments where an observable delay in hydration led to the separator in SubNav loading in client side and after the adjacent elements were initially rendered on page.

List of notable changes:

• Removed the previous reliance on isLarge condition in SubNav for rendering the separator and certain children. This was causing the initial render to exclude an important DOM node in dotcom, until after hydration was complete.
  • Fixed by replacing isLarge logic with CSS equivalents. Does the same thing.
• Removed a test case that is no longer neded, as we now use CSS to hide the element.
• Added a missing storybook example (including for narrow viewports) where aria-current isn't set. Separator should be hidden on narrow viewports here.
• Added optical alignment of the separator. Previously too high.

What should reviewers focus on?

• The intended fix can only be tested in dotcom
• Instead, we should look for regressions in general subnav behaviour. This can be done by referencing the preview Storybook examples against the current Live counterparts.

Steps to test:

1. Open the preview storybook
2. Open the production storybook
3. Compare each story and make sure there's no noticeable regression

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:

Demo of the fix running in dotcom 👇

Before	After
Screen.Recording.2025-07-28.at.16.38.36.mov	Screen.Recording.2025-07-28.at.16.38.09.mov

Optical alignment:

Before	After

[changeset-bot]

🦋 Changeset detected

Latest commit: a66f2c4

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

This PR includes changesets to release 8 packages

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

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]

🟢 No design token changes found

[github-actions]

🟢 No visual differences found

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

[Copilot]

Pull Request Overview

Fixes a layout shift bug in SubNav component where separators were conditionally rendered based on client-side state, causing hydration issues in SSR environments. The fix replaces JavaScript-based conditional rendering with CSS-based visibility control to ensure consistent DOM structure during initial render and hydration.

• Replaced isLarge condition logic with CSS equivalents for separator visibility
• Improved optical alignment of separator elements
• Added comprehensive visual regression tests for no active links scenario

Reviewed Changes

Copilot reviewed 6 out of 19 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/react/src/SubNav/SubNav.tsx	Replaced conditional rendering with CSS classes and improved separator structure
packages/react/src/SubNav/SubNav.module.css	Added CSS rules for separator visibility and optical alignment
packages/react/src/SubNav/SubNav.test.tsx	Removed test case that's no longer applicable with CSS-based approach
packages/react/src/SubNav/SubNav.features.stories.tsx	Added new story variants for testing no active links scenario
packages/react/src/SubNav/SubNav.visual.spec.ts	Added comprehensive visual regression tests for multiple locales
.changeset/poor-balloons-jam.md	Added changeset documenting the layout shift fix

[joshfarrant]

LGTM

[danielguillan]

Works great!