From b28f809ccba174f5cffc0053d8619a7e646ff9af Mon Sep 17 00:00:00 2001
From: Hanna Laakso <hanna.laakso@digital.cabinet-office.gov.uk>
Date: Tue, 20 Jun 2023 18:32:24 +0100
Subject: [PATCH 1/2] Announce space before and after visually hidden text

Absolute positioning has the unintended consequence of removing any whitespace before or after visually hidden text from the accessibility tree. This can lead to unintelligible screen reader announcements, such as the GOV.UK search results heading being announced as "Searchall content", instead of "Search all content".

Insert a space character before and after visually hidden text using pseudo elements to ensure correct screen reader announcements of visually hidden text with surrounding whitespace. This tests well in all screen readers, regardless of whether the whitespace is before the visually hidden text ("Search all content"), after the visually hidden text ("Countries starting with A") or where the heading text is only made up visually hidden text ("Navigation menu"). The only slight issue I found is that Mac VoiceOver in Safari explicitly announces the inserted spare characters when navigating by headings - but this is unlikely to block any users and the user numbers for Mac VoiceOver are small compared to other assistive technologies.

I also looked into using `opacity: 0`, without `position: absolute` - this tested well in all screen readers and browsers, with the text visually hidden but accessible to assistive technologies. However, as it doesn't remove the element from the page flow, long visually hidden text would end up wrapping and pushing other elements down the page. Another alternative, also explored on the original ticket would be to use a non-breaking space &nbsp;. This also tested well, but would require always to be inserted in the markup along the visually hidden text, making it more of a manual fix which might also get accidentlaly removed by the next person working in the file. Another alternative would have been to use aria-label with "Search all content" but this doesn't get announced at all by JAWS and Mac VoiceOver (even though it fixes the iOS VoiceOver issue and seems to be allowable content on headings).
---
 .../src/govuk/helpers/_visually-hidden.scss          | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/packages/govuk-frontend/src/govuk/helpers/_visually-hidden.scss b/packages/govuk-frontend/src/govuk/helpers/_visually-hidden.scss
index 010362c99e..ffdc7d608c 100644
--- a/packages/govuk-frontend/src/govuk/helpers/_visually-hidden.scss
+++ b/packages/govuk-frontend/src/govuk/helpers/_visually-hidden.scss
@@ -16,6 +16,18 @@
 @mixin govuk-visually-hidden($important: true) {
   position: absolute if($important, !important, null);
 
+  // Absolute positioning has the unintended consequence of removing any
+  // whitespace surrounding visually hidden text from the accessibility tree.
+  // Insert a space character before and after visually hidden text to separate
+  // it from any visible text surrounding it.
+  &::before {
+    content: "\00a0";
+  }
+
+  &::after {
+    content: "\00a0";
+  }
+
   width: 1px if($important, !important, null);
   height: 1px if($important, !important, null);
   // If margin is set to a negative value it can cause text to be announced in

From 2d24e73ebc11b16e1c2a8dba2d9b3a6aef994c11 Mon Sep 17 00:00:00 2001
From: Hanna Laakso <hanna.laakso@digital.cabinet-office.gov.uk>
Date: Tue, 20 Jun 2023 18:44:05 +0100
Subject: [PATCH 2/2] Add examples of visually hidden text to review app

---
 .../src/views/examples/typography/index.njk   | 67 +++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/packages/govuk-frontend-review/src/views/examples/typography/index.njk b/packages/govuk-frontend-review/src/views/examples/typography/index.njk
index 073d1dec23..b7d1b59f46 100644
--- a/packages/govuk-frontend-review/src/views/examples/typography/index.njk
+++ b/packages/govuk-frontend-review/src/views/examples/typography/index.njk
@@ -536,7 +536,74 @@
 
       </section>
 
+      <section class="govuk-!-margin-top-8">
+        <h2 class="govuk-heading-l govuk-!-padding-bottom-2" style="border-bottom: 4px solid;">Visually hidden text</h2>
+
+        <h3 class="govuk-heading-m">Heading with visually hidden text at the beginning</h3>
+
+        <h4 class="govuk-heading-s"><span class="govuk-visually-hidden">Countries starting with </span>A</h4>
+
+        <h3 class="govuk-heading-m">Heading with visually hidden text at the end</h3>
+
+        <h4 class="govuk-heading-s">Search <span class="govuk-visually-hidden">all content</span></h4>
+
+        <h3 class="govuk-heading-m">Heading that is visually hidden</h3>
+
+        <h4 class="govuk-visually-hidden">Navigation menu</h4>
+
+        <hr class="govuk-section-break govuk-section-break--visible govuk-section-break--xl">
+
+        <h3 class="govuk-heading-m">Paragraph that contains visually hidden text</h3>
+
+        <p class="govuk-body">This is a paragraph <span class="govuk-visually-hidden">with some visually hidden text</span>.</p>
 
+        <hr class="govuk-section-break govuk-section-break--visible govuk-section-break--xl">
+
+        <h3 class="govuk-heading-m">Table with visually hidden text</h3>
+
+        {{ govukTable({
+          caption: "2019",
+          captionClasses: "govuk-!-margin-bottom-4",
+          head: [
+            {
+              text: "Date",
+              classes: "govuk-visually-hidden"
+            },
+            {
+              text: "Day",
+              classes: "govuk-visually-hidden"
+            },
+            {
+              text: "Name",
+              classes: "govuk-visually-hidden"
+            }
+          ],
+          rows: [
+            [
+              {
+                text: "19 April"
+              },
+              {
+                text: "Friday"
+              },
+              {
+                text: "Good Friday"
+              }
+            ],
+            [
+              {
+                text: "22 April"
+              },
+              {
+                text: "Monday"
+              },
+              {
+                text: "Easter Monday"
+              }
+            ]
+          ]
+        }) }}
+      </section>
     </div>
   </div>
 {% endblock %}