Accessibility: keep keyboard focus inside the mobile navigation modal

[jinhongliang991013]

Summary

The mobile navigation visually covers the page, but keyboard focus is not
contained inside it. After tabbing through the menu controls, focus moves to
links and controls in the obscured landing-page content behind the overlay.

This makes the navigation behave like a non-modal layer even though it blocks
the viewport. It becomes especially problematic if the overlay is given
role="dialog" and aria-modal="true": the accessibility semantics would say
the background is unavailable while the browser can still focus it.

Reproduction

Tested on June 12, 2026 against https://gib.work/ using Microsoft
Edge/Chromium at a 390 x 844 viewport.

1. Open the landing page at mobile width.
2. Activate the hamburger menu.
3. Press Tab repeatedly without closing the menu.
4. Observe the focus sequence after the final social link in the overlay.

Recorded focus trace

A Playwright run confirmed that the overlay remained visible throughout the
test:

Tab position	Focused control	Inside overlay
1-9	Home, Open App, Close, About, Testimonial, FAQ, YouTube, Discord, X	Yes
10	Hero Get Started For Free link	No
11	Solana link	No
12+	Landing-page tabs and testimonial links	No

The first background element is therefore reachable while the full-screen menu
is still open.

mobile menu open
  -> ...
  -> X social link (last overlay control)
  -> Get Started For Free (background)
  -> Solana (background)
  -> Looking for Help tab (background)

Root cause

components/nav.tsx renders the full-screen menu as an animated sibling
overlay, but it does not:

• cycle Tab from the last menu control to the first;
• cycle Shift+Tab from the first menu control to the last; or
• make the page content outside the menu inert while the menu is open.

PR #113 improves the same component by adding dialog semantics, initial focus,
Escape handling, focus restoration, and scroll locking. Those changes are
useful, but its current patch does not add focus containment or inert, so this
specific failure remains after that PR.

Recommended implementation

Use one of these approaches:

1. Render the mobile navigation with a tested modal-dialog primitive that
   provides focus containment and background inertness; or
2. Keep the current component and implement all of the following together:
   • collect the enabled, visible focusable controls inside the overlay;
   • wrap Tab from the last control to the first;
   • wrap Shift+Tab from the first control to the last;
   • mark the background application content inert for the lifetime of the
     overlay and restore its previous state on close;
   • preserve the initial-focus, Escape-to-close, and trigger-focus-restoration
     behavior proposed in Improve landing page accessibility and mobile navigation #113.

The WAI-ARIA modal dialog pattern requires Tab and Shift+Tab to remain
inside the dialog:
https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/

The native inert attribute removes background descendants from sequential
focus and interaction:
https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inert

Acceptance criteria

• With the mobile menu open, repeated Tab cycles from the final menu
  control back to the first menu control.
• Shift+Tab on the first menu control cycles to the final menu control.
• No background link, button, tab, iframe, or embedded tweet control can
  receive keyboard focus while the menu is open.
• Escape closes the menu.
• Closing the menu returns focus to the hamburger trigger.
• The focus restriction is removed when the menu closes.
• Automated browser coverage verifies forward and reverse focus wrapping
  at a mobile viewport.

This is a behavioral accessibility fix only; no visual redesign is required.

[kly642833741-collab]

I prepared and locally verified a focused patch for this mobile navigation focus-trap issue.

What the patch does

• Adds dialog semantics to the mobile menu overlay.
• Moves initial focus into the opened menu.
• Keeps forward Tab and reverse Shift+Tab focus inside #mobile-navigation.
• Closes the menu on Escape.
• Restores focus to the hamburger trigger after close.
• Marks background siblings as inert and aria-hidden while the menu is open.
• Locks body scroll while the overlay is open and restores it on close.

Verification run

• npm run build passed successfully, including Next.js lint/type checking.
• Browser behavior was checked with Playwright + system Chrome at a 390 x 844 viewport:
  • initial focus landed inside #mobile-navigation;
  • Shift+Tab from the first menu control wrapped to the final menu control;
  • repeated Tab stayed inside the menu and did not reach background links;
  • Escape closed the overlay;
  • focus returned to the open-menu trigger.

Patch:

diff --git a/components/nav.tsx b/components/nav.tsx
index fe8bcef..2e41dfa 100644
--- a/components/nav.tsx
+++ b/components/nav.tsx
@@ -9,13 +9,126 @@ import Image from "next/image";
 import logo from "@/public/work-logo.png";
 import { YoutubeLogoMark } from "./logo/youtube";
 import { siteConfig } from "@/lib/site-config";
-import { useState } from "react";
+import { useEffect, useRef, useState, type KeyboardEvent } from "react";
 import { AnimatePresence, motion } from "framer-motion";
 import { FADE_IN, FADE_UP_ANIMATION_VARIANTS } from "@/lib/framer-variants";
 import { Separator } from "./ui/separator";
 
+const FOCUSABLE_SELECTOR =
+  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
 export function Nav() {
   const [isOpen, setIsOpen] = useState(false);
+  const mobileMenuButtonRef = useRef<HTMLButtonElement>(null);
+  const mobileMenuRef = useRef<HTMLDivElement>(null);
+  const shouldRestoreFocusRef = useRef(false);
+
+  const getMobileMenuControls = () =>
+    Array.from(
+      mobileMenuRef.current?.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR) ?? [],
+    ).filter((element) => !element.hasAttribute("disabled"));
+
+  const openMobileMenu = () => {
+    shouldRestoreFocusRef.current = true;
+    setIsOpen(true);
+  };
+
+  const closeMobileMenu = () => {
+    setIsOpen(false);
+  };
+
+  const handleMobileMenuKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      closeMobileMenu();
+      return;
+    }
+
+    if (event.key !== "Tab") {
+      return;
+    }
+
+    const controls = getMobileMenuControls();
+
+    if (controls.length === 0) {
+      event.preventDefault();
+      return;
+    }
+
+    const firstControl = controls[0];
+    const lastControl = controls[controls.length - 1];
+    const activeElement = document.activeElement;
+
+    if (event.shiftKey) {
+      if (
+        activeElement === firstControl ||
+        !mobileMenuRef.current?.contains(activeElement)
+      ) {
+        event.preventDefault();
+        lastControl.focus();
+      }
+
+      return;
+    }
+
+    if (activeElement === lastControl) {
+      event.preventDefault();
+      firstControl.focus();
+    }
+  };
+
+  useEffect(() => {
+    if (!isOpen) {
+      if (shouldRestoreFocusRef.current) {
+        shouldRestoreFocusRef.current = false;
+        mobileMenuButtonRef.current?.focus();
+      }
+
+      return;
+    }
+
+    const previousOverflow = document.body.style.overflow;
+    const overlay = mobileMenuRef.current;
+    const parent = overlay?.parentElement;
+    const inertSiblings =
+      parent && overlay
+        ? Array.from(parent.children).filter(
+            (child): child is HTMLElement =>
+              child instanceof HTMLElement && child !== overlay,
+          )
+        : [];
+    const previousSiblingState = inertSiblings.map((element) => ({
+      element,
+      inert: element.inert,
+      ariaHidden: element.getAttribute("aria-hidden"),
+    }));
+
+    document.body.style.overflow = "hidden";
+
+    inertSiblings.forEach((element) => {
+      element.inert = true;
+      element.setAttribute("aria-hidden", "true");
+    });
+
+    const focusFrame = requestAnimationFrame(() => {
+      getMobileMenuControls()[0]?.focus();
+    });
+
+    return () => {
+      cancelAnimationFrame(focusFrame);
+      document.body.style.overflow = previousOverflow;
+
+      previousSiblingState.forEach(({ element, inert, ariaHidden }) => {
+        element.inert = inert;
+
+        if (ariaHidden === null) {
+          element.removeAttribute("aria-hidden");
+        } else {
+          element.setAttribute("aria-hidden", ariaHidden);
+        }
+      });
+    };
+  }, [isOpen]);
 
   return (
     <>
@@ -80,10 +193,14 @@ export function Nav() {
             </Button>
 
             <Button
+              ref={mobileMenuButtonRef}
               size={"icon"}
               variant={"secondary"}
               className="md:hidden"
-              onClick={() => setIsOpen(true)}
+              onClick={openMobileMenu}
+              aria-controls="mobile-navigation"
+              aria-expanded={isOpen}
+              aria-label="Open navigation menu"
             >
               <Menu className="size-5" />
             </Button>
@@ -94,6 +211,12 @@ export function Nav() {
       <AnimatePresence>
         {isOpen && (
           <motion.div
+            id="mobile-navigation"
+            ref={mobileMenuRef}
+            role="dialog"
+            aria-modal="true"
+            aria-label="Mobile navigation"
+            onKeyDown={handleMobileMenuKeyDown}
             variants={FADE_IN}
             initial="hidden"
             animate="show"
@@ -115,7 +238,12 @@ export function Nav() {
                     </Link>
                   </Button>
 
-                  <Button size={"icon"} variant={"secondary"} onClick={() => setIsOpen(false)}>
+                  <Button
+                    size={"icon"}
+                    variant={"secondary"}
+                    onClick={closeMobileMenu}
+                    aria-label="Close navigation menu"
+                  >
                     <X className="size-5" />
                   </Button>
                 </div>
@@ -125,7 +253,7 @@ export function Nav() {
                 <Button
                   asChild
                   variant={"ghost"}
-                  onClick={() => setIsOpen(false)}
+                  onClick={closeMobileMenu}
                   className="text-muted-foreground uppercase"
                 >
                   <Link href={"/#about"}>About</Link>
@@ -133,7 +261,7 @@ export function Nav() {
                 <Button
                   asChild
                   variant={"ghost"}
-                  onClick={() => setIsOpen(false)}
+                  onClick={closeMobileMenu}
                   className="text-muted-foreground uppercase"
                 >
                   <Link href={"/#testimonial"}>Testimonial</Link>
@@ -149,7 +277,7 @@ export function Nav() {
                 <Button
                   asChild
                   variant={"ghost"}
-                  onClick={() => setIsOpen(false)}
+                  onClick={closeMobileMenu}
                   className="text-muted-foreground uppercase"
                 >
                   <Link href={"/#faq"}>FAQ</Link>