Semantics and roles: the accessibility tree does not see your divs

What a button gives you that a div never will

When React commits <button>Save</button>, the browser derives a second tree from the DOM: the accessibility tree, the one screen readers, voice control, and switch devices actually consume. The button node arrives in that tree fully equipped: an implicit role of button, an accessible name computed from its content (“Save”), membership in the sequential focus order, activation on both Enter and Space, correct announcement (“Save, button”), and a visible focus indicator. A div with an onClick arrives as a nameless generic node — present as text geometry, invisible as a control. Voice-control users cannot say “click Save” at it; switch users cannot reach it; keyboard users Tab straight past it.

Rebuilding parity by hand means five obligations at every call site: role="button", tabIndex of 0, an onKeyDown that activates on Enter and on Space (and prevents Space from scrolling the page), disabled semantics via aria-disabled plus actually blocking the handler, and a focus style. Each is individually forgettable, none produces a visible bug for mouse users, and the failure is silent until an audit. This is the first rule of ARIA from the spec authors themselves: if a native element with the semantics you need exists, use it instead of repurposing another element and bolting ARIA on. The corollary is blunter and equally official: no ARIA is better than bad ARIA — role="button" without the keyboard handling is a promise to assistive tech that the element then breaks, which is worse than staying a humble div.

The React-specific angle: JSX adds zero semantics. React renders exactly the elements you wrote, and components hide the element choice — a Button primitive that renders a div ships that decision to every consumer invisibly. Element choice is therefore an API-design decision in a component library, not a per-page styling detail, and it is the cheapest accessibility decision you will ever make: the platform has already implemented and AT-tested the behavior.

The accessible name is computed, not guessed

“What does the screen reader call this thing?” has a deterministic answer: the accessible name and description computation, a W3C algorithm that walks a strict precedence ladder per element. Knowing the ladder turns name bugs from folklore into arithmetic. For a given element: aria-labelledby wins if present and non-empty — it collects the referenced elements’ text, in id order, even from hidden nodes. Otherwise aria-label wins — a flat string that replaces content entirely. Otherwise the host language takes over: an associated label element for form controls, alt for images. Otherwise, for roles that allow name from content (button, link, heading — not div, not generic), the subtree text becomes the name. Last resort: title, and for inputs placeholder — both weak, both effectively a lint warning.

Three traps the ladder explains. First: aria-label on a plain div does nothing reliable — generic roles are not name-bearing, so AT may ignore it entirely; the attribute is not a magic caption, it is input to an algorithm that consults the role. Second: because aria-label replaces content, an icon button with visible text “Search” and aria-label="magnifier" is announced as “magnifier” — and a voice-control user saying “click Search” misses, which is why WCAG requires the visible label to appear in the accessible name. Third: aria-labelledby beats everything including itself being weird — it concatenates multiple ids, includes its own element if self-referenced, and reads display:none targets; powerful for composing names (“Delete” + row title), but a stale id reference fails silently to an empty string and the algorithm falls through to the next rung, changing the announcement without any console warning.

Landmarks and headings are how people navigate

Screen-reader users do not read pages top to bottom; they jump. In WebAIM’s screen-reader user surveys, navigating by headings is consistently the dominant strategy for finding content on a page, with landmarks as the structural complement. That makes the heading outline and the landmark map a primary navigation surface — equal in rank to your visible nav bar. Native sectioning elements ship landmark roles implicitly: header is banner, nav is navigation, main is main, footer is contentinfo. The rules of the surface: exactly one main; label repeated landmarks (aria-label="Primary" on one nav, “Breadcrumbs” on the other — here aria-label is legitimate because nav is a role that names); headings form a real outline — one h1, no level skipping, levels chosen by structure, never by font size. The WebAIM Million data shows how rare this discipline is in the wild: large fractions of home pages lack any landmarks or have broken heading orders, which means a well-structured app is a genuine competitive accessibility feature, not table stakes.

React adds two structural habits. Fragments exist so that “I need a single JSX root” never costs a wrapper div: every needless div is another generic node fattening the accessibility tree, and inside semantic structures it is destructive — a component that wraps its li in a div breaks the required ul-to-li parent chain, and some AT then stops announcing “list, 5 items”. Use Fragment (or key-ed fragments in lists) and keep semantic parent-child chains intact across component boundaries — the DOM does not know your component tree exists, only its output. Second, dangerouslySetInnerHTML forfeits every structural guarantee: injected markup bypasses JSX, so eslint-plugin-jsx-a11y never sees it, heading levels inside CMS-supplied HTML jump arbitrarily, and images arrive without alt. If you must inject (rendered markdown, CMS content), sanitize and audit the output against the same rules, because your tooling just went blind in that subtree.