diff --git a/src/govuk/components/accordion/accordion.yaml b/src/govuk/components/accordion/accordion.yaml
index a887f780df..53a161ad09 100644
--- a/src/govuk/components/accordion/accordion.yaml
+++ b/src/govuk/components/accordion/accordion.yaml
@@ -23,11 +23,11 @@ params:
     - name: heading.text
       type: string
       required: true
-      description: The title of each section. If `heading.html` is supplied, this is ignored. This is used both as the title for each section, and as the button to open or close each section.
+      description: The title of each section. If `heading.html` is supplied, this is ignored.
     - name: heading.html
       type: string
       required: true
-      description: The HTML content of the header for each section which is used both as the title for each section, and as the button to open or close each section.
+      description: The HTML content of the header for each section. Used as the title for each section. The header is inside the HTML `<button>` element, so you can only add [phrasing content](https://html.spec.whatwg.org/#phrasing-content) to it.
     - name: summary.text
       type: string
       required: false
@@ -35,7 +35,7 @@ params:
     - name: summary.html
       type: string
       required: false
-      description: HTML content for summary line.
+      description: The HTML content for the summary line. The summary line is inside the HTML `<button>` element, so you can only add [phrasing content](https://html.spec.whatwg.org/#phrasing-content) to it.
     - name: content.text
       type: string
       required: true