@a11y-context/mcp-server 0.1.0

package/corpus/web/react/components/switch.basic.md

@@ -0,0 +1,151 @@
+---
+id: switch.basic
+title: Switch
+stack: web/react
+status: beta
+latest_version: 0.3.0
+tags: [switch, form, settings, on-off, form-control, toggle]
+aliases: [toggle switch, preference toggle]
+summary: Two-state on/off control representing a persistent setting. Uses role="switch" with aria-checked, or native checkbox semantics when applicable.
+---
+
+# Switch
+
+Pattern ID: `switch.basic`
+
+Two-state on/off control representing a persistent setting. Uses `role="switch"` with `aria-checked`, or native checkbox semantics when applicable.
+
+## Use When
+- Use when a control represents a persistent binary setting that remains on or off beyond the current interaction (e.g., "Enable notifications", "Dark mode").
+- Use when the setting takes effect immediately when toggled, without requiring form submission.
+- Use when the control reflects the current state of a system or application preference.
+
+## Do Not Use When
+- Do not use when the control triggers an in-place action or transient feature toggle within the current context (use `button.toggle`).
+- Do not use when the choice is a value submitted with a form rather than a setting that takes effect immediately (use `checkbox.basic`).
+- Do not use when selecting one or more options from a set of related choices (use `checkbox.group`).
+- Do not use when more than two states are required (use `button.toggle`).
+
+## Must Haves
+- The switch has `role="switch"`.
+- The switch has an associated visible text label.
+- The switch has an accessible name that describes its action. Often this is worded to be true when the switch is set to "on" (e.g., "Enable notifications").
+- The accessible name is equivalent to the visible text label.
+- When additional context is needed beyond the visible text, add it via `aria-label`, `aria-labelledby`, or offscreen text (i.e., `.sr-only`). The visible text appears at the start of the accessible name.
+- When on, the switch has `aria-checked="true"`. When off, the switch has `aria-checked="false"`.
+  - If the switch is implemented as `input[type="checkbox"]`, use the native `checked` attribute instead of `aria-checked`.
+- The switch must be focusable:
+  - Native input (i.e., `input[type="checkbox"]`) is focusable by default.
+  - Non-native elements must include `tabIndex="0"`.
+- Keyboard:
+  - Tab/Shift+Tab moves focus to the switch.
+  - Space toggles the switch.
+  - Enter toggles the switch.
+    - Exception: If using native input `input[type="checkbox"]`, then only Space toggles the switch, not Enter.
+- If multiple switches are presented as a labeled set:
+  - Use `fieldset` with `legend`, or
+  - Wrap in `role="group"` with `aria-labelledby`.
+- If additional descriptive static text is relevant to a switch or switch group, associate it using `aria-describedby`.
+- Ensure a visible focus state (e.g., a 2px solid outline offset by 1-2px) around the switch control.
+
+## Customizable
+- The base element: `<div role="switch">` (as in the golden pattern), `<button role="switch">`, or `<input type="checkbox" role="switch">`. Native elements reduce the keyboard and focus wiring that must be hand-rolled.
+  - A native HTML switch control (`<input type="checkbox" switch>`) is emerging in browsers (WebKit ships an implementation) and may become the preferred base once support is broad.
+- Whether the visual design resembles a sliding switch.
+- Whether the accessible name is contained within the switch or referenced externally.
+- Whether state text ("On"/"Off") is visually displayed.
+- Whether multiple switches may be grouped.
+
+## Don'ts
+- Do not use a switch for non-setting actions.
+- Do not omit `aria-checked` when using `div` or `button` with `role="switch"`.
+- Do not use both `checked` and `aria-checked` on `input[type="checkbox"]`.
+- Do not use a switch to trigger actions; use it only for persistent on/off settings.
+
+## 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 SwitchDemo() {
+  const [notifications, setNotifications] = useState(false);
+
+  function toggle() {
+    setNotifications((v) => !v);
+  }
+
+  return (
+    <div>
+      {/* 
+        This example uses a <div>.
+        The same pattern may also be implemented using:
+        - <button role="switch">, or
+        - <input type="checkbox" role="switch">
+      */}
+
+      <div
+        role="switch"
+        aria-checked={notifications ? "true" : "false"}
+        tabIndex={0}
+        aria-labelledby="sw-label"
+        onClick={toggle}
+        onKeyDown={(e) => {
+          if (e.key === " " || e.key === "Enter") {
+            e.preventDefault();
+            toggle();
+          }
+        }}
+      >
+        <span id="sw-label">Notifications</span>
+        <span aria-hidden="true">
+          {notifications ? "On" : "Off"}
+        </span>
+      </div>
+
+      <fieldset>
+        <legend>Playback Settings</legend>
+        <p id="playback-desc">
+          These settings apply to all videos.
+        </p>
+
+        <div
+          role="switch"
+          aria-checked="true"
+          tabIndex={0}
+          aria-labelledby="autoplay-label"
+          aria-describedby="playback-desc"
+        >
+          <span id="autoplay-label">Autoplay</span>
+          <span aria-hidden="true">On</span>
+        </div>
+
+        <div
+          role="switch"
+          aria-checked="false"
+          tabIndex={0}
+          aria-labelledby="captions-label"
+          aria-describedby="playback-desc"
+        >
+          <span id="captions-label">Always show captions</span>
+          <span aria-hidden="true">Off</span>
+        </div>
+      </fieldset>
+    </div>
+  );
+}
+```
+
+## Acceptance Checks
+
+- Keyboard
+  - Tab moves focus to each switch.
+  - Space toggles state.
+  - Enter toggles state.
+  - Focus remains on the switch after toggling.
+- Screen Reader
+  - Switch is announced with its accessible name and role ("switch").
+  - State is announced correctly as on/off.
+  - Group label is announced when using `fieldset/legend` or `role="group"`.
+  - Additional descriptive text is announced when associated via `aria-describedby`.

package/corpus/web/react/components/toast.basic.md

@@ -0,0 +1,112 @@
+---
+id: toast.basic
+title: Toast
+stack: web/react
+status: beta
+latest_version: 0.1.0
+tags: [toast, notification, status, live-region]
+aliases: [notification, toast, transient message, status message]
+summary: Temporary, non-blocking status message announced via live region. May include optional dismiss control. Disappears automatically.
+---
+
+# Toast
+
+Pattern ID: `toast.basic`
+
+Temporary, non-blocking status message announced via live region. May include optional dismiss control. Disappears automatically.
+
+## Use When
+
+- Use when presenting a temporary, non-blocking status message.
+- Use when the message confirms an action (e.g., "Saved", "Added to watchlist").
+- Use when the message is text-only and contains no required actions, except for (at most) a dismiss button.
+
+## Do Not Use When
+- Do not use when the message requires user acknowledgment, moves keyboard focus, or blocks background interaction (use `dialog`).
+- Do not use when the message is urgent or must interrupt the user immediately (use `dialog.alert`).
+- Do not use when the message includes required actions or interactive controls beyond simple dismissal (use `snackbar`).
+
+## Must Haves
+
+- The live region container must be present in the DOM when the page/view loads.
+- The toast message must be announced via `role="status"`, or an equivalent such as `aria-live="polite"` and `aria-atomic="true"`.
+- When a toast is triggered, its message text must be injected into the existing live region container.
+- The toast must not move focus automatically when it appears.
+- The toast must disappear automatically (recommended ~5 seconds).
+- The live region text must be cleared when the toast dismisses to avoid stale messages being discovered later.
+- If a dismiss button is present, it must not steal focus when the toast appears.
+
+## Customizable
+
+- Visual placement (top-right, bottom-center, etc.).
+- Duration (within reasonable non-disruptive bounds).
+- Whether a dismiss button is included.
+- Styling (color, elevation, animation).
+
+## Don'ts
+
+- Do not mount/unmount the live region container based on toast visibility.
+- Do not move focus into the toast when it appears.
+- Do not use `role="alertdialog"`.
+- The toast must not contain buttons or elements that require user action (use `snackbar` or `dialog` instead).
+
+## Golden Pattern
+
+Structural reference for AI coding assistants — semantics, focus, and keyboard behavior. Styling, copy, and demo data are illustrative.
+
+```jsx
+"use client";
+
+const ToastContext = createContext(() => {});
+
+export function ToastProvider({ children }) {
+  const [message, setMessage] = useState("");
+  const timeoutRef = useRef(null);
+
+  const showToast = useCallback((text) => {
+    if (timeoutRef.current) window.clearTimeout(timeoutRef.current);
+    setMessage(text);
+    timeoutRef.current = window.setTimeout(() => setMessage(""), 5000);
+  }, []);
+
+  return (
+    <ToastContext.Provider value={showToast}>
+      {children}
+
+      {/* Live region is always mounted */}
+      <div role="status" aria-atomic="true">
+        {message}
+      </div>
+    </ToastContext.Provider>
+  );
+}
+
+export function useToast() {
+  return useContext(ToastContext);
+}
+
+/** Demo */
+export function ToastDemo() {
+  const toast = useToast();
+
+  return (
+    <div>
+      <button type="button" onClick={() => toast("Saved successfully.")}>
+        Save
+      </button>
+    </div>
+  );
+}
+```
+
+## Acceptance Checks
+
+- Keyboard
+  - Trigger a toast via keyboard.
+  - Focus remains on the triggering control.
+  - No focus is moved into the toast.
+- Screen Reader
+  - When triggered, the message is announced once as a polite status update.
+  - The message is not announced repeatedly.
+  - After the toast auto-dismisses, the live region is cleared (stale text is not discoverable later).
+  - Triggering a new toast replaces the previous announcement.

package/corpus/web/react/components/tooltip.basic.md

@@ -0,0 +1,139 @@
+---
+id: tooltip.basic
+title: Tooltip
+stack: web/react
+status: beta
+latest_version: 0.1.0
+tags: [tooltip, aria-describedby, hover, focus, supplementary-label]
+aliases: [tooltip, hint, help bubble, info bubble, hover text, popup label, title text, describedby]
+summary: A brief supplementary text label shown on hover and focus of its trigger; uses role="tooltip" referenced by aria-describedby, and is hoverable, dismissible, and persistent.
+---
+
+# Tooltip
+
+Pattern ID: `tooltip.basic`
+
+A brief supplementary text label shown on hover and focus of its trigger; uses `role="tooltip"` referenced by `aria-describedby`, and is hoverable, dismissible, and persistent.
+
+## Use When
+
+- Use when a brief plain-text label supplements a control (e.g., clarifying an icon-only button, a short hint on a form field).
+- Use when the content is non-essential supplementary text.
+- Use when the label should appear on both pointer hover and keyboard focus of the trigger.
+
+## Do Not Use When
+
+- Do not use when the content is interactive or rich, containing links or buttons (use `dialog.nonmodal`).
+- Do not use when the content is a status or confirmation message (use `toast.basic`).
+- Do not use when the label would be the control's only accessible name; give the control a real accessible name via a visible label or `aria-label` instead (use `button.basic`).
+- Do not use when the content is a menu of choices (use `menu.basic`).
+
+## Must Haves
+
+- The tooltip bubble is an element with `role="tooltip"` and a stable `id`.
+- The trigger references the tooltip with `aria-describedby` pointing to the tooltip's `id`.
+  - The tooltip supplements the accessible name, it does not replace it. The trigger has its own accessible name (e.g., visible text or `aria-label`).
+- The tooltip appears on both pointer hover and keyboard focus of the trigger.
+- Esc dismisses the tooltip whether it was opened by pointer hover or by keyboard focus, and does not move pointer hover or keyboard focus (dismissible).
+  - Bind the Esc handler at the document level, not only on the trigger, so it works when the tooltip is shown by hover and the trigger does not hold focus.
+  - When the trigger has keyboard focus, the trigger keeps focus after dismissal.
+- The tooltip remains visible while the pointer is over the trigger or over the tooltip, and while the trigger has focus (hoverable and persistent).
+  - Track hover and focus as independent conditions and keep the tooltip open while either is active, so a stray pointer movement does not hide it while the trigger still has keyboard focus.
+- The tooltip is not focusable and contains plain text only, with no interactive content.
+- Ensure a visible focus state (e.g., a 2px solid outline offset by 1-2px) around the trigger.
+
+## Customizable
+
+- `aria-describedby` associates the tooltip as a supplementary description. When the tooltip text is intended to be the control's accessible name (rare), `aria-labelledby` may be used instead of `aria-describedby`.
+- Positioning relative to the trigger and an optional show delay are at the engineer's discretion, as long as the tooltip remains hoverable, dismissible, and persistent.
+- The tooltip may be delivered via scripting or via the native `popover` attribute.
+
+## Don'ts
+
+- Do not place interactive content (links, buttons, form controls) in a tooltip.
+- Do not rely on the native `title` attribute as the tooltip; it is not keyboard-accessible and is announced inconsistently.
+- Do not make the tooltip vanish when the pointer moves from the trigger toward the tooltip; it must be hoverable.
+- Do not show the tooltip on hover only; it must also appear on keyboard focus.
+- Do not hide the tooltip on `onMouseLeave` while the trigger still has keyboard focus; hover and focus must be tracked independently.
+- Do not use `role="menu"` on the tooltip.
+- Do not leave the tooltip visible after the trigger has lost focus and the pointer has left both the trigger and the tooltip.
+
+## 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 TooltipDemo() {
+  // Hover and focus are tracked as independent conditions. The tooltip stays
+  // open while either is active (persistent), so a stray pointer movement
+  // cannot hide it while the trigger still holds keyboard focus.
+  const [hovered, setHovered] = useState(false);
+  const [focused, setFocused] = useState(false);
+  const open = hovered || focused;
+  const tooltipId = "tooltip-watchlist";
+
+  // Dismissible (WCAG 1.4.13): Esc closes the tooltip without moving pointer
+  // hover or keyboard focus. The listener is on the document, not the trigger,
+  // because a hover-only tooltip has no focused element to receive the keydown.
+  useEffect(() => {
+    if (!open) return;
+    const onKeyDown = (e) => {
+      if (e.key === "Escape") {
+        setHovered(false);
+        setFocused(false);
+      }
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [open]);
+
+  return (
+    // Wrapping the trigger and the bubble in one hover region keeps the tooltip
+    // open while the pointer moves from the trigger onto the bubble (hoverable).
+    <span
+      style={{ position: "relative", display: "inline-block" }}
+      onMouseEnter={() => setHovered(true)}
+      onMouseLeave={() => setHovered(false)}
+    >
+      {/* The trigger carries its own accessible name; the tooltip only supplements it. */}
+      <button
+        type="button"
+        aria-label="Add to watchlist"
+        aria-describedby={tooltipId}
+        onFocus={() => setFocused(true)}
+        onBlur={() => setFocused(false)}
+        onClick={() => alert("Added to watchlist")}
+      >
+        <span aria-hidden="true">[icon]</span>
+      </button>
+
+      {/* Plain-text bubble, not focusable, referenced by aria-describedby. */}
+      {open && (
+        <span
+          role="tooltip"
+          id={tooltipId}
+          style={{ position: "absolute", top: "100%", left: 0 }}
+        >
+          Adds this title to your watchlist.
+        </span>
+      )}
+    </span>
+  );
+}
+```
+
+## Acceptance Checks
+
+- Keyboard
+  - A visible focus indicator is present on the trigger when reached by keyboard.
+  - Focusing the trigger shows the tooltip.
+  - Esc dismisses the tooltip while focus stays on the trigger.
+  - A stray pointer movement over and off the trigger does not hide the tooltip while the trigger still has focus.
+- Pointer
+  - Hovering the trigger shows the tooltip.
+  - The pointer can move onto the tooltip without dismissing it.
+  - Pressing Esc while the tooltip is shown by hover dismisses it without moving the pointer.
+- Screen Reader
+  - The tooltip text is announced as the trigger's description via `aria-describedby`.