Building Accessible Web Forms That Pass a Real Audit
A healthcare client needed a patient intake form to pass a third-party accessibility audit tied to a compliance requirement, and we went in assuming our existing eslint-plugin-jsx-a11y setup had us mostly covered. It hadn't. Automated tooling caught missing alt text and obvious label mismatches, but the audit — done with an actual screen reader by someone who uses one daily — flagged issues no linter would ever catch, like error messages that appeared visually next to a field but weren't announced when the field failed validation.
The fix there was wiring aria-describedby from each input to its error message container, and making sure the error text actually existed in the DOM before the association pointed to it — React's render order meant we were sometimes setting aria-describedby to point at an element that hadn't mounted yet. We also switched from onBlur validation, which fires silently for screen reader users navigating by tab, to validating on submit with focus moved explicitly to the first invalid field.
Grouping mattered more than we expected. A shipping address section with five separate inputs read as five disconnected fields to a screen reader without a fieldset and legend wrapping them, giving no sense that they belonged together. Wrapping related inputs in fieldset/legend pairs, even ones that look visually identical to a plain div, gave real structural context.
Keyboard-only navigation surfaced a bug we'd never have caught by eye: a custom multi-select dropdown built with divs and onClick handlers had no keyboard path to open it at all. We rebuilt it on top of a native select for the base case and used Radix's accessible primitives for the styled version, rather than continuing to hand-roll ARIA behavior for a widget that already has solved patterns.
The form passed the second audit with zero critical issues. The bigger takeaway for us was that automated tools are a floor, not a ceiling — they'll tell you an image is missing alt text, but they won't tell you that your error handling is invisible to the people it's meant to help.
