accessibility

10 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Interactive elements must be keyboard-focusable

All interactive page elements should be reachable by keyboard. Add tabIndex={0} to all buttons, links, and non-text inputs, ideally at the component level. Consider tying the state of tabIndex to the disabled state of a component, if applicable.

Focus ring utilities for keyboard navigation

Use focus-ring utility for buttons, inputs, and most controls (offset ring). Use focus-inset utility for dense or flush surfaces such as interactive table rows (inset outline). focus-ring expands to: outline-hidden, focus-visible:ring-2, focus-visible:ring-ring, focus-visible:ring-offset-2, focus-visible:ring-offset-background. focus-inset uses outline (not ring) for reliable painting on interactive <tr> elements.

Focus indicator best practices

Prefer :focus-visible over :focus so click/tap does not show a focus indicator. Never use outline-none or outline-hidden without a ring or outline replacement. Always use the shared color (ring-ring or outline-ring). Do not animate the focus indicator; avoid transition-all or transition on controls that show one. Do not put focus-ring or raw ring-* on a <tr>, and do not add outline-hidden alongside focus-inset.

Interactive table row keyboard handling example

Example of bespoke interactive table row requiring manual accessibility props: <TableRow key={id} className="relative cursor-pointer h-16 focus-inset" onClick={(event) => { if (event.currentTarget !== event.target) return; handleBucketNavigation(bucket.id, event) }} onKeyDown={(event) => { if (event.currentTarget !== event.target) return; if (event.key === 'Enter' || event.key === ' ') { event.preventDefault(); handleBucketNavigation(bucket.id, event) } }} tabIndex={0}><TableCell>{name}</TableCell></TableRow>

Radio group keyboard navigation

Radio button groups should behave as a single control. Only the first item of radio groups should become focused with the Tab key. Individual options inside a group can be reached by arrow keys (↑ ↓ ← →). Space is the canonical key to activate radio options, with Enter being a secondary affordance.

Image alt text should describe content objectively

Images should have their contents described with an alt attribute. Write an objective description of the content rather than its context. Example correct: "A tricolor beagle galloping through a grassy field, ears in the air". Example incorrect: "Our logo".

Use aria-label for icons and visual elements

Icons and other visual elements that aren't strictly images should use the aria-label attribute to describe their purpose.

aria-hidden for purely visual elements

Visual elements that are purely visual aids may be removed from the accessibility tree via the aria-hidden attribute. Never use aria-hidden={true} on focusable elements, since these are critical pieces of functionality.

Use sr-only for scaffolding elements without visual labels

Scaffolding elements that only make sense visually (e.g., a table column for actions without a visual label) should be titled with sr-only text so screen reader users understand their purpose.

Skip links for keyboard navigation in long content

Apps with persistent header and sidebar chrome should expose a skip link as the first focusable element. Use the shared Skip to Content fragment which owns the component API, usage sample, and target landmark contract.

Give your agent this brain