Fields’ help text and errors should be associated with input

[Thibaud Colas]

With Django’s default field rendering, all field errors are rendered as a list above the field’s label, and help text is rendered after the field’s form element. Example with as_p:

<ul class="errorlist">
  <li>This field is required.</li>
</ul>
<p>
  <label for="id_duration_required">Duration required:</label>
  <input type="text" name="duration_required" required="" id="id_duration_required">
  <span class="helptext">Help</span>
</p>

One problem for screen reader users is that the association between the errors and the field, and between the help text and the field, is only communicated visually. This is a failure of either WCAG 2.1 level A ​SC 1.3.1: Info and Relationships, or ​SC 3.3.2: Labels or Instructions. More importantly, it just makes it harder than necessary for screen reader users to make use of help text, and to identify error messages.

The fix is relatively straightforward – using aria-describedby, as documented in the (non-normative) ​ARIA1 Using the aria-describedby property to provide a descriptive label for user interface controls technique. Here is another well-known accessibility-oriented UI library that implements this technique: ​GOV.UK design system – text input with error message.

Here is what implementing aria-describedby would look like in the same example as above:

<div class="errorlist" id="id_duration_required_errorlist">
  <p>This field is required.</p>
</div>
<p>
  <label for="id_duration_required">Duration required:</label>
  <input type="text" name="duration_required" required="" id="id_duration_required" aria-describedby="id_duration_required_errorlist id_duration_required_helptext">
  <span class="helptext" id="id_duration_required_helptext">Help</span>
</p>

We have additional id attributes, aria-describedby, and errorlist is no longer a <ul>. Result in VoiceOver:

Unfortunately I tried to have this with the errorlist kept as a ul, but it wasn’t announced by VoiceOver. I haven’t heard of this limitation before so am not sure why that might be the case – I’d appreciate others taking a look if possible.

[Thibaud Colas]

Screen recording of the VoiceOver text-to-speech output, announcing the field label, then error message, then help text.

[Mariusz Felisiak]

Thanks. Ideally, we should avoid changing <ul> to <div>. Maybe <ul> could be wrapped by <div>.

[Hasan Ramezani]

I created a draft ​PR.

@Mariusz, Could you please check it and let me know if I choose the right direction to fix the problem? If so, I can continue with test adjustment.
@Thibaud, It would be great if you can if it will produce your desired output.

[Jacob Walls]

​PR

[Mariusz Felisiak]

​PR

[Natalia Bidart]

Note that the PR focuses on solving this issue for help_text.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 966ecdd4:

Fixed #32819 -- Established relationship between form fields and their help text.

Thanks Nimra for the initial patch.

Thanks Natalia Bidart, Thibaud Colas, David Smith, and Mariusz Felisiak
for reviews.

[David Smith]

Reopening as the errors case still requires fixing.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 292f1ea9:

Refs #32819 -- Used auto_id instead of id_for_label as unique identifier for the field.

id_for_label is blank for widgets with multiple inputs such as radios
and multiple checkboxes. Therefore , help_text for fields using these
widgets cannot currently be associated using aria-describedby.
id_for_label is being used as a guard to avoid incorrectly adding
aria-describedby to those widgets.

This change uses auto_id as the unique identified for the fields
help_text. A guard is added to avoid incorrectly adding
aria-describedby to inputs by checking the widget's use_fieldset
attribute. Fields rendered in a <fieldset> should have
aria-describedby added to the <fieldset> and not every <input>.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 7f0275d8:

[5.0.x] Refs #32819 -- Used auto_id instead of id_for_label as unique identifier for the field.

id_for_label is blank for widgets with multiple inputs such as radios
and multiple checkboxes. Therefore , help_text for fields using these
widgets cannot currently be associated using aria-describedby.
id_for_label is being used as a guard to avoid incorrectly adding
aria-describedby to those widgets.

This change uses auto_id as the unique identified for the fields
help_text. A guard is added to avoid incorrectly adding
aria-describedby to inputs by checking the widget's use_fieldset
attribute. Fields rendered in a <fieldset> should have
aria-describedby added to the <fieldset> and not every <input>.

Backport of 292f1ea90f90ff140617299a25884c8fda24aa64 from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In 557fa51:

Refs #32819 -- Added aria-describedby test for widgets with custom id.

[Mariusz Felisiak <felisiak.mariusz@…>]

In eec7e9ba:

Refs #32819 -- Established relationship between form fieldsets and their help text.

This adds aria-describedby for widgets rendered in a fieldset such as
radios. aria-describedby for these widgets is added to the <fieldset>
element rather than each <input>.

[Natalia Bidart]

Setting as patch needs improvement because the docs for when a custom aria-describedby is given definitely needs more details/clarification about what the user should do to properly customize the attribute for help text and errors.

[David Smith]

​PR to avoid adding aria-describedby to hidden inputs.

[Sarah Boyce <42296566+sarahboyce@…>]

In c187f5f9:

Refs #32819 -- Avoided adding 'aria-describedby' to hidden inputs.

Hidden elements are not visible for both accessibility tools and browsers presentation layer. This change therefore only reduces the size of the generated HTML.

[David Smith]

​PR to add an id to ErrorList

[Sarah Boyce <42296566+sarahboyce@…>]

In edd74c34:

Refs #32819 -- Added id to ErrorList class and template.

[Thibaud Colas]

Amazing! One step closer to fully accessible forms 😌

[Sarah Boyce <42296566+sarahboyce@…>]

In 1e05431:

Refs #32819 -- Added aria-describedby property to BoundField.

[Sarah Boyce <42296566+sarahboyce@…>]

In 987854ba:

Fixed #32819 -- Added aria-describedby to fields with errors.