@a11y-context/mcp-server 0.1.0

package/corpus/web/react/components/menu.menubar.md

@@ -0,0 +1,296 @@
+---
+id: menu.menubar
+title: Menubar
+stack: web/react
+status: beta
+latest_version: 0.1.0
+tags: [menubar, menu, roving-tabindex, command-bar, application, keyboard-navigation]
+aliases: [menu bar, application menu bar, command bar, app menu bar, editor menu bar, file edit view menu, desktop menu bar]
+summary: A persistent horizontal bar of application command menus using role="menubar", role="menu", and role="menuitem", for desktop-application command surfaces only, never site navigation.
+---
+
+# Menubar
+
+Pattern ID: `menu.menubar`
+
+A persistent horizontal bar of application command menus using `role="menubar"`, `role="menu"`, and `role="menuitem"`, for desktop-application command surfaces only, never site navigation.
+
+This pattern is rarely appropriate on the web. Almost every horizontal bar of links is site navigation, which must not use menu roles (use `navigation-menu.basic`). Reach for a menubar only when replicating a desktop application command bar.
+
+## Use When
+- Use when building a genuine desktop-application-style command bar that replicates an operating-system menu bar of commands (e.g., a web-based document editor, IDE, or design tool with "File", "Edit", "View").
+- Use when the items are application commands, not navigation destinations (e.g., "New File", "Undo", "Toggle Sidebar").
+- Use when the surface is a persistent bar of multiple always-visible top-level menus, not a single button that opens one menu (e.g., a File/Edit/View bar fixed at the top of the editor).
+
+## Do Not Use When
+- Do not use when the bar is site or app navigation of any kind, including a nav bar styled to look like a menu bar or with fly-out submenus; this is the overwhelmingly common case (use `navigation-menu.basic`).
+- Do not use when a single button opens one action menu (use `menu.basic`).
+- Do not use when the user picks a value from a set (use `select.native`).
+- Do not use when a single trigger shows and hides a region of content (use `disclosure.basic`).
+
+## Must Haves
+
+### Roles & structure
+- The container has `role="menubar"`.
+- Horizontal orientation is implicit for `role="menubar"`; no `aria-orientation` is required.
+- Only menu-related elements appear inside the menubar (top-level items, submenus, and separators). No links, no arbitrary content.
+- Each top-level item has `role="menuitem"`.
+- Each submenu is a container with `role="menu"` and an accessible name that matches its top-level item (e.g., `aria-label="File"`).
+- Submenu commands have `role="menuitem"`, or `role="menuitemcheckbox"` or `role="menuitemradio"` for stateful commands.
+- Dividers within a submenu use `role="separator"`.
+- The submenu contains only menu parts (`menuitem`, `menuitemcheckbox`, `menuitemradio`, and `separator`), no links or arbitrary content.
+
+### Accessible name
+- The container has an accessible name (e.g., `aria-label="Application"`).
+
+### State & properties
+- Each top-level item that opens a submenu has `aria-haspopup="menu"` and `aria-expanded="true|false"` reflecting open/closed.
+- Each submenu is shown/hidden in the DOM (e.g., via the `hidden` attribute), so that when closed, its commands cannot be reached by keyboard or screen readers.
+
+### Keyboard
+- Arrow Left and Arrow Right move focus between top-level items and wrap at the ends.
+- Arrow Down, Enter, or Space on a top-level item opens its submenu and moves focus to the first submenu item.
+- Within an open submenu, Arrow Up and Arrow Down move focus between commands and wrap at the ends.
+- Within an open submenu, Arrow Right moves to the adjacent top-level menu, and Arrow Left moves to the previous top-level menu (opening that menu).
+- Within an open submenu, Home moves focus to the first command and End moves focus to the last command.
+- Enter or Space activates the focused submenu command.
+- Type-ahead moves focus to the next item whose label starts with the typed character, both across top-level items and within an open submenu.
+
+### Focus
+- Focus is managed with roving tabindex across the top-level items.
+  - The first top-level item starts at `tabindex="0"`; all other top-level items start at `tabindex="-1"`.
+  - Moving between top-level items updates tabindex so exactly one top-level item is at `tabindex="0"` at a time.
+- Ensure a visible focus state (e.g., a 2px solid outline offset by 1-2px) around the top-level items and submenu commands.
+
+### Dismissal
+- Esc closes the current submenu and returns focus to its top-level item.
+- The menubar closes any open submenu when focus moves outside the menubar (e.g., via Tab or an outside pointer click), so no submenu stays visible while its top-level item is at `aria-expanded="false"`.
+
+## Customizable
+- Stateful commands may use `role="menuitemcheckbox"` (with `aria-checked="true|false"`) or `role="menuitemradio"` (with `aria-checked="true|false"` within a grouped set) instead of plain `role="menuitem"`.
+- Roving tabindex is the default focus model. `aria-activedescendant` on the menubar is an acceptable alternative, with the caveat that its assistive-technology support is weaker than roving tabindex and it must be tested against target screen readers.
+- Submenu depth is at the engineer's discretion; nested submenus are permitted as long as each nested `role="menu"` carries an accessible name and the same keyboard contract applies at every level.
+
+## Don'ts
+- Do not use a menubar for site or app navigation; a horizontal bar of links is navigation and must use `navigation-menu.basic`, not menu roles.
+- Do not place links (`<a href>`) inside a menubar or its submenus; menubar children are commands, not destinations.
+- Do not half-implement the keyboard contract; a menubar without arrow-key traversal, submenu open/close, and type-ahead is broken for keyboard and screen reader users.
+- Do not make every top-level item and command tabbable; use roving tabindex so Tab enters and exits the menubar as a single stop.
+- Do not leave a submenu visible while its top-level item has `aria-expanded="false"` (and vice versa).
+
+## Golden Pattern
+
+Structural reference for AI coding assistants — semantics, focus, and keyboard behavior. Styling, copy, and demo data are illustrative.
+
+```jsx
+"use client";
+
+export function MenubarDemo() {
+  // Index of the top-level menu that currently holds roving focus.
+  const [activeTop, setActiveTop] = useState(0);
+  // Index of the open submenu, or null when all submenus are closed.
+  const [openTop, setOpenTop] = useState(null);
+  // Index of the focused command within the open submenu.
+  const [activeItem, setActiveItem] = useState(0);
+
+  const topRefs = useRef(new Map());
+  const itemRefs = useRef(new Map());
+
+  function focusTop(index) {
+    setActiveTop(index);
+    requestAnimationFrame(() => topRefs.current.get(index)?.focus());
+  }
+
+  function openMenu(index, itemIndex = 0) {
+    setActiveTop(index);
+    setOpenTop(index);
+    setActiveItem(itemIndex);
+    requestAnimationFrame(() => itemRefs.current.get(`${index}-${itemIndex}`)?.focus());
+  }
+
+  function closeMenu(restoreToTop = true) {
+    const top = openTop;
+    setOpenTop(null);
+    if (restoreToTop && top != null) {
+      requestAnimationFrame(() => topRefs.current.get(top)?.focus());
+    }
+  }
+
+  function activate(command) {
+    // Real handlers dispatch the command; alert() shows the item fires.
+    alert(`Command: ${command}`);
+    closeMenu();
+  }
+
+  // Type-ahead: focus the next sibling whose label starts with the typed key.
+  function typeAhead(labels, current, key, onMatch) {
+    const lower = key.toLowerCase();
+    for (let offset = 1; offset <= labels.length; offset += 1) {
+      const idx = (current + offset) % labels.length;
+      if (labels[idx].toLowerCase().startsWith(lower)) {
+        onMatch(idx);
+        return;
+      }
+    }
+  }
+
+  // A single printing character with no command/system modifier is type-ahead;
+  // Cmd/Ctrl/Alt combos are shortcuts and must pass through untouched.
+  function isTypeAheadKey(event) {
+    return event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey;
+  }
+
+  function onTopKeyDown(index, event) {
+    const count = MENUS.length;
+    switch (event.key) {
+      case "ArrowRight":
+        event.preventDefault();
+        focusTop((index + 1) % count);
+        break;
+      case "ArrowLeft":
+        event.preventDefault();
+        focusTop((index - 1 + count) % count);
+        break;
+      case "ArrowDown":
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        openMenu(index, 0);
+        break;
+      default:
+        if (isTypeAheadKey(event)) {
+          typeAhead(MENUS.map((m) => m.label), index, event.key, focusTop);
+        }
+    }
+  }
+
+  function onItemKeyDown(topIndex, itemIndex, event) {
+    const items = MENUS[topIndex].items;
+    const count = items.length;
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        openMenu(topIndex, (itemIndex + 1) % count);
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        openMenu(topIndex, (itemIndex - 1 + count) % count);
+        break;
+      case "Home":
+        event.preventDefault();
+        openMenu(topIndex, 0);
+        break;
+      case "End":
+        event.preventDefault();
+        openMenu(topIndex, count - 1);
+        break;
+      case "ArrowRight":
+        event.preventDefault();
+        openMenu((topIndex + 1) % MENUS.length, 0);
+        break;
+      case "ArrowLeft":
+        event.preventDefault();
+        openMenu((topIndex - 1 + MENUS.length) % MENUS.length, 0);
+        break;
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        activate(items[itemIndex]);
+        break;
+      case "Escape":
+        event.preventDefault();
+        closeMenu();
+        break;
+      default:
+        if (isTypeAheadKey(event)) {
+          typeAhead(items, itemIndex, event.key, (idx) => openMenu(topIndex, idx));
+        }
+    }
+  }
+
+  return (
+    <div
+      role="menubar"
+      aria-label="Editor"
+      style={{ display: "flex", gap: 4 }}
+      // Close the open submenu when focus leaves the menubar entirely (Tab-out
+      // or outside click), so no submenu lingers with aria-expanded="false".
+      onBlur={(event) => {
+        if (!event.currentTarget.contains(event.relatedTarget)) {
+          closeMenu(false);
+        }
+      }}
+    >
+      {MENUS.map((menu, topIndex) => (
+        <div key={menu.id} style={{ position: "relative" }}>
+          <button
+            type="button"
+            role="menuitem"
+            aria-haspopup="menu"
+            aria-expanded={openTop === topIndex ? "true" : "false"}
+            // Roving tabindex: exactly one top-level item is tabbable.
+            tabIndex={activeTop === topIndex ? 0 : -1}
+            onClick={() => (openTop === topIndex ? closeMenu() : openMenu(topIndex, 0))}
+            onKeyDown={(event) => onTopKeyDown(topIndex, event)}
+            ref={(el) => {
+              if (el) topRefs.current.set(topIndex, el);
+              else topRefs.current.delete(topIndex);
+            }}
+          >
+            {menu.label}
+          </button>
+
+          <div
+            role="menu"
+            aria-label={menu.label}
+            hidden={openTop !== topIndex}
+            style={{ position: "absolute", top: "100%", left: 0, minWidth: 160 }}
+          >
+            {menu.items.map((command, itemIndex) => (
+              <button
+                key={command}
+                type="button"
+                role="menuitem"
+                tabIndex={-1}
+                onClick={() => activate(command)}
+                onKeyDown={(event) => onItemKeyDown(topIndex, itemIndex, event)}
+                ref={(el) => {
+                  if (el) itemRefs.current.set(`${topIndex}-${itemIndex}`, el);
+                  else itemRefs.current.delete(`${topIndex}-${itemIndex}`);
+                }}
+                style={{ display: "block", width: "100%", textAlign: "left" }}
+              >
+                {command}
+              </button>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+const MENUS = [
+  { id: "file", label: "File", items: ["New File", "Open", "Save", "Export"] },
+  { id: "edit", label: "Edit", items: ["Undo", "Redo", "Cut", "Copy", "Paste"] },
+  { id: "view", label: "View", items: ["Zoom In", "Zoom Out", "Toggle Sidebar"] },
+];
+```
+
+## Acceptance Checks
+
+Keyboard
+- Arrow Left and Arrow Right move focus across the top-level items and wrap at the ends.
+- Arrow Down, Enter, or Space on a top-level item opens its submenu and focuses the first command.
+- Within an open submenu, Home focuses the first command and End focuses the last command.
+- Within an open submenu, Arrow Right moves to the adjacent top-level menu and Arrow Left moves to the previous top-level menu, opening that menu.
+- Esc closes the open submenu and returns focus to its top-level item.
+- Enter or Space activates the focused command.
+- Type-ahead moves focus to the next item whose label starts with the typed character.
+- Tab enters and exits the menubar as a single stop, closing any open submenu on exit, and does not visit every top-level item and command.
+
+Screen Reader
+- The container is announced as a menu bar with its accessible name.
+- Each open submenu is announced as a menu, with a name matching its top-level item.
+- Top-level items and commands are announced as menu items.
+- A top-level item that opens a submenu announces that it has a submenu via `aria-haspopup`, and announces its expanded or collapsed state via `aria-expanded`.

package/corpus/web/react/components/navigation-menu.basic.md

@@ -0,0 +1,349 @@
+---
+id: navigation-menu.basic
+title: Navigation Menu
+stack: web/react
+status: beta
+latest_version: 0.3.0
+tags: [navigation, menu, disclosure, header, sitemap, flyout]
+aliases: [nav dropdown, header dropdown, mega menu (simple), disclosure navigation, flyout menu]
+summary: A non-modal header navigation pattern that supports top-level links and optional sub-menus. Uses disclosure-style toggles (buttons) with aria-expanded/controls and Tab-based navigation (no roving focus / no role=menu).
+---
+
+# Navigation Menu
+
+Pattern ID: `navigation-menu.basic`
+
+A non-modal header navigation pattern that supports top-level links and optional sub-menus. Uses disclosure-style toggles (buttons) with `aria-expanded`/`aria-controls` and Tab-based navigation (no roving focus, no `role="menu"`).
+
+## Use When
+- Use when a website's top-level navigation contains at least one sub-menu of links.
+- Use for primary or secondary navigation regions (e.g., header nav, section nav) when the same link + sub-menu structure is needed.
+- Use when the navigation structure maps to a sitemap-like set of destinations.
+
+## Do Not Use When
+- Do not use when you are building a desktop-application command bar with arrow-key navigation and roving tabindex (use `menu.menubar`).
+- Do not use to select a value within a form (use `select.native` or `combobox.autocomplete` when searchable).
+- Do not use as the mobile or responsive version of a navigation menu.
+
+## Must Haves
+
+### Roles & structure
+- Navigation is contained within a `<nav>` landmark, or an element with `role="navigation"`, and an accessible name (`aria-label`) when multiple nav landmarks exist.
+- Top-level navigation items are presented in a list structure (e.g., `<ul><li>…</li></ul>`).
+- Each top-level item is one of the following:
+  - (A) **Simple link**: a single `<a>` to a destination.
+  - (B) **Parent link + menu button** (when the parent has its own destination page):
+    - The parent is a normal `<a>` (activates navigation).
+    - A separate adjacent **menu toggle button** opens/closes the sub-menu.
+  - (C) **Parent button** (when the parent does not have its own destination page):
+    - A `<button>` acts as the parent control and opens/closes the sub-menu.
+- The toggle control is a native `<button>` (preferred) or `role="button"` only when a native button cannot be used.
+  - If using `role="button"`, add `tabindex="0"` and keyboard support for Enter and Space, ensuring Space prevents page scrolling while activating.
+- The sub-menu container is positioned immediately after its toggle control in the DOM.
+- Sub-menu items are links and/or buttons contained in a list structure (`<ul><li>…</li></ul>`).
+
+### Accessible name
+- If the toggle is an **icon button associated with a parent link** (case B), it has an accessible name that includes the parent link text.
+  - Example: `aria-label="Categories menu"` (text is customizable but must include the parent link label).
+
+### State & properties
+- If the current page corresponds to a top-level item:
+  - If the top-level item is a link, apply aria-current="page" to that link.
+  - If the top-level item is a button-only parent (no destination), do not put aria-current on the button. Instead, apply aria-current="page" to the submenu link that represents the current page.
+  - If the navigation has no explicit Home link and the site logo links to the homepage, the logo link carries `aria-current="page"` when the user is on the homepage.
+  - Ensure there is some visual change that indicates this is the current page link.
+- The toggle reflects open state with `aria-expanded="true|false"`.
+- The toggle references its submenu with `aria-controls="IDREF"` (recommended).
+- The toggle does not carry `aria-haspopup`; a submenu of links is not a menu, listbox, tree, grid, or dialog, so `aria-expanded` alone is the correct state signal.
+- Top-level items that open a sub-menu include a visible indicator (e.g., down caret) that communicates "has submenu."
+  - The indicator is decorative and does not replace the accessible name of the toggle (e.g., use an aria-label like "Categories menu" on icon-only toggles).
+- Sub-menus all default to closed, or hidden, when the page loads.
+- The sub-menu is shown/hidden in the DOM (e.g., via `hidden`) so that when closed, submenu links cannot be reached by keyboard or screen readers.
+
+### Keyboard
+- Tab boundary behavior:
+  - If focus is on the **last focusable element** in an open submenu and the user presses Tab, the submenu closes and focus moves to the next focusable element after the submenu.
+  - If focus is on the **first focusable element** in an open submenu and the user presses Shift+Tab, the submenu closes and focus moves to the toggle control.
+
+### Focus
+- Ensure a visible focus state (e.g., a 2px solid outline offset by 1-2px) around all links and buttons.
+- The sub-menu is non-modal and does not trap focus.
+- When a submenu is opened, focus remains on the toggle control.
+  - Keyboard users reach the first submenu item with Tab.
+- Users can Tab through submenu items and continue to the rest of the page (no focus trap).
+
+### Dismissal
+- When focus moves outside the toggle + submenu (Tab away or click elsewhere), the submenu closes.
+- Esc closes an open submenu and returns focus to its toggle control.
+- If the navigation contains multiple sub-menus, opening one closes any other open sub-menu.
+
+## Customizable
+- Whether a submenu closes when a submenu item is activated (often yes).
+- Whether submenu content includes non-interactive text (e.g., "Signed in as…") or separators.
+- Positioning of submenus (left/right, below/above) provided DOM order and focus order remain logical.
+- Whether the toggle is a caret icon button, text button, or combined button label (as long as the accessibility semantics above are met).
+
+## Don'ts
+- Do not open sub-menus on hover only.
+  - If hover-to-open is supported for mouse users, sub-menus must also be operable via click and keyboard, and keyboard users must not be forced to tab through submenu items unless they intentionally open them.
+- Do not make a top-level item both a navigation link and the submenu toggle using the same element.
+  - If the parent has its own destination page and also has a submenu, use **parent link + separate toggle button**.
+- Do not use `role="menu"` / `role="menuitem"` unless you implement the full ARIA menu widget behavior (managed focus, arrow keys, typeahead).
+- Do not add `aria-haspopup` to the toggle; the submenu is a list of links, not a menu, so it announces a widget that is not present.
+- Do not leave submenu content visible while `aria-expanded="false"` (and vice versa).
+- Do not strand focus by removing the currently focused submenu item without closing and allowing focus to move naturally.
+- Do not render sub-menus expanded/visible by default. They open only after the user activates the corresponding toggle.
+
+## Golden Pattern
+
+Structural reference for AI coding assistants — semantics, focus, and keyboard behavior. Styling, copy, and demo data are illustrative.
+
+```jsx
+"use client";
+
+export function NavigationMenuBasic() {
+  const [openId, setOpenId] = useState(null);
+
+  const togglesRef = useRef(new Map());
+  const listsRef = useRef(new Map());
+
+  function closeAll() {
+    setOpenId(null);
+  }
+
+  function toggle(id) {
+    setOpenId((prev) => (prev === id ? null : id));
+  }
+
+  useEffect(() => {
+    if (!openId) return;
+
+    function onPointerDown(event) {
+      const btn = togglesRef.current.get(openId);
+      const list = listsRef.current.get(openId);
+      if (!btn || !list) return;
+
+      const inside = btn.contains(event.target) || list.contains(event.target);
+      if (!inside) closeAll();
+    }
+
+    document.addEventListener("pointerdown", onPointerDown);
+    return () => document.removeEventListener("pointerdown", onPointerDown);
+  }, [openId]);
+
+  useEffect(() => {
+    if (!openId) return;
+
+    function onFocusIn(event) {
+      const btn = togglesRef.current.get(openId);
+      const list = listsRef.current.get(openId);
+      if (!btn || !list) return;
+
+      const inside = btn.contains(event.target) || list.contains(event.target);
+      if (!inside) closeAll();
+    }
+
+    document.addEventListener("focusin", onFocusIn, true);
+    return () => document.removeEventListener("focusin", onFocusIn, true);
+  }, [openId]);
+
+  useEffect(() => {
+    if (!openId) return;
+
+    function onKeyDown(event) {
+      if (event.key !== "Escape") return;
+      event.preventDefault();
+
+      const btn = togglesRef.current.get(openId);
+      closeAll();
+      requestAnimationFrame(() => btn?.focus());
+    }
+
+    document.addEventListener("keydown", onKeyDown, true);
+    return () => document.removeEventListener("keydown", onKeyDown, true);
+  }, [openId]);
+
+  function onSubmenuKeyDown(id, event) {
+    if (event.key !== "Tab") return;
+
+    const list = listsRef.current.get(id);
+    if (!list) return;
+
+    const focusables = Array.from(
+      list.querySelectorAll(
+        'a[href], button:not([disabled]), [tabindex]:not([tabindex="-1"])',
+      ),
+    );
+
+    if (!focusables.length) return;
+
+    const first = focusables[0];
+    const last = focusables[focusables.length - 1];
+
+    if (!event.shiftKey && document.activeElement === last) closeAll();
+    if (event.shiftKey && document.activeElement === first) closeAll();
+  }
+
+  return (
+    <nav aria-label="Primary" className="navigation-menu-basic">
+      <ul style={{ listStyle: "none", paddingLeft: 0, display: "flex" }}>
+        <li style={{ position: "relative" }}>
+          <a href="/home" aria-current="page">Home</a>
+        </li>
+
+        <li style={{ position: "relative" }}>
+          <a href="/categories">Categories</a>
+          <button
+            type="button"
+            aria-label="Categories menu"
+            aria-expanded={openId === "categories" ? "true" : "false"}
+            aria-controls="nav-submenu-categories"
+            onClick={() => toggle("categories")}
+            ref={(el) => {
+              if (el) togglesRef.current.set("categories", el);
+              else togglesRef.current.delete("categories");
+            }}
+          >
+            ▼
+          </button>
+
+          <ul
+            id="nav-submenu-categories"
+            aria-label="Categories"
+            hidden={openId !== "categories"}
+            style={{
+              listStyle: "none",
+              paddingLeft: 0,
+              position: "absolute",
+              top: "calc(100% + 0.25rem)",
+              left: 0,
+            }}
+            onKeyDown={(event) => onSubmenuKeyDown("categories", event)}
+            ref={(el) => {
+              if (el) listsRef.current.set("categories", el);
+              else listsRef.current.delete("categories");
+            }}
+          >
+            <li>
+              <a href="/categories/science">Science</a>
+            </li>
+            <li>
+              <a href="/categories/arts">Arts</a>
+            </li>
+            <li>
+              <a href="/categories/engineering">Engineering</a>
+            </li>
+          </ul>
+        </li>
+
+        <li style={{ position: "relative" }}>
+          <button
+            type="button"
+            aria-expanded={openId === "faculty" ? "true" : "false"}
+            aria-controls="nav-submenu-faculty"
+            onClick={() => toggle("faculty")}
+            ref={(el) => {
+              if (el) togglesRef.current.set("faculty", el);
+              else togglesRef.current.delete("faculty");
+            }}
+          >
+            <span>Faculty</span>{" "}
+            <span aria-hidden="true">▼</span>
+          </button>
+
+          <ul
+            id="nav-submenu-faculty"
+            aria-label="Faculty"
+            hidden={openId !== "faculty"}
+            style={{
+              listStyle: "none",
+              paddingLeft: 0,
+              position: "absolute",
+              top: "calc(100% + 0.25rem)",
+              left: 0,
+            }}
+            onKeyDown={(event) => onSubmenuKeyDown("faculty", event)}
+            ref={(el) => {
+              if (el) listsRef.current.set("faculty", el);
+              else listsRef.current.delete("faculty");
+            }}
+          >
+            <li>
+              <a href="/faculty/directory">Directory</a>
+            </li>
+            <li>
+              <a href="/faculty/research">Research</a>
+            </li>
+            <li>
+              <a href="/faculty/contact">Contact</a>
+            </li>
+          </ul>
+        </li>
+
+        <li style={{ position: "relative" }}>
+          <a href="/about">About</a>
+          <button
+            type="button"
+            aria-label="About menu"
+            aria-expanded={openId === "about" ? "true" : "false"}
+            aria-controls="nav-submenu-about"
+            onClick={() => toggle("about")}
+            ref={(el) => {
+              if (el) togglesRef.current.set("about", el);
+              else togglesRef.current.delete("about");
+            }}
+          >
+            ▼
+          </button>
+
+          <ul
+            id="nav-submenu-about"
+            aria-label="About"
+            hidden={openId !== "about"}
+            style={{
+              listStyle: "none",
+              paddingLeft: 0,
+              position: "absolute",
+              top: "calc(100% + 0.25rem)",
+              left: 0,
+            }}
+            onKeyDown={(event) => onSubmenuKeyDown("about", event)}
+            ref={(el) => {
+              if (el) listsRef.current.set("about", el);
+              else listsRef.current.delete("about");
+            }}
+          >
+            <li>
+              <a href="/about/mission">Mission</a>
+            </li>
+            <li>
+              <a href="/about/team">Team</a>
+            </li>
+            <li>
+              <a href="/about/contact">Contact</a>
+            </li>
+          </ul>
+        </li>
+      </ul>
+    </nav>
+  );
+}
+```
+
+## Acceptance Checks
+
+Keyboard
+-   Top-level links are reachable with Tab and activate normally.
+-   If a parent has both a destination and submenu, Tab reaches the parent link, then the adjacent submenu toggle button.
+-   Activating a toggle button opens/closes its submenu; focus remains on the toggle.
+-   Tab enters submenu items only after the submenu is intentionally opened.
+-   Tab from last submenu item closes the submenu and moves to the next element after it.
+-   Shift+Tab from first submenu item closes the submenu and moves focus back to the toggle.
+-   Esc closes the submenu and moves focus to the toggle.
+-   When opening a submenu, any other open submenu closes.
+Screen Reader
+-   Toggle announces expanded/collapsed state via `aria-expanded`.
+-   Closed submenus are not reachable.
+-   Submenu items announce as links/buttons and operate normally.
+-   Icon toggle buttons have accessible names that include the associated parent label (e.g., "Categories menu").
+- On initial render, all sub-menus are closed (`aria-expanded="false"` on toggles; all sub-menus hidden/unreachable).