Details (Hidden text)

[govuk-design-system]

AKA: Hidden text, Expanding text area

Use this issue to discuss this component in the GOV.UK Design System.

[timpaul]

In research HMRC have seen some users who are reluctant to interact with this component because it's styled as a link. They're worried that they will be taken away from the transaction and lose their data.

[stevenaproctor]

@timpaul There are people who scan straight past it and do not interact with it. This could be because of time or lack of familiarity. But this means people can miss important content.

From an accessibility point of view, they are not treated as links by screen readers assistive technology so the experience is totally different.

A colleague wondered if anyone had thought to use the show-hide links, like in the manuals and learning to drive step-by-step guidance. Something like these screenshots.

[SineadFluent]

When there is text to show/hide. Does anyone have research to support whether it is better to change the label of the link between 'more detail' and 'less detail' or if it is better to keep a link as 'more detail'? Seems like it would make more sense if the link describes what it is doing and say 'less detail' when extra text is being shown but keeping the link labeled 'more detail' may be less cognitive load for the user. Any thoughts?

[hannalaakso]

@dashouse discovered that the native details can't be forced to display its contents when printed (unless element is already open on page load or was opened by user). This is because the visibility of the contents is toggled with open attribute in the markup, and this can't be controlled with CSS print styles.

Bug tracked here.

[joelanman]

Since we're using plus and minus in the Accordion component, I thought I'd see how Details would look with the same symbols, as the behaviour is very similar:

[edwardhorsford]

It looks like if you pass text to the details element it goes directly inside a div. Should it go in a paragraph?

[edwardhorsford]

This came up again on the cross gov slack again.

I think it could be helpful to include an example with more than one sentence - I think the correct thing to do is directly provide some html, but I'm not 100%.

cc @frankieroberto who also had questions on this.

[frankieroberto]

@edwardhorsford yeah, if you use the html option of the macro (or whatever Rails-equivalent you're using) it should be fine to add multiple paragraphs?

My question was about Inset text, which I've raised here, although it's very similar: https://github.com/alphagov/govuk-design-system/issues/822

[paulmsmith]

In Nunjucks you can capture the contents of a block into a variable using block assignments, which might be easier for some users perhaps?

An example

Write the HTML in a separate block using set:

{% set detailsHTML %}
    <p class="govuk-body">
        You might need permission from somebody else to do your project, for example you may need:
    </p>
    <ul class="govuk-list govuk-list--bullet">
        <li>
            agreement from the owner of a heritage asset
        </li>
        <li>
            access rights from a landowner
        </li>
        <li>
            planning permission from the council.
        </li>
    </ul>
    <p class="govuk-body">
        It could also include consent to record audio or take photographs of individuals.
    </p>
{% endset %}

Then reference that variable when using the macro:

{{ govukDetails({
    summaryText: "Examples of what might need permission",
    html: detailsHTML
    })
}}

My other suggestion would be to leverage Nunjucks 'call' within the macro but that would mean rewriting the macro in govuk-frontend and although powerful they would probably add complexity and be a tricky concept to grasp for less experienced users of the toolkit.

[edwardhorsford]

@paulmsmith I use the above approach heavily in my prototype - I wonder how well it's known by others.

[paulmsmith]

@edwardhorsford It is subtly documented in Nunjucks. If I get a minute I might do a pull request with an example for the docs maybe? For my own purposes I could be tempted to write a macro that uses 'call' but then uses the official macro under the hood.. I wouldn't suggest that to everybody because it is another level of abstraction but, it is a possibility.

[NickColley]

Using capturing like that is the safest way to pass HTML as it means you can avoid some cross site scripting vulnerabilities, I think it'd be good to have a general guide for this sort of stuff.

Where possible I have recommended that the Design System examples should use capturing

[paulmsmith]

@nickcolley Happy to contribute! Little stacked at the moment but will have more time next week. :)

[NickColley]

It would be good for you to capture some of your thoughts here please: https://github.com/alphagov/govuk-frontend/issues/941 !

[mpwoods]

This component has been added to four questions in the Brexit checker: https://www.gov.uk/get-ready-brexit-check/questions?page=3

The checker provides users with a list of personalised actions that they need to take to prepare for a no deal Brexit. User research has shown that users don't understand why they are being asked certain questions, and how their answers will determine what actions they need to take.

We want to carry out further user research to see how users respond, and to see if we could add it to all/more questions in the checker.

We're also adding customised tracking to the component to help gain further insights.

[edwardhorsford]

@mpwoods I'm curious about your placement of the details component after the checkboxes. Do you have any details of research / thinking behind this? I might speculate it's seen as less important than the main question - but with the downside that some AT users won't get to it till after answering the question.

My team were just discussing a similar thing - how to use details elements within questions (and what markup would be correct) so would be keen to hear your thinking.

[mpwoods]

@edwardhorsford It's a good question and we debated the placement for some time.

We looked at 3 potential positions: above the checkboxes; below the checkboxes (as now); and below the button.

Most of the questions have descriptive text above the checkboxes, and some have additional hint text too. So adding the component into that space felt a bit cluttered.

There was a concern that adding it below the button would cause some users to miss it, and also that links below buttons are often things like 'Cancel' so it could get confused with that. We're also looking to add a 'Skip question' link which might sit in that space.

We asked around for other examples of where the component is being used with questions and we found this which also places it above the button: https://global-entry.beta.homeoffice.gov.uk/register-to-apply/passportNationality

Due to the pace we've been working at, and wanting to add this component before the pre-election period freeze, we've opted for the current placement with the proviso that we'll carry out user testing as soon as we can. We're also adding custom tracking to the component so we can gain insights in the meantime.

Hope that helps.

[patrick-mccourt]

We've got a details component on our apply journey on JSA, when we went through accessibility testing it was flagged as looking like a link, but doesn't respond to "Click link" when using Dragon, but does respond to "Click button" As a result we failed this test on the report:

1. Confirm that saying "Click Link" numbers all the links on a page. (NB: If there is only one link visible it will automatically be selected.)
2. Confirm the correct link opens when the user says "Choose ".
3. Say ‘Go Back’ to return to the testing URL.
4. Activate each of the links in turn, by repeating steps 1-3 and selecting each number in turn.
5. Repeat with "Click Link" NB: Where the user "clicks" a single, unique link, Dragon takes the user straight to the relevant page

I have tried to give it a role of link to both the <details> and <summary> tags but the permitted roles are none for these tags and summary has an implicit role of button so always renders with role of button.

The issue was flagged by an accessibility testers originally, though we did have a real Dragon user test this application journey also and the report said they were able to expand the link successfully, but it doesn't mention which Dragon command they used.

This is how it's being used in our apply journey:

I believe this was chose so they could hide the continue without providing bank details link as missing bank details is a common cause of delayed claims. Not 100% sure on this as it was done by a supplier and handed over.

[roobottom]

We've just run 5 UR sessions for a service we've inherited. It uses the details component heavily. All participants said they expected that the "link" would take them to a new page. And as per @timpaul's first comment on this component, participants were concerned that they'd loose their progress if they clicked the perceived link.

[joelanman]

@roobottom thats really useful thanks, can you say any more about the context of the service? Can you upload a screenshot?

[roobottom]

Sure, it's for the "File your company tax return" service. Which is old, but does use a version of details that looks pretty much the same as the modern one. Here's a couple of screenshots:

1. Before the user starts we offer some guidance:

2. Once in the service, we use details to explain what each line-item is related to.

[selfthinker]

It is my understanding that this would indeed fail WCAG SC 1.3.1. It presents itself as a link but cannot be "programmatically determined" as one.

[selfthinker]

We discussed the general issue of buttons looking like links and specific examples like the details component among a group of accessibility specialists at GDS.

WCAG SC 1.3.1 says:

Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.

When the link button text makes it clear what it is doing, that is not a fail. For example, the accordion's "Open all" link button looks like a link but makes it clear what to expect from the text alone.

Otherwise we decided that a button that looks like an interactive thing without looking too much like a link is also not a fail. But this is where it gets tricky because the decision if something "looks like a link" is very subjective.

When we discussed the details component within the group we asked ourselves "Does this look like a link?" and found Yes, technically it looks quite a lot like a link. (They are blue and underlined.) But when we asked ourselves "When you click on it, would you expect it to lead you to a different page?" the answer from all of us was No. We found the main reason for that was the triangle before the link.

So, we thought we wouldn't fail the details component on 1.3.1. But as I mentioned, this is very subjective. We know from feedback on this very page that different users have confused it with a link. That makes this difficult to judge.

On the other hand, we found the accordion section link buttons technically look less like a link (they are blue but bigger and bolder and not underlined), but when we asked ourselves "When you click on it, would you expect it to lead you to a different page?" we all said Yes. Although the big plus makes it look different, it is so easy to ignore when it is out of the way on the right-hand side. And we know some users had issues interacting with it as well because they thought it was a link.

Sorry that this is a somewhat less satisfying statement because some elements of it are so vague. Does anyone have any alternative views on this subject or other insights?

[abbott567]

@selfthinker really appreciate the update.

Is there a risk that only asking the GDS Design Team how they expect the details component to work has biased the result? If GDS built it, and as designers in Government, we've all used it, we would probably all agree that we'd expect it to expand, because we all know for a fact thats what it does.

However, I have seen first hand that in user research sessions people often do not interact with details components because they don't understand what it is.

I appreciate that WCAG is very subjective, but I am a bit worried that we could do our users a disservice if we mould the subjectiveness of WCAG to fit our own understanding of how a component already works.

[selfthinker]

@abbott567, just to clarify, no-one from any design team was involved in that decision. (I don't think there is a "GDS Design Team", so I might potentially misunderstand what you mean by that.) At least one person in the group was quite new to GDS and didn't know the Design System very well.

But yes, obviously we're all biased in some ways. Although I think it's more likely we were more biased by knowing how the web works rather than how the Design System works. (I remember someone mentioned the browsers' default styling of the details component and that it's very similar.) All we can do is to try to be objective. But it's difficult to achieve full objectivity within a WCAG audit setting. I'd be very thankful for any tips on how to improve that.

Most of us also knew the accordion quite well and failed it, even though we knew how it was supposed to work. So, I don't think 'knowing the Design System' is the one factor that might make us biased. DAC did a WCAG audit of the Design System and didn't fail the details component. They are a third party auditor and don't work for GDS. Although I guess you could argue they know web design in UK government quite well because they've been auditing government services for years.

We're not saying that there isn't an issue. And I agree that this component should be improved. We're just saying that we don't think it's a strict WCAG fail.

[abbott567]

@selfthinker thanks for the clarity. Apologies, when I said GDS Design Team I just meant the team responsible for maintaining the Design System.

It's reassuring to know it was usable when tested by the DAC.

Just for feedback, on the Design System accessibility statement it says a 'sample audit' was done on each of the page types. It lists 'a component page' as one of those, and the link just goes to the radio buttons component, so it is not clear that DAC has tested the details component. It reads (to me at least) that just the radio button component was tested in the sample audit, which if it's not true is probably doing GDS a disservice.

[roobottom]

This might be useful: https://www.nngroup.com/articles/accordion-icons/

[abbott567]

@roobottom that article is super interesting. Thanks for sharing

[querkmachine]

Noting for any future explorers:

Today we were contacted by a developer, saying that an external auditor had flagged the Details component as having an issue, as screen readers were announcing the (seemingly superfluous) text "disclosure triangle" in Google Chrome. In this instance, the test was using TalkBack on Android 12.

We have previously noticed this in 2018 when using macOS VoiceOver with Google Chrome. Checking again today, this is still the case.

Help with nationality, collapsed, disclosure triangle, group

Further testing found that this is part of Chrome's accessibility tree for the details/summary elements—"DisclosureTriangle" seemingly being the accessibility tree's name for the summary element—and is not specific to our implementation.

We therefore do not consider this to be an issue with the component.

[exonian]

We got some usability feedback on this component in an accessibility assessment conducted by DAC recently.

Voice activation users noted that the expandable option ‘Help with subject matter of dispute’ at the bottom of the page does not get picked up by voice activation software. This leaves the need for keyboard only commands to be used which, is a slightly longer and more difficult way to access content.

Current code ref(s): #new_client_vehicle_details_form > details > summary > span Help with subject matter of dispute

Voice activation user comments: “The accordion above the ‘save and continue’ button does not get picked up by Dragon. This meant that I had to use keyboard commands to tab onto it.”

I've captured the page html as a gist as @christopherthomasdesign suggested the specifics of the page around the component might be useful in replicating the issue. The page is several pages into the user journey on our service, requiring particular answers to reach it, but I can provide these as replication steps if that's more helpful.

[exonian]

We have since had a re-assessment by DAC and this issue didn't come up then. I've also tried to replicate it at the MoJ Empathy Lab and expanding the accordion using Dragon worked as expected.

So this seems most likely to have been a user error.

[christopherthomasdesign]

Ah that's good to know, thanks for following up @exonian!

[adamsilver]

Our internal a11y audit raised this:

The "Show examples" [Details component] is styled like a collapsed link but calls itself a collapsed button. The UI components should reflect and be styled and named consistently. (2.4.6, 4.1.2)

[mrkwrght]

HIya everyone

Im currently working with the pension regulator on a service with a specific user base

In the last round of usability testing we had all of the users thinking the details components was actually just a normal link.

We are going to removing it from the page as users also expected to receive the template a lot sooner in the service

But wanted to raise this here because it looks like similar discussion to happening around it

[that-firefly]

In research HMRC have seen some users who are reluctant to interact with this component because it's styled as a link. They're worried that they will be taken away from the transaction and lose their data.

I agree. I think in terms of design there is an issue with affordance on the icon of the arrow and long text on the top level. If there are rules to restrain the text amount on the the top level title then it could work but when you add low affordance with complexity people/users will "ignore" it.

[CharlotteDowns]

We ran an external accessibility audit for some of the components and patterns in GOV.UK Frontend in May 2023. In that audit, we included an example of the Details component. We’re adding results from that audit here so that we can:

• document, discuss and address the findings
• inform future contributors of the findings

One usability issue raised

The 'details' HTML tag is not easily accessible when used with Dragon and VoiceOver. Consider using a button?

The details component ‘About GOV.UK One Login’, is not easily accessible for all user groups. The details element is not recognised by verbal commands for users navigating with Dragon Naturally Speaking, and the user is required to use verbal keyboard commands such as ‘press tab’. For users of screen reading assistive technologies the details component does not convey its state or functionality for users navigating with VoiceOver.

More detail in this issue:

• #3693

[DavidBiddle]

Has anyone previously looked at using this component with a heading as the summary?

Our specific use case is that we're working on a page with a markdown editor, which has some formatting help in a details component underneath. We thought it might make sense for the summary to be a h2 so that the formatting help is easier to discover and navigate to in screen readers.

As far as I can tell there's nothing in the HTML spec which precludes this (summary's content model is phrasing content optionally intermixed with heading content). But the example in the Design System only uses span, and the nunjuck macro's summaryHtml option will insert the supplied HTML inside the span (so summaryHtml: "<h2>Help with nationality</h2>" will render the h2 inside a span, which isn't valid HTML). So I'm not sure if this is something that's been considered previously and there are good reasons to restrict it to span, or if our use case is novel and it's worth us trying it and reporting back when it eventually goes through research.

[linkim12]

Hello everyone!

We’ve implemented a ‘show more’ or ‘show less’ component, similar to the ‘Details’ component. We’ve used this component for a screen where we present a subsequent amount of information from a database that serves diverse users, from professional experts in the field to novice users.

Our decision is informed by user research, indicating that while users expect to see ‘Abstract’ information, an excessive presentation of content can lead to feelings of overwhelm.

We used this component to meet a wide range of user needs, such as: • As a service user, I need to be able to skim through the information quickly and easily, without having to read everything in detail so that I can find the information that is most relevant to my current needs without wasting time on extraneous details. • As a service user, I need to be able to read full details of information on a single page, without having to navigate to multiple pages so that I can find information I need efficiently without getting lost.

While it shares similarities with the ‘Details’ component, there are some distinctions. The ‘show more or show less’ component doesn’t include any arrows or other icons. Also, it continues from the existing content rather than being added on a separate line.

We wanted to share our design iteration to the GDS community – I’ve included this in this thread as it resembles to the ‘Details’ component in terms of revealing or hiding additional text based on user’s preference. However, I haven’t encountered this component in other government services. It’d be good to learn if any other services also use this component, and what lessons they've learnt from iterating and testing this design.

Thanks!

[joelanman]

@linkim12 thanks for sharing! Have you done any accessibility testing? Are you able to share the code for it?

[stephenjmcneill1971]

Recently had an accessibility report done on our service and one of the medium highlighted fails was that this component does not identify itself in Voiceover as a button on IOS devices. Works fine on desktop. Has anyone else had a problem with this. The fact that it looks like a link was not reported on.

[querkmachine]

@stephenjmcneill1971 It's a curious one because the underlaying element is indeed neither a button nor link. VoiceOver is not wrong to identify it as neither, it's just awkward that it doesn't identify it in a way useful to a user like other screen readers do.

As the component uses valid HTML and we haven't changed them or their semantics in any way, I think our feel is that this is a problem for VoiceOver to fix rather than for us. It's not a WCAG failure either, but we have noted it in our accessibility statement under "Other identified and tracked accessibility concerns".

[Greenhouse99]

@linkim12 thanks for sharing! Have you done any accessibility testing? Are you able to share the code for it?

Hi there, we did do accessibility testing, and we had a non-compliance for this initially for 1.3.1, "Hidden elements still receive focus."

However, we have developed and tested a new solution for this. The non-compliance has been confirmed to have been resolved by our development and test teams.

The solution was that when the "show more" link is collapsed, bypass the hidden content in the focus order. This is so that users can move quickly to the next section of the page. Also, to remove the content from the accessibility tree, add an aria-hidden attribute to the content that is toggled between true or false depending on whether the accordion/mobile menu is expanded or collapsed.

https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden

[querkmachine]

A fix for VoiceOver not announcing details/summary elements has landed in Safari Technology Preview 183. It'll likely release in the next versions of Safari.

https://bugs.webkit.org/show_bug.cgi?id=108979

[darraghmckeogh]

We're completing usability testing for a BSR service and found the same issue others have mentioned; it is not clear to users of screen reader technology that they can interact with the details component to expand it.

[JohnMH-Softwire]

We completed usability testing for the Election Registration Office Portal, as part of the Electoral Integrity Programme in DLUHC. In a round of testing with 5 participants, 1 person thought that the Details component would link to/open up a video. They were familiar with the triangle meaning video from Youtube/iPlayer. As a result, they wouldn't click on this component because they don't have time to look at a video.

[lalexander12]

Does anyone know the maximum word/character count for details? We have had feedback in an accessibility report that we have too much content in ours for screenreaders.

https://check-your-client-qualifies-for-legal-aid.service.gov.uk/no-analytics

[joelanman]

@lalexander12 did they give a reason why its a problem? Long alt text for example can be an issue since it doesn't support any structure, like lists or headings, but Details does as far as I know.

[lalexander12]

When accessing the site on an iPhone or iPad, the status of expandable containers is not announced to VoiceOver users.

For instance, on the ‘Your client’s employment income’ page, the first expandable element is announced as “Clients who are police officers, double tap to expand.” Even once the element is expanded, it is announced as “…double tap to expand” — users are not informed of the change in state.

Visually, the new content dynamically appears below the expanded element. Screen reader users, however, are not provided with this information. The expected behaviour for expandable elements is for them to be announced as “collapsed” or “expanded” based on their state, as is seen on desktop (see [Positive: Additional information presented in collapsible sections (Positive)] ). However, even on being expanded, the element continues to be announced as “Clients who are police officers, double tap to expand.” This would be confusing for screen reader users, who might not realise that the element has been expanded and that they can access the new content.

Expandable element on Client Employment Income page FIGURE 2.3: Expandable element on Client Employment Income page

2.2.2 Code Snippet
<details open="">
  <summary>
      <span> 
        Clients who are police officers 
      </span>
  </summary>
  <div>
    <p> 
      If your client is a police officer, the...
    </p>
      ...
  </div>
</details>

2.2.3 Recommendation Screen reader users should be informed of the element’s state. When collapsed, the state of the element should be announced as “double tap to expand”. On interacting with it, screen readers should announce “expanded” and the element should then be announced as “double tap to collapse”. This lets screen reader users know the current state of the element and informs them when new content is available.

This issue occurs because certain versions of iOS and VoiceOver do not have native support for the details and summary elements. Problems with the details element have been raised by AlphaGOV and it appears that some users are able to access the component as expected while others are not. A potential solution would be to implement a native element with an aria-expanded attribute dynamically updated based on the user’s input.

Hi, are you able to read this link from our report?

https://uv3073-moj-ccq-spotcheck.uservisionaccessibility.co.uk/expanded-elements-not-announced-as-such-on-ios-low.html

[querkmachine]

We have numerous bug reports open with the WebKit team regarding VoiceOver not announcing details element states:

• https://github.com/alphagov/reported-bugs/issues/28
• https://github.com/alphagov/reported-bugs/issues/29
• https://github.com/alphagov/reported-bugs/issues/64

[lalexander12]

Can I ask about using a details component within a question that contains radios? For example, we have a multiple page question, with several question/radios. In one instance we add a 'details' between the question and the radios. Is it better to keep details outside of the question/radios, for example, above or below?