Accessibility Improvement: Screen-Reader Error Identification in Forms

Release: v1.0.445
Control: A11Y-20
Category: Forms & Inputs

Overview

Validation error messages in the platform's core forms are now fully wired to their associated input fields using the ARIA attributes aria-invalid and aria-describedby. This change ensures that screen-reader users receive clear, programmatic feedback when a form field fails validation — without relying solely on visual cues.

What Changed

Previously, when a user submitted a form with invalid data, error messages were displayed visually but the corresponding <input> elements carried no attributes that screen readers could act on. A keyboard or screen-reader user tabbing back to a flagged field would hear only the field label, with no indication that an error existed or what it said.

As of v1.0.445, each errored input now:

1. Sets aria-invalid="true" — signals to assistive technology that the field is in an error state.
2. Sets aria-describedby="<error-id>" — links the input to the element containing the error message text.
3. The error message element carries role="alert" — causes the message to be announced immediately when it appears in the DOM.

Affected Forms

Form	File
Sign-in	src/components/auth/credentials-sign-in-form.tsx
Sign-up	src/components/auth/credentials-sign-up-form.tsx
Profile settings	ProfileForm
Organisation settings	OrgSettingsForm
Feedback widget	FeedbackWidget

Attribute Pattern

All five forms follow this consistent pattern for form-level validation errors:

<input
  id="signin-email"
  type="email"
  aria-invalid={!!error}
  aria-describedby={error ? 'signin-error' : undefined}
  // ...other props
/>
{error && (
  <div id="signin-error" role="alert" className="...">
    {error}
  </div>
)}

• aria-invalid is set dynamically: true when an error is present, absent (not false) when the field is clean, avoiding unnecessary noise for screen readers on valid fields.
• aria-describedby is only set when an error element exists, keeping the accessibility tree clean during normal (non-error) states.
• role="alert" on the error container triggers an immediate live-region announcement when the error message renders.

Impact

• Screen-reader users tabbing back to an errored field will now hear the field label followed by the error description, giving them full context to correct their input.
• Keyboard-only users benefit from the same improvements, as ARIA attributes are read by any assistive technology that inspects the accessibility tree.
• No visual or behavioural changes — form layout, submission logic, and error message copy are unchanged.

Future Work

The current implementation handles form-level errors (a single error message per form). Field-level error association (individual error messages per input, each linked to its specific field) is noted as a planned future addition that will build on this foundation.