From abbf6fc345606714dbcb03c73a4991c5bffeb166 Mon Sep 17 00:00:00 2001
From: Psychotoxical <171614930+Psychotoxical@users.noreply.github.com>
Date: Fri, 24 Apr 2026 19:47:10 +0200
Subject: [PATCH] chore(orbit): auto-focus first help accordion + visible
 keyboard-focus ring

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/components/OrbitHelpModal.tsx | 9 +++++++--
 src/styles/components.css         | 9 +++++++++
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/src/components/OrbitHelpModal.tsx b/src/components/OrbitHelpModal.tsx
index 92b7a4bd..5a84f216 100644
--- a/src/components/OrbitHelpModal.tsx
+++ b/src/components/OrbitHelpModal.tsx
@@ -22,10 +22,15 @@ export default function OrbitHelpModal() {
   useEffect(() => {
     if (!isOpen) return;
     // Focus the first accordion summary so arrow keys work immediately.
-    queueMicrotask(() => {
+    // Uses a short setTimeout because the browser re-focuses the clicked
+    // trigger button after the click handler returns — our focus call has
+    // to happen *after* that, otherwise the browser silently overrides it
+    // and the user only gets keyboard nav after pressing Tab first.
+    const id = window.setTimeout(() => {
       const first = bodyRef.current?.querySelector<HTMLElement>('summary');
       first?.focus();
-    });
+    }, 60);
+    return () => window.clearTimeout(id);
   }, [isOpen]);
 
   useEffect(() => {
diff --git a/src/styles/components.css b/src/styles/components.css
index 4ff0d3a4..8a823650 100644
--- a/src/styles/components.css
+++ b/src/styles/components.css
@@ -11955,6 +11955,15 @@ html[data-psy-native-hidden="true"] *::after {
   color: var(--text-secondary, var(--text-primary));
 }
 .orbit-help-modal__body p:last-child { margin-bottom: 0; }
+
+/* Keyboard focus indicator for accordion summaries — the default outline
+   is too subtle against the modal's dark background. Uses focus-visible
+   so mouse clicks don't leave a lingering ring. */
+.orbit-help-modal__body summary:focus-visible {
+  outline: none;
+  background: color-mix(in srgb, var(--accent) 14%, transparent);
+  box-shadow: inset 3px 0 0 var(--accent);
+}
 .orbit-help-modal__warn {
   display: flex;
   flex-direction: column;