update guidance and example

src/components/accordion/default/index.njk

@@ -10,34 +10,34 @@ layout: layout-example.njk
   items: [
     {
       heading: {
-        text: "Section A"
+        text: "Writing well for the web"
       },
       content: {
-        html: "<p class='govuk-body'>This is the content for section A.</p>"
+        html: "<p class='govuk-body'>This is the content for Writing well for the web.</p>"
       }
     },
     {
       heading: {
-        text: "Section B"
+        text: "Writing well for specialists"
       },
       content: {
-        html: "<p class='govuk-body'>This is the content for section B.</p>"
+        html: "<p class='govuk-body'>This is the content for Writing well for specialists.</p>"
       }
     },
       {
       heading: {
-        text: "Section C"
+        text: "Know your audience"
       },
       content: {
-        html: "<p class='govuk-body'>This is the content for section C.</p>"
+        html: "<p class='govuk-body'>This is the content for Know your audience.</p>"
       }
     },
       {
       heading: {
-        text: "Section D"
+        text: "How people read"
       },
       content: {
-        html: "<p class='govuk-body'>This is the content for section D.</p>"
+        html: "<p class='govuk-body'>This is the content for How people read.</p>"
       }
     }
   ]

src/components/accordion/index.md.njk

@@ -20,24 +20,13 @@ The accordion component lets users show and hide sections of related content on
 Only use an accordion if there's evidence it’s helpful for users to:
 
 - see an overview of multiple, related sections of content
-- expand and collapse those sections as needed
+- show and hide those sections as needed
 
-Accordions can work well for people who use a service regularly, for example, users of a caseworking system. Their need to perform tasks quickly may be greater than their need for simplicity of first-time use.
-
-### Accordions and tabs
-
-Accordions and [tabs](/components/tabs/) are similar components. They both 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
-- there are many 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.
+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.
+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:
 
@@ -46,56 +35,76 @@ Test your content without an accordion first. Consider if it’s better to:
 - 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 total amount of content it needs to contain will make the page slow to load.
+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.
 
-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.
+Consider using an accordion instead of tabs if users might need to view more than one section at a time.
 
-Do not use an accordion if your users commonly need to read through all of the content in order, for example, to understand a step-by-step process.
+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 if your users need it to.
+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.
 
-Find out the best order for the sections from user research.
+Do user research to find out the best order for the sections.
 
 ### Use clear labels
 
-Accordions hide content, so the labels need to make it very clear what they will reveal, otherwise users will not know if they need to click on them. If it’s necessary, you can also add a summary line to help users understand what is in the section.
+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 elements 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.
+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.
 
 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 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.
 
 ### Services using this component
 
 **Government Digital Service**<br/>
-Service Manual<br/>
-GOV.UK country pages, for example, [Albania](https://www.gov.uk/world/albania)<br/>
+GOV.UK Service Manual<br/>
+GOV.UK country pages<br/>
 Registers<br/>
 
-**Environment Agency**<br/>
-Flood information service
+**DVSA**<br/>
+Check the MOT history of a vehicle
 
 **Department for Education**<br/>
 Find and compare schools in England
 
 ### Next steps
-There are other approaches to accordions in government. For example [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. [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. More research is needed on these approaches.
+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.