Chapter 3: Accessibility
Core Idea
Base UI handles the complex accessibility mechanics internally (ARIA/role attributes, pointer interactions, keyboard navigation, focus management), but visual focus indication, color contrast, and accessible labelling remain the developer's responsibility.
Key Concepts
- Keyboard navigation: components follow WAI-ARIA Authoring Practices — arrow keys, alphanumeric keys,
Home/End/Enter/Esc are supported out of the box where applicable.
- Focus management: automatic after interactions; some components expose
initialFocus/finalFocus props to configure where focus lands and returns to. Base UI manages that focus moves — the developer must still style :focus/:focus-visible so the movement is visible (see WCAG focus-appearance guidance).
- Color contrast: not automated — the developer must meet contrast minimums between foreground/background; APCA (apcacontrast.com) is suggested as a stricter modern alternative to WCAG 2 contrast ratios.
- Accessible labels: Form/Input/Field/Fieldset auto-associate labels with controls; for custom controls without a native
<label>, use alt, aria-label, or aria-labelledby per WAI-ARIA naming rules.
- Testing surface: Base UI is tested across a broad matrix of browsers, devices, platforms, and screen readers.
Key Takeaways
- Never assume "accessible component" means "accessible page" — focus styling, contrast, and labelling are still on you even though focus movement and ARIA wiring are not.
- Use
initialFocus/finalFocus (available on focus-trapping components like Dialog/AlertDialog) instead of manually managing ref.focus() calls when the default focus target is wrong.
- Prefer the Form/Field/Fieldset/Input family (ch023–ch026) over ad-hoc
<label> + custom input wiring — it gets label association and error-message association right by construction.
Connects To
- ch021 (Dialog) / ch012 (Alert Dialog):
initialFocus/finalFocus and focus-trap behavior in practice.
- ch023 (Field) / ch025 (Form): automatic label/error association.
- ch047 (Tooltip): keyboard-triggerable accessible hint pattern.