From 7915f38f2cce2774f358b0298f223477da2a2f7a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Molakvo=C3=A6=20=28skjnldsv=29?=
 <skjnldsv@protonmail.com>
Date: Tue, 12 May 2026 21:26:11 +0200
Subject: [PATCH] fix(a11y): add visible label and search icon to search input
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The search input had an aria-label but no visible label and no visual
symbol indicating it is a search field, which fails WCAG 3.3.2 /
BITV 9.3.3.2 (input fields must be identifiable without relying on
placeholder text alone).

- Override searchbox.html to add a <label> (visually hidden via
  .sr-only so the layout is not disrupted) and a FontAwesome
  magnifying-glass icon positioned inside the input.
- Add .sr-only utility class and search icon CSS to custom.css.

Fixes #9739

Signed-off-by: John Molakvoæ (skjnldsv) <skjnldsv@protonmail.com>
---
 _shared_assets/static/custom.css        | 34 +++++++++++++++++++++++++
 _shared_assets/templates/searchbox.html | 30 ++++++++++++++++++++++
 2 files changed, 64 insertions(+)
 create mode 100644 _shared_assets/templates/searchbox.html

diff --git a/_shared_assets/static/custom.css b/_shared_assets/static/custom.css
index 04b115a40e0..6f34ad00fef 100644
--- a/_shared_assets/static/custom.css
+++ b/_shared_assets/static/custom.css
@@ -12,6 +12,40 @@ h6 {
 	font-family: system-ui, -apple-system, "Segoe UI", Roboto, Oxygen-Sans, Cantarell, Ubuntu, "Helvetica Neue", "Noto Sans", "Liberation Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
 }
 
+/* Visually hidden utility — element stays in the accessibility tree
+   but is not visible on screen. Satisfies WCAG 3.3.2 / BITV 9.3.3.2
+   for the search form label. */
+.sr-only {
+	position: absolute;
+	width: 1px;
+	height: 1px;
+	padding: 0;
+	margin: -1px;
+	overflow: hidden;
+	clip: rect(0, 0, 0, 0);
+	white-space: nowrap;
+	border: 0;
+}
+
+/* Search input wrapper — positions the magnifying-glass icon inside
+   the input so sighted users can identify the field without a label. */
+.wy-form-search {
+	position: relative;
+}
+
+.wy-form-search-icon {
+	position: absolute;
+	top: 50%;
+	left: 10px;
+	transform: translateY(-50%);
+	color: #555;
+	pointer-events: none;
+}
+
+.wy-form-search input[type="text"] {
+	padding-left: 30px;
+}
+
 /* NC blue */
 .wy-side-nav-search {
 	background-color: #0082c9;
diff --git a/_shared_assets/templates/searchbox.html b/_shared_assets/templates/searchbox.html
new file mode 100644
index 00000000000..92b14978a3f
--- /dev/null
+++ b/_shared_assets/templates/searchbox.html
@@ -0,0 +1,30 @@
+{%- if 'singlehtml' not in builder %}
+{#
+  Custom searchbox override.
+
+  RTD's default searchbox has an aria-label but no visible label and no
+  search symbol, which fails WCAG 3.3.2 / BITV 9.3.3.2 (inputs must
+  have a visible label or identifying symbol).
+
+  Changes from the upstream template:
+  - add an explicit <label> element (visually hidden via .sr-only, still
+    announced by screen readers as an accessible name)
+  - add a FontAwesome magnifying-glass icon that gives sighted users a
+    visual cue that this is a search field
+#}
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="{{ pathto('search') }}" method="get">
+    <label for="rtd-search-input" class="sr-only">{{ _('Search docs') }}</label>
+    <div class="wy-form-search">
+      <span class="fa fa-search wy-form-search-icon" aria-hidden="true"></span>
+      <input id="rtd-search-input"
+             type="text"
+             name="q"
+             placeholder="{{ _('Search docs') }}"
+             aria-label="{{ _('Search docs') }}" />
+    </div>
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+{%- endif %}