From c6adf7761edc1f040cba8edce1561870252fdb75 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 26 Apr 2026 17:51:36 +0000
Subject: [PATCH 1/2] Initial plan


From dab754edf897ee6b945568a26ee58ba0ad48a0df Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 26 Apr 2026 17:57:16 +0000
Subject: [PATCH 2/2] docs: rename skip link anchor from #_top to #main-content
 (WCAG 2.4.1)

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/a0abdd9f-fe08-4f9a-860a-4b9fd872fe24

Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
---
 docs/src/components/CustomHead.astro |  5 ++++
 docs/src/components/SkipLink.astro   |  2 +-
 docs/src/scripts/skip-link.ts        | 41 ++++++++++++++++++++++++++++
 3 files changed, 47 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/scripts/skip-link.ts

diff --git a/docs/src/components/CustomHead.astro b/docs/src/components/CustomHead.astro
index 55cadb7769e..45394d8f8cb 100644
--- a/docs/src/components/CustomHead.astro
+++ b/docs/src/components/CustomHead.astro
@@ -84,6 +84,11 @@ const filteredHead = head.filter(({ tag, attrs }) => {
   import '../scripts/copy-button-aria.ts';
 </script>
 
+<!-- Skip link accessibility enhancement: adds id="main-content" and tabindex="-1" to <main> -->
+<script>
+  import '../scripts/skip-link.ts';
+</script>
+
 <script is:inline>
   (function() {
     const storedTheme = localStorage.getItem('starlight-theme') || 'auto';
diff --git a/docs/src/components/SkipLink.astro b/docs/src/components/SkipLink.astro
index afd587553ae..28e9876d1c9 100644
--- a/docs/src/components/SkipLink.astro
+++ b/docs/src/components/SkipLink.astro
@@ -4,4 +4,4 @@
 <!-- Skip navigation link for WCAG 2.4.1 compliance.
      Visually hidden until focused via keyboard; moves focus directly to the
      main content area, bypassing repeated navigation blocks. -->
-<a href="#_top" class="skip-link">Skip to main content</a>
+<a href="#main-content" class="skip-link">Skip to main content</a>
diff --git a/docs/src/scripts/skip-link.ts b/docs/src/scripts/skip-link.ts
new file mode 100644
index 00000000000..cb0cdb912ab
--- /dev/null
+++ b/docs/src/scripts/skip-link.ts
@@ -0,0 +1,41 @@
+/**
+ * Skip Link Accessibility Enhancement
+ *
+ * Starlight renders the main content inside a `<main>` element but does not
+ * expose a stable `id` on it.  The page title heading receives `id="_top"` by
+ * default, which the custom SkipLink component previously targeted.  The name
+ * `_top` implies "top of page" rather than "main content", creating ambiguity
+ * for assistive technology users (WCAG 2.4.1).
+ *
+ * This script adds `id="main-content"` and `tabindex="-1"` to the `<main>`
+ * element so that the skip link (`href="#main-content"`) lands on the correct
+ * landmark and keyboard focus is reliably placed there.  The `tabindex="-1"`
+ * attribute makes the element programmatically focusable without including it
+ * in the natural tab order.
+ *
+ * The enhancement is applied on every page load and re-applied on Astro
+ * client-side navigation so it works across all pages and navigations.
+ */
+
+function enhanceMainLandmark(): void {
+	const main = document.querySelector<HTMLElement>('main');
+	if (!main) {
+		return;
+	}
+	if (!main.id) {
+		main.id = 'main-content';
+	}
+	if (!main.hasAttribute('tabindex')) {
+		main.setAttribute('tabindex', '-1');
+	}
+}
+
+// Run on initial page load
+if (document.readyState === 'loading') {
+	document.addEventListener('DOMContentLoaded', enhanceMainLandmark);
+} else {
+	enhanceMainLandmark();
+}
+
+// Re-run on Astro client-side navigation
+document.addEventListener('astro:page-load', enhanceMainLandmark);