From af70ae5f225d1e1df1dc2f2b09cc8501ffa3a666 Mon Sep 17 00:00:00 2001
From: Hannah <hannahbergam@gmail.com>
Date: Tue, 27 Jan 2026 14:05:13 -0800
Subject: [PATCH 1/3] screenreader working for guide

---
 src/oceans/components/common/Guide.jsx | 43 ++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 3 deletions(-)

diff --git a/src/oceans/components/common/Guide.jsx b/src/oceans/components/common/Guide.jsx
index f17b8ffc..f21f5a93 100644
--- a/src/oceans/components/common/Guide.jsx
+++ b/src/oceans/components/common/Guide.jsx
@@ -29,11 +29,30 @@ export const stopTypingSounds = () => {
 };
 
 let UnwrappedGuide = class Guide extends React.Component {
+  componentDidUpdate(prevProps, prevState) {
+    // Focus the dialog on guide change, but do not trap focus
+    const currentGuide = guide.getCurrentGuide();
+    if (
+      currentGuide &&
+      this.guideDialogRef &&
+      this.guideDialogRef.current &&
+      document.activeElement !== this.guideDialogRef.current
+    ) {
+      this.guideDialogRef.current.focus();
+    }
+  }
   onTypingDone() {
     clearInterval(getState().guideTypingTimer);
     setState({guideShowing: true, guideTypingTimer: undefined});
   }
 
+  onGuideKeyDown = (e) => {
+    if (e.key === ' ' || e.key === 'Enter' || e.key === 'Spacebar') {
+      e.preventDefault();
+      this.onGuideClick();
+    }
+  };
+
   onGuideClick = () => {
     const state = getState();
     const currentGuide = guide.getCurrentGuide();
@@ -142,6 +161,11 @@ let UnwrappedGuide = class Guide extends React.Component {
       !currentGuide.noDimBackground &&
       currentGuide.style !== 'Info';
 
+      // Ref for focus management
+      if (!this.guideDialogRef) {
+        this.guideDialogRef = React.createRef();
+      }
+
     return (
       <div>
         {currentGuide && currentGuide.image && (
@@ -157,9 +181,16 @@ let UnwrappedGuide = class Guide extends React.Component {
               key={currentGuide.id}
               style={guideBgStyle}
               onClick={this.onGuideClick}
+              onKeyDown={this.onGuideKeyDown}
+              tabIndex={0}
+              role="button"
+              aria-label={I18n.t('continue')}
               id="uitest-dismiss-guide"
             >
               <div
+                ref={this.guideDialogRef}
+                aria-labelledby="guide-heading"
+                tabIndex={-1}
                 style={{
                   ...styles.guide,
                   ...styles[`guide${currentGuide.style}`]
@@ -167,12 +198,18 @@ let UnwrappedGuide = class Guide extends React.Component {
               >
                 <div>
                   {currentGuide.style === 'Info' && (
-                    <div style={styles.guideHeading}>
+                    <div id="guide-heading" style={styles.guideHeading}>
                       {I18n.t('didYouKnow')}
                     </div>
                   )}
 
-                  <div style={styles.guideTypingText}>
+
+                  {/* Visually hidden aria-live region for screen readers */}
+                  <div style={{position: 'absolute', left: '-9999px', width: '1px', height: '1px', overflow: 'hidden'}} aria-live="polite">
+                    {currentGuide.textFn(getState())}
+                  </div>
+                  {/* Visible Typist animation for sighted users */}
+                  <div style={styles.guideTypingText} aria-hidden="true">
                     <Typist
                       avgTypingDelay={35}
                       stdTypingDelay={15}
@@ -190,7 +227,7 @@ let UnwrappedGuide = class Guide extends React.Component {
                         : styles.guideFinalTextContainer
                     }
                   >
-                    <div style={styles.guideFinalText}>
+                    <div style={styles.guideFinalText} aria-hidden="true">
                       {currentGuide.textFn(getState())}
                     </div>
                   </div>

From e04c61eb7d2cef1c64e5b9364a66fbaa2ef69821 Mon Sep 17 00:00:00 2001
From: Hannah <hannahbergam@gmail.com>
Date: Tue, 27 Jan 2026 14:21:30 -0800
Subject: [PATCH 2/3] pr feedback

---
 src/oceans/components/common/Guide.jsx | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/src/oceans/components/common/Guide.jsx b/src/oceans/components/common/Guide.jsx
index f21f5a93..7218cea6 100644
--- a/src/oceans/components/common/Guide.jsx
+++ b/src/oceans/components/common/Guide.jsx
@@ -29,16 +29,23 @@ export const stopTypingSounds = () => {
 };
 
 let UnwrappedGuide = class Guide extends React.Component {
-  componentDidUpdate(prevProps, prevState) {
-    // Focus the dialog on guide change, but do not trap focus
+  guideDialogRef = React.createRef();
+
+  componentDidUpdate() {
+    // Focus the dialog only when the guide changes, not on every re-render
     const currentGuide = guide.getCurrentGuide();
+    const currentGuideId = currentGuide ? currentGuide.id : null;
+
     if (
+      currentGuideId !== this.lastFocusedGuideId &&
       currentGuide &&
       this.guideDialogRef &&
-      this.guideDialogRef.current &&
-      document.activeElement !== this.guideDialogRef.current
+      this.guideDialogRef.current
     ) {
       this.guideDialogRef.current.focus();
+      this.lastFocusedGuideId = currentGuideId;
+    } else if (!currentGuide) {
+      this.lastFocusedGuideId = null;
     }
   }
   onTypingDone() {
@@ -161,11 +168,6 @@ let UnwrappedGuide = class Guide extends React.Component {
       !currentGuide.noDimBackground &&
       currentGuide.style !== 'Info';
 
-      // Ref for focus management
-      if (!this.guideDialogRef) {
-        this.guideDialogRef = React.createRef();
-      }
-
     return (
       <div>
         {currentGuide && currentGuide.image && (

From 91fdfdfcbcd64e6d553690bb69dee9390615b2b0 Mon Sep 17 00:00:00 2001
From: Hannah <hannahbergam@gmail.com>
Date: Fri, 30 Jan 2026 10:39:53 -0800
Subject: [PATCH 3/3] fixing focus outline to match

---
 src/oceans/components/common/Guide.jsx |  1 +
 src/oceans/styles/fade.css             | 11 +++++++++++
 2 files changed, 12 insertions(+)

diff --git a/src/oceans/components/common/Guide.jsx b/src/oceans/components/common/Guide.jsx
index 7218cea6..cc1f342c 100644
--- a/src/oceans/components/common/Guide.jsx
+++ b/src/oceans/components/common/Guide.jsx
@@ -193,6 +193,7 @@ let UnwrappedGuide = class Guide extends React.Component {
                 ref={this.guideDialogRef}
                 aria-labelledby="guide-heading"
                 tabIndex={-1}
+                className="guide-dialog"
                 style={{
                   ...styles.guide,
                   ...styles[`guide${currentGuide.style}`]
diff --git a/src/oceans/styles/fade.css b/src/oceans/styles/fade.css
index ee3f8139..d927b43b 100644
--- a/src/oceans/styles/fade.css
+++ b/src/oceans/styles/fade.css
@@ -15,3 +15,14 @@
     opacity: 1;
   }
 }
+
+/* Only show focus outline when navigating with keyboard, not on programmatic focus */
+.guide-dialog:focus {
+  outline: none;
+}
+
+.guide-dialog:focus-visible {
+  outline: 2px solid white;
+  outline-offset: 2px;
+  box-shadow: 0 0 0 4px black;
+}