Skip to content

Remove the 'supplemental' pattern if a block is specified #445

@frankieroberto

Description

@frankieroberto

Currently, if you pass a block to a govuk_text_field (or other field helpers), an additional <div> element will get created between the label/legend and the input itself. This will be associated with the input using aria-describedby in the same way that a hint would be, however the text will appear in regular black rather than dark grey.

This means that this code:

<%= f.govuk_text_field :full_name, width: "three-quarters",
    label: { text: full_name_label, tag: :h1, size: 'xl', class: "govuk-!-margin-bottom-8" },
    caption: { text: @school.name, size: 'xl' } do %>
    <p class="govuk-body">We just need their first name and last name, not titles like Mr, Mrs, Dr.</p>
 <% end %>

will generate this HTML:

<div class="govuk-form-group">
  <h1 class="govuk-label-wrapper">
    <label for="add-participant-wizard-full-name-field" class="govuk-label govuk-label--xl govuk-!-margin-bottom-8">
      <span class="govuk-caption-xl">Abbey Lane Children's Centre</span>
      What’s this ECT’s full name?
    </label>
  </h1>
  <div id="add-participant-wizard-full-name-supplemental">
    <p class="govuk-body">We just need their first name and last name, not titles like Mr, Mrs, Dr.</p>
</div>
<input id="add-participant-wizard-full-name-field" class="govuk-input govuk-!-width-three-quarters" 
 aria-describedby="add-participant-wizard-full-name-supplemental" type="text" name="add_participant_wizard[full_name]">
</div>

Unfortunately, this pattern can tempt people into including detailed guidance between the label/caption and the input, such as multiple paragraphs, lists, or links.

This can introduce an accessibility issue, as mentioned by the GOV.UK Design System guidance for hints:

Hint text

Use hint text for help that’s relevant to the majority of users, like how their information will be used, or where to find it.

When not to use hint text

Do not use long paragraphs and lists in hint text. Screen readers read out the entire text when users interact with the form element. This could frustrate users if the text is long.

Avoid links

Do not include links within hint text. While screen readers will read out the link text when describing the field, they will not tell users that the text is a link.

Instead, the guidance for questions pages recommends placing detailed guidance above the question label/legend, and have a separate h1 tag:

Asking complex questions without using hint text

Do not use hint text if you need to give a lengthy explanation with lists and paragraphs. Screen readers read out the entire text when users interact with the form element. This could frustrate users if the text is long.

Do not use links in hint text. While screen readers will read out the link text when describing the field, they will not tell users the text is a link.

If you’re asking a question that needs a detailed explanation, use:

  • a h1 heading that’s a statement (for example, ‘Interview needs’) rather than a question
    whatever mix of text, paragraphs, lists and examples best explains your question to users
  • a label, above the form input, that asks users a specific question – for example, ‘Do you have any interview needs?’

In the Manage training for early career teachers service, we’ve made this mistake on several pages, introducing an accessibility issue:

Example:

Screenshot 2023-09-26 at 14 36 33

To avoid this, we should consider deprecating the feature by adding a warning and then removing it within the next major version?

Metadata

Metadata

Labels

accessibilityMaking it easier for people with disabilities

Type

No type

Projects

Status

In Progress

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions