Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add accordion component #635

Merged
merged 2 commits into from
Jan 10, 2019
Merged

Add accordion component #635

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c33a651
Add accordion guidance
hannalaakso Nov 14, 2018
402e483
Update index.md.njk
Jan 10, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions src/components/accordion/default/index.njk
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
title: Accordion
layout: layout-example.njk
---

{% from "accordion/macro.njk" import govukAccordion %}

{{ govukAccordion({
id: "accordion-default",
items: [
{
heading: {
text: "Writing well for the web"
},
content: {
html: "<p class='govuk-body'>This is the content for Writing well for the web.</p>"
}
},
{
heading: {
text: "Writing well for specialists"
},
content: {
html: "<p class='govuk-body'>This is the content for Writing well for specialists.</p>"
}
},
{
heading: {
text: "Know your audience"
},
content: {
html: "<p class='govuk-body'>This is the content for Know your audience.</p>"
}
},
{
heading: {
text: "How people read"
},
content: {
html: "<p class='govuk-body'>This is the content for How people read.</p>"
}
}
]
}) }}
99 changes: 99 additions & 0 deletions src/components/accordion/index.md.njk
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
---
title: Accordion
description: The accordion component lets users show and hide sections of related content on a page
section: Components
aliases:
backlog_issue_id: 1
layout: layout-pane.njk
status: Experimental
statusMessage: This component is currently experimental because <a class="govuk-link" href="#next-steps">more research</a> is needed to validate it.
---

{% from "_example.njk" import example %}

The accordion component lets users show and hide sections of related content on a page.

{{ example({group: "components", item: "accordion", example: "default", html: true, nunjucks: true, open: false, size: "xl"}) }}

## When to use this component

Only use an accordion if there's evidence it’s helpful for users to:

- see an overview of multiple, related sections of content
- show and hide those sections as needed

Accordions can work well for people who use a service regularly, for example users of caseworking systems who need to perform familiar tasks quickly.

## When not to use this component

Accordions hide content from users and not everyone will notice them or understand how they work. For this reason do not use an accordion for content which is essential to all users.

Test your content without an accordion first. Consider if it’s better to:

- simplify and reduce the amount of content
- split the content across multiple pages
- keep the content on a single page, separated by headings
- use a list of links to let users navigate quickly to specific sections of content

Do not use the accordion component if the amount of content it would need to contain will make the page slow to load.

Accordions work best for simple content and links. Do not use accordions to split up a series of questions into sections. Use separate pages instead.

## Accordions, tabs and details

Accordions, [tabs](/components/tabs/) and [details](/components/details/) all hide sections of content which a user can choose to reveal.

Consider using an accordion instead of tabs if users might need to view more than one section at a time.

You should also take into account the number of sections of content – accordions display vertically, so they can fit more sections than horizontal tabs.

Tabs may work better for users who need to switch quickly between 2 sections. Accordions push other sections down the page when they open, but tabs do not move which makes it easier to switch.

Consider using an accordion instead of the [details](/components/details/) component if there are multiple related sections of content. The details component might be better if you only have one or 2 sections of content. The details component is less visually prominent than an accordion, so tends to work better for content which is not as important to users.

## How it works

There are 2 ways to use the accordion component. You can use HTML or, if you’re using Nunjucks or the GOV.UK Prototype Kit, you can use the Nunjucks macro.

The accordion component uses JavaScript. When JavaScript is not available, users will see all the content displayed with the section labels as headings.

### Find out how your users interact with the content

Users might need the sections they have opened to stay open if they leave and then return to the page. You can configure the accordion component to stay open.

Do user research to find out the best order for the sections.

### Use clear labels

Accordions hide content, so the labels need to be clear. If necessary, you can add a summary line to help users understand what is in the section.

{{ example({group: "components", item: "accordion", example: "with-summary-section", html: true, nunjucks: true, open: false, size: "xl"}) }}

If you struggle to come up with clear labels, it might be because the way you’ve separated the content is not clear.

### Do not disable sections

Disabling controls is normally confusing for users. If there is no content for a section, either remove the section or, if this would be confusing for your users, explain why there is no content when the section is opened.

## Research on this component

This component is experimental because there are different approaches to accordions in services. More research is needed to determine the best approach, or to know when a different approach works better.

The design for this component was originally created and tested by a team at the Government Digital Service (GDS) on the [GOV.UK Service Manual](https://www.gov.uk/service-manual) and [GOV.UK topic pages](https://designnotes.blog.gov.uk/2017/06/29/designing-new-navigation-elements-for-gov-uk/).

The team made sure the component is accessible, for example that users can interact with it using just the keyboard.

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

The hover colour is a light grey which some users might not see.

The 'Open all' button reads out as 'Open all sections' for screen readers. This is potentially confusing for users as the visual content is different to what screen readers read out.

### Next steps
Investigate the problem of some users not seeing the plus and minus icons on the right, for example people using screen magnifiers.

The plus and minus icons used in this component are the most commonly used accordion controls in government services.

However, more research is needed to find out how this compares to other approaches. For example [GOV.UK Step by step navigation](https://www.gov.uk/learn-to-drive-a-car) uses the words 'Show' and 'Hide' on the left side. [Check the MOT history of a vehicle](https://www.gov.uk/check-mot-history) uses up and down arrows instead of plus and minus icons.
127 changes: 127 additions & 0 deletions src/components/accordion/with-summary-section/index.njk
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
---
title: Accordion with summary sections
layout: layout-example.njk
---

{% from "accordion/macro.njk" import govukAccordion %}

{{ govukAccordion({
id: "accordion-with-summary-sections",
items: [
{
heading: {
text: "Understanding agile project management"
},
summary: {
text: "Introductions, methods, core features."
},
content: {
html:
'<ul class="govuk-list">
<li>
<a class="govuk-link" href="#">Agile and government services: an introduction</a>
</li>
<li>
<a class="govuk-link" href="#">Agile methods: an introduction</a>
</li>
<li>
<a class="govuk-link" href="#">Core principles of agile</a>
</li>
</ul>'
}
},
{
heading: {
text: "Working with agile methods"
},
summary: {
text: "Workspaces, tools and techniques, user stories, planning."
},
content: {
html:
'<ul class="govuk-list">
<li>
<a class="govuk-link" href="#">Creating an agile working environment</a>
</li>
<li>
<a class="govuk-link" href="#">Agile tools and techniques</a>
</li>
<li>
<a class="govuk-link" href="#">Set up a team wall</a>
</li>
<li>
<a class="govuk-link" href="#">Writing user stories</a>
</li>
<li>
<a class="govuk-link" href="#">Planning in agile</a>
</li>
<li>
<a class="govuk-link" href="#">Deciding on priorities</a>
</li>
<li>
<a class="govuk-link" href="#">Developing a roadmap</a>
</li>
</ul>'
}
},
{
heading: {
text: "Governing agile services"
},
summary: {
text: "Principles, measuring progress, spending money."
},
content: {
html:
'<ul class="govuk-list">
<li>
<a class="govuk-link" href="#">Governance principles for agile service delivery</a>
</li>
<li>
<a class="govuk-link" href="#">Measuring and reporting progress</a>
</li>
<li>
<a class="govuk-link" href="#">Spend controls: check if you need approval to spend money on a service</a>
</li>
<li>
<a class="govuk-link" href="#">Spend controls: apply for approval to spend money on a service</a>
</li>
<li>
<a class="govuk-link" href="#">Spend controls: the new pipeline process</a>
</li>
<li>
<a class="govuk-link" href="#">Working across organisational boundaries</a>
</li>
</ul>'
}
},
{
heading: {
text: "Phases of an agile project"
},
summary: {
text: "Discovery, alpha, beta, live and retirement."
},
content: {
html:
'<ul class="govuk-list">
<li>
<a class="govuk-link" href="#">How the discovery phase works</a>
</li>
<li>
<a class="govuk-link" href="#">How the alpha phase works</a>
</li>
<li>
<a class="govuk-link" href="#">How the beta phase works</a>
</li>
<li>
<a class="govuk-link" href="#">How the live phase works</a>
</li>
<li>
<a class="govuk-link" href="#">Retiring your service</a>
</li>
</ul>'
}
}
]
}) }}
6 changes: 6 additions & 0 deletions src/javascripts/govuk-frontend.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import Accordion from 'govuk-frontend/components/accordion/accordion'
import Button from 'govuk-frontend/components/button/button'
import Details from 'govuk-frontend/components/details/details'
import CharacterCount from 'govuk-frontend/components/character-count/character-count'
Expand All @@ -9,6 +10,11 @@ import Tabs from 'govuk-frontend/components/tabs/tabs'

new Button(document).init()

var $accordion = document.querySelector('[data-module="accordion"]')
if ($accordion) {
new Accordion($accordion).init()
}

var $details = document.querySelector('details')
if ($details) {
new Details($details).init()
Expand Down