govuk_publishing_components 28.9.0 → 29.0.0

data/app/views/govuk_publishing_components/components/docs/contents_list.yml

@@ -66,7 +66,7 @@ examples:
         - href: "#third-thing"
           text: Third thing
   with_custom_aria_label:
-    description: 'An aria-label string should be used to contextualise the navigation for assistive technology. Defaults to "Contents" if aria-label is not passed.'
+    description: 'An `aria-label` string should be used to contextualise the navigation for assistive technology. Defaults to `Contents` if `aria-label` is not passed.'
     data:
       aria_label: "Pages in this guide"
       contents:

data/app/views/govuk_publishing_components/components/docs/contextual_breadcrumbs.yml

@@ -25,7 +25,7 @@ examples:
       content_item:
         title: "A content item"
   inverse:
-    description: Passes the 'inverse' option to the breadcrumbs, if shown.
+    description: Passes the `inverse` option to the breadcrumbs, if shown.
     data:
       content_item:
         title: "Another content item"

data/app/views/govuk_publishing_components/components/docs/contextual_guidance.yml

@@ -15,7 +15,7 @@ shared_accessibility_criteria:
   - link
 examples:
   default:
-    description: Reveals a contextul guidance on the side overflowing the container
+    description: Reveals a contextual guidance on the side overflowing the container
     data:
       html_for: news-title
       title: Writing a news title

data/app/views/govuk_publishing_components/components/docs/contextual_sidebar.yml

@@ -86,33 +86,6 @@ examples:
                       - text: The Highway Code
                         href: "/guidance/the-highway-code"
                     optional: false
-  with_brexit_cta:
-    description: For documents tagged with certain taxons defined in `brexit_cta_taxon_allow_list` we show a custom Brexit call to action element.
-    data:
-      content_item:
-        title: "Transport news story"
-        content_id: "3c402d90-fe77-49b9-a8aa-1800d4fc2b3d"
-        locale: "en"
-        links:
-          ordered_related_items:
-          - title: Find an apprenticeship
-            base_path: /apply-apprenticeship
-          - title: Training and study at work
-            base_path: /training-study-work-your-rights
-          - title: Careers helpline for teenagers
-            base_path: /careers-helpline-for-teenagers
-          document_collections:
-          - title: Recruit an apprentice (formerly apprenticeship vacancies)
-            base_path: /government/collections/apprenticeship-vacancies
-            document_type: document_collection
-          - title: The future of jobs and skills
-            base_path: /government/collections/the-future-of-jobs-and-skills
-            document_type: document_collection
-          taxons:
-            - content_id: "2f8b848d-23c8-4f42-a41a-df1f81c64d0f"
-              title: "Exporting"
-              phase: "live"
-
   with_ukraine_cta:
     description: For documents tagged to the Ukraine topical event we show a custom 'Ukraine Invasion' call to action element.
     data:

data/app/views/govuk_publishing_components/components/docs/cookie_banner.yml

@@ -1,7 +1,7 @@
 name: Cookie banner
 description: Help users manage their personal data by telling them when you store cookies on their device.
 body: |
-  By default the cookie banner is shown to all users with just a link to the settings page. If JS is on this is enhanced to show accept/reject buttons if preferences aren't set, or to hide the banner if they are.
+  By default the cookie banner is shown to all users with just a link to the settings page. If JavaScript is on this is enhanced to show accept/reject buttons if preferences aren't set, or to hide the banner if they are.
 
   Setting `data-hide-cookie-banner="true"` on any link inside the banner will overwrite the default action and when clicked will dismiss the cookie banner for a period of 365 days (approx. 1 year).
 
@@ -35,7 +35,7 @@ examples:
     data:
       title: Can we store analytics cookies on your device?
       text: Analytics cookies help us understand how our website is being used.
-      confirmation_message: You’ve accepted all cookies. You can <a class='govuk-link' href='/cookies'>change your cookie settings</a> at any time.
+      confirmation_message: You’ve accepted all cookies. You can `<a class='govuk-link' href='/cookies'>change your cookie settings</a>` at any time.
       services_cookies:
         "yes":
           text: "Yes"

data/app/views/govuk_publishing_components/components/docs/date_input.yml

@@ -14,7 +14,7 @@ accessibility_criteria: |
 
   Labels use the [label component](/component-guide/label).
 
-  Avoid using autofocus and tabindex unless you have user research to support this behaviour.
+  Avoid using [`autofocus`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus) and `tabindex` unless you have user research to support this behaviour.
 govuk_frontend_components:
   - date-input
 examples:

data/app/views/govuk_publishing_components/components/docs/details.yml

@@ -22,7 +22,7 @@ examples:
       block: |
         We need to know your nationality so we can work out which elections you’re entitled to vote in. If you can’t provide your nationality, you’ll have to send copies of identity documents through the post.
   with_data_attributes:
-    description: Can be used for tracking. Tracking is applied to the summary element when the details element is opened and closed. By default, `track-label` is set to the status ("open" or "closed") unless a track_label is passed into the component.
+    description: Can be used for tracking. Tracking is applied to the summary element when the details element is opened and closed. By default, `track-label` is set to the status (`open` or `closed`) unless a `track_label` is passed into the component.
     data:
       title: Help with nationality
       data_attributes:

data/app/views/govuk_publishing_components/components/docs/devolved_nations.yml

@@ -83,7 +83,7 @@ examples:
           alternative_url: /
       type: detailed_guide
   specific_heading level:
-    description: Use a different heading level for the main link title. Defaults to `H2` if not passed.
+    description: Use a different heading level for the main link title. Defaults to `h2` if not passed.
     data:
       heading_level: 3
       national_applicability:

data/app/views/govuk_publishing_components/components/docs/document_list.yml

@@ -254,7 +254,7 @@ examples:
     context:
       right_to_left: true
   with_parts:
-    description: Display child items, such as parts of guides or travel advice. Child items accept the same paramaters as parent items.
+    description: Display child items, such as parts of guides or travel advice. Child items accept the same parameters as parent items.
     data:
       items:
       - link:
@@ -285,7 +285,7 @@ examples:
 
       Locales can be set separately for the document link text and individual metadata items. To set link text locale, pass a locale attribute along with the link object. To set metadata locale, pass a locale attribute containing a parallel object to your metadata (depending on which metadata have translations and which need a lang attribute to specify that they are in a different language).
 
-      The lang attribute must be set to a [valid BCP47 string](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang#Language_tag_syntax). A valid code can be the two or three letter language code - for example, English is en or eng, Korean is ko or kor - but if in doubt please check.
+      The lang attribute must be set to a [valid BCP47 string](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang#Language_tag_syntax). A valid code can be the two or three letter language code - for example, English is `en` or `eng`, Korean is `ko` or `kor` - but if in doubt please check.
     data:
       items:
       - link:

data/app/views/govuk_publishing_components/components/docs/error_alert.yml

@@ -3,7 +3,7 @@ description: Used at the top of the page, to summarise a unsuccessful user actio
 accessibility_criteria: |
   - should be focused on page load, to ensure the message is noticed by
     assistive tech
-  - Should have a role of ‘alert’ to communicate that is a important and
+  - Should have a role of `alert` to communicate that is a important and
     time sensitive message
 examples:
   default:

data/app/views/govuk_publishing_components/components/docs/error_summary.yml

@@ -45,9 +45,9 @@ examples:
       title: Message to alert the user to a problem goes here
       description: Optional description of the errors and how to correct them
       items:
-      - text: Descriptive link to the question with an error oppening in a new window
+      - text: Descriptive link to the question with an error opening in a new window
         href: '#example-error-1'
         target: '_blank'
-      - text: Descriptive link to the question with an error oppening in the same window
+      - text: Descriptive link to the question with an error opening in the same window
         href: '#example-error-2'
         target: '_self'

data/app/views/govuk_publishing_components/components/docs/feedback.yml

@@ -19,7 +19,7 @@ accessibility_criteria: |
   * indicate when they have focus
   * be recognisable as form input elements
   * have correctly associated labels
-  * be of the appropriate type for their use, e.g. password inputs should be of type 'password'
+  * be of the appropriate type for their use, e.g. password inputs should be of type `password`
 shared_accessibility_criteria:
   - link
 examples:

data/app/views/govuk_publishing_components/components/docs/fieldset.yml

@@ -3,7 +3,7 @@ description: The fieldset element is used to group several controls within a web
 body: |
   [Using the fieldset and legend elements](https://accessibility.blog.gov.uk/2016/07/22/using-the-fieldset-and-legend-elements/)
 
-  You can use the 'text' property or pass 'text' as a block.
+  You can use the `text` property or pass `text` as a block.
 accessibility_criteria: |
   - must give inputs within the fieldset context with legend text
 examples:
@@ -29,7 +29,7 @@ examples:
           <input type="radio" id="passport-no" name="default">
           <label for="passport-no">No</label>
   with_heading:
-    description: Make the legend different sizes. Valid options are 's', 'm', 'l' and 'xl'.
+    description: Make the legend different sizes. Valid options are `s`, `m`, `l` and `xl`.
     data:
       legend_text: 'Do you have a driving license?'
       heading_level: 2
@@ -42,7 +42,7 @@ examples:
           <input type="radio" id="level-no" name="default">
           <label for="level-no">No</label>
   with_custom_legend_size:
-    description: Make the legend different sizes. Valid options are 's', 'm', 'l' and 'xl'.
+    description: Make the legend different sizes. Valid options are `s`, `m`, `l` and `xl`.
     data:
       legend_text: 'Do you have a driving license?'
       heading_size: 'l'
@@ -54,7 +54,7 @@ examples:
           <input type="radio" id="size-no" name="default">
           <label for="size-no">No</label>
   with_error_message:
-    description: The component also accepts an error_id, or generates one automatically.
+    description: The component also accepts an `error_id`, or generates one automatically.
     data:
       legend_text: 'Do you have a passport?'
       error_message: 'Please choose an option'

data/app/views/govuk_publishing_components/components/docs/heading.yml

@@ -27,7 +27,7 @@ examples:
     description: |
       Set a different font size for the heading. Uses the [GOV.UK Frontend heading sizes](https://design-system.service.gov.uk/styles/typography/#headings) but defaults to 27px for legacy reasons. Valid options are `xl`, `l`, `m` and `s`.
 
-      This option is not tied to the heading_level option in order to give flexibility.
+      This option is not tied to the `heading_level` option in order to give flexibility.
     data:
       text: 'One big heading'
       font_size: "xl"
@@ -46,7 +46,7 @@ examples:
       text: 'Padded'
       padding: true
   with_margin:
-    description: The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having no margin bottom.
+    description: The component accepts a number for margin bottom from `0` to `9` (`0px` to `60px`) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having no margin bottom.
     data:
       text: 'Really big bottom margin'
       margin_bottom: 9
@@ -59,7 +59,7 @@ examples:
       text: 'Consultation description'
       mobile_top_margin: true
   with_border:
-    description: A top border can be applied to the component of different thicknesses. Accepted values are 1 (1px), 2 (2px) and 5 (5px). Note that this works best with padding applied.
+    description: A top border can be applied to the component of different thicknesses. Accepted values are `1` (`1px`), `2` (`2px`) and `5` (`5px`). Note that this works best with padding applied.
     data:
       text: 'With a border'
       padding: true
@@ -81,7 +81,7 @@ examples:
     description: |
       The component is used on translated pages that don’t have a translation for the text strings. This means that it could display the fallback English string if the translate method can’t find an appropriate translation. This makes sure that the lang can be set to ensure that browsers understand which parts of the page are in each language.
 
-      The lang attribute must be set to a [valid BCP47 string](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang#Language_tag_syntax). A valid code can be the two or three letter language code - for example, English is en or eng, Korean is ko or kor - but if in doubt please check.
+      The lang attribute must be set to a [valid BCP47 string](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang#Language_tag_syntax). A valid code can be the two or three letter language code - for example, English is `en` or `eng`, Korean is `ko` or `kor` - but if in doubt please check.
     data:
       text: "Ein gweinidogion"
       lang: "cy"

data/app/views/govuk_publishing_components/components/docs/hint.yml

@@ -15,7 +15,7 @@ examples:
     data:
       text: "It’s on your National Insurance card, benefit letter, payslip or P60. For example, ‘QQ 12 34 56 C’."
   with_margin_bottom:
-    description: The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to a margin bottom of 3 (15px).
+    description: The component accepts a number for margin bottom from `0` to `9` (`0px` to `60px`) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to a margin bottom of `3` (`15px`).
     data:
       text: "You qualify if you were born in the UK before June 1960."
       margin_bottom: 9

data/app/views/govuk_publishing_components/components/docs/input.yml

@@ -14,7 +14,7 @@ accessibility_criteria: |
 
   Labels use the [label component](/component-guide/label).
 
-  Avoid using autofocus and tabindex unless you have user research to support this behaviour.
+  Avoid using `autofocus` and `tabindex` unless you have user research to support this behaviour.
 govuk_frontend_components:
   - text-input
 examples:
@@ -24,12 +24,19 @@ examples:
         text: "What is your name?"
       name: "name"
   specific_input_type:
-    description: By default the input will be type="text". This parameter accepts an alternative, e.g. "search" or "email". No validation is done on this input.
+    description: By default the input will be `type="text"`. This parameter accepts an alternative, e.g. `search` or `email`. `spellcheck="false"` is the default this can be changed by passing a `true` value. Consider adding `autocomplete`. No validation is done on this input.
     data:
       label:
         text: "What is your email address?"
       name: "address"
       type: "email"
+  with_autocomplete:
+    data:
+      label:
+        text: "Automatically complete the field with a user's email address (in supporting browsers)"
+      name: "name"
+      type: "email"
+      autocomplete: "email"
   numeric_input:
     description: If input is set to `type="number"` we set the component up as described in the [GOV.UK Design System guidance](https://design-system.service.gov.uk/components/text-input/#numbers) adding `inputmode` and `pattern`. These values can be overridden if necessary.
     data:
@@ -38,7 +45,7 @@ examples:
       name: "account-number"
       type: "number"
   with_an_identifier:
-    description: Give the input a specific ID.
+    description: Give the input a specific `ID`.
     data:
       label:
         text: "Has an id"
@@ -46,11 +53,11 @@ examples:
       id: "hasid"
   with_aria_attributes:
     description: |
-      The component accepts two possible aria attributes: aria-describedby and aria-controls.
+      The component accepts two possible aria attributes: `aria-describedby` and `aria-controls`.
 
-      [aria-describedby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-describedby_attribute) is used to indicate the ID of the element that describes the input. This will be overridden in the event of an error, where the error will be used for the describedby attribute value. This example uses the ID of the main container for demonstration purposes as there aren't any useful elements with IDs in the component guide. In real use this would be passed the ID of an element that correctly described the input.
+      [`aria-describedby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-describedby_attribute) is used to indicate the `ID` of the element that describes the input. This will be overridden in the event of an error, where the error will be used for the `describedby` attribute value. This example uses the `ID` of the main container for demonstration purposes as there aren't any useful elements with `IDs` in the component guide. In real use this would be passed the `ID` of an element that correctly described the input.
 
-      aria-controls allows the addition of an aria-controls attribute, for use in places like the finders where the page is updated dynamically after value changes to the input.
+      `aria-controls` allows the addition of an `aria-controls` attribute, for use in places like the finders where the page is updated dynamically after value changes to the input.
     data:
       label:
         text: "This is an example only and may not work with a screen reader"
@@ -104,13 +111,6 @@ examples:
       name: "name"
       value: "You can't type more"
       maxlength: 10
-  with_autocomplete:
-    data:
-      label:
-        text: "Automatically complete the field with a user's email address (in supporting browsers)"
-      name: "name"
-      type: "email"
-      autocomplete: "email"
   with_custom_width:
     data:
       label:
@@ -119,17 +119,20 @@ examples:
       name: "name"
       width: 10
   with_search_icon:
+    description: |
+        Adds a search icon, [`spellcheck`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck) can also be added to indicate that the element should be, if possible, checked for spelling errors.
     data:
       label:
         text: "Search the internet"
       name: "search-box"
       type: "search"
       search_icon: true
+      spellcheck: true
   with_label_as_heading:
     description: |
-      Wraps the label in a heading tag. Valid options are 1 to 6. To adjust the size of the label/heading, use the `heading_size` option. Valid options are 's', 'm', 'l' and 'xl'.
+      Wraps the label in a heading tag. Valid options are `1` to `6`. To adjust the size of the label/heading, use the `heading_size` option. Valid options are `s`, `m`, `l` and `xl`.
 
-      Based on the [heading/label pattern](https://design-system.service.gov.uk/patterns/question-pages/) in the Design System.
+      Based on the [heading/label pattern](https://design-system.service.gov.uk/patterns/question-pages/) in the GOV.UK Design System.
     data:
       label:
         text: "This is a heading 1 and a label"

data/app/views/govuk_publishing_components/components/docs/inset_text.yml

@@ -19,7 +19,7 @@ examples:
           <a class="govuk-link" href='/foo'>Check for broken links</a>
         </div>
   with_custom_margins:
-    description: The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having margin of 6 (30px) top and bottom.
+    description: The component accepts a number for margin bottom from `0` to `9` (`0px` to `60px`) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having margin of `6` (`30px`) top and bottom.
     data:
       text: "When a failure occurs, you must submit logbook, landing and transhipment data manually to the UK Fisheries Call Centre each day and by no later than 23.59 UTC"
       margin_top: 0

data/app/views/govuk_publishing_components/components/docs/label.yml

@@ -13,7 +13,7 @@ accessibility_criteria: |
 
   - be associated with an input. The `hint_id` must match the `aria-describedby` property on the input your label is associated with.
 
-  If hint text is within a label it will be announced in its entirity by screen readers. By putting the hint alongside labels and associating hints with inputs using `aria-describedby`, then screen readers will read the label, describe the type of input (eg radio) and then read additional text. It means users of screen readers can scan and skip options as easy as people making choices with sight. [A discussion of this approach](https://github.com/alphagov/govuk_elements/issues/574).
+  If hint text is within a label it will be announced in its entirety by screen readers. By putting the hint alongside labels and associating hints with inputs using `aria-describedby`, then screen readers will read the label, describe the type of input (eg radio) and then read additional text. It means users of screen readers can scan and skip options as easy as people making choices with sight. [A discussion of this approach](https://github.com/alphagov/govuk_elements/issues/574).
 govuk_frontend_components:
   - label
 examples:

data/app/views/govuk_publishing_components/components/docs/layout_footer.yml

@@ -15,12 +15,12 @@ accessibility_criteria: |
 
   - avoid navigation landmarks or roles
 
-    The footer element alone is sufficient for such cases; while a [nav element](https://www.w3.org/TR/html52/sections.html#the-nav-element) can be used, it is usually unnecessary.
+    The footer element alone is sufficient for such cases; while a [`nav` element](https://www.w3.org/TR/html52/sections.html#the-nav-element) can be used, it is usually unnecessary.
 
     Note: This decision has been made based on prior experience seeing removal of overuse of `<nav>` elements from www.GOV.UK, which made it confusing for users of assistive technologies to know what were the most important navigation aspects of GOV.UK.
     Should be challenged if user research indicates this is an issue.
 
-  - have a role of [`contentinfo`](https://www.w3.org/TR/wai-aria-1.1/#contentinfo) at the root of the component (<footer>)
+  - have a role of [`contentinfo`](https://www.w3.org/TR/wai-aria-1.1/#contentinfo) at the root of the component (`<footer>`)
 
     Note: This decision has been made given that most uses of this role tend to be used directly on a `<footer>` element.
     Assumption made is that is most predictable for users of assistive technologies.

data/app/views/govuk_publishing_components/components/docs/lead_paragraph.yml

@@ -21,7 +21,7 @@ examples:
     context:
       dark_background: true
   custom_margin_bottom:
-    description: The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having a margin bottom of 45px.
+    description: The component accepts a number for margin bottom from `0` to `9` (`0px` to `60px`) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having a margin bottom of `45px`.
     data:
       text: This is some example text for a lead paragraph
       margin_bottom: 6

data/app/views/govuk_publishing_components/components/docs/list.yml

@@ -66,7 +66,7 @@ examples:
     description: |
       Sets the margin on the bottom of the list element.
 
-      The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having a 20px margin.
+      The component accepts a number for margin bottom from `0` to `9` (`0px` to `60px`) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having a `20px` margin.
     data:
       margin_bottom: 9
       <<: *default-example-data

data/app/views/govuk_publishing_components/components/docs/metadata.yml

@@ -359,7 +359,7 @@ examples:
       dark_background: true
   with_custom_margin_bottom:
     description: |
-      The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to the `margin-bottom` values defined in the [responsive-bottom-margin mixin](https://github.com/alphagov/govuk_publishing_components/blob/master/app/assets/stylesheets/govuk_publishing_components/components/mixins/_margins.scss#L1)
+      The component accepts a number for margin bottom from `0` to `9` (`0px` to `60px`) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to the `margin-bottom` values defined in the [responsive-bottom-margin mixin](https://github.com/alphagov/govuk_publishing_components/blob/master/app/assets/stylesheets/govuk_publishing_components/components/mixins/_margins.scss#L1)
     data:
       first_published: 14 June 2014
       last_updated: 10 September 2015

data/app/views/govuk_publishing_components/components/docs/notice.yml

@@ -3,7 +3,7 @@ description: A notice to convey and highlight information
 body: |
   The notice component replaces the notice and withdrawal notice patterns on GOV.UK.
 
-  The component accepts either a simple string description_text parameter that it wraps in a paragraph, or a description_govspeak parameter that is rendered through govspeak for more complex HTML layout.
+  The component accepts either a simple string `description_text` parameter that it wraps in a paragraph, or a `description_govspeak` parameter that is rendered through govspeak for more complex HTML layout.
 accessibility_criteria: |
   The notice must:
 
@@ -45,7 +45,7 @@ examples:
   with_locale:
     description: |
       Passing a lang value allows the content of the notice to be labelled as being a different language from surrounding content.
-      The lang attribute must be set to a [valid BCP47 string](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang#Language_tag_syntax). A valid code can be the two or three letter language code - for example, English is en or eng, Korean is ko or kor - but if in doubt please check.
+      The lang attribute must be set to a [valid BCP47 string](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang#Language_tag_syntax). A valid code can be the two or three letter language code - for example, English is `en` or `eng`, Korean is `ko` or `kor` - but if in doubt please check.
     data:
       title: 'This publication was withdrawn on 30 September 2015'
       description_govspeak: <p>This document is no longer current. We published a new version on 30 September 2015.</p>

data/app/views/govuk_publishing_components/components/docs/print_link.yml

@@ -23,7 +23,7 @@ examples:
         track-action: "clicked"
         track-label: "Print this page"
   with_custom_margins:
-    description: The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having margin level 3 on top and bottom.
+    description: The component accepts a number for margin bottom from `0` to `9` (`0px` to `60px`) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having margin level `3` on top and bottom.
     data:
       margin_top: 0
       margin_bottom: 4

data/app/views/govuk_publishing_components/components/docs/search.yml

@@ -4,7 +4,7 @@ body: |
   A search box with label and attached submit button. The component must be used within an HTML form.
   The search input has a name="q" attribute and a customisable ID and NAME.
 
-  It can be used on white or on govuk-blue using the on_govuk_blue option.
+  It can be used on white or on govuk-blue using the `on_govuk_blue` option.
 
   Markup such as heading tags can be included in the label using the label_text option. Styling is not included in the component for heading tags in labels, however this is what the search results page does.
 accessibility_criteria: |
@@ -74,7 +74,7 @@ examples:
       label_size: "xl"
   wrap_label_inside_a_heading:
     description: |
-      Puts the label inside a heading; heading level defaults to 2 if not set.
+      Puts the label inside a heading; heading level defaults to `2` if not set.
 
       (The size of the label can still be set with `label_size` to appear more like a heading.)
     data:
@@ -84,7 +84,7 @@ examples:
     description: |
       Allows the spacing at the bottom of the component to be adjusted.
 
-      This accepts a number from 0 to 9 (0px to 60px) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having no margin bottom.
+      This accepts a number from `0` to `9` (`0px` to `60px`) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having no margin bottom.
     data:
       margin_bottom: 9
   with_margin_bottom_for_the_label:
@@ -93,7 +93,7 @@ examples:
 
       Requires `inline_label` to be false.
 
-      This accepts a number from 0 to 9 (0px to 60px) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having no margin bottom.
+      This accepts a number from `0` to `9` (`0px` to `60px`) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having no margin bottom.
     data:
       label_margin_bottom: 9
       inline_label: false

data/app/views/govuk_publishing_components/components/docs/select.yml

@@ -55,7 +55,7 @@ examples:
       - text: 'Something else'
         value: 'option2'
   with_tracking:
-    description: 'Tracking can be enabled on the select component by passing a minimum of data_track_category and data_track_action. Other tracking attributes are optional. Note: tracking events do not currently fire within the component guide.'
+    description: 'Tracking can be enabled on the select component by passing a minimum of `data_track_category` and `data_track_action`. Other tracking attributes are optional. Note: tracking events do not currently fire within the component guide.'
     data:
       id: 'dropdown3'
       label: 'With tracking enabled'
@@ -103,7 +103,7 @@ examples:
       - text: 'Option three'
         value: 'option3'
   with_error:
-    description: If the user has to select an option, it is recommended that a radio button is used instead of a select, but this is not always possible. Note that error_id is optional, if it is not passed one will be generated automatically.
+    description: If the user has to select an option, it is recommended that a radio button is used instead of a select, but this is not always possible. Note that `error_id` is optional, if it is not passed one will be generated automatically.
     data:
       id: 'dropdown4-1'
       label: 'How will you be travelling to the conference?'
@@ -117,7 +117,7 @@ examples:
       - text: 'Will make own arrangements'
         value: 'option2'
   with_error_id_but_no_message:
-    description: For some selects the error message should be rendered separately but an error state is still required (currently required in smart answers). In this scenario an error_id can be passed without an error_message to highlight the component and set aria-describedby correctly.
+    description: For some selects the error message should be rendered separately but an error state is still required (currently required in smart answers). In this scenario an `error_id` can be passed without an `error_message` to highlight the component and set `aria-describedby` correctly.
     data:
       id: 'dropdown4-2'
       label: 'What lunch option would you like?'
@@ -143,7 +143,7 @@ examples:
       - text: 'Option three'
         value: 'option3'
   with_custom_label_size:
-    description: Make the label different sizes. Valid options are 's', 'm', 'l' and 'xl'.
+    description: Make the label different sizes. Valid options are `s`, `m`, `l` and `xl`.
     data:
       id: 'dropdown6'
       label: 'Bigger!'
@@ -156,7 +156,7 @@ examples:
       - text: 'Option three'
         value: 'option3'
   with_page_heading:
-    description: This adds a H1 element with a label element inside containing the text supplied.
+    description: This adds a `h1` element with a label element inside containing the text supplied.
     data:
       id: 'select-with-heading'
       label: 'This is a page heading'

data/app/views/govuk_publishing_components/components/docs/show_password.yml

@@ -38,14 +38,14 @@ examples:
         text: Please enter your password
       value: this is my password
   disable_form_submit_check:
-    description: The component sets the `autocomplete` attribute on the input to "off" so that browsers don't remember the password. This isn't reliable, so the component reverts the input type back to a password when its parent form is submitted. If this is causing conflicts with other JavaScript on your form, you can set `disable-form-submit-check` to `true` to disable this functionality and implement it yourself.
+    description: The component sets the `autocomplete` attribute on the input to `off` so that browsers don't remember the password. This isn't reliable, so the component reverts the input type back to a password when its parent form is submitted. If this is causing conflicts with other JavaScript on your form, you can set `disable-form-submit-check` to `true` to disable this functionality and implement it yourself.
     data:
       label:
         text: Please enter your password
       value: this is my password
       disable_form_submit_check: true
   set_autocomplete_attribute:
-    description: By default, autocomplete is set to `off`. This can be set to `new-password` or `current-password` to help browsers differentiate between new and current passwords.
+    description: By default, `autocomplete` is set to `off`. This can be set to `new-password` or `current-password` to help browsers differentiate between new and current passwords.
     data:
       label:
         text: Please enter your password
@@ -80,7 +80,7 @@ examples:
       - text: Look I keep telling you
       - text: This isn't your password
   with_data_attributes:
-    description: Data attributes can be passed to add to the input element. If the data attribute starts with `data-button-` this attribute will be applied to the show/hide button, instead of the input. Note that if JS is disabled, all attributes are added to the input.
+    description: Data attributes can be passed to add to the input element. If the data attribute starts with `data-button-` this attribute will be applied to the show/hide button, instead of the input. Note that if JavaScript disabled, all attributes are added to the input.
     data:
       label:
         text: Your password

data/app/views/govuk_publishing_components/components/docs/signup_link.yml

@@ -24,7 +24,7 @@ examples:
       link_text: 'Click right here to sign up!!'
       link_href: '/this-signs-you-up'
   with_custom_margin_bottom:
-    description: The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having no margin bottom.
+    description: The component accepts a number for margin bottom from `0` to `9` (`0px` to `60px`) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having no margin bottom.
     data:
       heading: 'Sign up for email notifications'
       link_text: 'Click right here to sign up!!'

data/app/views/govuk_publishing_components/components/docs/single_page_notification_button.yml

@@ -27,7 +27,7 @@ examples:
         test_attribute: "testing"
   with_margin_bottom:
     description: |
-      The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having a margin bottom of 15px.
+      The component accepts a number for margin bottom from `0` to `9` (`0px` to `60px`) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having a margin bottom of 15px.
     data:
       base_path: '/current-page-path'
       margin_bottom: 5
@@ -41,7 +41,7 @@ examples:
     description: |
       When there is more than one button on a page, we should specify their location so that Analytics can differentiate between them.
 
-      The location should have one of two values: "top" or "bottom".
+      The location should have one of two values: `top` or `bottom`.
 
       When this parameter is passed, its value is reflected in the `data-action` attribute (i.e "Unsubscribe-button-top"). When the flag is not present, `data-action` defaults to "Subscribe-button" or "Unsubscribe-button", depending on the state of the button.
     data:

data/app/views/govuk_publishing_components/components/docs/step_by_step_nav.yml

@@ -22,7 +22,7 @@ accessibility_criteria: |
   - inform the user which step the current page is in
   - be readable when only the text of the page is zoomed - achieved for the numbers and logic elements by their text being wrapped in several elements that give them a white background and ensure the text when zoomed expands to the left, not to the right, where it would obscure the step titles
 
-  The show/hide all button only needs to list the first panel id in the aria-controls attribute, rather than all of them.
+  The show/hide all button only needs to list the first panel `id` in the `aria-controls` attribute, rather than all of them.
 
   Step headings must use a button element: