Update error summary markup to improve screen reader announcements

CHANGELOG.md

@@ -1,5 +1,23 @@
 # NHS.UK frontend Changelog
 
+## Unreleased
+
+* Updates the error summary markup ([fixes #1035](https://github.com/nhsuk/nhsuk-frontend/issues/1035), [PR 1036](https://github.com/nhsuk/nhsuk-frontend/pull/1036))
+
+### Recommended changes - error summary markup
+
+#### Remove `aria-labelledby`, remove `id="error-summary-title"` from title and move `role="alert"` to child container on the error summary component
+
+If you’re not using the Nunjucks macros, you can improve the experience for screen reader users by making these changes to the error summary markup:
+
+- Remove `aria-labelledby="error-summary-title"` and `role="alert"` from the parent element (`nhsuk-error-summary`)
+- Add a `div` wrapper around the contents of `nhsuk-error-summary` with the attribute `role="alert"`
+- Remove `id="error-summary-title"` from the error summary `h2` (`nhsuk-error-summary__title`)
+
+This will enable screen reader users to have a better, more coherent experience with the error summary. Most notably it will ensure that users of JAWS 2022 or later will hear the entire contents of the error summary on page load and therefore have further context on why there is an error on the page they’re on. It also prevents VoiceOver from announcing 'There is a problem' twice.
+
+This was originally added in this [GOV.UK Frontend PR #2677](https://github.com/alphagov/govuk-frontend/pull/2677).
+
 ## 9.0.0 - 18 September 2024
 
 :boom: **Breaking changes**

packages/components/error-summary/template.njk

@@ -1,27 +1,32 @@
 {% from "../../macros/attributes.njk" import nhsukAttributes %}
 
 <div class="nhsuk-error-summary
-  {%- if params.classes %} {{ params.classes }}{% endif %}" aria-labelledby="error-summary-title" role="alert" tabindex="-1"
+  {%- if params.classes %} {{ params.classes }}{% endif %}" tabindex="-1"
   {{- nhsukAttributes(params.attributes) }}>
-  <h2 class="nhsuk-error-summary__title" id="error-summary-title">
+  {# Keep the role="alert" in a seperate child container to prevent a race condition between
+  the focusing js at the alert, resulting in information getting missed in screen reader announcements #}
+  <div role="alert">
+    <h2 class="nhsuk-error-summary__title">
     {{ params.titleHtml | safe if params.titleHtml else params.titleText }}
-  </h2>
-  <div class="nhsuk-error-summary__body">
-    {%- if params.descriptionHtml or params.descriptionText %}
-    <p>
-      {{ params.descriptionHtml | safe if params.descriptionHtml else params.descriptionText }}
-    </p>
-    {% endif -%}
-    <ul class="nhsuk-list nhsuk-error-summary__list" role="list">
-    {%- for item in params.errorList %}
-      <li>
-      {%- if item.href %}
-        <a href="{{ item.href }}"{{- nhsukAttributes(item.attributes) }}>{{ item.html | safe if item.html else item.text }}</a>
-      {% else %}
-        {{ item.html | safe if item.html else item.text }}
-      {%- endif -%}
-      </li>
-    {%- endfor %}
-    </ul>
+    </h2>
+    <div class="nhsuk-error-summary__body">
+      {%- if params.descriptionHtml or params.descriptionText %}
+      <p>
+        {{ params.descriptionHtml | safe if params.descriptionHtml else params.descriptionText }}
+      </p>
+      {% endif -%}
+      <ul class="nhsuk-list nhsuk-error-summary__list" role="list">
+      {%- for item in params.errorList %}
+        <li>
+        {%- if item.href %}
+          <a href="{{ item.href }}"{{- nhsukAttributes(item.attributes) }}>{{ item.html | safe if item.html else item.text }}</a>
+        {% else %}
+          {{ item.html | safe if item.html else item.text }}
+        {%- endif -%}
+        </li>
+      {%- endfor %}
+      </ul>
+    </div>
   </div>
+
 </div>