fix: address HCL a11y audit Sev-2 issues — focus order, label, shortcuts, live region (June 2026) (#61834)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Kevin Heis <heiskr@users.noreply.github.com>

Author: 3 people

data/ui.yml

@@ -324,6 +324,7 @@ product_landing:
   article_grid:
     heading: Articles
     all_categories: All categories
+    filter_by_category: Category
     search_articles: Search articles
     no_articles_found: No articles found matching your criteria.
     showing_results: Showing {start}-{end} of {total}

src/fixtures/fixtures/data/ui.yml

@@ -324,6 +324,7 @@ product_landing:
   article_grid:
     heading: Articles
     all_categories: All categories
+    filter_by_category: Category
     search_articles: Search articles
     no_articles_found: No articles found matching your criteria.
     showing_results: Showing {start}-{end} of {total}

src/landings/components/shared/LandingArticleGridWithFilter.tsx

@@ -266,6 +266,7 @@ export const ArticleGrid = ({
           <div className={styles.categoryDropdown}>
             <ActionMenu>
               <ActionMenu.Button>
+                {t('article_grid.filter_by_category')}:{' '}
                 {categories[selectedCategoryIndex] === ALL_CATEGORIES
                   ? t('article_grid.all_categories')
                   : categories[selectedCategoryIndex]}

src/links/components/LinkPreviewPopover.tsx

@@ -555,6 +555,9 @@ export function LinkPreviewPopover() {
       link.addEventListener('mouseover', showPopover)
       link.addEventListener('mouseout', hidePopover)
       link.addEventListener('keydown', keyboardHandler)
+      // Expose the keyboard shortcut to assistive technologies so screen
+      // reader users can discover how to open the link preview hovercard.
+      link.setAttribute('aria-keyshortcuts', 'Alt+ArrowUp')
     }
 
     document.addEventListener('keydown', escapeHandler)
@@ -564,6 +567,7 @@ export function LinkPreviewPopover() {
         link.removeEventListener('mouseover', showPopover)
         link.removeEventListener('mouseout', hidePopover)
         link.removeEventListener('keydown', keyboardHandler)
+        link.removeAttribute('aria-keyshortcuts')
       }
       document.removeEventListener('keydown', escapeHandler)
     }

src/tools/components/InArticlePicker.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useLayoutEffect, useState } from 'react'
+import React, { useEffect, useLayoutEffect, useRef, useState } from 'react'
 import Cookies from '@/frame/components/lib/cookies'
 import { UnderlineNav } from '@primer/react'
 import { sendEvent } from '@/events/components/events'
@@ -39,6 +39,11 @@ export const InArticlePicker = ({
   const { query, locale } = router
   const [currentValue, setCurrentValue] = useState('')
 
+  // Tracks whether the last currentValue change was triggered by a user click
+  // (as opposed to initial mount or external navigation). When true, we move
+  // focus to the newly-selected tab so keyboard users don't lose their place.
+  const focusAfterNavRef = useRef(false)
+
   // Run on mount for client-side only features
   useEffect(() => {
     const raw = query[queryStringKey]
@@ -128,6 +133,7 @@ export const InArticlePicker = ({
   }, [currentValue])
 
   function onClickChoice(value: string) {
+    focusAfterNavRef.current = true
     const params = new URLSearchParams(asPathQuery)
     params.set(queryStringKey, value)
     const newPath = `/${locale}${asPathRoot}?${params}`
@@ -142,6 +148,21 @@ export const InArticlePicker = ({
     Cookies.set(cookieKey, value)
   }
 
+  // After a user clicks a tab, the shallow route change updates `currentValue`.
+  // Once the DOM reflects the new selection (aria-current="page" is on the new
+  // tab), move keyboard focus there so the user's context is preserved.
+  // WCAG 2.4.3 Focus Order — focus must land on the triggered control.
+  useEffect(() => {
+    if (!focusAfterNavRef.current || !currentValue) return
+    focusAfterNavRef.current = false
+
+    const container = document.querySelector<HTMLElement>(
+      `[data-testid="${queryStringKey}-picker"]`,
+    )
+    const selectedTab = container?.querySelector<HTMLElement>('[aria-current="page"]')
+    selectedTab?.focus()
+  }, [currentValue, queryStringKey])
+
   const sharedContainerProps = {
     'aria-label': ariaLabel,
   }

src/webhooks/components/Webhook.tsx

@@ -4,6 +4,7 @@ import useSWR from 'swr'
 import { useRouter } from 'next/router'
 import { slug } from 'github-slugger'
 import cx from 'classnames'
+import { announce } from '@primer/live-region-element'
 
 import { useVersion } from '@/versions/components/useVersion'
 import { HeadingLink } from '@/frame/components/article/HeadingLink'
@@ -85,6 +86,10 @@ export function Webhook({ webhook }: Props) {
     setSelectedWebhookActionType(type)
     setSelectedActionTypeIndex(index)
 
+    // Announce the newly selected action type to screen readers so users
+    // relying on AT know the page content has changed.
+    announce(`${t('action_type')}: ${type}`, { politeness: 'polite' })
+
     const { asPath, locale } = router
     let [pathRoot, pathQuery = ''] = asPath.split('?')
     const params = new URLSearchParams(pathQuery)