--- title: "Accessible patterns (paste-ready) (a11y)" description: "React 19 + Tailwind v4 with void tokens (bg-surface-raised, text-fg, border-line, outline-line-focus…)." canonical: https://void-design.vercel.app/docs/a11y/patterns lastModified: 2026-09-16 --- # Accessible patterns (paste-ready) React 19 + Tailwind v4 with void tokens (`bg-surface-raised`, `text-fg`, `border-line`, `outline-line-focus`…). Each pattern follows the WAI-ARIA Authoring Practices keyboard model. **Prefer a primitive library (Radix, Base UI, React Aria) for menus, comboboxes, selects and date pickers.** These snippets are for zero-dependency cases and for understanding what a primitive must do. Contents: 1 utilities · 2 skip link · 3 icon button · 4 disclosure (details, nav menu) · 5 dialog · 6 tabs · 7 actions menu · 8 toast / live region · 9 form field · 10 checklist per widget ## 1. Utilities ```css /* globals.css: Tailwind v4 ships sr-only / not-sr-only; these are for non-Tailwind stacks */ .sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0; } @layer base { :where(a, button, input, select, textarea, summary, [tabindex]):focus-visible { outline: 2px solid var(--line-focus); outline-offset: 2px; } html:has(dialog:modal) { overflow: hidden; } /* scroll lock while a modal is open */ html { scrollbar-gutter: stable; } /* no layout shift when scroll locks */ @media (prefers-reduced-motion: reduce) { *, *::before, *::after { transition-duration: 1ms !important; animation-duration: 1ms !important; animation-delay: 0ms !important; } } } ``` ## 2. Skip link ```tsx // first child of Skip to content // …
{children}
``` ## 3. Icon button (name is type-required) ```tsx import type { ButtonHTMLAttributes, ReactNode } from "react"; type IconButtonProps = Omit, "aria-label" | "children"> & { label: string; // required: becomes the accessible name icon: ReactNode; // e.g. }; export function IconButton({ label, icon, className = "", type = "button", ...rest }: IconButtonProps) { return ( ); } ``` `size-9` (36px) plus a `-inset-1` pseudo-element gives a 44px hit area; `pointer-coarse:` widens it further on touch. Tooltips supplement the label, they don't replace it. ## 4. Disclosure ### 4a. Zero-JS: `
` ```tsx
{/* same name = only one open at a time */} How much does Acme cost?
Free for open source. Team is $12 per seat per month.
``` Key facts that search and AI should read: render them `open` or as plain sections (see the `seo` skill). ### 4b. Mobile navigation menu (disclosure, not `role="menu"`) Site navigation is a list of links behind a toggle. **Don't** use `role="menu"` for it (menu roles are for app-style action menus). ```tsx "use client"; import Link from "next/link"; import { usePathname } from "next/navigation"; import { useEffect, useId, useRef, useState } from "react"; export function MobileNav({ links }: { links: { href: string; label: string }[] }) { const [open, setOpen] = useState(false); const id = useId(); const pathname = usePathname(); const button = useRef(null); useEffect(() => setOpen(false), [pathname]); // close on navigation useEffect(() => { if (!open) return; const onKey = (e: KeyboardEvent) => { if (e.key === "Escape") { setOpen(false); button.current?.focus(); } }; document.addEventListener("keydown", onKey); return () => document.removeEventListener("keydown", onKey); }, [open]); return ( ); } ``` The desktop nav renders the same links as a plain visible list. Don't ship two full copies of a large nav; hide with CSS breakpoints on one list where possible. ## 5. Modal dialog (native ``) `showModal()` makes the rest of the page inert, traps Tab inside, closes on Esc (`cancel` event), focuses the first focusable element (or `initialFocus`), and returns focus to the opener on close. Support: all browsers since 2022. `closedby="any"` (light dismiss) is Chromium 134+ and Firefox 141+ only, so the component below handles backdrop clicks itself. ```tsx "use client"; import { useEffect, useId, useRef, type ReactNode, type RefObject } from "react"; type ModalProps = { open: boolean; onClose: () => void; // parent sets open=false title: string; description?: string; initialFocus?: RefObject; // e.g. the least destructive button children: ReactNode; }; export function Modal({ open, onClose, title, description, initialFocus, children }: ModalProps) { const ref = useRef(null); const downOnBackdrop = useRef(false); const titleId = useId(); const descId = useId(); useEffect(() => { const d = ref.current; if (!d) return; if (open && !d.open) { d.showModal(); initialFocus?.current?.focus(); } if (!open && d.open) d.close(); }, [open, initialFocus]); return ( { downOnBackdrop.current = e.target === e.currentTarget; }} onClick={(e) => { if (downOnBackdrop.current && e.target === e.currentTarget) ref.current?.close(); }} // backdrop click className="m-auto w-[min(32rem,calc(100vw-2rem))] rounded-xl border border-line bg-surface-raised p-0 text-fg shadow-3 backdrop:bg-black/50" >
{/* fills the dialog so clicks inside never hit the backdrop test */}

{title}

{description &&

{description}

}
{children}
 ); } ``` ```tsx // usage const [open, setOpen] = useState(false); const cancelRef = useRef(null); setOpen(false)} title="Delete project?" description="This removes 12 deployments. You can't undo it."> ``` Rules: - The title is required (`aria-labelledby`). Destructive dialogs initially focus Cancel. - Portal isn't needed: `showModal()` renders in the top layer above everything, including `transform` ancestors. - Entry animation with `@starting-style` (see `speed/references/rendering-smoothness.md` §6). No animation under reduced motion. - Drawers and sheets: the same element, positioned at an edge (`m-0 ml-auto h-dvh max-h-none`). - Non-modal overlays (tooltips, simple link popovers): use the `popover` attribute instead of `show()`. Zero-JS open with invoker commands (Baseline newly available, Safari 26.2+; keep the React version for older browsers): ```html

Delete project?

 ``` ## 6. Tabs (roving tabindex, automatic activation) ```tsx "use client"; import { useId, useRef, useState, type KeyboardEvent, type ReactNode } from "react"; type TabItem = { id: string; label: string; panel: ReactNode }; export function Tabs({ items, label, defaultId }: { items: TabItem[]; label: string; defaultId?: string }) { const base = useId(); const [active, setActive] = useState(defaultId ?? items[0]?.id); const tabs = useRef<(HTMLButtonElement | null)[]>([]); function onKeyDown(e: KeyboardEvent, i: number) { const last = items.length - 1; const next = e.key === "ArrowRight" ? (i === last ? 0 : i + 1) : e.key === "ArrowLeft" ? (i === 0 ? last : i - 1) : e.key === "Home" ? 0 : e.key === "End" ? last : -1; if (next === -1) return; e.preventDefault(); setActive(items[next].id); tabs.current[next]?.focus(); } return (
{items.map((t, i) => { const selected = t.id === active; return ( ); })}
{items.map((t) => ( ))}
); } ``` - Tab moves into the tablist, arrow keys move between tabs, and Tab again moves into the panel. - Don't animate tab switches triggered by the keyboard. - If the tab state should survive reload or sharing, put it in the URL (`?tab=`). - Content in hidden panels is still in the HTML but hidden. Don't put the page's key facts only in non-default tabs. ## 7. Actions menu (menu button) For app-style action lists ("Rename, Duplicate, Delete"). Use Radix `DropdownMenu` / Base UI `Menu` / React Aria `Menu` when you also need submenus, typeahead, checkbox items or collision-aware positioning. ```tsx "use client"; import { useEffect, useId, useRef, useState, type KeyboardEvent } from "react"; type Item = { label: string; onSelect: () => void; destructive?: boolean }; export function ActionsMenu({ label, items }: { label: string; items: Item[] }) { const [open, setOpen] = useState(false); const id = useId(); const root = useRef(null); const trigger = useRef(null); const refs = useRef<(HTMLButtonElement | null)[]>([]); const focusAt = (i: number) => refs.current[(i + items.length) % items.length]?.focus(); const openAt = (i: number) => { setOpen(true); requestAnimationFrame(() => focusAt(i)); }; const close = (restore = true) => { setOpen(false); if (restore) trigger.current?.focus(); }; useEffect(() => { if (!open) return; const onPointerDown = (e: PointerEvent) => { if (!root.current?.contains(e.target as Node)) setOpen(false); }; document.addEventListener("pointerdown", onPointerDown); return () => document.removeEventListener("pointerdown", onPointerDown); }, [open]); function onTriggerKey(e: KeyboardEvent) { if (e.key === "ArrowDown" || e.key === "Enter" || e.key === " ") { e.preventDefault(); openAt(0); } if (e.key === "ArrowUp") { e.preventDefault(); openAt(items.length - 1); } } function onItemKey(e: KeyboardEvent, i: number) { const map: Record void> = { ArrowDown: () => focusAt(i + 1), ArrowUp: () => focusAt(i - 1), Home: () => focusAt(0), End: () => focusAt(items.length - 1), Escape: () => close(), Tab: () => close(false), }; const fn = map[e.key]; if (!fn) return; if (e.key !== "Tab") e.preventDefault(); fn(); } return (
); } ``` - Menu items get `tabIndex={-1}` and are reached with arrows. Focus shows as a background highlight (`focus:bg-surface-hover`), which must reach ≥ 3:1 against the menu surface or be paired with a ring. - Right-click context menus appear instantly, with no animation. ## 8. Toasts and live regions Recommended: `sonner` (~9.4 KB gzip), mounted once in the root layout, wired to tokens: ```tsx // app/layout.tsx import { Toaster } from "sonner"; // anywhere in a client component import { toast } from "sonner"; toast.success("Project renamed"); toast.error("Couldn't save. Check your connection and try again."); ``` Zero-dependency version. The regions exist from first render and only their text changes: ```tsx "use client"; import { createContext, useCallback, useContext, useState, type ReactNode } from "react"; type Toast = { id: number; text: string; kind: "status" | "alert" }; const Ctx = createContext<(text: string, kind?: Toast["kind"]) => void>(() => {}); export const useToast = () => useContext(Ctx); export function ToastProvider({ children }: { children: ReactNode }) { const [toasts, setToasts] = useState([]); const dismiss = (id: number) => setToasts((t) => t.filter((x) => x.id !== id)); const notify = useCallback((text: string, kind: Toast["kind"] = "status") => { const id = Date.now() + Math.random(); setToasts((t) => [...t, { id, text, kind }]); if (kind === "status") setTimeout(() => dismiss(id), 6000); // errors stay until dismissed }, []); const list = (kind: Toast["kind"]) => toasts.filter((t) => t.kind === kind).map((t) => (

{t.text}

)); return ( {children}
{list("status")}
{list("alert")}
 ); } ``` - Toasts are for the results of mutations, never for navigation or selection. - Position them `fixed` so they don't cause layout shift. Keep them visible ≥ 6 s, and errors until dismissed. Never put the only copy of important information in a toast. - An action inside a toast (Undo) must also be reachable another way, or the toast persists until handled. ## 9. Form field with error ```tsx "use client"; import { useId } from "react"; export function EmailField({ error }: { error?: string }) { const id = useId(); const errId = `${id}-error`; const hintId = `${id}-hint`; return (

We'll send the invite here.

{error &&

⚠ {error}

}
); } ``` On submit with errors: `form.querySelector("[aria-invalid=true]")?.focus()`. Server Actions: return field errors and render them the same way. `useActionState` keeps the typed values. ## 10. Checklist per widget | Widget | Role / element | Keyboard | State attributes | |---|---|---|---| | Button | `