@a11y-context/mcp-server 0.1.0

package/corpus/web/react/components/combobox.autocomplete.md

@@ -0,0 +1,293 @@
+---
+id: combobox.autocomplete
+title: Autocomplete Combobox
+stack: web/react
+status: beta
+latest_version: 0.1.0
+tags: [combobox, autocomplete, listbox, filter, aria-activedescendant, form, search]
+aliases: [typeahead, type-ahead, autosuggest, auto-suggest, search select, filterable dropdown, predictive input, combo box]
+summary: An editable text input that filters a listbox of options as the user types; uses role="combobox" with aria-autocomplete, aria-expanded, aria-controls, and aria-activedescendant while DOM focus stays on the input.
+---
+
+# Autocomplete Combobox
+
+Pattern ID: `combobox.autocomplete`
+
+An editable text input that filters a listbox of options as the user types; uses `role="combobox"` with `aria-autocomplete`, `aria-expanded`, `aria-controls`, and `aria-activedescendant` while DOM focus stays on the input.
+
+## Use When
+- Use when the option set is large enough that typing to filter or search is faster than scanning a list (e.g., "Country", "City", "Assign to a user").
+- Use when the user narrows the available options by typing (e.g., "Search shows", "Add a tag").
+- Use when free-text entry is allowed alongside suggestions (e.g., a tag field that accepts new values while suggesting existing ones).
+
+## Do Not Use When
+- Do not use when no typing is needed and the set is small or preset (use `select.native`, or for a rich custom-styled picker use `select.basic`).
+- Do not use when the options must be permanently visible with no popup (use `listbox.basic`).
+- Do not use when the control performs actions rather than picking a value (use `menu.basic`).
+- Do not use when the trigger reveals navigation links (use `navigation-menu.dropdown`).
+
+## Must Haves
+
+### Roles & structure
+- Use a native `<input>` element with `role="combobox"` as the editable control.
+- Set `aria-autocomplete="list"` on the input to indicate that typing filters a list of options.
+- Render the popup as an element with `role="listbox"` and a stable ID (the same one referenced by `aria-controls`).
+- Give each option `role="option"`, a stable ID, and `aria-selected="true|false"`.
+
+### Accessible name
+- Provide a visible native `<label>` associated with the input via `for`/`id`.
+
+### State & properties
+- Set `aria-expanded="true|false"` on the input reflecting whether the listbox is displayed.
+- Set `aria-controls="IDREF"` on the input pointing to the listbox element.
+- The listbox is shown/hidden in the DOM (e.g., via the `hidden` attribute), so that when closed, its options cannot be reached by keyboard or screen readers.
+
+### Keyboard
+- Arrow Down moves to the first option, opening the listbox first if it is closed.
+- Arrow Up moves to the last option, opening the listbox first if it is closed.
+- Alt+Arrow Down opens the listbox without moving the active option.
+- When the listbox is open, Arrow Up and Arrow Down move the active option and wrap at the ends.
+- Enter sets the input value to the active option and closes the listbox.
+- Home, End, Left, and Right move the caret within the input text rather than the active option.
+- A printable character returns focus to the input, inserts the character, and filters the listbox to matching options.
+- Do not capture the keys the browser uses for text editing (character keys, caret movement, selection, and deletion).
+
+### Focus
+- Keep DOM focus on the input at all times so native text editing keeps working.
+- Indicate the active option by setting `aria-activedescendant="{optionId}"` on the input, pointing to the currently highlighted option.
+  - When no option is active, remove `aria-activedescendant` (do not point it at a stale or nonexistent ID).
+- Scroll the active option into view via scripting when it changes so it is visible.
+- Ensure a visible focus state (e.g., a 2px solid outline offset by 1-2px) around the input, and a distinct visual highlight on the active option.
+
+### Dismissal
+- Esc closes the listbox if it is open, or clears the input if the listbox is already closed.
+
+## Customizable
+- `aria-autocomplete` may be `"none"`, `"list"` (the default for this pattern), or `"both"`.
+  - With `"both"`, an inline completion string is inserted and selected after the caret; this can be confusing with some screen readers, so test it with assistive technology before shipping.
+- Selection behavior may be manual (the active option is committed only on Enter) or automatic (the first suggestion is pre-selected as the user types). Choose one and test with keyboard and screen readers.
+- An optional trigger button that opens the listbox may be included; give it `tabindex="-1"` so it does not add a stop in the tab order, and keep the input as the accessible combobox.
+- Whether the list filters to matches or auto-selects the first match is at the engineer's discretion, as long as the announced options reflect what is visible.
+
+## Don'ts
+- Do not capture the keys used for text editing (typing, caret movement, selection, deletion); the input must behave as a normal text field.
+- Do not move DOM focus into the options; it breaks native text editing. Track the active option with `aria-activedescendant` instead.
+- Do not use `role="menu"` or `role="menuitem"` for the options; use `role="listbox"` and `role="option"`.
+- Do not forget to scroll the active option into view when it changes.
+- Do not leave the listbox visible while `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 Combobox({ label = "Country", options = COUNTRIES }) {
+  const [query, setQuery] = useState("");
+  const [open, setOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(-1);
+
+  const inputRef = useRef(null);
+  const listRef = useRef(null);
+
+  const baseId = useId();
+  const labelId = `${baseId}-label`;
+  const listboxId = `${baseId}-listbox`;
+  const optionId = (idx) => `${baseId}-opt-${idx}`;
+
+  const matches = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    if (!q) return options;
+    return options.filter((o) => o.toLowerCase().includes(q));
+  }, [query, options]);
+
+  // Keep the active option in view whenever it changes.
+  useEffect(() => {
+    if (!open || activeIndex < 0) return;
+    const el = listRef.current?.querySelector(`#${CSS.escape(optionId(activeIndex))}`);
+    el?.scrollIntoView({ block: "nearest" });
+  }, [open, activeIndex]);
+
+  function openList() {
+    setOpen(true);
+  }
+
+  function closeList() {
+    setOpen(false);
+    setActiveIndex(-1);
+  }
+
+  function commit(idx) {
+    const value = matches[idx];
+    if (value == null) return;
+    setQuery(value);
+    closeList();
+  }
+
+  function onChange(e) {
+    setQuery(e.target.value);
+    setOpen(true);
+    setActiveIndex(-1);
+  }
+
+  function onKeyDown(e) {
+    switch (e.key) {
+      case "ArrowDown":
+        e.preventDefault();
+        if (e.altKey) {
+          openList();
+          break;
+        }
+        // Never move the active option when there is nothing to point at,
+        // or aria-activedescendant would reference a nonexistent option.
+        if (matches.length === 0) {
+          openList();
+          break;
+        }
+        if (!open) {
+          openList();
+          setActiveIndex(0);
+        } else {
+          setActiveIndex((i) => (i + 1) % matches.length);
+        }
+        break;
+      case "ArrowUp":
+        e.preventDefault();
+        if (matches.length === 0) {
+          openList();
+          break;
+        }
+        if (!open) {
+          openList();
+          setActiveIndex(matches.length - 1);
+        } else {
+          setActiveIndex((i) => (i <= 0 ? matches.length - 1 : i - 1));
+        }
+        break;
+      case "Enter":
+        if (open && activeIndex >= 0) {
+          e.preventDefault();
+          commit(activeIndex);
+        }
+        break;
+      case "Escape":
+        if (open) {
+          e.preventDefault();
+          closeList();
+        } else if (query) {
+          setQuery("");
+        }
+        break;
+      // Home, End, ArrowLeft, and ArrowRight are intentionally not handled,
+      // so the browser moves the text caret as usual.
+      default:
+        break;
+    }
+  }
+
+  const listVisible = open && matches.length > 0;
+  const activeDescendant =
+    listVisible && activeIndex >= 0 ? optionId(activeIndex) : undefined;
+
+  return (
+    <div style={{ position: "relative", display: "inline-block" }}>
+      <label id={labelId} htmlFor={`${baseId}-input`} style={{ display: "block" }}>
+        {label}
+      </label>
+
+      <input
+        ref={inputRef}
+        id={`${baseId}-input`}
+        type="text"
+        role="combobox"
+        // Suppress native autofill so it does not overlay the custom listbox.
+        autoComplete="off"
+        aria-autocomplete="list"
+        // Expanded state must track actual listbox visibility, not just intent.
+        aria-expanded={listVisible ? "true" : "false"}
+        aria-controls={listboxId}
+        aria-activedescendant={activeDescendant}
+        value={query}
+        onChange={onChange}
+        onKeyDown={onKeyDown}
+        onFocus={() => query && openList()}
+        onBlur={(e) => {
+          if (!e.currentTarget.parentNode.contains(e.relatedTarget)) closeList();
+        }}
+      />
+
+      <ul
+        ref={listRef}
+        id={listboxId}
+        role="listbox"
+        aria-labelledby={labelId}
+        hidden={!listVisible}
+        style={{
+          position: "absolute",
+          zIndex: 10,
+          left: 0,
+          right: 0,
+          margin: 0,
+          padding: 0,
+          listStyle: "none",
+          maxHeight: 200,
+          overflow: "auto",
+          border: "1px solid GrayText",
+          background: "Canvas",
+        }}
+      >
+        {matches.map((value, idx) => (
+          <li
+            key={value}
+            id={optionId(idx)}
+            role="option"
+            aria-selected={idx === activeIndex ? "true" : "false"}
+            // Keep DOM focus on the input; do not steal it on pointer down.
+            onMouseDown={(e) => e.preventDefault()}
+            onMouseEnter={() => setActiveIndex(idx)}
+            onClick={() => commit(idx)}
+            style={{
+              padding: "6px 8px",
+              outline: idx === activeIndex ? "2px solid Highlight" : "none",
+            }}
+          >
+            {value}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+const COUNTRIES = [
+  "Argentina",
+  "Australia",
+  "Brazil",
+  "Canada",
+  "France",
+  "Germany",
+  "India",
+  "Japan",
+  "Mexico",
+  "Nigeria",
+  "United Kingdom",
+  "United States",
+];
+```
+
+## Acceptance Checks
+
+Keyboard
+- Typing a character filters the listbox to matching options.
+- Arrow Down and Arrow Up move the active option and wrap at the ends.
+- Alt+Arrow Down opens the listbox without moving the active option.
+- Enter sets the input value to the active option and closes the listbox.
+- Esc closes the listbox when open, and clears the input when the listbox is already closed.
+- Home, End, Left, and Right move the text caret and do not move the active option.
+- Text editing (typing, selecting, and deleting) works normally while the listbox is open.
+
+Screen Reader
+- The input is announced as a combobox with its label and expanded/collapsed state (from `role="combobox"` + `aria-expanded`).
+- The listbox and its options are announced as a listbox and options.
+- The currently active option is conveyed as the user navigates (via `aria-activedescendant`).

package/corpus/web/react/components/dialog.modal.md

@@ -0,0 +1,202 @@
+---
+id: dialog.modal
+title: "Dialog (Modal)"
+stack: web/react
+status: beta
+latest_version: 0.3.1
+tags: [dialog, modal, pop-up, overlay, focus-trap, blocking, native-dialog, show-modal]
+aliases: [dialog, modal, pop-up]
+summary: User-initiated blocking dialog. Uses the native <dialog> element with .showModal() so the browser handles focus trap, background inertness, Escape dismissal, focus restoration, and top-layer rendering.
+---
+
+# Dialog (Modal)
+
+Pattern ID: `dialog.modal`
+
+User-initiated blocking dialog. Uses the native `<dialog>` element with `.showModal()` so the browser handles focus trap, background inertness, Escape dismissal, focus restoration, and top-layer rendering. When the native element cannot be used, a manual `<div role="dialog">` fallback is documented under Customizable with the full behavior contract that must be implemented by hand.
+
+## Use When
+- Use when content appears in an overlay that blocks interaction with the underlying page.
+- Use when keyboard focus must move into the dialog and remain contained until dismissal.
+- Use when the user must explicitly complete or dismiss the dialog before returning to the main interface.
+
+## Do Not Use When
+- Do not use when the content is part of the normal page flow and does not block background interaction.
+- Do not use when presenting brief, non-blocking status messages that do not require focus movement (use `toast` or `snackbar`).
+- Do not use when the message is urgent and requires immediate acknowledgment (use `dialog.alert`).
+- Do not use when the interaction involves complex, multi-step workflows spanning multiple screens.
+
+## Must Haves
+- Use the native `<dialog>` element (preferred). When `<dialog>` cannot be used, `<div role="dialog">` is the documented fallback — see Customizable → Manual fallback.
+- **Open with `.showModal()`, close with `.close()`.** A `<dialog>` present in the DOM without `.showModal()` is non-modal — no focus trap, no background inertness, no `aria-modal`, no top-layer rendering. Unmounting a `<dialog>` while open (rather than calling `.close()`) leaves focus stranded because the browser's focus-restoration to the invoker runs on `.close()` (or on the browser's implicit `.close()` from Esc's `cancel` event and from `<form method="dialog">` submits). Both lifecycle endpoints must be exercised.
+- Dialog surface has an accessible name via `aria-labelledby` (preferred) or `aria-label`. If `aria-labelledby` is used, it references a visible title element (e.g., `<h2 id="...">`).
+- If a description is rendered, it is referenced by `aria-describedby`. Do not rely on incidental reading order.
+- Dialog width is fluid so content reflows at 400% zoom (WCAG 1.4.10 Reflow). Prefer `max-width: min(<Npx>, 100%)`; do not set fixed pixel widths that would exceed the 320-CSS-pixel viewport at 400% zoom.
+- Provide a visible close control (`<button type="button">`) with an accessible name (e.g., `aria-label="Close dialog"`).
+- The invoking control declares dialog-trigger semantics — apply `aria-haspopup="dialog"` to the trigger element.
+- The dialog satisfies the following behavior contract (all six required):
+  - Focus moves into the dialog on open.
+  - Focus is trapped within the dialog while open.
+  - Escape closes the dialog.
+  - Focus returns to the invoking element on close.
+  - Background content is not focusable or reachable by keyboard or screen readers while open.
+  - Body scroll is prevented while open.
+- Under native `<dialog>` + `.showModal()` (the Golden Pattern), these six behaviors are provided automatically by the browser. Under the manual `<div role="dialog">` fallback (Customizable → Manual fallback), each is the implementation's responsibility.
+- Focus indicators on the dialog surface, close button, and any focusable content follow the [Foundations focus rule](/web/react/foundations#rule-focus-states).
+
+## Customizable
+- **Manual `<div role="dialog">` fallback** when native `<dialog>` cannot be used (portal / stacking-context conflicts, legacy target matrix). Implement all six behaviors by hand: `aria-modal="true"`, focus trap, `inert` on the app content root (never `body` or `documentElement`), body scroll lock (on iOS Safari use `position: fixed; top: -${scrollY}px`), Escape listener, focus restoration, and render via portal to `document.body`.
+- **Backdrop click closes** by default; may be intentionally disabled for destructive confirmations so users must Cancel or Confirm explicitly.
+- **Initial focus target** — three acceptable defaults:
+  - the dialog surface (`tabIndex={-1}`) — accessible name announces, then Tab to first control (default under `.showModal()`);
+  - a safe-default control (Cancel / Close) for destructive confirmations, to prevent inadvertent Enter-confirm;
+  - the first interactive element for form-shaped dialogs.
+- **`<form method="dialog">`** may be used for zero-JS form dismiss — the submit button's `value` becomes `dialog.returnValue` on the `close` event.
+
+## Don'ts
+- Do not render `<dialog>` without calling `.showModal()` and expect modal behavior. A bare `<dialog>` produces a non-modal reveal with none of the modal contract.
+- Do not implement the manual `<div role="dialog">` fallback without every one of its Must Haves. Partial implementations produce broken screen-reader announcements and stranded focus.
+- Do not rely on `aria-modal="true"` to block background interaction; it is announcement metadata, not an interaction gate. Background isolation is a separate implementation concern.
+- Do not render the manual fallback inside containers that create clipping or stacking contexts (e.g., `overflow: hidden/auto`, `transform`), and do not rely on `z-index` alone to "make it work."
+- Do not inert `document.body` or `document.documentElement` on the manual fallback; inert only the application content root.
+- Do not omit focus restoration; closing a dialog must return the user to the element that invoked it.
+- Do not set fixed pixel widths on the dialog surface that exceed the 320-CSS-pixel viewport at 400% zoom.
+
+## 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 ModalDialog({
+  open,
+  title,
+  description,
+  onClose,
+  children,
+}) {
+  const dialogRef = useRef(null);
+  const titleId = useId();
+
+  // Open / close the native dialog imperatively when `open` changes.
+  // .showModal() is what produces the modal contract: focus trap, background
+  // inertness, Escape dismissal, focus restoration, and top-layer rendering.
+  useEffect(() => {
+    const el = dialogRef.current;
+    if (!el) return;
+    if (open && !el.open) el.showModal();
+    if (!open && el.open) el.close();
+  }, [open]);
+
+  // Route the browser's `cancel` (Escape) and `close` events through onClose
+  // so callers see a single close pathway. preventDefault on `cancel` lets
+  // the effect above handle el.close() for consistency.
+  useEffect(() => {
+    const el = dialogRef.current;
+    if (!el) return;
+    const handleCancel = (e) => {
+      e.preventDefault();
+      onClose();
+    };
+    const handleClose = () => onClose();
+    el.addEventListener("cancel", handleCancel);
+    el.addEventListener("close", handleClose);
+    return () => {
+      el.removeEventListener("cancel", handleCancel);
+      el.removeEventListener("close", handleClose);
+    };
+  }, [onClose]);
+
+  // Backdrop click closes. A click that lands on the <dialog> element itself
+  // (not on a content descendant) is a click on the padding around the
+  // content — treat that as a backdrop dismiss.
+  const handleClick = (e) => {
+    if (e.target === dialogRef.current) onClose();
+  };
+
+  return (
+    <dialog
+      ref={dialogRef}
+      aria-labelledby={titleId}
+      onClick={handleClick}
+      style={{
+        maxWidth: "min(560px, 100%)",
+        border: 0,
+        borderRadius: 12,
+        padding: 16,
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          justifyContent: "space-between",
+          alignItems: "flex-start",
+          gap: 12,
+        }}
+      >
+        <div style={{ minWidth: 0 }}>
+          <h2 id={titleId} style={{ margin: 0 }}>
+            {title}
+          </h2>
+          {description ? (
+            <p style={{ marginTop: 8, marginBottom: 0 }}>{description}</p>
+          ) : null}
+        </div>
+
+        <button
+          type="button"
+          onClick={onClose}
+          aria-label="Close dialog"
+          style={{
+            width: 36,
+            height: 36,
+            borderRadius: 8,
+            border: "1px solid rgba(0,0,0,0.2)",
+            background: "transparent",
+            display: "inline-grid",
+            placeItems: "center",
+            lineHeight: 1,
+            cursor: "pointer",
+            flex: "0 0 auto",
+          }}
+        >
+          <span aria-hidden="true" style={{ fontSize: 18 }}>
+            ×
+          </span>
+        </button>
+      </div>
+
+      <div style={{ marginTop: 16 }}>{children}</div>
+    </dialog>
+  );
+}
+```
+
+## Acceptance Checks
+- On open:
+  - Focus moves into the dialog.
+  - Dialog is announced with its accessible name.
+  - Background content is not reachable by keyboard or screen reader.
+  - Body scroll is prevented.
+
+- While open:
+  - Tab and Shift+Tab remain within the dialog.
+  - Escape closes the dialog.
+  - Clicking the backdrop closes the dialog (unless the pattern has intentionally opted out per Customizable → Backdrop click contract).
+  - Clicking inside the dialog content does not close it.
+  - Focus indicators on all interactive elements follow the Foundations focus rule.
+
+- On close:
+  - Focus returns to the invoking element.
+  - Background content becomes interactive again.
+  - Body scroll is restored.
+
+- Semantics:
+  - Dialog has an accessible name.
+  - Close button has an accessible name.
+  - Under native `<dialog>` + `.showModal()`, the modal state is conveyed by the top-layer/modal contract; under the manual fallback, `aria-modal="true"` is set explicitly.
+  - The invoking control declares dialog-trigger semantics (e.g., `aria-haspopup="dialog"`).
+
+- Reflow:
+  - At 400% browser zoom (~320 CSS pixels wide), dialog content reflows within the viewport without horizontal scrolling.

package/corpus/web/react/components/dialog.nonmodal.md

@@ -0,0 +1,184 @@
+---
+id: dialog.nonmodal
+title: "Dialog (Non-Modal)"
+stack: web/react
+status: beta
+latest_version: 0.1.0
+tags: [dialog, non-modal, overlay, popover, focus-restoration, modeless]
+aliases: [non-modal dialog, modeless dialog, non-blocking dialog, popover dialog, editor popover, composer panel, floating panel]
+summary: A dialog that does not block the page; uses role="dialog" with an accessible name, moves focus in on open and restores it on close, but does not trap focus or inert the background.
+---
+
+# Dialog (Non-Modal)
+
+Pattern ID: `dialog.nonmodal`
+
+A dialog that does not block the page; uses `role="dialog"` with an accessible name, moves focus in on open and restores it on close, but does not trap focus or `inert` the background.
+
+This is the counterpart to `dialog.modal`; the defining contrast is the absence of background isolation and focus trapping.
+
+## Use When
+- Use when an overlay presents content or a task without blocking the page (e.g., a non-blocking editor popover, a composer, a rich panel with interactive controls).
+- Use when the user can keep interacting with the rest of the page while the overlay is open.
+- Use when focus should move into the dialog on open but not be trapped there.
+
+## Do Not Use When
+- Do not use when the user must complete or dismiss the overlay before returning to the page (use `dialog.modal`).
+- Do not use when a control simply shows and hides inline content (use `disclosure.basic`).
+- Do not use when the overlay is a menu of commands (use `menu.basic`).
+- Do not use when the message is a brief, non-interactive status update (use `toast.basic`).
+- Do not use when the content is a plain-text supplementary hint (use `tooltip.basic`).
+
+## Must Haves
+- The dialog surface uses `role="dialog"`, or a native `<dialog>` element shown non-modally (rendered in the DOM or opened with `.show()`, never `.showModal()`).
+- The dialog has an accessible name via `aria-labelledby` (preferred), referencing a visible title element (e.g., `<h2 id="...">`), or `aria-label`.
+- Focus moves into the dialog on open, landing on the dialog container or its first interactive control.
+- Esc closes the dialog, regardless of where focus currently sits, since focus is not trapped and may have moved into the page.
+- Focus is restored to the invoking element on close.
+  - Capture the invoking element at open time, and restore focus with `requestAnimationFrame` after the dialog is unmounted.
+- The dialog does not trap focus. Tab and Shift+Tab move out of the dialog into the rest of the page, which stays interactive.
+- The dialog does not set `aria-modal="true"` and does not apply `inert` to the background.
+- Provide a visible close control. Use a native `<button>` (preferred), or `role="button"` only when a native button cannot be used.
+  - If `role="button"` is used instead of a native `<button>`, add `tabindex="0"` and keyboard support for Enter and Space, ensuring Space prevents page scrolling while activating the control.
+- The close control has an accessible name that describes its purpose or action (e.g., `aria-label="Close"`).
+- Ensure a visible focus state (e.g., a 2px solid outline offset by 1-2px) around the trigger, the close control, and any focusable content within the dialog.
+
+## Customizable
+- Delivery is at the engineer's discretion as long as the non-modal contract above holds. Acceptable options:
+  - A native `<dialog>` element shown non-modally.
+  - The `popover` attribute, which adds light dismiss on outside click and Esc for free.
+  - A `<div role="dialog">` with explicit positioning.
+- Whether an outside click also dismisses the dialog is optional. The `popover` attribute provides it automatically; a `role="dialog"` div may add it via an outside-pointer handler, or omit it.
+- Initial focus may land on the dialog container (`tabindex="-1"`) so the accessible name is announced before the user Tabs to the first control, or on the first interactive control when the user's next action is to type or select. Either is acceptable.
+
+## Don'ts
+- Do not set `aria-modal="true"` on a non-modal dialog; it falsely tells assistive technology the background is inert.
+- Do not trap focus within the dialog.
+- Do not apply `inert` to, or otherwise block, the background content.
+- Do not omit focus restoration; closing the dialog must return focus to the element that invoked it.
+- Do not bind Esc only to a container-level handler on the dialog surface; once focus leaves the untrapped dialog, that handler stops firing and Esc no longer closes.
+
+## 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 NonModalDialog() {
+  const [open, setOpen] = useState(false);
+  const openerRef = useRef(null);
+  const dialogRef = useRef(null);
+  const titleId = useId();
+
+  const openDialog = () => {
+    // Capture the opener at the moment we open, so focus can be restored on close.
+    openerRef.current = document.activeElement;
+    setOpen(true);
+  };
+
+  const closeDialog = () => {
+    setOpen(false);
+    // Defer until the dialog has unmounted and the opener is focusable again.
+    const opener = openerRef.current;
+    requestAnimationFrame(() => opener?.focus());
+  };
+
+  // Move focus into the dialog on open. No focus trap: Tab leaves the dialog
+  // into the rest of the page, which stays interactive (no inert, no aria-modal).
+  useEffect(() => {
+    if (open) dialogRef.current?.focus();
+  }, [open]);
+
+  // Esc must close from anywhere, because focus is not trapped and may sit in
+  // the page. A container-level onKeyDown would miss those keystrokes, so bind
+  // Esc at the document level while open.
+  useEffect(() => {
+    if (!open) return;
+    const onKeyDown = (e) => {
+      if (e.key === "Escape") closeDialog();
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [open]);
+
+  return (
+    <div>
+      <button type="button" onClick={openDialog}>
+        Edit note
+      </button>
+
+      {/* The rest of the page stays interactive while the dialog is open. */}
+      <button
+        type="button"
+        onClick={() => alert("Background control still works")}
+      >
+        Background action
+      </button>
+
+      {open
+        ? createPortal(
+            <div
+              ref={dialogRef}
+              role="dialog"
+              aria-labelledby={titleId}
+              tabIndex={-1}
+              style={{
+                position: "fixed",
+                top: 80,
+                right: 24,
+                width: "min(360px, 100%)",
+                border: "1px solid rgba(0,0,0,0.3)",
+                borderRadius: 12,
+                padding: 16,
+              }}
+            >
+              <div
+                style={{
+                  display: "flex",
+                  justifyContent: "space-between",
+                  gap: 12,
+                }}
+              >
+                <h2 id={titleId} style={{ margin: 0 }}>
+                  Edit note
+                </h2>
+                <button type="button" onClick={closeDialog} aria-label="Close">
+                  <span aria-hidden="true">×</span>
+                </button>
+              </div>
+
+              <label>
+                Note
+                <textarea defaultValue={DEFAULT_NOTES[0]} rows={4} />
+              </label>
+
+              <button type="button" onClick={closeDialog}>
+                Save
+              </button>
+            </div>,
+            document.body
+          )
+        : null}
+    </div>
+  );
+}
+
+const DEFAULT_NOTES = [
+  "Reminder: finish the S2 finale review before it leaves the service on Friday.",
+];
+```
+
+## Acceptance Checks
+- On open:
+  - Focus moves into the dialog.
+  - The dialog is announced with its accessible name.
+  - Background content remains reachable and interactive.
+
+- While open:
+  - Esc closes the dialog, including when focus has moved out of the dialog into the page.
+  - Tab and Shift+Tab move focus out of the dialog into the page, confirming focus is not trapped.
+  - The trigger, the close control, and any focusable content within the dialog show a visible focus indicator (e.g., a 2px solid outline) when focused.
+
+- On close:
+  - Focus returns to the invoking element.