Consider updating hints and error messages to use paragraphs

[36degrees]

What

Consider updating hints and error messages to use paragraphs rather than spans and divs.

govuk-frontend/src/govuk/components/error-message/template.njk

Lines 3 to 6 in d5a3fa8

	<span {%- if params.id %} id="{{ params.id }}"{% endif %} class="govuk-error-message{%- if params.classes %} {{ params.classes }}{% endif %}" {%- for attribute, value in params.attributes %} {{ attribute }}="{{ value }}"{% endfor -%}>
	{% if visuallyHiddenText %}<span class="govuk-visually-hidden">{{ visuallyHiddenText }}:</span> {% endif -%}
	{{ params.html | safe if params.html else params.text }}
	</span>

govuk-frontend/src/govuk/components/hint/template.njk

Lines 1 to 4 in d5a3fa8

	<div {%- if params.id %} id="{{ params.id }}"{% endif %} class="govuk-hint {%- if params.classes %} {{ params.classes }}{% endif %}"
	{%- for attribute, value in params.attributes %} {{attribute}}="{{value}}"{% endfor %}>
	{{ params.html | safe if params.html else params.text }}
	</div>

Why

As raised by a user on x-gov Slack:

the error message is in a tag. Is there a reason why a <span> is used, rather than a <div> or <p>, for example? The reason I ask is because I’ve been doing some testing with JAWS and I’ve found that there’s no pause between reading the hint text and the error message. So JAWS reads “For example 12 11 2007 error colon the date your passport was issued must be in the past”. Using a <div> didn’t make a difference, but using a <p> resulted in a pause between the hint text and the error message, so potentially making it a little clearer.

It looks like hints used to be paragraphs, but were changed to spans when the hints were moved inside the label – presumably as only phrasing content is permitted within a label. Error messages, when they were added later, were also spans inside the label.

We recently updated hints to use divs rather than spans so that they can be used with flow content (for example multiple paragraph tags, or a list)

Since we moved hints and error messages out of the labels, we should consider whether they should now by marked up as paragraphs instead.

Who needs to know about this

Developers, designers

Done when

• Tested alternate form controls with error messages and hints marked up as paragraphs in assistive technologies
• Identified other potential issues cause by changing hints and error messages to paragraphs
• Decision made and code change made
• Check if the changelog for Remove display:block hint style as we're switching from span to div #1856 needs updating as a result of this work

[36degrees]

One consideration – we often see very long hints that are made up of multiple paragraphs, or include lists – so we might need to either keep hints as divs or make them configurable to support either a single paragraph or a div wrapper.

However, there are other issues with very long hints – they're associated with the input using aria-describedby which only really makes sense for shorter hints.

So, another alternative would be to be more restrictive about the sort of content that can go into a hint and provide an alternative pattern for cases where longer guidance is needed alongside a form input.

[vanitabarrett]

As discussed as part of our v4 prioritising, we should make sure:

• we test a variety of approaches with screenreaders to see which perform best
• we should make sure our implementation matches up with our guidance Add guidance on using longer supporting text for questions govuk-design-system#1716
• if we are considering moving to paragraphs, we need to think about the implications for services and what we recommend they do instead

We should remember that we can always tackle the error messages and hint text separately if we're more confident of one change than another.

[vanitabarrett]

I’ve tested with Voiceover, NVDA and JAWS, comparing our current implementation (<span> for error messages and <div> for hints) with the proposed change (<p> for both). There doesn’t seem to be any difference in the way screen readers announce the hint or error message when it’s marked up as a paragraph.

➡️ Full testing spreadsheet

It feels pretty low risk to make this change for error messages. We know that hints are slightly more complex, as we did make a change previously from <span> to <div> to support more content which this slightly backtracks on. However, given the work we’ve done on alphagov/govuk-design-system#1716 and the (I think) anecdotal evidence we’ve seen that long hints aren’t a great user experience for screen reader users, I think my vote would be to make both hints and error messages be marked up as paragraphs. We should be able to point people towards the guidance for avoiding long hint text in the release notes.

Next Steps

If we agree that we want to use paragraphs for both hints and error messages, the next steps:

• Complete testing in Voiceover (iOS) and TalkBack (Android) to confirm everything works as expected
• Raise a PR to change the HTML templates to use paragraphs and update the tests accordingly
• Draft release notes, especially given guidance for users with long hint text

[vanitabarrett]

We've decided to go ahead and make the change for error messages. The change to hints needs a little more research as it'll block users from adding any block level elements to the hint. Generally we think this is ok as we already recommend not to have long hint text with lists or paragraphs. However, we want to explore what the actual effect of this in when using aria-describedby as we do, so we can call it out in the release notes if/when we make the change to hints.

[vanitabarrett]

Having had a chat with the other developers about this, we're confident in the change to error messages but think we're going to hold off on the change to hints for now as it's quite different to recommend users not to write long hint text vs actually forcing them not to. We know there are some examples of extremely long hint text which aren't appropriate, but there are also probably some more in the middle ground which wouldn't be allowed by this change but are probably not too noisy for screenreader users. The new guidance on avoiding complex hint text goes some way to providing people with an alternative, but it assumes one question per page. This change probably needs a bit more research first.

As a side note, the possibility of adding text and html option for hints came up in this conversation where text would render as a paragraph and html would render in a div. Probably needs some exploring. Not sure if this would make users think that long html hint text is more "allowed".

[vanitabarrett]

This change has been made for error messages in #2452, but I'm re-opening this issue as we haven't made the change for hints yet (see comment above).

[edwardhorsford]

An example where a service might legitimately have a 'long hint', but isn't really long - where they have both a single line hint and an example for formatting.

A date might have a hint like:

This is the date when the event occurred
For example, 1 January 2021