Update descriptions for Nunjucks macro options + fixes

packages/govuk-frontend/src/govuk/components/accordion/accordion.yaml

@@ -2,7 +2,7 @@ params:
   - name: id
     type: string
     required: true
-    description: Must be unique across the domain of your service if `rememberExpanded` is `true` (as the expanded state of individual instances of the component persists across page loads using [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)). Used as an `id` in the HTML for the accordion as a whole, and also as a prefix for the `id`s of the section contents and the buttons that open them, so that those `id`s can be the target of `aria-labelledby` and `aria-control` attributes.
+    description: Must be unique across the domain of your service if `rememberExpanded` is `true` (as the expanded state of individual instances of the component persists across page loads using [session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)). Used as an `id` in the HTML for the accordion as a whole, and also as a prefix for the `id`s of the section contents and the buttons that open them, so that those `id`s can be the target of `aria-labelledby` and `aria-control` attributes.
   - name: headingLevel
     type: integer
     required: false
@@ -30,7 +30,7 @@ params:
   - name: hideSectionAriaLabelText
     type: string
     required: false
-    description: Text made available to assistive technologies, like screen-readers, as the final part of the toggle's accessible name when the section is expanded. Defaults to 'Hide this section'.
+    description: Text made available to assistive technologies, like screen-readers, as the final part of the toggle's accessible name when the section is expanded. Defaults to `"Hide this section"`.
   - name: showAllSectionsText
     type: string
     required: false
@@ -42,16 +42,16 @@ params:
   - name: showSectionAriaLabelText
     type: string
     required: false
-    description: Text made available to assistive technologies, like screen-readers, as the final part of the toggle's accessible name when the section is collapsed. Defaults to 'Show this section'.
+    description: Text made available to assistive technologies, like screen-readers, as the final part of the toggle's accessible name when the section is collapsed. Defaults to `"Show this section"`.
   - name: items
     type: array
     required: true
-    description: An array of sections within the accordion.
+    description: The sections within the accordion.
     params:
       - name: heading
         type: object
         required: true
-        description: The heading of each section.
+        description: The heading of each accordion section.
         params:
           - name: text
             type: string
@@ -64,7 +64,7 @@ params:
       - name: summary
         type: object
         required: false
-        description: The summary line of each section.
+        description: The summary line of each accordion section.
         params:
           - name: text
             type: string
@@ -77,7 +77,7 @@ params:
       - name: content
         type: object
         required: true
-        description: The content of each section.
+        description: The content of each accordion section.
         params:
           - name: text
             type: string

packages/govuk-frontend/src/govuk/components/back-link/back-link.yaml

@@ -2,11 +2,11 @@ params:
   - name: text
     type: string
     required: false
-    description: Text to use within the back link component. If `html` is provided, the `text` option will be ignored. Defaults to 'Back'.
+    description: Text to use within the back link component. If `html` is provided, the `text` option will be ignored. Defaults to `"Back"`.
   - name: html
     type: string
     required: false
-    description: HTML to use within the back link component. If `html` is provided, the `text` option will be ignored. Defaults to 'Back'.
+    description: HTML to use within the back link component. If `html` is provided, the `text` option will be ignored. Defaults to `"Back"`.
   - name: href
     type: string
     required: true

packages/govuk-frontend/src/govuk/components/breadcrumbs/breadcrumbs.yaml

@@ -2,7 +2,7 @@ params:
   - name: items
     type: array
     required: true
-    description: Array of breadcrumbs item objects.
+    description: The items within breadcrumbs.
     params:
       - name: text
         type: string

packages/govuk-frontend/src/govuk/components/button/button.yaml

@@ -6,19 +6,19 @@ params:
   - name: text
     type: string
     required: true
-    description: If `html` is set, this is not required. Text for the `input`, `button` or `a` element. If `html` is provided, the `text` option will be ignored and `element` will be automatically set to `button` unless `href` is also set, or it has already been defined.
+    description: If `html` is set, this is not required. Text for the `input`, `button` or `a` element. If `html` is provided, the `text` option will be ignored and `element` will be automatically set to `"button"` unless `href` is also set, or it has already been defined.
   - name: html
     type: string
     required: true
-    description: If `text` is set, this is not required. HTML for the `button` or `a` element only. If `html` is provided, the `text` option will be ignored and `element` will be automatically set to `button` unless `href` is also set, or it has already been defined. This option has no effect if `element` is set to `input`.
+    description: If `text` is set, this is not required. HTML for the `button` or `a` element only. If `html` is provided, the `text` option will be ignored and `element` will be automatically set to `"button"` unless `href` is also set, or it has already been defined. This option has no effect if `element` is set to `"input"`.
   - name: name
     type: string
     required: false
     description: Name for the `input` or `button`. This has no effect on `a` elements.
   - name: type
     type: string
     required: false
-    description: Type of `input` or `button` – `button`, `submit` or `reset`. Defaults to `submit`. This has no effect on `a` elements.
+    description: Type for the `input` or `button` element – `"button"`, `"submit"` or `"reset"`. Defaults to `"submit"`. This has no effect on `a` elements.
   - name: value
     type: string
     required: false
@@ -30,7 +30,7 @@ params:
   - name: href
     type: string
     required: false
-    description: The URL that the button component should link to. If this is set, `element` will be automatically set to `a` if it has not already been defined.
+    description: The URL that the button component should link to. If this is set, `element` will be automatically set to `"a"` if it has not already been defined.
   - name: classes
     type: string
     required: false

packages/govuk-frontend/src/govuk/components/character-count/character-count.yaml

@@ -30,22 +30,22 @@ params:
   - name: label
     type: object
     required: true
-    description: Options for the label component.
+    description: The label used by the character count component.
     isComponent: true
   - name: hint
     type: object
     required: false
-    description: Options for the hint component.
+    description: Can be used to add a hint to the character count component.
     isComponent: true
   - name: errorMessage
     type: object
     required: false
-    description: Options for the error message component. The error message component will not display if you use a falsy value for `errorMessage`, for example `false` or `null`.
+    description: Can be used to add an error message to the character count component. The error message component will not display if you use a falsy value for `errorMessage`, for example `false` or `null`.
     isComponent: true
   - name: formGroup
     type: object
     required: false
-    description: Options for the form-group wrapper.
+    description: Additional options for the form group containing the character count component.
     params:
       - name: classes
         type: string
@@ -66,7 +66,7 @@ params:
   - name: countMessage
     type: object
     required: false
-    description: Options for the count message.
+    description: Additional options for the count message used by the character count component.
     params:
       - name: classes
         type: string

packages/govuk-frontend/src/govuk/components/checkboxes/checkboxes.yaml

@@ -6,22 +6,22 @@ params:
   - name: fieldset
     type: object
     required: false
-    description: Options for the fieldset component (for example legend).
+    description: Can be used to add a fieldset to the checkboxes component.
     isComponent: true
   - name: hint
     type: object
     required: false
-    description: Options for the hint component (for example text).
+    description: Can be used to add a hint to the checkboxes component.
     isComponent: true
   - name: errorMessage
     type: object
     required: false
-    description: Options for the error message component. The error message component will not display if you use a falsy value for `errorMessage`, for example `false` or `null`.
+    description: Can be used to add an error message to the checkboxes component. The error message component will not display if you use a falsy value for `errorMessage`, for example `false` or `null`.
     isComponent: true
   - name: formGroup
     type: object
     required: false
-    description: Options for the form-group wrapper.
+    description: Additional options for the form group containing the checkboxes component.
     params:
       - name: classes
         type: string
@@ -30,15 +30,15 @@ params:
   - name: idPrefix
     type: string
     required: false
-    description: String to prefix id for each checkbox item if no id is specified on each item. If not passed, fall back to using the name option instead.
+    description: Optional prefix. This is used to prefix the `id` attribute for each checkbox item input, hint and error message, separated by `-`. Defaults to the `name` option value.
   - name: name
     type: string
     required: true
     description: Name attribute for all checkbox items.
   - name: items
     type: array
     required: true
-    description: Array of checkbox items objects.
+    description: The checkbox items within the checkboxes component.
     params:
       - name: text
         type: string
@@ -63,17 +63,17 @@ params:
       - name: label
         type: object
         required: false
-        description: Provide attributes and classes to each checkbox item label.
+        description: Additional options for the label used by each checkbox item within the checkboxes component.
         isComponent: true
       - name: hint
         type: object
         required: false
-        description: Provide hint to each checkbox item.
+        description: Can be used to add a hint to each checkbox item within the checkboxes component.
         isComponent: true
       - name: divider
         type: string
         required: false
-        description: Divider text to separate checkbox items, for example the text 'or'.
+        description: Divider text to separate checkbox items, for example the text `"or"`.
       - name: checked
         type: boolean
         required: false
@@ -90,7 +90,7 @@ params:
       - name: behaviour
         type: string
         required: false
-        description: If set to `exclusive`, implements a 'None of these' type behaviour via JavaScript when checkboxes are clicked.
+        description: If set to `"exclusive"`, implements a 'None of these' type behaviour via JavaScript when checkboxes are clicked.
       - name: disabled
         type: boolean
         required: false

packages/govuk-frontend/src/govuk/components/cookie-banner/cookie-banner.yaml

@@ -2,7 +2,7 @@ params:
   - name: ariaLabel
     type: string
     required: false
-    description: The text for the `aria-label` which labels the cookie banner region. This region applies to all messages that the cookie banner includes. For example, the cookie message and the confirmation message. Defaults to 'Cookie banner'.
+    description: The text for the `aria-label` which labels the cookie banner region. This region applies to all messages that the cookie banner includes. For example, the cookie message and the confirmation message. Defaults to `"Cookie banner"`.
   - name: hidden
     type: boolean
     required: false
@@ -39,7 +39,7 @@ params:
       - name: actions
         type: array
         required: false
-        description: The buttons and links that you want to display in the message. `actions` defaults to `button` unless you set `href`, which renders the action as a link.
+        description: The buttons and links that you want to display in the message. `actions` defaults to `"button"` unless you set `href`, which renders the action as a link.
         params:
           - name: text
             type: string
@@ -48,11 +48,11 @@ params:
           - name: type
             type: string
             required: false
-            description: The type of button. You can set `button` or `submit`. Set `button` and `href` to render a link styled as a button. If you set `href`, it overrides `submit`.
+            description: The type of button – `"button"` or `"submit"`. If `href` is provided, set `type` to `"button"` render a link styled as a button.
           - name: href
             type: string
             required: false
-            description: The `href` for a link. Set `button` and `href` to render a link styled as a button.
+            description: The `href` for a link. Set `type` to `"button"` and set `href` to render a link styled as a button.
           - name: name
             type: string
             required: false
@@ -76,7 +76,7 @@ params:
       - name: role
         type: string
         required: false
-        description: Set `role` to `alert` on confirmation messages to allow assistive tech to automatically read the message. You will also need to move focus to the confirmation message using JavaScript you have written yourself.
+        description: Set `role` to `"alert"` on confirmation messages to allow assistive tech to automatically read the message. You will also need to move focus to the confirmation message using JavaScript you have written yourself.
       - name: classes
         type: string
         required: false

packages/govuk-frontend/src/govuk/components/date-input/date-input.yaml

@@ -6,11 +6,11 @@ params:
   - name: namePrefix
     type: string
     required: false
-    description: Optional prefix. This is used to prefix each `item.name` using `-`.
+    description: Optional prefix. This is used to prefix each item `name`, separated by `-`.
   - name: items
     type: array
     required: false
-    description: An array of input objects with name, value and classes.
+    description: The inputs within the date input component.
     params:
       - name: id
         type: string
@@ -31,7 +31,7 @@ params:
       - name: autocomplete
         type: string
         required: false
-        description: Attribute to [identify input purpose](https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose.html), for instance `bday-day`. See [autofill](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill) for full list of attributes that can be used.
+        description: Attribute to [identify input purpose](https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose.html), for instance `"bday-day"`. See [autofill](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill) for full list of attributes that can be used.
       - name: pattern
         type: string
         required: false
@@ -47,17 +47,17 @@ params:
   - name: hint
     type: object
     required: false
-    description: Options for the hint component.
+    description: Can be used to add a hint to a date input component.
     isComponent: true
   - name: errorMessage
     type: object
     required: false
-    description: Options for the error message component. The error message component will not display if you use a falsy value for `errorMessage`, for example `false` or `null`.
+    description: Can be used to add an error message to the date input component. The error message component will not display if you use a falsy value for `errorMessage`, for example `false` or `null`.
     isComponent: true
   - name: formGroup
     type: object
     required: false
-    description: Options for the form-group wrapper.
+    description: Additional options for the form group containing the date input component.
     params:
       - name: classes
         type: string
@@ -66,7 +66,7 @@ params:
   - name: fieldset
     type: object
     required: false
-    description: Options for the fieldset component (for example legend).
+    description: Can be used to add a fieldset to the date input component.
     isComponent: true
   - name: classes
     type: string

packages/govuk-frontend/src/govuk/components/error-message/error-message.yaml

@@ -22,7 +22,7 @@ params:
   - name: visuallyHiddenText
     type: string
     required: false
-    description: A visually hidden prefix used before the error message. Defaults to 'Error'.
+    description: A visually hidden prefix used before the error message. Defaults to `"Error"`.
 
 accessibilityCriteria: |
   When used with a single input, the error message MUST:

packages/govuk-frontend/src/govuk/components/error-summary/error-summary.yaml

@@ -22,7 +22,7 @@ params:
   - name: errorList
     type: array
     required: true
-    description: The list of errors to include in the summary.
+    description: The list of errors to include in the error summary.
     params:
       - name: href
         type: string

packages/govuk-frontend/src/govuk/components/exit-this-page/exit-this-page.yaml

@@ -2,15 +2,15 @@ params:
   - name: text
     type: string
     required: false
-    description: Text for the link. If `html` is provided, the `text` option will be ignored. Defaults to 'Emergency Exit this page' with 'Emergency' visually hidden.
+    description: Text for the link. If `html` is provided, the `text` option will be ignored. Defaults to `"Emergency Exit this page"` with 'Emergency' visually hidden.
   - name: html
     type: string
     required: false
-    description: HTML for the link. If `html` is provided, the `text` option will be ignored. Defaults to 'Emergency Exit this page' with 'Emergency' visually hidden.
+    description: HTML for the link. If `html` is provided, the `text` option will be ignored. Defaults to `"Emergency Exit this page"` with 'Emergency' visually hidden.
   - name: redirectUrl
     type: string
     required: false
-    description: URL to redirect the current tab to. Defaults to `https://www.bbc.co.uk/weather`.
+    description: URL to redirect the current tab to. Defaults to `"https://www.bbc.co.uk/weather"`.
   - name: id
     type: string
     required: false
@@ -26,19 +26,19 @@ params:
   - name: activatedText
     type: string
     required: false
-    description: Text announced by screen readers when Exit this Page has been activated via the keyboard shortcut. Defaults to 'Loading.'.
+    description: Text announced by screen readers when Exit this Page has been activated via the keyboard shortcut. Defaults to `"Loading."`.
   - name: timedOutText
     type: string
     required: false
-    description: Text announced by screen readers when the keyboard shortcut has timed out without successful activation. Defaults to 'Exit this page expired.'.
+    description: Text announced by screen readers when the keyboard shortcut has timed out without successful activation. Defaults to `"Exit this page expired."`.
   - name: pressTwoMoreTimesText
     type: string
     required: false
-    description: Text announced by screen readers when the user must press <kbd>Shift</kbd> two more times to activate the button. Defaults to 'Shift, press 2 more times to exit.'.
+    description: Text announced by screen readers when the user must press <kbd>Shift</kbd> two more times to activate the button. Defaults to `"Shift, press 2 more times to exit."`.
   - name: pressOneMoreTimeText
     type: string
     required: false
-    description: Text announced by screen readers when the user must press <kbd>Shift</kbd> one more time to activate the button. Defaults to 'Shift, press 1 more time to exit.'.
+    description: Text announced by screen readers when the user must press <kbd>Shift</kbd> one more time to activate the button. Defaults to `"Shift, press 1 more time to exit."`.
 
 examples:
   - name: default

packages/govuk-frontend/src/govuk/components/fieldset/fieldset.yaml

@@ -6,7 +6,7 @@ params:
   - name: legend
     type: object
     required: false
-    description: Options for the legend.
+    description: The legend for the fieldset component.
     params:
       - name: text
         type: string