Accordion

[govuk-design-system]

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

[frankieroberto]

I've done some work to extract the Accordion javascript from the Design Manual into a standalone component which no longer requires jQuery.

You can see the code here: https://github.com/frankieroberto/accordion

[tameemsafi]

Just a note that the DVSA heroku app link has a password. Below are the details:

username: admin
password: dvsa

Also source can be found here:
https://github.com/dvsa/front-end/blob/master/src/assets/js/dvsa/modules/accordions/accordion.js

[kr8n3r]

we're aiming for Service standard browsers support matrix right?

[timpaul]

Thanks @tameemsafi - I've updated the top comment with those details.

[frankieroberto]

@tameemsafi the DVSA components seems to have two versions, one with + and - icons, and the other with arrows. Have you tested both? Any reasons to prefer one over the other?

Also looks like your javascript does some scrolling, which I find slightly jarring, but perhaps there's a reason for this?

[tameemsafi]

@frankieroberto We did test both and the one with up/down arrows is the one that was chosen as it was more user-friendly. However, I put both in the styleguide just to show the different versions.

The scrolling feature works better if there is more content but I see what you mean that it looks a little annoying on the styleguide page.

You can see it being used live here:
https://www.check-mot.service.gov.uk/

[frankieroberto]

@tameemsafi interesting, thanks.

[fofr]

We're trying out a version of this in a form on "Find postgraduate teacher training courses":
https://search-and-compare-prototype.herokuapp.com/start/subjects (bat/beta)

[joelanman]

From Check MOT service:

[hannalaakso]

@frankieroberto has very kindly agreed to work with us on developing this component. The work will be based on https://github.com/frankieroberto/accordion

[hannalaakso]

Accordion component criteria

In addition to meeting the Design System criteria, we have agreed that this component will meet the following additional criteria:

Coding criteria

The accordion component must:

• be built using GOV.UK Frontend
• follow the GOV.UK Frontend coding standards
• have a Nunjucks macro
• have unit and integration tests
• be tested with these browsers
• be tested with these assistive technologies
• if appropriate, use Details disclosure element (this should be explored as part of the coding work)

Design criteria

The accordion component must:

• be usable on any screen size
• allow users to complete their task if JavaScript is not available
• change appearance when it is expanded/collapsed

Guidance criteria

The component guidance must:

• follow the GOV.UK Design System content pattern
• provide examples of common use cases
• describe what research has been done and what still needs to be done
• follow the GOV.UK style guide

Research criteria

The contributor must:

• have collected at least 3 different examples of accordions being used in services on GOV.UK
• have tested with a representative range of users, including those with disabilities, in a prototype or live service OR
• be able to show that the component is clearly based on relevant user research from other organisations and best practice (in this case, the component would be published as experimental)

Accessibility criteria

• must meet WCAG 2.0 AA guidelines
• not depend on colour to communicate information
• handle cases where user changes their default colours
• it must be possible to focus on the controls using the tab key
• the controls must change in appearance when keyboard focus moves to it
• it must be possible to activate the controls using the appropriate keys
• the controls must indicate when the mouse is hovered over it
• it must be possible to activate the accordion controls using a click
• the controls must be large enough to tap accurately with one finger
• it must be possible to activate the controls using voice commands (see Coding criteria).
• the expanded/collapsed state must be available to screen readers
• the relationship between the accordion controls and disclosed content must be available to screen readers
• it must be possible to focus on the accordion controls using standard screen reader button commands
• the controls must have a visible text label
• the contrast between the accordion text label and its background must meet (or exceed) a ratio of 4.5:1
• the markup must validate against HTML5 validator
• the content must be in a logical order in the source code

[ignaciaorellana]

This contribution in being worked on GOV.UK Frontend by @frankieroberto, see further details here: alphagov/govuk-frontend#958

[joelanman]

Interesting thread on the Australian design system

[frankieroberto]

The Worldwide section of GOV.UK uses accordions on the country pages, eg:

[adamsilver]

This looks really good—nice one, Frankie!

Here’s some notes/questions:

1. There’s a typo in the Nunjucks macro documentation: it says “Required. undefined See items”

2. Is “Open all” clear enough for screen reader users? I wonder if it should have “sections” (or similar) added to the end using visually hidden? Same for “Close all”

3. Is the “Open all/Close all” toggle button text configurable?

4. Hover state: is the subtle change of background colour obvious enough? We had a subtle grey used on Tabs (Tabs #5955 (comment))

5. Can it be configured so that particular sections start open?

6. Can it be configured so that all sections start open?

7. The focus outline only surrounds the button on the left even though the entire row is clickable. Is there a reason for this? I’d suggest the whole thing gets the focus outline.

8. Further to (7) could the <button> wrap the entire row contents including the H2 and SVG icon.

9. Could you add focusable=false to the SVG so that it’s not part of the tab sequence?

10. Could you add a visually-hidden class to the SVG so that it’s not read out for screen reader users as the <button> seems to provide enough information?

11. While forms shouldn’t be used with accordions, there is a potential need to have form controls inside an accordion like this for filtering controls. See the following links:

• http://nostyle.herokuapp.com/examples/filter-form
• Accordion #6104 (comment)

12. With the filters, it's worth noting that the accordion label/heading is actually a legend. I wonder if we can make the accordion component work on legends etc.

13. There is a bug, at least in the second example where the <h2> contains the <button> and then another <h2> inside it.

14. Can it be configured so that the accordion doesn't have the “Open all” button?

[stagarz]

I agree with @edwardhorsford, content is now much harder to scan and significantly more scrolling is required to get through the same amount of information. Especially for internal services, where users are expected to interact with complex data on a daily basis, the accessibility tradeoff doesn't hold up.

Is there a chance to have the old design back for internal services please?

[querkmachine]

Hi @edwardhorsford and @stagarz,

Thanks for your feedback. We had a short discussion about this within the team last week.

In short, we don't consider this to be a priority. The new accordion design has been thoroughly tested with users (including those with access needs), tested with assistive technologies, and reviewed by accessibility experts. The new implementation is WCAG compliant; the old implementation was not.

Although we are aware and accept that the new accordion is harder to scan and takes up more vertical space, we consider these to be reasonable trade-offs for the sake of making the accordion accessible. We don't feel like there is a compelling reason to make changes to the design at this time, especially as many of the accessiility problems with the original version were visual in nature.

We are confident that the new design is a marked improvement on the original. We encourage implementors to really think about the compromises needed to continue using the older design and to carry out user testing on anything new (or old, in this case). If you do carry out testing (ideally including assistive technology users) then we'd be interested in seeing it!

[MalcolmVonMoJ]

Our content designers requested that direct-linking to an element ID within the accordion should open that section immediately. Therefore, I have written this JavaScript to achieve that:

function haleAccordionDirectID() {
	if (window.location.href.split("#").length == 2) {
		
		// Split the string and get the ID
		const halePageRequestedID = window.location.href.split("#")[1];

		// Check for the requested ID within the accordion
		if (document.querySelector(".govuk-accordion__section #" + halePageRequestedID) !== null) {

			const haleRequiredSection = document.getElementById(halePageRequestedID).closest(".govuk-accordion__section");
			haleRequiredSection.classList.add("govuk-accordion__section--expanded");

			haleRequiredSection.scrollIntoView();
		}
	}
}

It is yet to be reviewed by our other developers, but I thought I'd share it here before I forget.

[36degrees]

@MalcolmVonMoJ as well as adding the --expanded modifier class, there's also quite a lot of other things that the component does when showing and hiding sections, including:

• updating the text and icon used for the 'Show / Hide' for the section
• updating the text and icon for the 'Show / Hide all sections' button
• setting the aria-expanded attribute on the button so that the expanded state is correctly communicated to users of assistive tech such as screen readers

Without also taking care of these things the various bits of the interface are likely to get out of sync, and the expanded state will not be communicated correctly to assistive tech users.

[MalcolmVonMoJ]

Thanks for replying Ollie. Originally I thought that would be the case. But it was pointed out to me that if I only add --expanded then those other things are dealt with by the existing JavaScript (lines 261-264).
My new JS is running first, and it seems to work locally.
If I'm missing something, please say.

[nick-golding-softwire]

I have a use case which I believe is similar to @edwardhorsford's comment above on 17th May.

It's not a public-facing service; the users are local authority staff in a role requiring some data processing expertise. We are supplying them an error report for a spreadsheet of data they've uploaded; there could be many errors in each of many rows in the spreadsheet.

Ideally I'd like the first thing they see to be an overview, where each row in the spreadsheet has one row in the overview that summarises how many errors there are in that row but without going into detail. Then I'd like the user to be able to expand each row to see the full details of the errors in it.

Hopefully that description makes sense. It seems to me that the "old" design Ed refers to - which I haven't used before - is a better pattern for this than the new one, as there could be dozens of rows (accordion sections) and the new accordion design would take up a lot of space, be daunting to users, and be very hard for a user to scan to get that overview of the report.

Are the "old" accordion designs / macros available somewhere for my team to implement and test? (We would look into the accessibility issues at the same time and aim to test with assistive technology users. If there's a summary of the issues somewhere that would help us ensure we're addressing the right things.)

Alternatively if there's a better pattern for our use case then I'm very open to recommendations!

[patrickhlauke]

Arguably, using aria-expanded as well as changing the actual text of the buttons ("Show" / "Hide") leads to confusing announcements, along the lines of Writing well for specialists , Show this section collapsed / Writing well for specialists , Hide this section expanded.

I'd say either use aria-expanded, or change the text.

[patrickhlauke]

Currently, the demo at https://design-system.service.gov.uk/components/accordion/ uses :focus, rather than :focus-visible. As a result, the rather heavy "yellow/orange background and thick underline" styling is applied as a result of a mouse click (in anything other than Safari), which is visually confusing for mouse/pointer users I'd say.

[CharlotteDowns]

We have removed the 'Experimental' tag from components, patterns, and guidance in the Design System 😌.

The tag was being used on the Accordion component to raise awareness that more research is needed to validate it. However, we recently published new guidance on how to share findings from users which we hope will make it easier to collect more information about how our Design System is being used across services.

If your team has used this component please let us know 💪🏻.

[Jeff-Cuss]

Was there a stage in the development of this component where the following choice was made?
Either:
The 'Show all sections' control becomes 'Hide all sections' when the user has opened one or more sections of the accordion.
Or:
The 'Show all sections' control does not become 'Hide all sections' until the user has opened all the sections of the accordion - like it is now?

I'm keen to hear if there was any research or user testing around this issue.

Sorry if it's in here somewhere already, I have tried to find it!

[querkmachine]

@patrickhlauke Noticed that your comments went uncommented upon.

Your thoughts regarding aria-expanded make sense to me, especially as we've made similar changes to other components in the past. The GOV.UK header previously used "Show/hide menu" text on mobile alongside aria-expanded, but this was reduced to simply "Menu" some time back.

Opening this as an issue on the frontend repo would give it more visibility. You can do that, or someone on the team can do it if you'd prefer.

The use of :focus instead of :focus-visible is likely because we still support browsers that don't support :focus-visible. At the time of your comment this included Internet Explorer 8(!) but today the stragglers are IE 11 and Safari 12.

@Jeff-Cuss I think this got asked and answered elsewhere, but my reckoning on this is that showing all sections is just the more common action a user is likely to want.

For example, a user may show one or two sections with promising-sounding headers to find what they want, not find it, and choose to show all of them so that they can scan through everything.

Conversely, a user seems fairly unlikely to want to hide all sections unless they're trying to visually declutter a page for some reason (maybe printing?) In all likeliness, if the accordion doesn't have what they're after, they'll just leave the page rather than hiding everything.

[Jeff-Cuss]

@patrickhlauke Noticed that your comments went uncommented upon.

Your thoughts regarding aria-expanded make sense to me, especially as we've made similar changes to other components in the past. The GOV.UK header previously used "Show/hide menu" text on mobile alongside aria-expanded, but this was reduced to simply "Menu" some time back.

Opening this as an issue on the frontend repo would give it more visibility. You can do that, or someone on the team can do it if you'd prefer.

The use of :focus instead of :focus-visible is likely because we still support browsers that don't support :focus-visible. At the time of your comment this included Internet Explorer 8(!) but today the stragglers are IE 11 and Safari 12.

@Jeff-Cuss I think this got asked and answered elsewhere, but my reckoning on this is that showing all sections is just the more common action a user is likely to want.

For example, a user may show one or two sections with promising-sounding headers to find what they want, not find it, and choose to show all of them so that they can scan through everything.

Conversely, a user seems fairly unlikely to want to hide all sections unless they're trying to visually declutter a page for some reason (maybe printing?) In all likeliness, if the accordion doesn't have what they're after, they'll just leave the page rather than hiding everything.

Many thanks for following this up and for the further information @patrickhlauke

[HenryEscott-IPO]

Hello, I'm currently working on a service that utilises the accordion component. As part of testing, we've run the Axe accessibility tool, which has flagged a critical issue with the use of the aria-controls attribute that gets set by the govuk-frontend accordion JavaScript.

I can see from the list of known accessibility tool issues there has been an accordion fix for the aria-labelledby attribute, but I haven't stumbled upon anything existing regarding aria-controls. Happy to raise as a new issue if required. Thanks!

[querkmachine]

Hey @HenryEscott-IPO,

At a glance, this seems to be raising an error because the content of the accordion section does not have an id of rights-accordian-content-1. This means that aria-controls has an invalid value, because it's referencing an ID that doesn't exist.

I can't say for sure without seeing the other HTML for the accordion, but it looks like 'accordion' has been typo'd as 'accordian' in the aria-controls value. If you aren't seeing the same error for any other section of the accordion, then it's probably the typo causing the issue!

[HenryEscott-IPO]

@querkmachine amazing thanks for the support and speedy response. Dodgy 'accordian' typo aside, it looks like we were setting the id of the section content div to be rights-accordian-content-0 (0 based index) whereas the govuk-frontend accordion JavaScript sets the aria-controls value as rights-accordian-content-1 (index + 1). Thanks very much!