From 10048b5d5e02dfc7bdb595683b43d2d26cb82ccd Mon Sep 17 00:00:00 2001
From: Jan Maarten <83665577+janmaarten-a11y@users.noreply.github.com>
Date: Mon, 22 Jun 2026 23:35:38 -0700
Subject: [PATCH 1/3] Add NavList.Heading slot for accessible section-nav
 headings

Introduces an optional NavList.Heading that names the navigation region,
labels the <nav> landmark, and coordinates heading levels so group
headings nest correctly beneath it.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .changeset/navlist-heading-slot.md            |   9 ++
 packages/react/src/NavList/NavList.docs.json  |  40 +++++-
 .../src/NavList/NavList.features.stories.tsx  |  46 +++++++
 packages/react/src/NavList/NavList.module.css |   6 +
 packages/react/src/NavList/NavList.test.tsx   | 118 +++++++++++++++++
 packages/react/src/NavList/NavList.tsx        | 124 +++++++++++++++---
 6 files changed, 324 insertions(+), 19 deletions(-)
 create mode 100644 .changeset/navlist-heading-slot.md

diff --git a/.changeset/navlist-heading-slot.md b/.changeset/navlist-heading-slot.md
new file mode 100644
index 00000000000..4e2cb3e7558
--- /dev/null
+++ b/.changeset/navlist-heading-slot.md
@@ -0,0 +1,9 @@
+---
+'@primer/react': minor
+---
+
+Add a `NavList.Heading` slot that names the navigation region. It renders an `h2`
+by default (configurable to `h3` via `as`), supports a `visuallyHidden` variant,
+labels the `nav` landmark via `aria-labelledby`, and makes `NavList.Group`
+headings default to one level deeper (`h3`, or `h4` under an `h3` heading) for a
+correct heading hierarchy.
diff --git a/packages/react/src/NavList/NavList.docs.json b/packages/react/src/NavList/NavList.docs.json
index f44605ffe60..65e9ccb1058 100644
--- a/packages/react/src/NavList/NavList.docs.json
+++ b/packages/react/src/NavList/NavList.docs.json
@@ -48,6 +48,41 @@
     }
   ],
   "subcomponents": [
+    {
+      "name": "NavList.Heading",
+      "props": [
+        {
+          "name": "as",
+          "type": "'h2' | 'h3'",
+          "defaultValue": "\"h2\"",
+          "required": false,
+          "description": "Semantic heading level for the NavList. Also sets the default level for child group headings, which render one level deeper (h3 under an h2, h4 under an h3). Constrained to h2/h3 so the hierarchy stays shallow."
+        },
+        {
+          "name": "visuallyHidden",
+          "type": "boolean",
+          "defaultValue": "false",
+          "required": false,
+          "description": "Visually hide the heading while keeping it available to assistive technology and as the accessible name for the `nav` landmark."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "description": "The text rendered as the NavList's heading."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Custom CSS class name."
+        },
+        {
+          "name": "style",
+          "type": "React.CSSProperties",
+          "description": "Custom CSS styles."
+        }
+      ]
+    },
     {
       "name": "NavList.Item",
       "props": [
@@ -194,10 +229,9 @@
         },
         {
           "name": "as",
-          "description": "Heading level for the group heading. Sets the semantic heading tag.",
+          "description": "Heading level for the group heading. Sets the semantic heading tag. Defaults to one level below a `NavList.Heading` (h3 under an h2, h4 under an h3), or `h3` when there is no `NavList.Heading`.",
           "required": false,
-          "type": "'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'",
-          "defaultValue": "\"h3\""
+          "type": "'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'"
         }
       ]
     },
diff --git a/packages/react/src/NavList/NavList.features.stories.tsx b/packages/react/src/NavList/NavList.features.stories.tsx
index e575ffe71f6..64812e6f75d 100644
--- a/packages/react/src/NavList/NavList.features.stories.tsx
+++ b/packages/react/src/NavList/NavList.features.stories.tsx
@@ -646,4 +646,50 @@ export const WithItemGap: StoryFn = () => (
 
 WithItemGap.storyName = 'With gap between items (behind feature flag)'
 
+export const WithHeading: StoryFn = () => (
+  <PageLayout>
+    <PageLayout.Pane position="start">
+      <NavList>
+        <NavList.Heading>Settings</NavList.Heading>
+        <NavList.Group title="Account">
+          <NavList.Item href="#" aria-current="page">
+            Profile
+          </NavList.Item>
+          <NavList.Item href="#">Appearance</NavList.Item>
+        </NavList.Group>
+        <NavList.Group title="Security">
+          <NavList.Item href="#">Password and authentication</NavList.Item>
+          <NavList.Item href="#">Sessions</NavList.Item>
+        </NavList.Group>
+      </NavList>
+    </PageLayout.Pane>
+    <PageLayout.Content></PageLayout.Content>
+  </PageLayout>
+)
+
+WithHeading.storyName = 'With Heading'
+
+export const WithVisuallyHiddenHeading: StoryFn = () => (
+  <PageLayout>
+    <PageLayout.Pane position="start">
+      <NavList>
+        <NavList.Heading visuallyHidden>Settings</NavList.Heading>
+        <NavList.Group title="Account">
+          <NavList.Item href="#" aria-current="page">
+            Profile
+          </NavList.Item>
+          <NavList.Item href="#">Appearance</NavList.Item>
+        </NavList.Group>
+        <NavList.Group title="Security">
+          <NavList.Item href="#">Password and authentication</NavList.Item>
+          <NavList.Item href="#">Sessions</NavList.Item>
+        </NavList.Group>
+      </NavList>
+    </PageLayout.Pane>
+    <PageLayout.Content></PageLayout.Content>
+  </PageLayout>
+)
+
+WithVisuallyHiddenHeading.storyName = 'With Heading (hidden)'
+
 export default meta
diff --git a/packages/react/src/NavList/NavList.module.css b/packages/react/src/NavList/NavList.module.css
index 9908361e112..93dbb6674eb 100644
--- a/packages/react/src/NavList/NavList.module.css
+++ b/packages/react/src/NavList/NavList.module.css
@@ -1,3 +1,9 @@
+.Heading {
+  margin-block-end: var(--base-size-8);
+  /* stylelint-disable-next-line primer/spacing */
+  margin-inline-start: calc(var(--control-medium-paddingInline-condensed) + var(--base-size-8));
+}
+
 .GroupHeading > a {
   color: var(--fgColor-default);
   text-decoration: inherit;
diff --git a/packages/react/src/NavList/NavList.test.tsx b/packages/react/src/NavList/NavList.test.tsx
index b70f1314d4b..d80e551b8c5 100644
--- a/packages/react/src/NavList/NavList.test.tsx
+++ b/packages/react/src/NavList/NavList.test.tsx
@@ -619,4 +619,122 @@ describe('NavList.ShowMoreItem with pages', () => {
       expect(getComputedStyle(subGroup as HTMLElement).marginBlockStart).toBe('0px')
     })
   })
+
+  describe('NavList.Heading', () => {
+    it('renders an h2 heading by default', () => {
+      const {getByRole} = render(
+        <NavList>
+          <NavList.Heading>Settings</NavList.Heading>
+          <NavList.Item href="#">Item 1</NavList.Item>
+        </NavList>,
+      )
+
+      expect(getByRole('heading', {level: 2, name: 'Settings'})).toBeInTheDocument()
+    })
+
+    it('respects an explicit heading level via the `as` prop', () => {
+      const {getByRole} = render(
+        <NavList>
+          <NavList.Heading as="h3">Settings</NavList.Heading>
+          <NavList.Item href="#">Item 1</NavList.Item>
+        </NavList>,
+      )
+
+      expect(getByRole('heading', {level: 3, name: 'Settings'})).toBeInTheDocument()
+    })
+
+    it('labels the nav landmark with the heading', () => {
+      const {getByRole} = render(
+        <NavList>
+          <NavList.Heading>Settings</NavList.Heading>
+          <NavList.Item href="#">Item 1</NavList.Item>
+        </NavList>,
+      )
+
+      const nav = getByRole('navigation', {name: 'Settings'})
+      const heading = getByRole('heading', {name: 'Settings'})
+      expect(nav).toHaveAttribute('aria-labelledby', heading.id)
+    })
+
+    it('does not override a consumer-supplied aria-label', () => {
+      const {getByRole} = render(
+        <NavList aria-label="Custom label">
+          <NavList.Heading>Settings</NavList.Heading>
+          <NavList.Item href="#">Item 1</NavList.Item>
+        </NavList>,
+      )
+
+      const nav = getByRole('navigation', {name: 'Custom label'})
+      expect(nav).not.toHaveAttribute('aria-labelledby')
+    })
+
+    it('defaults group headings to one level below the NavList.Heading', () => {
+      const {getByRole} = render(
+        <NavList>
+          <NavList.Heading>Settings</NavList.Heading>
+          <NavList.Group title="Account">
+            <NavList.Item href="#">Profile</NavList.Item>
+          </NavList.Group>
+        </NavList>,
+      )
+
+      expect(getByRole('heading', {level: 2, name: 'Settings'})).toBeInTheDocument()
+      expect(getByRole('heading', {level: 3, name: 'Account'})).toBeInTheDocument()
+    })
+
+    it('derives group headings to h4 when the NavList.Heading is an h3', () => {
+      const {getByRole} = render(
+        <NavList>
+          <NavList.Heading as="h3">Settings</NavList.Heading>
+          <NavList.Group title="Account">
+            <NavList.Item href="#">Profile</NavList.Item>
+          </NavList.Group>
+        </NavList>,
+      )
+
+      expect(getByRole('heading', {level: 3, name: 'Settings'})).toBeInTheDocument()
+      expect(getByRole('heading', {level: 4, name: 'Account'})).toBeInTheDocument()
+    })
+
+    it('keeps the h3 group heading default when there is no NavList.Heading', () => {
+      const {getByRole} = render(
+        <NavList>
+          <NavList.Group title="Account">
+            <NavList.Item href="#">Profile</NavList.Item>
+          </NavList.Group>
+        </NavList>,
+      )
+
+      expect(getByRole('heading', {level: 3, name: 'Account'})).toBeInTheDocument()
+    })
+
+    it('lets group headings override their computed level with `as`', () => {
+      const {getByRole} = render(
+        <NavList>
+          <NavList.Heading>Settings</NavList.Heading>
+          <NavList.Group>
+            <NavList.GroupHeading as="h4">Account</NavList.GroupHeading>
+            <NavList.Item href="#">Profile</NavList.Item>
+          </NavList.Group>
+        </NavList>,
+      )
+
+      expect(getByRole('heading', {level: 4, name: 'Account'})).toBeInTheDocument()
+    })
+
+    it('keeps a visually hidden heading in the accessibility tree', () => {
+      const {getByRole} = render(
+        <NavList>
+          <NavList.Heading visuallyHidden>Settings</NavList.Heading>
+          <NavList.Item href="#">Item 1</NavList.Item>
+        </NavList>,
+      )
+
+      const heading = getByRole('heading', {level: 2, name: 'Settings'})
+      expect(heading).toBeInTheDocument()
+      expect(getByRole('navigation', {name: 'Settings'})).toBeInTheDocument()
+      // The visually-hidden styles are applied to the heading itself, not a wrapping element.
+      expect(heading.parentElement?.tagName).not.toBe('SPAN')
+    })
+  })
 })
diff --git a/packages/react/src/NavList/NavList.tsx b/packages/react/src/NavList/NavList.tsx
index 6af6985976b..368543d3986 100644
--- a/packages/react/src/NavList/NavList.tsx
+++ b/packages/react/src/NavList/NavList.tsx
@@ -19,6 +19,31 @@ import navListClasses from './NavList.module.css'
 import {flushSync} from 'react-dom'
 import {useSlots} from '../hooks/useSlots'
 import {fixedForwardRef, type PolymorphicProps} from '../utils/modern-polymorphic'
+import HeadingComponent from '../Heading'
+import visuallyHiddenClasses from '../_VisuallyHidden.module.css'
+import type {FCWithSlotMarker} from '../utils/types/Slots'
+
+type HeadingLevels = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+
+// NavList establishes a shallow hierarchy: the NavList itself is named by a
+// heading (h2 or h3) and its groups render one level deeper (h3 or h4). We don't
+// expose an h1 (that's the page title) and we don't go deeper than h4.
+type NavListHeadingLevels = 'h2' | 'h3'
+
+// Publishes the resolved numeric level of a NavList.Heading (e.g. 2 for an h2) so
+// NavList.Group/NavList.GroupHeading can default to one level deeper. `null` when
+// there is no NavList.Heading, in which case groups keep their historical h3 default.
+const NavListHeadingLevelContext = React.createContext<number | null>(null)
+
+function headingTagToLevel(as: NavListHeadingLevels): number {
+  return Number.parseInt(as.slice(1), 10)
+}
+
+function levelToHeadingTag(level: number): HeadingLevels {
+  // Clamp to h4 so group headings never go deeper than the supported hierarchy.
+  const clamped = Math.min(Math.max(level, 1), 4)
+  return `h${clamped}` as HeadingLevels
+}
 
 // ----------------------------------------------------------------------------
 // NavList
@@ -27,21 +52,81 @@ export type NavListProps = {
   children: React.ReactNode
 } & React.ComponentProps<'nav'>
 
-const Root = React.forwardRef<HTMLElement, NavListProps>(({children, ...props}, ref) => {
+const Root = React.forwardRef<HTMLElement, NavListProps>(
+  ({children, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, ...props}, ref) => {
+    const [slots, childrenWithoutHeading] = useSlots(children, {
+      heading: Heading,
+    })
+
+    const fallbackHeadingId = useId()
+    const heading = slots.heading
+    const headingId = heading ? (heading.props.id ?? fallbackHeadingId) : undefined
+    const headingLevel = heading ? headingTagToLevel(heading.props.as ?? 'h2') : null
+
+    // Don't override a consumer-supplied accessible name; otherwise label the
+    // <nav> landmark with the heading so it gets an accessible name automatically.
+    const navLabelledby = ariaLabelledby ?? (ariaLabel ? undefined : headingId)
+
+    return (
+      <nav {...props} aria-label={ariaLabel} aria-labelledby={navLabelledby} ref={ref} data-component="NavList">
+        <NavListHeadingLevelContext.Provider value={headingLevel}>
+          {heading ? React.cloneElement(heading, {id: headingId}) : null}
+          <ActionListContainerContext.Provider
+            value={{
+              container: 'NavList',
+            }}
+          >
+            <ActionList>{childrenWithoutHeading}</ActionList>
+          </ActionListContainerContext.Provider>
+        </NavListHeadingLevelContext.Provider>
+      </nav>
+    )
+  },
+)
+
+Root.displayName = 'NavList'
+
+// ----------------------------------------------------------------------------
+// NavList.Heading
+
+export type NavListHeadingProps = {
+  /** Semantic heading level for the NavList. Also sets the default level for child group headings, which render one level deeper. */
+  as?: NavListHeadingLevels
+  /** Visually hide the heading while keeping it available to assistive technology. */
+  visuallyHidden?: boolean
+  children: React.ReactNode
+  className?: string
+  id?: string
+  style?: React.CSSProperties
+}
+
+const Heading: FCWithSlotMarker<NavListHeadingProps> = ({
+  as = 'h2',
+  visuallyHidden = false,
+  className,
+  children,
+  ...props
+}) => {
   return (
-    <nav {...props} ref={ref} data-component="NavList">
-      <ActionListContainerContext.Provider
-        value={{
-          container: 'NavList',
-        }}
-      >
-        <ActionList>{children}</ActionList>
-      </ActionListContainerContext.Provider>
-    </nav>
+    <HeadingComponent
+      as={as}
+      variant="small"
+      className={clsx(
+        // Apply the visually-hidden styles directly to the heading rather than wrapping
+        // it in a span (a heading isn't valid phrasing content inside a span).
+        visuallyHidden ? visuallyHiddenClasses.InternalVisuallyHidden : navListClasses.Heading,
+        className,
+      )}
+      data-component="NavList.Heading"
+      {...props}
+    >
+      {children}
+    </HeadingComponent>
   )
-})
+}
 
-Root.displayName = 'NavList'
+Heading.displayName = 'NavList.Heading'
+Heading.__SLOT__ = Symbol('NavList.Heading')
 
 // ----------------------------------------------------------------------------
 // NavList.Item
@@ -285,13 +370,17 @@ export type NavListGroupProps = React.HTMLAttributes<HTMLLIElement> & {
 }
 
 const Group: React.FC<NavListGroupProps> = ({title, children, ...props}) => {
+  const headingLevel = React.useContext(NavListHeadingLevelContext)
+  // Default the group heading to one level below the NavList.Heading (h3 under an
+  // h2, h4 under an h3), falling back to h3 when there is no NavList.Heading. To
+  // use a different level, pass NavList.GroupHeading with an explicit `as` instead.
+  const groupHeadingAs = headingLevel ? levelToHeadingTag(headingLevel + 1) : 'h3'
   return (
     <>
       <ActionList.Divider />
       <ActionList.Group {...props}>
-        {/* Setting up the default value for the heading level. TODO: API update to give flexibility to NavList.Group title's heading level */}
         {title ? (
-          <ActionList.GroupHeading as="h3" data-component="ActionList.GroupHeading">
+          <ActionList.GroupHeading as={groupHeadingAs} data-component="ActionList.GroupHeading">
             {title}
           </ActionList.GroupHeading>
         ) : null}
@@ -409,10 +498,12 @@ export type NavListGroupHeadingProps = ActionListGroupHeadingProps
  * This is an alternative to the `title` prop on `NavList.Group`.
  * It was primarily added to allow links in group headings.
  */
-const GroupHeading: React.FC<NavListGroupHeadingProps> = ({as = 'h3', className, ...rest}) => {
+const GroupHeading: React.FC<NavListGroupHeadingProps> = ({as, className, ...rest}) => {
+  const headingLevel = React.useContext(NavListHeadingLevelContext)
+  const resolvedAs = as ?? (headingLevel ? levelToHeadingTag(headingLevel + 1) : 'h3')
   return (
     <ActionList.GroupHeading
-      as={as}
+      as={resolvedAs}
       className={clsx(navListClasses.GroupHeading, className)}
       data-component="NavList.GroupHeading"
       headingWrapElement="li"
@@ -426,6 +517,7 @@ const GroupHeading: React.FC<NavListGroupHeadingProps> = ({as = 'h3', className,
 
 export const NavList = Object.assign(Root, {
   Description: ActionList.Description,
+  Heading,
   Item,
   SubNav,
   LeadingVisual,

From 9f623ada6d6e4a9bd9fb298bb3c7a222063c2cb1 Mon Sep 17 00:00:00 2001
From: Jan Maarten <83665577+janmaarten-a11y@users.noreply.github.com>
Date: Mon, 22 Jun 2026 23:41:56 -0700
Subject: [PATCH 2/3] Remove redundant Storybook storyName for WithHeading

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 packages/react/src/NavList/NavList.features.stories.tsx | 2 --
 1 file changed, 2 deletions(-)

diff --git a/packages/react/src/NavList/NavList.features.stories.tsx b/packages/react/src/NavList/NavList.features.stories.tsx
index 64812e6f75d..fb3983f64c0 100644
--- a/packages/react/src/NavList/NavList.features.stories.tsx
+++ b/packages/react/src/NavList/NavList.features.stories.tsx
@@ -667,8 +667,6 @@ export const WithHeading: StoryFn = () => (
   </PageLayout>
 )
 
-WithHeading.storyName = 'With Heading'
-
 export const WithVisuallyHiddenHeading: StoryFn = () => (
   <PageLayout>
     <PageLayout.Pane position="start">

From 9533be7bcf74766c65625a984c29fc956f4ce3cf Mon Sep 17 00:00:00 2001
From: Jan Maarten <83665577+janmaarten-a11y@users.noreply.github.com>
Date: Tue, 23 Jun 2026 12:22:49 -0700
Subject: [PATCH 3/3] Address review: widen NavList.Heading props and document
 id

Merge intrinsic h2 element props into NavListHeadingProps so consumers can
pass aria-*, data-*, title, and other standard heading attributes without a
type assertion, and document the id prop in NavList.docs.json.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 packages/react/src/NavList/NavList.docs.json |  5 +++++
 packages/react/src/NavList/NavList.test.tsx  | 15 +++++++++++++++
 packages/react/src/NavList/NavList.tsx       |  6 +-----
 3 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/packages/react/src/NavList/NavList.docs.json b/packages/react/src/NavList/NavList.docs.json
index 65e9ccb1058..6ea9ab1e73f 100644
--- a/packages/react/src/NavList/NavList.docs.json
+++ b/packages/react/src/NavList/NavList.docs.json
@@ -71,6 +71,11 @@
           "required": true,
           "description": "The text rendered as the NavList's heading."
         },
+        {
+          "name": "id",
+          "type": "string",
+          "description": "Custom id for the heading element. When set, it is used as the `aria-labelledby` target that names the `nav` landmark; otherwise a generated id is used."
+        },
         {
           "name": "className",
           "type": "string",
diff --git a/packages/react/src/NavList/NavList.test.tsx b/packages/react/src/NavList/NavList.test.tsx
index d80e551b8c5..cedde128ac5 100644
--- a/packages/react/src/NavList/NavList.test.tsx
+++ b/packages/react/src/NavList/NavList.test.tsx
@@ -736,5 +736,20 @@ describe('NavList.ShowMoreItem with pages', () => {
       // The visually-hidden styles are applied to the heading itself, not a wrapping element.
       expect(heading.parentElement?.tagName).not.toBe('SPAN')
     })
+
+    it('forwards standard HTML attributes to the heading element', () => {
+      const {getByRole} = render(
+        <NavList>
+          <NavList.Heading data-testid="nav-heading" title="Section navigation">
+            Settings
+          </NavList.Heading>
+          <NavList.Item href="#">Item 1</NavList.Item>
+        </NavList>,
+      )
+
+      const heading = getByRole('heading', {level: 2, name: 'Settings'})
+      expect(heading).toHaveAttribute('data-testid', 'nav-heading')
+      expect(heading).toHaveAttribute('title', 'Section navigation')
+    })
   })
 })
diff --git a/packages/react/src/NavList/NavList.tsx b/packages/react/src/NavList/NavList.tsx
index 368543d3986..3deb4662531 100644
--- a/packages/react/src/NavList/NavList.tsx
+++ b/packages/react/src/NavList/NavList.tsx
@@ -94,11 +94,7 @@ export type NavListHeadingProps = {
   as?: NavListHeadingLevels
   /** Visually hide the heading while keeping it available to assistive technology. */
   visuallyHidden?: boolean
-  children: React.ReactNode
-  className?: string
-  id?: string
-  style?: React.CSSProperties
-}
+} & React.ComponentPropsWithoutRef<'h2'>
 
 const Heading: FCWithSlotMarker<NavListHeadingProps> = ({
   as = 'h2',