Cross-system reference

How to read this guide

Column key

Status markers

Open UI status labels

Actions

Accessibility notes

• Button — Implicit role="button". Activate with Enter or Space. For toggle buttons, add aria-pressed. Screen readers announce "button" automatically for <button> elements; avoid <div> with role="button" when possible.
• Toggle — Use aria-pressed="true|false" to convey state. Screen readers announce "pressed" / "not pressed". For icon-only toggles, provide aria-label.
• Toggle Group — Use a radio group when the user must choose exactly one option (see Forms below). Native radios provide one tab stop for the group, arrow-key navigation, and the "X of Y" screen-reader announcement. When users may clear the selection or choose several options, put <button aria-pressed> elements inside a container with role="group" and aria-label, and implement keyboard navigation for the group. Do not put buttons with aria-pressed inside role="radiogroup". Radio groups require options with role="radio" and aria-checked; using the wrong roles prevents screen readers from announcing the selected state.
• Segmented button — Follow the accessibility requirements for a radio group. The section below explains its appearance.
• Link — Implicit role="link" on <a href>. Activate with Enter (not Space). Link text must be descriptive — screen readers list links out of context. Avoid "click here".

Segmented button — what the other systems do

A segmented button (Apple: segmented control; IBM Carbon: content switcher) is a linear row of two-to-five mutually exclusive options that reads as one control. Every system builds it out of the same parts and differs mainly in how the selected segment is painted — this is the evidence behind data-look="segmented" in Radio group, drawn from each system's own spec.

What every system agrees on, and what this library therefore does:

• One shared container plus dividers — the row must read as a single control, not as adjacent buttons. Ours draws the frame and the dividers from the segments' own borders (a <legend> cuts a hole in a border set on the <fieldset>).
• Equal segment widths — a grid of 1fr columns here, which sizes every segment to the widest one's content and cannot wrap.
• The selected segment is filled, and not in the primary-action colour. A picker painted in the app's call-to-action colour reads as a pair of buttons; ours uses a --brand tint, the token-set equivalent of Material's Secondary container.
• Selection is not carried by colour alone — Material's checkmark is the second channel, and this library draws the same check, replacing the segment's own icon so the row never changes width when the selection moves.
• Two to five options, each with a short noun label. More than five is a select; a set that switches whole sections of an app is Tabs (Apple: "for switching between completely separate sections of an app, use a tab bar instead"; Carbon: tabs are for "navigating between distinct content areas like subpages").
• Multi-select segmented buttons exist (Material's second variant), and they are not this row — that is the Toggle Group row above, because zero-or-many cannot be expressed by radios.

Forms

Accessibility notes

• Checkbox — Implicit role from <input type="checkbox">. Space toggles. For mixed/indeterminate state, set aria-checked="mixed". Always pair with <label>. Screen readers announce "checkbox, checked/not checked".
• Radio Group — Wrap in <fieldset> and declare role="radiogroup" (a bare fieldset is role="group", and radios inside do not upgrade it); name it with a <legend> or aria-label. Arrow keys move between options and select — selection follows focus, which is what separates a radio group from a listbox. Only the selected radio is in the tab order (roving tabindex), so the group is one Tab stop. Home/End do nothing here, unlike in a listbox or toolbar. Screen readers announce group label + "radio button, X of Y". Hiding the radio to paint a custom look is fine with opacity, never with display: none — see Radio group § Accessibility.
• Switch — Use role="switch" on a checkbox. Screen readers announce "switch, on/off" (JAWS) or "toggle, checked" (NVDA). Visually distinguish from checkbox to avoid confusion.
• Select — role="listbox" on the popup, role="option" on items. Arrow keys navigate, Enter/Space select, Escape closes. Type-ahead search expected. aria-activedescendant or roving tabindex for focus.
• Combobox — role="combobox" on the input, aria-expanded, aria-controls pointing to listbox, aria-activedescendant for virtual focus. Arrow keys navigate suggestions, Escape clears/closes.
• Slider — role="slider" implicit on <input type="range">. aria-valuemin, aria-valuemax, aria-valuenow, optional aria-valuetext for human-readable value. Arrow keys adjust value. For multi-thumb, see Slider (Multi-Thumb).
• Calendar — Date pickers combine grid navigation (Arrow keys move days, Page Up/Down for months) with spinbutton semantics. Native <input type="date"> provides built-in a11y. Custom implementations must follow the grid pattern with proper role="grid" and announce date changes.

Navigation

Accessibility notes

• Tabs — role="tablist" on container, role="tab" on each tab, role="tabpanel" on panels. Arrow keys move between tabs. aria-selected="true" on active tab. Only active tab in tab order (tabindex="0"), others tabindex="-1". JAWS/NVDA announce "tab, 1 of N, selected".
• Breadcrumb — Wrap in <nav aria-label="Breadcrumb">. Use <ol> for ordered list semantics. Current page gets aria-current="page". Screen readers announce the navigation landmark and list structure.
• Navigation — Use <nav> with a descriptive aria-label (e.g., "Main navigation"). Multiple <nav> elements on a page must have distinct labels. Screen readers list navigation landmarks.
• Menubar — role="menubar" with role="menuitem" children. Arrow Left/Right moves between top-level items, Up/Down opens submenus. Complex pattern — only use for app-style menubars, not site navigation.
• Toolbar — role="toolbar" on container with aria-label. Arrow Left/Right moves between tools (roving tabindex). Tab moves in/out of the toolbar as a single tab stop. Group related controls with aria-label on the toolbar.
• Pagination — Wrap in <nav aria-label="Pagination">. Current page gets aria-current="page". Use <a> or <button> for page links, not <span>.

Overlays

Accessibility notes

• Dialog (Modal) — role="dialog" implicit on <dialog>. Must have aria-labelledby (heading) or aria-label. Focus moves into dialog on open, trapped inside. Escape closes. On close, focus returns to the trigger element. JAWS announces "dialog, [title]" on open.
• Alert Dialog — role="alertdialog". Same as dialog but announces urgently. Focus must move to the least destructive action button (e.g., "Cancel"). Cannot be dismissed by clicking backdrop — requires explicit user action.
• Response Dialog — Replaces window.prompt(). Uses standard role="dialog" by default — a form input is not an urgent interruption — and takes alertdialog: true for a destructive confirmation, which uses role="alertdialog" and autofocus on Cancel (Dialog § 11). The caller supplies the body (typically a <form>); a first focusable element with autofocus lets the user type immediately. Form fields must have associated <label> elements (or aria-label). Escape, backdrop, [x], and Cancel all dismiss (return null). Returns a promise resolving to FormData from the first <form> in the body on confirm, or null on cancel. See response_dialog() in lib/dialog.mjs.
• Popover — Non-modal: no focus trap, page remains interactive. Use role="dialog" if interactive, or no special role for simple info panels. Close on Escape and light-dismiss (click outside). Manage focus: move to popover on open, return to trigger on close.
• Tooltip — role="tooltip" on the popup element. Connect via aria-describedby on the trigger. Show on mouseenter/focusin, hide on mouseleave/focusout/Escape. Must not contain interactive content. JAWS reads tooltip text as part of the element's description.
• Context Menu / Dropdown Menu — role="menu" on container, role="menuitem" on items. Arrow Up/Down navigates items, Enter activates, Escape closes. Type-ahead jumps to matching items. Context menus have two openers: right-click (at the pointer) and Shift+F10 / the Menu key (anchored to the focused element). A pointer-only context menu is unreachable for a keyboard or screen-reader user.
• Toast — Use <output> with role="status" (polite) for info, role="alert" (assertive) for errors. Do not move focus to toasts. Auto-dismiss after ~4–6s. Must be pausable on hover for WCAG 2.2.2 (Pause, Stop, Hide). Stack multiple toasts visually.
• Drawer / Sheet — Same a11y requirements as Dialog. Slide-in animation must respect prefers-reduced-motion. JAWS/NVDA treat it as a modal dialog.

Feedback

Accessibility notes

• Callout — A tinted remark about the element beside it, read in document order. It carries no ARIA role: role="alert" would announce it on every re-render of the surrounding view, and the message is already visible next to its subject. Colour reinforces the message and never carries it alone. A message about the page belongs in the Status Bar or a toast instead.
• Notification List — Persistent list of warning items opened from a trigger button. Button has aria-haspopup="dialog" + aria-expanded and its aria-label includes the current item count so JAWS/NVDA announce "Warnings, 2" on focus. The visual count badge is aria-hidden. The popover panel has role="dialog" + aria-label; the inner list has explicit role="list" (preserves semantics when list-style: none is applied); each item has role="listitem" and decorative icons are aria-hidden. Use toast() for transient announcements — a notification list is for persistent state.
• Status Bar — Persistent visible projection of the top active notification. The inner live region carries role="status" (implicit aria-live="polite" + aria-atomic="true"), so changes are announced politely without stealing focus — MDN names "status bars" as the canonical use case for the role. The role lives on the inner region, not the host, so the count badge wrapper isn't pulled into the announcement via aria-atomic. The expand button (visible only when there's more than one active item) has an aria-label from the host's label attribute; the count badge and decorative icons are aria-hidden. Roles set at construction — never flipped at runtime — so SR live-region behavior stays reliable. Errors that need an assertive announcement are routed through toast(), not via a runtime role swap. References: WCAG 2.2 §4.1.3 Status Messages, Technique ARIA22.

Disclosure

Accessibility notes

• Accordion — Native <details name="group"> provides exclusive accordion behavior (Baseline 2024). <summary> is the trigger — implicit role="button", activates with Enter/Space. Screen readers announce "expanded/collapsed", so don't add aria-expanded to a native <summary> (it fights the native state). The accordion() decorator (public/ui/lib/accordion.mjs) wraps each panel in a role="region" labelled by its summary (aria-labelledby) and wires aria-controls; per APG, regions are dropped past ~6 panels ({ region: false }).
• Collapsible — <details> / <summary> provides built-in disclosure semantics; the styled .ui-disclosure works with zero JS. Screen readers announce "expanded/collapsed". accordion() adds the panel region/labelledby wiring, exclusive name, and lazy load() (polite live region + aria-busy, error reverts the open). The chevron is a decorative CSS ::before; the open animation (::details-content + interpolate-size) is a progressive enhancement disabled under prefers-reduced-motion.
• Tree View — implemented as the tree() decorator (public/ui/lib/tree.mjs), which progressively enhances a nested <ul>/<li>: role="tree"/treeitem/group, aria-level/aria-setsize/aria-posinset, roving tabindex, Up/Down between visible rows, Right expands / enters children, Left collapses / moves to parent, aria-expanded on parent nodes, single-select via aria-selected, plus optional lazy children via a load() promise (announced through a live region). No other system in the row above offers a tree primitive, so the APG pattern is the only reference for it.

Content

Accessibility notes

• Card — Use <article> for self-contained content (screen readers list articles). If the entire card is clickable, the click target must be the inner <a> or <button>, not the card wrapper — otherwise screen readers announce the entire card text as the link label.
• Table — Use role="table" (implicit on <table>) for static data; use role="grid" for interactive tables with cell-level focus. <caption> or aria-label for table name. <th scope="col|row"> for headers. Screen readers announce row/column position when navigating.
• Badge — Decorative badges need no special markup. Status badges (e.g., "new", "3 unread") should be announced — use aria-label on the parent or include visually-hidden text.
• Icon — Decorative icons: aria-hidden="true". Meaningful icons: provide aria-label or visually-hidden text. Icon buttons must always have an accessible name.
• Progress — <progress> has implicit role="progressbar". Add aria-label for context (e.g., "Upload progress"). For indeterminate progress, omit the value attribute. JAWS/NVDA announce percentage.
• Meter — <meter> has implicit role. Use aria-label for context. low, high, optimum attributes convey thresholds. Screen reader support varies — consider adding visible text alongside.
• Carousel — role="region" with aria-label and aria-roledescription="carousel". Slides: role="group" with aria-roledescription="slide" and aria-label="N of M". Auto-rotation must have a pause button (WCAG 2.2.2). Prev/Next buttons must be keyboard accessible.
• Skeleton — Use aria-busy="true" on the container while loading. Use aria-hidden="true" on skeleton placeholders. When content loads, remove aria-busy so screen readers re-announce the region.

Layout

Accessibility notes

• Scroll Area — Custom scrollbar styling is cosmetic. Ensure keyboard scrollability with tabindex="0" if the area is not focusable by default. Screen readers handle scroll containers natively.
• Grid (layout) — CSS Grid is a layout tool, not a data grid. No ARIA roles needed for CSS Grid layout. The APG Grid pattern is for interactive data grids, not page layout.
• Landmarks — Use semantic HTML elements: <header> = role="banner", <nav> = role="navigation", <main> = role="main", <footer> = role="contentinfo", <aside> = role="complementary". Multiple instances of <nav> or <aside> need distinct aria-label values.
• Resizable — role="separator" with aria-valuenow (panel size as percentage). Arrow keys resize. aria-label describes what is being resized (e.g., "Resize sidebar").
• Navigation rail — a toolbar of disclosure buttons, not a tablist: every view may be closed, and a disclosure button can close its own view where a selected tab cannot. Each button carries aria-expanded + aria-controls, a constant visually hidden name, and the rail is one Tab stop with Up/Down and Home/End. Opening leaves focus on the button; the rail is never inert. Buttons are 48 × 48 CSS px (WCAG 2.5.8 / 2.5.5), the icon and open marker clear 3:1 (1.4.11), and the open state survives forced colors as an outline.
• Side panel (collapsible) — the handle is a real <button> with aria-expanded + aria-controls (Disclosure), and its accessible name stays constant across states — aria-expanded is what conveys the state. A collapsed panel's contents get inert so Tab skips them, marked on the children rather than the panel: inert is inherited with no way to opt back in, so applying it to the panel would also disable the handle and prevent reopening. Non-modal — focus is never trapped and Escape dismisses nothing.

Further reading

Standards and specifications

• Open UI — Component standardization initiative
• WAI-ARIA Authoring Practices (APG) — Accessibility patterns per component
• WCAG 2.2 — Web Content Accessibility Guidelines
• HTML Living Standard — Native element specifications
• MDN Web Components — Web Components reference

Component libraries

• Material Web — Google's web components (Lit-based)
• Radix UI Primitives — Unstyled React primitives
• Bootstrap 5.3 — CSS framework with JS components

Design systems (the specs, not the code)

Consulted where a pattern's look carries meaning and the APG says nothing about it — the segmented-button section above is built from these.

• Material Design 3 — per-component Guidelines, Specs (dp values + colour roles) and Accessibility pages; the "M3 Expressive" notes say which components have been superseded
• Apple Human Interface Guidelines — best practices per control, and the per-platform differences
• IBM Carbon — usage pages that draw the boundaries between neighbouring patterns (tabs vs content switcher vs toggle)

Accessibility testing

• JAWS — Most-used screen reader (Windows)
• NVDA — Free screen reader (Windows)
• VoiceOver — Built-in screen reader (macOS/iOS)
• axe DevTools — Automated accessibility testing

See also

• Components — the demos, grouped by role.
• Accessibility — the a11y baseline these notes serve.
• Conventions — tag prefixes, event tiers, private props.