a11y(frontend): select outline, CardTitle polymorphic as prop, cheatsheet labels

src/components/KeyboardCheatsheet/KeyboardCheatsheet.test.tsx

@@ -267,4 +267,86 @@ describe("KeyboardCheatsheet", () => {
 
     unmount();
   });
+
+  it("test_dialog_is_aria_labelledby_visible_heading", async () => {
+    // The DialogContent must carry an aria-labelledby pointing at
+    // the visible <h2> so screen readers announce "Keyboard, dialog"
+    // instead of leaving the modal unlabeled (Radix logs a warning
+    // otherwise). The id referenced must also resolve to a real
+    // element with that id inside the cheatsheet.
+    const onClose = vi.fn();
+    const { unmount } = renderIntoContainer(
+      <KeyboardCheatsheet open={true} onClose={onClose} />
+    );
+
+    const body = await settle((b) =>
+      b.querySelector('[data-testid="keyboard-cheatsheet"]') !== null
+    );
+
+    const sheet = body.querySelector(
+      '[data-testid="keyboard-cheatsheet"]'
+    ) as HTMLElement | null;
+    expect(sheet).not.toBeNull();
+
+    // The Radix DialogContent exposes its labelledby on the panel
+    // element itself. We accept either the dialog content id (which
+    // is the data-testid) or its first role-bearing descendant —
+    // depending on which element Radix attaches aria-labelledby to.
+    const labelledBy =
+      sheet?.getAttribute("aria-labelledby") ??
+      sheet
+        ?.querySelector("[aria-labelledby]")
+        ?.getAttribute("aria-labelledby") ??
+      null;
+    expect(labelledBy).not.toBeNull();
+    expect(labelledBy).toBe("keyboard-cheatsheet-title");
+
+    // And the id must point at a real element whose text content is
+    // the visible "Keyboard" heading — closing the loop between the
+    // a11y wiring and the visible UI.
+    const titleEl = body.querySelector("#keyboard-cheatsheet-title");
+    expect(titleEl).not.toBeNull();
+    expect(titleEl?.textContent).toBe("Keyboard");
+
+    unmount();
+  });
+
+  it("test_close_button_has_specific_aria_label_and_describedby", async () => {
+    // The cheatsheet renders an explicit close button (the shared
+    // DialogContent X in the corner has a generic "Close dialog"
+    // label that's out of scope here). The cheatsheet-specific one
+    // must:
+    //  - be findable by its cheatsheet-specific aria-label, and
+    //  - carry aria-describedby pointing back at the visible heading
+    //    so screen-reader users hear "Close keyboard cheatsheet,
+    //    Keyboard, button".
+    const onClose = vi.fn();
+    const { unmount } = renderIntoContainer(
+      <KeyboardCheatsheet open={true} onClose={onClose} />
+    );
+
+    const body = await settle((b) =>
+      b.querySelector('[data-testid="keyboard-cheatsheet"]') !== null
+    );
+
+    const closeBtn = body.querySelector(
+      '[aria-label="Close keyboard cheatsheet"]'
+    ) as HTMLButtonElement | null;
+    expect(closeBtn).not.toBeNull();
+
+    // The describedby wires the close button back to the title so
+    // the screen-reader announcement has context.
+    expect(closeBtn?.getAttribute("aria-describedby")).toBe(
+      "keyboard-cheatsheet-title"
+    );
+
+    // Clicking the close button must invoke the consumer's onClose.
+    expect(onClose).not.toHaveBeenCalled();
+    act(() => {
+      closeBtn?.click();
+    });
+    expect(onClose).toHaveBeenCalledTimes(1);
+
+    unmount();
+  });
 });

src/components/KeyboardCheatsheet/KeyboardCheatsheet.tsx

@@ -1,5 +1,5 @@
 import { useEffect } from "react";
-import { Keyboard } from "lucide-react";
+import { Keyboard, X } from "lucide-react";
 import { Dialog, DialogContent } from "@/components/ui/dialog";
 
 type KeyboardCheatsheetProps = {
@@ -20,6 +20,14 @@ const SHORTCUTS = [
   { keys: ["?"], description: "Toggle this help" },
 ] as const;
 
+/**
+ * Stable id used to wire the dialog's `aria-labelledby` and the close
+ * button's `aria-describedby` to the visible `<h2>` heading. Exposed
+ * as a constant so tests can assert against the same string the
+ * component renders.
+ */
+const CHEATSHEET_TITLE_ID = "keyboard-cheatsheet-title";
+
 /**
  * Keyboard help overlay (SP4).
  *
@@ -78,19 +86,52 @@ export function KeyboardCheatsheet({ open, onClose }: KeyboardCheatsheetProps) {
         // `left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2`).
         // We narrow it to max-w-md and apply the modern palette so
         // it sits on the same surface as the rest of SP4.
+        //
+        // a11y wiring:
+        //  - `aria-labelledby` points at the visible <h2> below so
+        //    screen readers announce "Keyboard, dialog" instead of an
+        //    unlabeled region (Radix logs a warning otherwise).
+        //  - `aria-describedby={undefined}` suppresses Radix's
+        //    missing-description warning; the cheatsheet's content
+        //    (key list + helper text) is its own description.
         className="max-w-md bg-[color:var(--m-surface)] text-[color:var(--m-ink-primary)] border border-[color:var(--m-border-heavy)]/20"
+        aria-labelledby={CHEATSHEET_TITLE_ID}
         aria-describedby={undefined}
         data-testid="keyboard-cheatsheet"
       >
-        <header className="flex items-center gap-2 mb-3">
-          <Keyboard
-            className="h-4 w-4 text-[color:var(--m-ink-secondary)]"
-            strokeWidth={1.75}
-            aria-hidden
-          />
-          <h2 className="text-[10.5px] font-semibold uppercase tracking-[0.18em] text-[color:var(--m-ink-tertiary)]">
-            Keyboard
-          </h2>
+        <header className="flex items-center justify-between gap-2 mb-3 pr-10">
+          <div className="flex items-center gap-2">
+            <Keyboard
+              className="h-4 w-4 text-[color:var(--m-ink-secondary)]"
+              strokeWidth={1.75}
+              aria-hidden
+            />
+            <h2
+              id={CHEATSHEET_TITLE_ID}
+              className="text-[10.5px] font-semibold uppercase tracking-[0.18em] text-[color:var(--m-ink-tertiary)]"
+            >
+              Keyboard
+            </h2>
+          </div>
+          {/*
+            Explicit close button with a cheatsheet-specific label.
+            The shared DialogContent primitive renders its own X in
+            the top-right corner with a generic "Close dialog" label
+            (out of scope here), so this one carries the specific
+            aria-label and an aria-describedby pointer back to the
+            heading for screen-reader context. `pr-10` on the header
+            keeps the visible title text clear of the primitive's
+            absolute-positioned X in the corner.
+          */}
+          <button
+            type="button"
+            aria-label="Close keyboard cheatsheet"
+            aria-describedby={CHEATSHEET_TITLE_ID}
+            onClick={onClose}
+            className="rounded-md p-1 text-[color:var(--m-ink-secondary)] opacity-70 transition-opacity hover:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+          >
+            <X className="h-4 w-4" aria-hidden />
+          </button>
         </header>
 
         <ul className="flex flex-col gap-2.5">