search

alphagov / govuk-frontend

GOV.UK Frontend contains the code you need to start building a user interface for government platforms and services.
https://frontend.design-system.service.gov.uk/
MIT License
1.18k stars 323 forks source link

Consider updating hints and error messages to use paragraphs #2083

Open 36degrees opened 3 years ago

36degrees commented 3 years ago

What

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

https://github.com/alphagov/govuk-frontend/blob/d5a3fa8c5e61dbc7ca0f7a8429cc8e6716ee7c32/src/govuk/components/error-message/template.njk#L3-L6

https://github.com/alphagov/govuk-frontend/blob/d5a3fa8c5e61dbc7ca0f7a8429cc8e6716ee7c32/src/govuk/components/hint/template.njk#L1-L4

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

36degrees commented 3 years ago

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 commented 3 years ago

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

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 commented 2 years ago

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 https://github.com/alphagov/govuk-design-system/pull/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:

vanitabarrett commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

This change has been made for error messages in https://github.com/alphagov/govuk-frontend/pull/2452, but I'm re-opening this issue as we haven't made the change for hints yet (see comment above).

edwardhorsford commented 2 years ago

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