Add accessibility checklists

.eleventy.js

@@ -4,6 +4,7 @@ const { DateTime } = require("luxon");
 module.exports = function(eleventyConfig) {
     // Set custom variable to decide the path prefix as it is used in a couple of places.
     const _customPathPrefix = process.env.PATH_PREFIX ?? '';
+    const _siteRoot = process.env.SITE_ROOT ?? 'http://localhost/';
     // Pass assets through to final build directory
     eleventyConfig.addPassthroughCopy({ "docs/assets/logos": "assets/logos"});
     // Register the plugins
@@ -41,6 +42,10 @@ module.exports = function(eleventyConfig) {
                         href: _customPathPrefix + '/cookies/',
                         text: 'Cookies'
                     },
+                    {
+                        href: _customPathPrefix + '/accessibility-statement/',
+                        text: 'Accessibility'
+                    },
                     {
                         href: 'https://github.com/HO-CTO/engineering-guidance-and-standards',
                         text: 'GitHub repository'
@@ -141,6 +146,7 @@ module.exports = function(eleventyConfig) {
     });
 
     eleventyConfig.addGlobalData('pathPrefix', _customPathPrefix);
+    eleventyConfig.addGlobalData('siteRoot', _siteRoot);
 
     return {
         dataTemplateEngine: 'njk',

.github/ISSUE_TEMPLATE/report_an_accessibility_issue.md

@@ -0,0 +1,42 @@
+---
+name: Report an accessibility issue
+about: Create a report to help us improve the accessibility of the site
+title: "[A11Y]"
+labels: 'accessibility'
+assignees: ''
+
+---
+
+**Describe the accessibility issue**
+A clear and concise description of what is hindering your access to the site.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. Chrome, Safari]
+ - Version [e.g. 22]
+
+**Any assistance technologies used**
+- Screen reader: [e.g. VoiceOver, JAWS etc.]
+- Navigation method: [Mouse, keyboard, speech recognition, etc.]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, Safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.github/PULL_REQUEST_TEMPLATE.md

@@ -3,6 +3,8 @@ Is this pull request a content or a code change? (Please fill in the relevant se
 # Code change
 I can confirm:
 ## Accessibility considerations
+- [ ] Please review the [accessibility checks for layout changes](https://github.com/HO-CTO/engineering-guidance-and-standards/blob/main/technical-docs/accessibility/layout-checks.md).
+
 - [ ] This change will not change layouts, page structures or anything else that might impact accessibility
 
 or
@@ -13,6 +15,8 @@ or
 (If the change might impact accessibility then please add some further information here)
 
 # Content change 
+- [ ] Please review the [accessibility checks for content changes](https://github.com/HO-CTO/engineering-guidance-and-standards/blob/main/technical-docs/accessibility/content-checks.md).
+
 I can confirm:
 - [ ] Content does not include any code or configuration changes (excluding frontmatter information)
 - [ ] Content meets the content standards

.github/workflows/build-and-deploy-main.yml

@@ -27,6 +27,7 @@ jobs:
           npm run build
         env:
           PATH_PREFIX: /engineering-guidance-and-standards/
+          SITE_ROOT: https://ho-cto.github.io/engineering-guidance-and-standards/
       - name: Upload Pages Artifact
         uses: actions/upload-pages-artifact@v2
         with:

cypress/e2e/a11y.spec.cy.js

@@ -25,13 +25,41 @@ function terminalLog(violations) {
 }
 
 describe('All pages pass axe-core accessibility checks', () => {
+  const titles = {};
+
   for(const page of pages) {
     it(`${page.title} (${page.url}) is accessible`, () => {
       cy.visit(testing_params.TEST_ROOT_URL + page.url)
       cy.injectAxe()
       cy.checkA11y({exclude: '[data-axe-exclude]'}, null, terminalLog);
     })
+
+    titles[page.title] = [
+      ...(titles[page.title] ?? []),
+      page.url
+    ];
   }
+
+  it('All pages have a unique title', () => {
+    const duplicateTitles = Object.entries(titles).filter(([_, urls]) => urls.length > 1);
+
+    const message = "Expect there to be no duplicate titles";
+
+    if(duplicateTitles.length > 0) {
+      const tableData = duplicateTitles.map(([title, urls]) => ({
+        "Title": title,
+        "URLs with this title": urls.join("\n")
+      }));
+
+      // Task doesn't run if top-level expect fails
+      cy.task('table', tableData).then(() => {
+        expect(duplicateTitles, message).to.be.empty
+      })
+    } else {
+      // Log that the check passed
+      expect(duplicateTitles, message).to.be.empty
+    }
+  })
 })
 
 describe('Tag pages pass axe-core accessibility checks', () => {

docs/about.md

@@ -1,6 +1,6 @@
 ---
 eleventyExcludeFromCollections: true
-layout: page
+layout: post
 order: 5
 title: About
 description: Find out more about what we are doing

docs/accessibility-statement.md

@@ -0,0 +1,60 @@
+---
+eleventyExcludeFromCollections: true
+layout: post
+order: 1
+title: Accessibility statement 
+description:
+tags:
+---
+
+This accessibility statement applies to the Engineering Guidance and Standards documentation site at [{{siteRoot}}]({{ siteRoot }}).
+
+This website is run by the Home Office. We want as many people as possible to be able to use this website. For example, that means you should be able to:
+
+- Change colours, contrast levels and fonts
+- Zoom in up to 200% without the text spilling off the screen
+- Navigate the website using just a keyboard
+- Navigate most of the website using speech recognition software
+- Listen to most of the website using a screen reader (including the most recent versions of JAWS, NVDA and VoiceOver)
+
+We've also made the website text as simple as possible to understand.
+
+[AbilityNet has advice on making your device easier to use](https://mcmw.abilitynet.org.uk/).
+
+## How accessible this website is
+
+Accessibility issues with the site are tracked in GitHub. You can [view a list of outstanding accessibility issues](https://github.com/HO-CTO/engineering-guidance-and-standards/issues?q=is%3Aissue+is%3Aopen+label%3Aaccessibility).
+
+## Reporting accessibility problems with this website
+
+If you are having difficulties accessing this site, please let us know. You can:
+- [Raise a new issue in GitHub](https://github.com/HO-CTO/engineering-guidance-and-standards/issues/new?assignees=&labels=accessibility&projects=&template=report_an_accessibility_issue.md&title=%5BA11Y%5D)
+- [Email us at [email protected]](mailto:[email protected])
+
+## Enforcement procedure
+
+The Equality and Human Rights Commission (EHRC) is responsible for enforcing the Public Sector Bodies (Websites and Mobile Applications) (No. 2) Accessibility Regulations 2018 (the 'accessibility regulations'). If you're not happy with how we respond to your complaint, [contact the Equality Advisory and Support Service (EASS)](https://www.equalityadvisoryservice.com/).
+
+If you are in Northern Ireland and are not happy with how we respond to your complaint, you can contact the [Equalities Commission for Northern Ireland](https://www.equalityni.org/Home) who are responsible for enforcing the 'accessibility regulations' in Northern Ireland.
+
+## Technical information about this website's accessibility
+
+The Home Office is committed to making its website accessible, in accordance with the Public Sector Bodies (Websites and Mobile Applications) (No. 2) Accessibility Regulations 2018.
+
+### Compliance status
+
+This website is compliant with the [Web Content Accessibility Guidelines version 2.1](https://www.w3.org/TR/WCAG21/) AA standard.
+
+## Non-accessible content
+
+At the time of writing there is no known non-accessible content. You can [list recently raised accessibility issues in GitHub](https://github.com/HO-CTO/engineering-guidance-and-standards/issues?q=is%3Aissue+is%3Aopen+label%3Aaccessibility).
+
+## Preparation of this accessibility statement
+
+- This statement was prepared and reviewed on 13th September 2023.
+- This website was last tested on 14th September 2023. Testing was carried out internally by the Home Office.
+
+We test this site as it develops by running automated accessibility tests provided by [`axe-core`](https://github.com/dequelabs/axe-core) on all changes, and by following a script of manual checks to perform when reviewing changes to the site. These are stored in GitHub:
+
+- [Checklist for content changes](https://github.com/HO-CTO/engineering-guidance-and-standards/blob/main/technical-docs/accessibility/content-checks.md)
+- [Checklist for layout and template changes](https://github.com/HO-CTO/engineering-guidance-and-standards/blob/main/technical-docs/accessibility/layout-checks.md)

docs/provide-feedback.md

@@ -1,6 +1,6 @@
 ---
 eleventyExcludeFromCollections: true
-layout: page
+layout: post
 order: 5
 title: Provide feedback
 description:
@@ -19,4 +19,4 @@ You will need a GitHub account in order to create an issue, which will involve a
 
 ## Get in touch directly
 
-If you do not want to raise an issue on GitHub then you can contact the members of our engineering community that maintain the site at [[email protected]](mailto:[email protected]).
+If you do not want to raise an issue on GitHub then you can contact the members of our engineering community that maintain the site at [[email protected]](mailto:[email protected]).

technical-docs/accessibility/content-checks.md

@@ -0,0 +1,40 @@
+# Checking the accessibility of a content addition or change
+
+When content is added to the site, or later updated it should be checked for accessibility issues as part of the 
+review process. 
+
+## Automated checks
+
+Most content checks are context specific and can't be assessed by automated tools. [The accessibility cypress tests](
+../../cypress/e2e/a11y.spec.cy.js) will run [axe-core](https://github.com/dequelabs/axe-core) tests against each page
+in the site. This will check for issues like empty links, skipped heading levels. As part of checking every page it will
+also verfiy that page titles are not repeated on multiple pages.
+
+## Manual checks
+
+Read through the page content. This is best done by checking out the repository and [reviewing the changes locally](
+../../README.md#preview-your-changes-locally). You should be checking the following.
+
+- [ ] The page uses plain language and avoids figures of speech, idioms, and complicated metaphors.
+- [ ] Any images have an alt tag with an accessible description of the image. This can be achieved in markdown using
+  `![Alt text](/path/to/image.png)`. If the image is decorative the alt text should be present but empty. This is
+  the default behaviour in markdown if nothing is entered between the square braces, i.e. 
+  `![](/path/to/decorative-image.png)`.
+- [ ] Any links that open a new tab or window are identified as doing so.
+- [ ] Where there is a list of things, an ordered list, unordered list, or definition list is used as appropriate. 
+  Tabular data is displayed in a table. The markdown syntax for these can be found in the Gov.uk eleventy plugin
+  documentation:
+    - [Ordered and unordered lists](https://x-govuk.github.io/govuk-eleventy-plugin/markdown/#lists)
+    - [Definition lists](https://x-govuk.github.io/govuk-eleventy-plugin/markdown-advanced/#definition-lists)
+    - [Tables](https://x-govuk.github.io/govuk-eleventy-plugin/markdown-advanced/#tables)
+- [ ] If any video or audio has been embedded in the page, these should have transcripts or captions, and should not 
+  automatically play when a user accesses the page.
+
+Open the page in an accessibility testing tool such as [WebAIM's WAVE browser plugins](https://wave.webaim.org/):
+
+- Check the focus ordering:
+    - [ ] The order should match the visible order on the page.
+    - [ ] Check through the links included in the list - does the accessible name make it clear what is being linked to.
+- Check the page structure:
+    - [ ] The order should match the visible order on the page.
+    - [ ] Check through the headings - does the accessible name make it clear what that section is about.

technical-docs/accessibility/layout-checks.md

@@ -0,0 +1,33 @@
+# Checking the accessibility of a layout or template change
+
+When changes are made to the templates that layout the pages in the site, the accessibility of the site should be 
+checked as part of the review process. 
+
+## Automated checks
+
+[The accessibility cypress tests](../../cypress/e2e/a11y.spec.cy.js) will run 
+[axe-core](https://github.com/dequelabs/axe-core) tests against each page in the site. This will check for issues like:
+- The html is valid, and has a defined language.
+- The page's content is contained in landmark regions, and these regions have unique roles.
+- Each page has a unique title.
+
+## Manual checks
+
+### Prerequisites
+- Check out the repository and serve the site, see 
+  [reviewing the changes locally](./../README.md#preview-your-changes-locally) for instructions.
+- You may need to enable keyboard navigation in your operating system's settings for keyboard navigation checks to work. 
+
+Then open up example pages that will be affected by your layout changes. For each:
+
+- [ ] Tab through the focusable elements of the page. Is it clear what has focus, and does focus progress in a logical 
+  order?
+- [ ] The first item before the menu should be a link to skip to the main content, which is only visible when focussed.
+  Check this navigates to the start of the page's main content.
+- [ ] Are blocks of text left-aligned?
+- [ ] If standard content is included or generated as part of the template, check this against 
+  [the content checklist](./content-checks.md).
+- [ ] Zoom the page in to 200%. There should be no horizontal overflow. If this causes the layout to reflow check that
+  the visual order and focus order are maintained.
+- [ ] Access the page on a small screen, or use browser tools to emulate this. If this causes the layout to reflow check that
+  the visual order and focus order are maintained.