docs: rename skip link anchor #_top → #main-content (WCAG 2.4.1) (#28618)

Author: Copilot

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';

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>

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);