[v-kartykp]

Summary

Accessibility fixes for the docs site's page title, mobile navigation drawer, CLI version menu, navigation lists, and mobile search results.

Changes

Page title missing from document.title (gatsby-browser.js)

To prevent React 19 from hoisting metadata tags, Gatsby renders the Head export inside an <svg>. This creates the <title> and <meta> elements in the SVG namespace, and Gatsby then copies them into <head> in place of the server-rendered tags. Browsers and assistive technology ignore an SVG <title>, so document.title was an empty string on every page once the client-side code loaded.

An onClientEntry hook now adds a MutationObserver on <head>. It recreates any non-HTML-namespaced [data-gatsby-head] node as an HTML element with the same attributes and content. This works the same way as Gatsby's own handling of <script> tags. document.title is now correct on initial load and after client-side navigation, including navigation from search results.

Mobile nav drawer contrast (nav-drawer.module.css)

When the drawer moved from sx props to CSS modules, its background was hardcoded to #333333. The drawer content is still rendered inside LightTheme, so the nav items use the light theme's dark text, which gave roughly 1.2:1 contrast. The drawer body now uses --bgColor-default / --fgColor-default, matching the original canvas.default / fg.default theme values.

CLI version menu link contrast (variant-select.js, variant-select.module.css)

Version menu items were rendered with the Primer link accent color (#0969da). On the selected item's background this is 4.46:1, below the 4.5:1 minimum. The menu links now use --fgColor-default, like other action menu items.

Mobile search results not fully visible (search.module.css)

Primer's ThemeProvider wraps LightTheme content in a <div data-color-mode>. That wrapper became the flex item inside the mobile search overlay, so the results list grew to its full content height instead of shrinking and scrolling. On short viewports (for example 320 × 256 px or at 200% zoom), most results were off-screen. The wrapper is now a shrinkable flex column, so the results panel fits the remaining viewport height and scrolls.

Console warnings (root.js, page.js, table-of-contents.js)

• Gatsby applies wrapRootElement to the Head export as well as to pages. Primer's ThemeProvider renders a <div data-color-mode>, so a <div> ended up inside Head, causing the "<div> is not a valid head element" warning. ThemeProvider now lives in wrapPageElement, which Gatsby does not apply to Head. MDXProvider stays in wrapRootElement.
• The mobile table of contents button passed leadingIcon, which Primer's Button doesn't support. React warned about an unknown DOM prop and the open/closed chevron never rendered. It now uses leadingVisual, so the chevron shows.

CLI version menu group and list semantics (variant-select.js, variant-select.module.css)

Each version entry rendered a role="menuitem" <li> with a separate <a> inside it, and keyboard focus moved to that inner link. Screen readers in focus mode announced only "Version x, link". They didn't announce the "Current"/"Legacy" group or the item's position in the menu. The entries now use ActionList.LinkItem with our Gatsby-aware link as the as component. The focused element is now the <a role="menuitem"> inside its labelled role="group", so the group name and position are announced. Client-side version switching, closing the menu and returning focus to the menu button work as before. This also stops state="[object Object]" from being rendered as a DOM attribute on the menu items.

Position information for navigation lists (nav-items.js, nav-hierarchy.js)

Sidebar navigation links and the page-level navigation hierarchy lists now include their position in the accessible name (for example, "npm access, 2 of 74"). This matches the table of contents and search results. Expandable sidebar items keep their existing name, because Primer's NavList uses that name to label the expanded sub-list.

Testing

• Verified locally with gatsby develop in a browser:
  • document.title is correct on initial load and after navigating through search and the sidebar. No SVG-namespaced nodes remain in <head>.
  • Nav drawer items render dark text on a light background at 640 px width.
  • Version menu links render #1f2328 on the selected item background.
  • At 320 × 256 px, the search results panel is constrained to the viewport and all 12 results are reachable by scrolling and arrow keys.
  • No "invalid head element" or unknown leadingIcon prop messages in the browser console. The mobile table of contents button shows its chevron.
  • In the CLI version menu, focus moves between role="menuitem" links inside the "Current"/"Legacy" groups. Selecting a version with Enter or a click navigates to that version, closes the menu and returns focus to the menu button.
  • Sidebar links (for example the CLI commands list) and the page navigation lists on section index pages include "N of M" in their accessible names.
• npm test and npm run lint pass.

[Copilot]

🟢 Approval recommended

The targeted namespace and styling changes have no identified blocking issues.

No open issues 🎉

What changed in this PR

Improves docs-site accessibility by restoring page titles, correcting navigation contrast, and keeping mobile search results scrollable.

Changes:

• Converts Gatsby head elements to the HTML namespace.
• Uses theme foreground and background colors for navigation controls.
• Allows mobile search results to shrink within the viewport.

File	Description
src/​components/​variant-select.module.css	Sets accessible version-link colors.
src/​components/​variant-select.js	Applies the version-link style.
src/​components/​search.module.css	Makes the search theme wrapper shrinkable.
src/​components/​nav-drawer.module.css	Restores theme-based drawer contrast.
gatsby-browser.js	Repairs namespaces on Gatsby head elements.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The changes address the described accessibility problems, with no unresolved blocking findings.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Cross-framework head handling and assistive-technology behavior need human validation, and expandable navigation labeling still needs correction.

1 open issue

• Limit accessible-name overrides to leaf navigation entries · New

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Head-node replacement and menu focus behavior warrant final human browser verification.

No open issues 🎉

1 resolved since last review

• Limit accessible-name overrides to leaf navigation entries

_{Review effort: Balanced}