Merge pull request #2427 from alphagov/header-navigation

Improve the screen reader experience for the header menu

CHANGELOG.md

@@ -63,6 +63,21 @@ Do not include an empty `<span class="govuk-summary-list__actions"></span>` with
 
 This change was introduced in [pull request #2323: Avoid invalid nesting of `<span>` within a `<dd>` in summary list](https://github.com/alphagov/govuk-frontend/pull/2323). Thanks to [Malcolm Hire]( https://github.com/malcolmhire) for reporting this issue.
 
+#### Update the HTML for navigation in the header
+
+We've updated the HTML for the header. This update only affects you if your header includes navigation.
+
+Any additional classes passed using the `navigationClasses` Nunjucks option are now applied to the `<nav>` rather than the `<ul>`. Check that the additional classes are still doing what you expect.
+
+If you're not using Nunjucks macros, then you should move:
+
+- the `<button>` inside the `<nav>`, immediately before the `<ul>`
+- the `aria-label` from the `<ul>` to the `<nav>`
+
+Check your changes against the [header example in the Design System](https://design-system.service.gov.uk/components/header/#header-with-service-name-and-navigation).
+
+This change was introduced in [pull request #2427: Improve the screen reader experience for the header menu](https://github.com/alphagov/govuk-frontend/pull/2427).
+
 #### Make sure components that conditionally reveal other questions still work as expected
 
 On radios and checkboxes, the JavaScript now looks within the whole page for conditionally revealed content. Before, it only looked within the same set of radios or checkboxes.

src/govuk/components/header/_index.scss

@@ -206,16 +206,18 @@
   }
 
   .govuk-header__navigation {
-    display: block;
-    margin: 0;
-    padding: 0;
-    list-style: none;
-
     @include govuk-media-query ($from: desktop) {
       margin-bottom: govuk-spacing(2);
     }
   }
 
+  .govuk-header__navigation-list {
+    // Reset user-agent default list styles
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
   .js-enabled {
     .govuk-header__menu-button {
       display: block;
@@ -224,14 +226,14 @@
       }
     }
 
-    .govuk-header__navigation {
+    .govuk-header__navigation-list {
       display: none;
       @include govuk-media-query ($from: desktop) {
         display: block;
       }
     }
 
-    .govuk-header__navigation--open {
+    .govuk-header__navigation-list--open {
       display: block;
     }
   }

src/govuk/components/header/header.js

@@ -21,7 +21,7 @@ Header.prototype.init = function () {
     return
   }
 
-  this.syncState(this.$menu.classList.contains('govuk-header__navigation--open'))
+  this.syncState(this.$menu.classList.contains('govuk-header__navigation-list--open'))
   this.$menuButton.addEventListener('click', this.handleMenuButtonClick.bind(this))
 }
 
@@ -45,7 +45,7 @@ Header.prototype.syncState = function (isVisible) {
  * sync the accessibility state and menu button state
  */
 Header.prototype.handleMenuButtonClick = function () {
-  var isVisible = this.$menu.classList.toggle('govuk-header__navigation--open')
+  var isVisible = this.$menu.classList.toggle('govuk-header__navigation-list--open')
   this.syncState(isVisible)
 }
 

src/govuk/components/header/header.test.js

@@ -68,8 +68,8 @@ describe('Header navigation', () => {
       })
 
       it('adds the --open modifier class to the menu, making it visible', async () => {
-        const hasOpenClass = await page.$eval('.govuk-header__navigation',
-          el => el.classList.contains('govuk-header__navigation--open')
+        const hasOpenClass = await page.$eval('.govuk-header__navigation-list',
+          el => el.classList.contains('govuk-header__navigation-list--open')
         )
 
         expect(hasOpenClass).toBeTruthy()
@@ -102,8 +102,8 @@ describe('Header navigation', () => {
       })
 
       it('removes the --open modifier class from the menu, hiding it', async () => {
-        const hasOpenClass = await page.$eval('.govuk-header__navigation',
-          el => el.classList.contains('govuk-header__navigation--open')
+        const hasOpenClass = await page.$eval('.govuk-header__navigation-list',
+          el => el.classList.contains('govuk-header__navigation-list--open')
         )
 
         expect(hasOpenClass).toBeFalsy()

src/govuk/components/header/template.njk

@@ -54,9 +54,10 @@
     </a>
     {% endif %}
     {% if params.navigation %}
-    <button type="button" class="govuk-header__menu-button govuk-js-header-toggle" aria-controls="navigation" aria-label="{{ params.menuButtonLabel | default('Show or hide navigation menu') }}">Menu</button>
-    <nav>
-      <ul id="navigation" class="govuk-header__navigation {{ params.navigationClasses if params.navigationClasses }}" aria-label="{{ params.navigationLabel | default('Navigation menu') }}">
+    <nav aria-label="{{ params.navigationLabel | default('Menu') }}" class="govuk-header__navigation {{ params.navigationClasses if params.navigationClasses }}">
+      <button type="button" class="govuk-header__menu-button govuk-js-header-toggle" aria-controls="navigation" aria-label="{{ params.menuButtonLabel | default('Show or hide menu') }}">Menu</button>
+
+      <ul id="navigation" class="govuk-header__navigation-list">
         {% for item in params.navigation %}
           {% if item.text or item.html %}
             <li class="govuk-header__navigation-item{{ ' govuk-header__navigation-item--active' if item.active }}">

src/govuk/components/header/template.test.js

@@ -109,7 +109,7 @@ describe('header', () => {
       const $ = render('header', examples['with navigation'])
 
       const $component = $('.govuk-header')
-      const $list = $component.find('ul.govuk-header__navigation')
+      const $list = $component.find('ul.govuk-header__navigation-list')
       const $items = $list.find('li.govuk-header__navigation-item')
       const $firstItem = $items.find('a.govuk-header__link:first-child')
       expect($items.length).toEqual(4)
@@ -121,18 +121,18 @@ describe('header', () => {
       const $ = render('header', examples['with navigation'])
 
       const $component = $('.govuk-header')
-      const $list = $component.find('ul.govuk-header__navigation')
+      const $nav = $component.find('nav')
 
-      expect($list.attr('aria-label')).toEqual('Navigation menu')
+      expect($nav.attr('aria-label')).toEqual('Menu')
     })
 
     it('allows navigation label to be customised', () => {
       const $ = render('header', examples['with custom navigation label'])
 
       const $component = $('.govuk-header')
-      const $list = $component.find('ul.govuk-header__navigation')
+      const $nav = $component.find('nav')
 
-      expect($list.attr('aria-label')).toEqual('Custom navigation label')
+      expect($nav.attr('aria-label')).toEqual('Custom navigation label')
     })
 
     it('renders navigation with active item', () => {
@@ -191,7 +191,7 @@ describe('header', () => {
 
         const $button = $('.govuk-header__menu-button')
 
-        expect($button.attr('aria-label')).toEqual('Show or hide navigation menu')
+        expect($button.attr('aria-label')).toEqual('Show or hide menu')
       })
       it('allows label to be customised', () => {
         const $ = render('header', examples['with custom menu button label'])