From 0effae7fb86fc8f117a1045df881a3ad71540b7f Mon Sep 17 00:00:00 2001
From: helloigig <wuyuqi827@gmail.com>
Date: Wed, 4 Nov 2026 00:36:38 +0000
Subject: [PATCH] Use <mark> for search result highlights

Matched terms were styled spans, so the highlight was only visual.
Render them as <mark> so screen readers can announce them, keeping the
existing look by inheriting the text colour. In forced colours mode the
highlights now use the system Mark colours instead of disappearing.

Closes #1249
---
 .../search/SearchResultList.test.tsx          | 42 +++++++++++++++++++
 src/documentation/search/SearchResultList.tsx | 11 ++++-
 2 files changed, 51 insertions(+), 2 deletions(-)
 create mode 100644 src/documentation/search/SearchResultList.test.tsx

diff --git a/src/documentation/search/SearchResultList.test.tsx b/src/documentation/search/SearchResultList.test.tsx
new file mode 100644
index 000000000..d7d5dfec2
--- /dev/null
+++ b/src/documentation/search/SearchResultList.test.tsx
@@ -0,0 +1,42 @@
+/**
+ * (c) 2026, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { render, screen } from "@testing-library/react";
+import { IntlProvider } from "react-intl";
+import { MemoryRouter } from "react-router";
+import { Result } from "./common";
+import SearchResultList from "./SearchResultList";
+
+describe("SearchResultList", () => {
+  it("marks matched terms so assistive technology can announce them", () => {
+    const result: Result = {
+      id: "loops",
+      navigation: { tab: "reference", slug: { id: "loops" } },
+      containerTitle: "Loops",
+      title: "Loops",
+      extract: {
+        title: [{ type: "match", extract: "Loops" }],
+        content: [
+          { type: "match", extract: "Loops" },
+          { type: "text", extract: " repeat sections of code." },
+        ],
+      },
+    };
+    render(
+      <IntlProvider locale="en">
+        <MemoryRouter>
+          <SearchResultList
+            title="Reference"
+            results={[result]}
+            viewedResults={[]}
+            onViewResult={() => {}}
+          />
+        </MemoryRouter>
+      </IntlProvider>
+    );
+    const marks = screen.getAllByRole("mark");
+    expect(marks.map((m) => m.textContent)).toEqual(["Loops", "Loops"]);
+  });
+});
diff --git a/src/documentation/search/SearchResultList.tsx b/src/documentation/search/SearchResultList.tsx
index b5e02c006..24933f3a2 100644
--- a/src/documentation/search/SearchResultList.tsx
+++ b/src/documentation/search/SearchResultList.tsx
@@ -116,8 +116,15 @@ const ExtractText = ({ extract, title, ...props }: ExtractTextProps) => {
             {t.extract}
           </Text>
         ) : (
-          // eslint-disable-next-line @eslint-react/no-array-index-key -- position is the only identity here
-          <Text key={i} as="span" bgColor="#6C4BC14D" borderRadius="md" p="0.5">
+          <Text
+            // eslint-disable-next-line @eslint-react/no-array-index-key -- position is the only identity here
+            key={i}
+            as="mark"
+            color="inherit"
+            bgColor="#6C4BC14D"
+            borderRadius="md"
+            p="0.5"
+          >
             {t.extract}
           </Text>
         )