From 29b6c6ccde0dc324e8846a972c2ed521bb0bd088 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Oct 2025 23:07:59 +0000
Subject: [PATCH 1/3] Initial plan


From 9658737422fc171186ebd20cced91b2c3d2eb678 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Oct 2025 23:25:59 +0000
Subject: [PATCH 2/3] Update Banner to use aria-labelledby with Banner.Title by
 default

Co-authored-by: langermank <18661030+langermank@users.noreply.github.com>
---
 packages/react/src/Banner/Banner.test.tsx |  71 ++++++++++-----
 packages/react/src/Banner/Banner.tsx      | 101 ++++++++++++----------
 2 files changed, 104 insertions(+), 68 deletions(-)

diff --git a/packages/react/src/Banner/Banner.test.tsx b/packages/react/src/Banner/Banner.test.tsx
index b08b0d52bc0..d62813884f0 100644
--- a/packages/react/src/Banner/Banner.test.tsx
+++ b/packages/react/src/Banner/Banner.test.tsx
@@ -6,7 +6,7 @@ import {Banner} from '../Banner'
 describe('Banner', () => {
   it('should render as a region element', () => {
     render(<Banner title="test" />)
-    expect(screen.getByRole('region', {name: 'Information'})).toBeInTheDocument()
+    expect(screen.getByRole('region', {name: 'test'})).toBeInTheDocument()
     expect(screen.getByRole('heading', {name: 'test'})).toBeInTheDocument()
   })
 
@@ -15,34 +15,41 @@ describe('Banner', () => {
     expect(render(<Element />).container.firstChild).toHaveClass('test-class-name')
   })
 
-  it('should label the landmark element with the corresponding variant label text', () => {
-    render(<Banner title="test" />)
-    expect(screen.getByRole('region')).toEqual(screen.getByLabelText('Information'))
+  it('should label the landmark element with the title by default', () => {
+    render(<Banner title="My Banner Title" />)
+    const region = screen.getByRole('region', {name: 'My Banner Title'})
+    expect(region).toHaveAttribute('aria-labelledby')
+    expect(region).not.toHaveAttribute('aria-label')
   })
 
-  it('should label the landmark element with the label for the critical variant', () => {
-    render(<Banner title="test" variant="critical" />)
-    expect(screen.getByRole('region')).toEqual(screen.getByLabelText('Critical'))
+  it('should use aria-labelledby to reference the title for the critical variant', () => {
+    render(<Banner title="Critical Issue" variant="critical" />)
+    const region = screen.getByRole('region', {name: 'Critical Issue'})
+    expect(region).toHaveAttribute('aria-labelledby')
   })
 
-  it('should label the landmark element with the label for the info variant', () => {
-    render(<Banner title="test" variant="info" />)
-    expect(screen.getByRole('region')).toEqual(screen.getByLabelText('Information'))
+  it('should use aria-labelledby to reference the title for the info variant', () => {
+    render(<Banner title="Information" variant="info" />)
+    const region = screen.getByRole('region', {name: 'Information'})
+    expect(region).toHaveAttribute('aria-labelledby')
   })
 
-  it('should label the landmark element with the label for the success variant', () => {
-    render(<Banner title="test" variant="success" />)
-    expect(screen.getByRole('region')).toEqual(screen.getByLabelText('Success'))
+  it('should use aria-labelledby to reference the title for the success variant', () => {
+    render(<Banner title="Success Message" variant="success" />)
+    const region = screen.getByRole('region', {name: 'Success Message'})
+    expect(region).toHaveAttribute('aria-labelledby')
   })
 
-  it('should label the landmark element with the label for the upsell variant', () => {
-    render(<Banner title="test" variant="upsell" />)
-    expect(screen.getByRole('region')).toEqual(screen.getByLabelText('Recommendation'))
+  it('should use aria-labelledby to reference the title for the upsell variant', () => {
+    render(<Banner title="Recommendation" variant="upsell" />)
+    const region = screen.getByRole('region', {name: 'Recommendation'})
+    expect(region).toHaveAttribute('aria-labelledby')
   })
 
-  it('should label the landmark element with the label for the warning variant', () => {
-    render(<Banner title="test" variant="warning" />)
-    expect(screen.getByRole('region')).toEqual(screen.getByLabelText('Warning'))
+  it('should use aria-labelledby to reference the title for the warning variant', () => {
+    render(<Banner title="Warning" variant="warning" />)
+    const region = screen.getByRole('region', {name: 'Warning'})
+    expect(region).toHaveAttribute('aria-labelledby')
   })
 
   it('should support the `aria-label` prop to override the default label for the landmark', () => {
@@ -69,6 +76,30 @@ describe('Banner', () => {
     expect(region).not.toHaveAttribute('aria-labelledby')
   })
 
+  it('should use aria-labelledby to reference Banner.Title when provided as a child', () => {
+    render(
+      <Banner>
+        <Banner.Title>Custom Title Component</Banner.Title>
+      </Banner>,
+    )
+    const region = screen.getByRole('region', {name: 'Custom Title Component'})
+    const heading = screen.getByRole('heading', {name: 'Custom Title Component'})
+    expect(region).toHaveAttribute('aria-labelledby', heading.id)
+    expect(heading).toHaveAttribute('id')
+    expect(region).not.toHaveAttribute('aria-label')
+  })
+
+  it('should use aria-labelledby to reference Banner.Title with custom id', () => {
+    render(
+      <Banner aria-labelledby="custom-title-id">
+        <Banner.Title id="custom-title-id">Title with Custom ID</Banner.Title>
+      </Banner>,
+    )
+    const region = screen.getByRole('region', {name: 'Title with Custom ID'})
+    expect(region).toHaveAttribute('aria-labelledby', 'custom-title-id')
+    expect(screen.getByRole('heading')).toHaveAttribute('id', 'custom-title-id')
+  })
+
   it('should default the title to a h2', () => {
     render(<Banner title="test" />)
     expect(screen.getByRole('heading', {level: 2})).toBeInTheDocument()
@@ -86,7 +117,7 @@ describe('Banner', () => {
   it('should rendering a description with the `description` prop', () => {
     render(<Banner title="test" description="test-description" />)
     expect(screen.getByText('test-description')).toBeInTheDocument()
-    expect(screen.getByRole('region', {name: 'Information'})).toContainElement(screen.getByText('test-description'))
+    expect(screen.getByRole('region', {name: 'test'})).toContainElement(screen.getByText('test-description'))
   })
 
   it('should support a primary action', async () => {
diff --git a/packages/react/src/Banner/Banner.tsx b/packages/react/src/Banner/Banner.tsx
index 81d04875cf6..31c0d6d5a47 100644
--- a/packages/react/src/Banner/Banner.tsx
+++ b/packages/react/src/Banner/Banner.tsx
@@ -4,11 +4,18 @@ import {AlertIcon, InfoIcon, StopIcon, CheckCircleIcon, XIcon} from '@primer/oct
 import {Button, IconButton, type ButtonProps} from '../Button'
 import {VisuallyHidden} from '../VisuallyHidden'
 import {useMergedRefs} from '../internal/hooks/useMergedRefs'
+import {useId} from '../hooks/useId'
 import classes from './Banner.module.css'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 
 export type BannerVariant = 'critical' | 'info' | 'success' | 'upsell' | 'warning'
 
+type BannerContextValue = {
+  titleId: string
+}
+
+const BannerContext = React.createContext<BannerContextValue | undefined>(undefined)
+
 export type BannerProps = React.ComponentPropsWithoutRef<'section'> & {
   /**
    * Provide an optional label to override the default name for the Banner
@@ -84,14 +91,6 @@ const iconForVariant: Record<BannerVariant, React.ReactNode> = {
   warning: <AlertIcon />,
 }
 
-const labels: Record<BannerVariant, string> = {
-  critical: 'Critical',
-  info: 'Information',
-  success: 'Success',
-  upsell: 'Recommendation',
-  warning: 'Warning',
-}
-
 export const Banner = React.forwardRef<HTMLElement, BannerProps>(function Banner(
   {
     'aria-label': label,
@@ -116,6 +115,7 @@ export const Banner = React.forwardRef<HTMLElement, BannerProps>(function Banner
   const bannerRef = React.useRef<HTMLElement>(null)
   const ref = useMergedRefs(forwardRef, bannerRef)
   const supportsCustomIcon = variant === 'info' || variant === 'upsell'
+  const titleId = useId()
 
   if (__DEV__) {
     // This hook is called consistently depending on the environment
@@ -141,46 +141,48 @@ export const Banner = React.forwardRef<HTMLElement, BannerProps>(function Banner
   }
 
   return (
-    <section
-      {...rest}
-      aria-labelledby={labelledBy}
-      aria-label={labelledBy ? undefined : (label ?? labels[variant])}
-      className={clsx(className, classes.Banner)}
-      data-dismissible={onDismiss ? '' : undefined}
-      data-title-hidden={hideTitle ? '' : undefined}
-      data-variant={variant}
-      data-actions-layout={actionsLayout}
-      tabIndex={-1}
-      ref={ref}
-      data-layout={rest.layout || 'default'}
-    >
-      <div className={classes.BannerIcon}>{icon && supportsCustomIcon ? icon : iconForVariant[variant]}</div>
-      <div className={classes.BannerContainer}>
-        <div className={classes.BannerContent}>
-          {title ? (
-            hideTitle ? (
-              <VisuallyHidden>
+    <BannerContext.Provider value={{titleId}}>
+      <section
+        {...rest}
+        aria-labelledby={labelledBy ?? (label ? undefined : titleId)}
+        aria-label={labelledBy ? undefined : label}
+        className={clsx(className, classes.Banner)}
+        data-dismissible={onDismiss ? '' : undefined}
+        data-title-hidden={hideTitle ? '' : undefined}
+        data-variant={variant}
+        data-actions-layout={actionsLayout}
+        tabIndex={-1}
+        ref={ref}
+        data-layout={rest.layout || 'default'}
+      >
+        <div className={classes.BannerIcon}>{icon && supportsCustomIcon ? icon : iconForVariant[variant]}</div>
+        <div className={classes.BannerContainer}>
+          <div className={classes.BannerContent}>
+            {title ? (
+              hideTitle ? (
+                <VisuallyHidden>
+                  <BannerTitle>{title}</BannerTitle>
+                </VisuallyHidden>
+              ) : (
                 <BannerTitle>{title}</BannerTitle>
-              </VisuallyHidden>
-            ) : (
-              <BannerTitle>{title}</BannerTitle>
-            )
-          ) : null}
-          {description ? <BannerDescription>{description}</BannerDescription> : null}
-          {children}
+              )
+            ) : null}
+            {description ? <BannerDescription>{description}</BannerDescription> : null}
+            {children}
+          </div>
+          {hasActions ? <BannerActions primaryAction={primaryAction} secondaryAction={secondaryAction} /> : null}
         </div>
-        {hasActions ? <BannerActions primaryAction={primaryAction} secondaryAction={secondaryAction} /> : null}
-      </div>
-      {dismissible ? (
-        <IconButton
-          aria-label="Dismiss banner"
-          onClick={onDismiss}
-          className={classes.BannerDismiss}
-          icon={XIcon}
-          variant="invisible"
-        />
-      ) : null}
-    </section>
+        {dismissible ? (
+          <IconButton
+            aria-label="Dismiss banner"
+            onClick={onDismiss}
+            className={classes.BannerDismiss}
+            icon={XIcon}
+            variant="invisible"
+          />
+        ) : null}
+      </section>
+    </BannerContext.Provider>
   )
 })
 
@@ -192,9 +194,12 @@ export type BannerTitleProps<As extends HeadingElement> = {
 } & React.ComponentPropsWithoutRef<As extends 'h2' ? 'h2' : As>
 
 export function BannerTitle<As extends HeadingElement>(props: BannerTitleProps<As>) {
-  const {as: Heading = 'h2', className, children, ...rest} = props
+  const {as: Heading = 'h2', className, children, id, ...rest} = props
+  const context = React.useContext(BannerContext)
+  const titleId = id ?? context?.titleId
+
   return (
-    <Heading {...rest} className={clsx(className, classes.BannerTitle)} data-banner-title="">
+    <Heading {...rest} id={titleId} className={clsx(className, classes.BannerTitle)} data-banner-title="">
       {children}
     </Heading>
   )

From 9849b61e85ccf900e54b0c40fd2cbb86ef64eec6 Mon Sep 17 00:00:00 2001
From: Liu Liu <liuliu-dev@github.com>
Date: Wed, 28 Jan 2026 13:52:07 -0800
Subject: [PATCH 3/3] changeset

---
 .changeset/banner-aria-labelledby-title.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/banner-aria-labelledby-title.md

diff --git a/.changeset/banner-aria-labelledby-title.md b/.changeset/banner-aria-labelledby-title.md
new file mode 100644
index 00000000000..c10c0756daa
--- /dev/null
+++ b/.changeset/banner-aria-labelledby-title.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Banner: Use `aria-labelledby` to reference the title for the landmark region instead of generic variant labels.