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: https://github.com/alphagov/govuk-frontend/pull/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 (https://github.com/alphagov/govuk-design-system-backlog/issues/100#issuecomment-414043554)

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
    • https://github.com/alphagov/govuk-design-system-backlog/issues/1#issuecomment-407744868

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?

[adamsilver]

@dashouse Hey Dave. @frankieroberto asked me to do this on Monday so I duplicated my comment on the PR: https://github.com/alphagov/govuk-frontend/pull/958

[miaallers-zz]

I have a comment on the placement and use of the 'plus' signs/ arrows:

• I'm not convinced that a plus sign or arrow necessarily has enough affordance for low confidence users
• The placement of the arrows to the far right of each section might make it invisible for users who use screen magnification
• Ditto the placement of the 'open all' element
• Using a word such as 'open', which refers to the interaction itself, may be confusing for screen reader users (who would not see anything opening). It may make more sense to use a word such as 'show', which explains the intent of the interaction, and does not describe the interaction

The way that we dealt with these issues on the GOV.UK Step by Step accordion was to use descriptive link text beneath the section headings:

(Please note that the placement of the 'show all' link should ideally be on the far left to accommodate magnified screen use. It just hasn't been implemented yet!)

[adamsilver]

@miaallers great feedback.

Thanks to your comment, I've just realised that the step by step pattern is basically an accordion but with numbers (and a connecting line). That's pretty cool and wonder if this could end up being the same pattern (or reusing what's under the hood) somehow.

In the screenshot, the “Show all” text is also aligned right and may be problematic for people using a magnifier (like you said). Did you do any testing around this?

[adamsilver]

@frankieroberto did you consider using several instances of the Details component as a style for the accordion?

[frankieroberto]

@miaallers thanks for your comments. We did consider that the placement of the + and - icons and the "Open all" button on the right means they may be missed by users (included those using screen magnification). However we don’t have any strong evidence yet that those poses any actual problems, especially as the context of the page and the blue link-style headings provide the primary cue that the section is navigable. Whilst some users may interpret these as links to a new page, this interpretation doesn’t prevent them from discovering the content.

We do acknowledge that moving the icons and the "open all" button to the left may be an improvement, however the downside would be having to indent all of the text in both the heading and the expanded panel, leaving less space for the content (particularly on mobile).

For the time being, we thought it best to stick to the existing design, which is use across a wide variety of live services, and acknowledge the issue via the "experimental" badge and this message in the documentation:

Known issues and gaps

The plus and minus icon is on the right side of the component which means users of screen magnifiers might not see it.

As to the label on the button, "Show all" and "Hide all" is a good suggestion, and perhaps more generic than "Open all" and "Close all". However I think both can be interpreted in a fairly abstract way. Another alternative might be "Expand all" and "Collapse all", which are the words used in ARIA, and in the Voiceover screenreader on Mac / iOS.

[frankieroberto]

@adamsilver I think the Accordion has a different use case from the Details component. We should probably give more guidance on this in the documentation though.

In my mind, the Details component is for revealing more detailed content related to the current context which only some users will need. The revealed content is likely to be 1 or more (but less than 5) paragraphs of prose.

Whereas the Accordion component is for presenting several comparable sections of content where it is likely that users will only need or or two of them. The revealed content is likely to be more structured content than simply paragraphs, such as a list, tables, or even form fields.

[vickytnz]

Something that I've found interesting reading these comments and looking at the proposed guide is that there are potentially a wider range of options for using this, such as showing filtering options as highlighted earlier in this thread for find courses.

In the guide you say:

Accordions work best for simple content and links. Do not use accordions to divide a form into sections. Split the sections across separate pages instead.

I'm not sure if this this means that using it for filtering options is not recommended?

I feel that the filtering is a situation that people may want to use an accordion, so some form of steer could be good. For example, it could be:

• discouraged - for example, do not use this for filtering
• recommended outright and then shown as an example
• described as something that may need more research

[mschwendener]

"Expand all" and "Collapse all", which are the words used in ARIA, and in the Voiceover screenreader on Mac / iOS.

They also describe more precisely what is going to happen.

[davidolsan]

Nested accordion

What

An accordion nested inside accordion

Why

• Inline admin form used by FE Providers to quickly update and edit course information has high-level sections. The course list is hidden by the default. By opening inner accordion providers are able to see all the instances of their courses.

[timpaul]

Thanks for posting this example @davidolsan.

Just as an aside, we'd recommend positioning checkbox labels to the right of their inputs, as it makes it easier for users of screen readers to discover them.

We'll update the guidance to reflect this.

[StephenHill-NHSBSA]

For what it's worth (mentioned previously by others) - we found in our service that when we originally had the + icons to the right, people often missed the fact that it was an accordion and often clicked 'No, I do not get any of these benefits' despite in fact having one a benefit that was actually an option.

Our fix was to move these to the left, and put 'show' underneath each title. This tested a lot better with users and since doing this we've had very few problems.

[mschwendener]

Or put the + in front of Show, in the second line?

[StephenHill-NHSBSA]

Or put the + in front of Show, in the second line?

Potentially. What you see above was our first iteration at trying to improve this for our users and since doing so we haven't had any further issues - but I'm sure there could be some further A / B testing if needs be.

[TMDX]

To add a bit to this discussion from a slightly different context.

We're in the process of designing a service that contains a potentially information dense transaction summary screen. We adopted accordions to separate out sections of the transaction (in our case types of intellectual property rights). Our implementation of the accordion contains a number in the section heading, see below:

All data contained within the screenshots below has been mocked up for demonstration purposes and is not representative of any real entity.

Closed accordion:

Open accordion:

In a previous iteration; given the context of the element and the screen, when tested users believed the 'plus' and 'minus' icons related to adding or removing items in the transaction. Users were sometime hesitant to click on the sections because of this. We resolved it by opting for 'chevrons' as seen in the 'Check MOT' service. So far this has tested much more positively.

[frankieroberto]

@TMDX thanks. Would you be interested in opening a Pull Request to govuk-frontend to add your chevron icons as an alternative option, so that others could potentially use it too?

[TMDX]

@frankieroberto Certainly. However, the credit for the icons goes to the 'Check MOT service'.

[edwardhorsford]

I've referenced this component in the discussion on secondary buttons.

It's using a button close all styled mostly as a link (missing the underline styling). I wonder if this needs any extra semantics? how does it work for voice dictation users?

I appreciate the accordions themselves are also buttons with similar styling - though the context of their appearance makes them fell less 'linky' to me.

[frankieroberto]

@edwardhorsford this actually came up during development. I think we specifically changed the element from an <a> to a <button> in order to get the button semantics (eg for voice dictation users).

The design (blue but without underline) is a bit of a deliberate halfway house between buttons and links, to make them look clickable without looking like a link. The section headers use a similar style (but also with a background colour on hover) for the same reason

[a184studio]

@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.

Hi Frankie,

I know that the use of (+) (-) and (ARROW) as they can mean multiple things in multiple scenarios. (+) could mean add, (-) could be remove, same for the (ARROWs) could be for move up or down within a list. Also how you have illustrated above for reveal more.

Have you seen any evidence, say in testing and with screen readers for using icons instead of saying OPEN, or SHOW for each one of those sections?

[frankieroberto]

@a184studio hiya. I've not personally tested any alternative designs (using arrows or words). I can see that the icons might pose issues in some contexts though.

If you see any issues within your service, it'd be great to know about them. Cheers!

[a184studio]

@frankieroberto Thanks for the reply. I will do. I've just started looking into this today. I'll share what I come up with ASAP.

[a184studio]

@frankieroberto Hi Franie, Do you have the code to target and override the text for "OPEN ALL", I want to change it so show and HIDE ALL / SHOW ALL, as OPEN means something, we just need to SHOW it at this stage.

Thanks.

[tmakin]

@a184studio That behaviour is not customisable via configuration as the text is hardcoded in the JS component. One option might be to override the Accordion.prototype.initControls and Accordion.prototype.updateOpenAllButton functions. See source for more info: https://github.com/alphagov/govuk-frontend/blob/master/src/govuk/components/accordion/accordion.js

Would be great if there was a tidier way to do this as it would help with customisation/localisation e.g.

Accordion.prototype.getOpenCloseText(expanded) {
  return expanded ? 'Custom close all' : 'Custom open all'
}

Or perhaps an optional config param on the constructor. e.g.

new Accordion($module, config) {
 config = config || {};
 this.openAllText = config.openAllText || 'Open All';
 etc. 
}

[frankieroberto]

@tmakin @a184studio right now, the 'best' option is probably to fork the Accordion javascript and update the text within your fork. Not ideal, I know.

The Design System team have an open issue around considering how best to allow text within javascript components (eg the Accordion and Character Count) to be customised or translated. See https://github.com/alphagov/govuk-frontend/issues/1325 (part of this epic: https://github.com/alphagov/govuk-frontend/issues/1389). See also this previous request: https://github.com/alphagov/govuk-frontend/pull/1328

I'm sure they'd welcome your thoughts on how best you'd expect to be able to do this – eg via data attributes in the HTML, or configuration options in the javascript, or something else.

[a184studio]

@frankieroberto @tmakin Thanks for the feed back. See attached. This is just a test, so things read incorrectly. Also there is a lot of actions, so needs to be simplified more if we can. Should possibly say SHOW all, as we previously talked about, (+) (-) meaning different things.

I'll investigate those other boards.

[jennifer-hodgson]

Hi folks,

A colleague has noticed what appears to be an issue with the accordion pattern: deep links to an anchor in another section do not work if the section is not expanded.

We've encountered the issue specifically on our HMRC content style guide, which uses the GOV.UK Accordion pattern. See, for example, the entry for "duty" linking through to "capitalisation of taxes, duties and levies".

[NickColley]

@jennifer-hodgson hey Jen, thanks for letting us know about this, so that the team can triage this properly and consider if there's anything we can do I've raised this as a separate issue on the GOV.UK Frontend repo: https://github.com/alphagov/govuk-frontend/issues/1581

[jennifer-hodgson]

@nickcolley - thanks for picking that up. Appreciate your help!

J

[sunerl]

Here are a few articles on the placement of the (plus/minus) icon in the accordion. Maybe consider user testing if the placement of the icon have any influence on usability as these articles indicate. http://uxmovement.com/navigation/where-to-place-your-accordion-menu-icons/ https://www.viget.com/articles/testing-accordion-menu-designs-iconography/

[36degrees]

We had a report of an accessibility audit flagging not being able to tab to the accordion plus/minus 'control'.

The plus/minus is not actually a separate control, and clicking it has the same effect as clicking the section heading (which is in the tab order) or anywhere in the section header.

https://github.com/alphagov/govuk-frontend/issues/1770

We think that this was only raised as an issue as a result of the synthetic nature of an audit environment, and so for now we've closed the issue. However, we'd be keen to hear if anyone observes participants confused by this in user research.

[andyjones81]

Is it possible to configure the accordion so that it is always set to closed whenever the page loads, rather than the last state it was in?

[hannalaakso]

@awjdigital There isn't currently a way to do this. We can discuss this with the team to see if it could be added. Did the need to do this come out of some user research? (Knowing the user need will help us us determine priority and write the relevant guidance.)

[andyjones81]

Hi, yes it came out of user research we’re doing right now - and almost all of our participants have commented that they’d expect the accordion to be collapsed when they go back to it afterwards.

As a hack we could assign a uniqueID on each page load but that’s a bit overkill.

On 16 Apr 2020, at 18:32, Hanna notifications@github.com wrote:



@awjdigitalhttps://github.com/awjdigital There isn't currently a way to do this. We can discuss this with the team to see if it could be added. Did the need to do this come out of some user research? (Knowing the user need will help us us determine priority and write the relevant guidance.)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://github.com/alphagov/govuk-design-system-backlog/issues/1#issuecomment-614791390, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AKFTZD5XLDE75B4HVVZWIP3RM46LLANCNFSM4ELMSXXQ.

[hannalaakso]

Thanks @awjdigital I've assigned a label to look at this in our team triage session next week.

[hannalaakso]

@awjdigital Thanks again for raising this. We discussed it as a team. As the feature would add complexity to the component and the available options (the public API), there would need to be a good reason to add it.

Did any users get blocked or struggle to complete a task as a result? What was the context of testing and the content used in the accordion?