From 840e5514e588512837149ca8bd88c15b2004caf6 Mon Sep 17 00:00:00 2001
From: Divyansh Singh <40380293+brc-dd@users.noreply.github.com>
Date: Thu, 3 Sep 2026 00:34:48 +0530
Subject: [PATCH] fix(theme): name controls by their visible text

WCAG 2.5.3 wants the accessible name of a control to contain its visible
text. The search button now takes its name from `buttonText` on every
screen size (the text is visually hidden on small screens instead of
removed) and no longer reads `buttonAriaLabel`; a flyout button only gets
its `label` as `aria-label` when it shows no text; the key hints in the
local search footer name their keys with hidden text instead of an
`aria-label`, which a `kbd` element cannot carry.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../theme-default/components/VPFlyout.vue     |  2 +-
 .../components/VPLocalSearchBox.vue           | 20 ++++++++++++-------
 .../components/VPNavBarSearch.vue             |  2 --
 .../components/VPNavBarSearchButton.vue       | 19 ++++++++++++++++--
 4 files changed, 31 insertions(+), 12 deletions(-)

diff --git a/src/client/theme-default/components/VPFlyout.vue b/src/client/theme-default/components/VPFlyout.vue
index 503066fc..7b50b689 100644
--- a/src/client/theme-default/components/VPFlyout.vue
+++ b/src/client/theme-default/components/VPFlyout.vue
@@ -94,7 +94,7 @@ useEventListener('pointerdown', (e) => {
       class="button"
       :aria-expanded="open"
       :aria-controls="menuId"
-      :aria-label="label"
+      :aria-label="button ? undefined : label"
       @pointerenter="onPointerEnter"
       @pointerleave="onPointerLeave"
       @click="toggle"
diff --git a/src/client/theme-default/components/VPLocalSearchBox.vue b/src/client/theme-default/components/VPLocalSearchBox.vue
index af727577..f8fe02fa 100644
--- a/src/client/theme-default/components/VPLocalSearchBox.vue
+++ b/src/client/theme-default/components/VPLocalSearchBox.vue
@@ -601,22 +601,28 @@ function onMouseMove(e: MouseEvent) {
 
         <div class="search-keyboard-shortcuts">
           <span>
-            <kbd :aria-label="translate('modal.footer.navigateUpKeyAriaLabel')">
-              <span class="vpi-arrow-up navigate-icon" />
+            <kbd>
+              <span class="vpi-arrow-up navigate-icon" aria-hidden="true" />
+              <span class="visually-hidden">{{ translate('modal.footer.navigateUpKeyAriaLabel') }}</span>
             </kbd>
-            <kbd :aria-label="translate('modal.footer.navigateDownKeyAriaLabel')">
-              <span class="vpi-arrow-down navigate-icon" />
+            <kbd>
+              <span class="vpi-arrow-down navigate-icon" aria-hidden="true" />
+              <span class="visually-hidden">{{ translate('modal.footer.navigateDownKeyAriaLabel') }}</span>
             </kbd>
             {{ translate('modal.footer.navigateText') }}
           </span>
           <span>
-            <kbd :aria-label="translate('modal.footer.selectKeyAriaLabel')">
-              <span class="vpi-corner-down-left navigate-icon" />
+            <kbd>
+              <span class="vpi-corner-down-left navigate-icon" aria-hidden="true" />
+              <span class="visually-hidden">{{ translate('modal.footer.selectKeyAriaLabel') }}</span>
             </kbd>
             {{ translate('modal.footer.selectText') }}
           </span>
           <span>
-            <kbd :aria-label="translate('modal.footer.closeKeyAriaLabel')">esc</kbd>
+            <kbd>
+              <span aria-hidden="true">esc</span>
+              <span class="visually-hidden">{{ translate('modal.footer.closeKeyAriaLabel') }}</span>
+            </kbd>
             {{ translate('modal.footer.closeText') }}
           </span>
         </div>
diff --git a/src/client/theme-default/components/VPNavBarSearch.vue b/src/client/theme-default/components/VPNavBarSearch.vue
index 1fe94891..95d1dcc3 100644
--- a/src/client/theme-default/components/VPNavBarSearch.vue
+++ b/src/client/theme-default/components/VPNavBarSearch.vue
@@ -163,7 +163,6 @@ function isEditingContent(event: KeyboardEvent): boolean {
       <VPNavBarSearchButton
         v-if="resolvedMode.showKeywordSearch"
         :text="algoliaOptions.translations?.button?.buttonText || 'Search'"
-        :aria-label="algoliaOptions.translations?.button?.buttonAriaLabel || 'Search'"
         :aria-keyshortcuts="'/ control+k meta+k'"
         @click="loadAndOpen('search')"
       />
@@ -183,7 +182,6 @@ function isEditingContent(event: KeyboardEvent): boolean {
     <template v-else-if="provider === 'local'">
       <VPNavBarSearchButton
         :text="algoliaOptions.translations?.button?.buttonText || 'Search'"
-        :aria-label="algoliaOptions.translations?.button?.buttonAriaLabel || 'Search'"
         :aria-keyshortcuts="'/ control+k meta+k'"
         @click="showSearch = true"
       />
diff --git a/src/client/theme-default/components/VPNavBarSearchButton.vue b/src/client/theme-default/components/VPNavBarSearchButton.vue
index 106fbd55..58430c0f 100644
--- a/src/client/theme-default/components/VPNavBarSearchButton.vue
+++ b/src/client/theme-default/components/VPNavBarSearchButton.vue
@@ -25,7 +25,17 @@ defineProps<{
   font-size: 1.25rem;
 }
 
-.text,
+/* the text stays in the accessibility tree while the bar shows only the icon */
+.text {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  white-space: nowrap;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  overflow: hidden;
+}
+
 .keys {
   display: none;
 }
@@ -59,7 +69,12 @@ kbd {
   }
 
   .text {
-    display: inline;
+    position: static;
+    width: auto;
+    height: auto;
+    clip: auto;
+    clip-path: none;
+    overflow: visible;
     font-size: 0.8125rem;
   }