Update param descriptions for notification banner

Co-authored-by: Eoin Shaughnessy <eoin.shaughnessy@digital.cabinet-office.gov.uk>

src/govuk/components/notification-banner/notification-banner.yaml

@@ -2,47 +2,52 @@ params:
 - name: text
   type: string
   required: true
-  description: If `html` is set, this is not required. Text to use within the notification banner. If `html` is provided, the `text` argument will be ignored.
+  description: The text that displays in the notification banner. You can use any string with this option. If you set `html`, this option is not required and is ignored.
 - name: html
   type: string
   required: true
-  description: If `text` is set, this is not required. HTML to use within the notification banner. If `html` is provided, the `text` argument will be ignored.
+  description: The HTML to use within the notification banner. You can use any string with this option. If you set `html`, `text` is not required and is ignored.
 - name: titleText
   type: string
   required: false
-  description: Title text to use within the notification banner. Defaults to 'Important' ('Success' for success type and 'Error' for error type). If `titleHtml` is supplied, the `title` argument will be ignored.
+  description: |
+    The title text that displays in the notification banner. You can use any string with this option. Use this option to set text that does not contain HTML. The available default values are 'Important', 'Success', 'Error', and null:
+    - if you do not set `type`, `titleText` defaults to 'Important'
+    - if you set `type` to `success`, `titleText` defaults to 'Success'
+    - if you set `type` to `error`, `titleText` defaults to 'Error'
+    - if you set `titleHtml`, this option is ignored
 - name: titleHtml
   type: string
   required: false
-  description: Title HTML to use within the notification banner. If `titleHtml` is provided, the `title` argument will be ignored.
+  description: The title HTML to use within the notification banner. You can use any string with this option. Use this option to set text that contains HTML. If you set `titleHtml`, the `titleText` option is ignored.
 - name: titleHeadingLevel
   type: string
   required: false
-  description: Heading level, from 1 to 6. Default is `2`.
+  description: Sets heading level for the title only. You can only use values between `1` and `6` with this option. The default is `2`.
 - name: type
   type: string
   required: false
-  description: If `type` is set to `success` or `error`, the notification banner sets `role` to `alert` and `tabindex` to `-1`, and JavaScript moves the keyboard focus moves to the notification banner when the page loads. If `type` is not set, the notification banner defaults to setting `role` to `region` and using `aria-labelledby` to provide information for users of assistive technologies.
+  description: The type of notification to render. You can use only the `success`, `error`, or null values with this option. If you set `type` to `success` or `error`, the notification banner sets `role` to `alert`. JavaScript then moves the keyboard focus to the notification banner when the page loads. If you do not set `type`, the notification banner sets `role` to `region`.
 - name: role
   type: string
   required: false
-  description: Overrides the value of the `role` attribute for the notification banner. Defaults to `region`. If `type` is set to `success` or `error`, defaults to `alert`.
+  description: Overrides the value of the `role` attribute for the notification banner. Defaults to `region`. If you set `type` to `success` or `error`, `role` defaults to `alert`.
 - name: titleId
   type: string
   required: false
-  description: Overrides the value of the `id` attribute for the title. `id` used by the `aria-labelledby` attribute on the notification banner to provide information to users of assistive technologies. `id` defaults to `govuk-notification-banner-title` if `role` is set to `region`. If `type` is set to `success` or `error`, `id` is not rendered by default.
+  description: The `id` for the banner title, and the `aria-labelledby` attribute in the banner. Defaults to `govuk-notification-banner-title`.
 - name: disableAutoFocus
   type: boolean
   required: false
-  description: If you set 'type' to 'success' or 'error', or 'role' to 'alert', JavaScript moves the keyboard focus to the notification banner when the page loads. To disable this behaviour, set 'disableAutoFocus' to 'true'.
+  description: If you set `type` to `success` or `error`, or `role` to `alert`, JavaScript moves the keyboard focus to the notification banner when the page loads. To disable this behaviour, set `disableAutoFocus` to `true`.
 - name: classes
   type: string
   required: false
-  description: Classes to add to the notification banner.
+  description: The classes that you want to add to the notification banner.
 - name: attributes
   type: object
   required: false
-  description: HTML attributes (for example data attributes) to add to the notification banner.
+  description: The HTML attributes that you want to add to the notification banner, for example, data attributes.
 
 examples:
 - name: default