Banner: Should prefer aria-labelled-by over aria-label

.changeset/hot-melons-jump.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": patch
+---
+
+Banner: Should prefer aria-labelled-by over aria-label

packages/react/src/Banner/Banner.test.tsx

@@ -50,6 +50,25 @@ describe('Banner', () => {
     expect(screen.getByRole('region')).toHaveAttribute('aria-label', 'Test')
   })
 
+  it('should prefer aria-labelledby over aria-label and not set both', () => {
+    render(
+      <Banner aria-label="Override" aria-labelledby="my-banner-title">
+        <Banner.Title id="my-banner-title">Explicit Banner Title</Banner.Title>
+      </Banner>,
+    )
+
+    const region = screen.getByRole('region', {name: 'Explicit Banner Title'})
+    expect(region).toHaveAttribute('aria-labelledby', 'my-banner-title')
+    expect(region).not.toHaveAttribute('aria-label')
+  })
+
+  it('should only set aria-label when aria-labelledby is not provided', () => {
+    render(<Banner aria-label="Custom Label" title="test" />)
+    const region = screen.getByRole('region')
+    expect(region).toHaveAttribute('aria-label', 'Custom Label')
+    expect(region).not.toHaveAttribute('aria-labelledby')
+  })
+
   it('should default the title to a h2', () => {
     render(<Banner title="test" />)
     expect(screen.getByRole('heading', {level: 2})).toBeInTheDocument()

packages/react/src/Banner/Banner.tsx

@@ -85,6 +85,7 @@ const labels: Record<BannerVariant, string> = {
 export const Banner = React.forwardRef<HTMLElement, BannerProps>(function Banner(
   {
     'aria-label': label,
+    'aria-labelledby': labelledBy,
     children,
     className,
     description,
@@ -131,7 +132,8 @@ export const Banner = React.forwardRef<HTMLElement, BannerProps>(function Banner
   return (
     <section
       {...rest}
-      aria-label={label ?? labels[variant]}
+      aria-labelledby={labelledBy}
+      aria-label={labelledBy ? undefined : (label ?? labels[variant])}
       className={clsx(className, classes.Banner)}
       data-dismissible={onDismiss ? '' : undefined}
       data-title-hidden={hideTitle ? '' : undefined}