diff --git a/.eleventy.js b/.eleventy.js index 157cfb47..c7a5301a 100644 --- a/.eleventy.js +++ b/.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', diff --git a/.github/ISSUE_TEMPLATE/report_an_accessibility_issue.md b/.github/ISSUE_TEMPLATE/report_an_accessibility_issue.md new file mode 100644 index 00000000..a5d0200b --- /dev/null +++ b/.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. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 7a3172a9..8df37e52 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.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 diff --git a/.github/workflows/build-and-deploy-main.yml b/.github/workflows/build-and-deploy-main.yml index 4aadde00..8c1fdf82 100644 --- a/.github/workflows/build-and-deploy-main.yml +++ b/.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: diff --git a/cypress/e2e/a11y.spec.cy.js b/cypress/e2e/a11y.spec.cy.js index 8e4f15a2..7e868478 100644 --- a/cypress/e2e/a11y.spec.cy.js +++ b/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', () => { diff --git a/docs/about.md b/docs/about.md index fa23b848..e391d4ec 100644 --- a/docs/about.md +++ b/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 diff --git a/docs/accessibility-statement.md b/docs/accessibility-statement.md new file mode 100644 index 00000000..1f43af93 --- /dev/null +++ b/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 segas@digital.homeoffice.gov.uk](mailto:segas@digital.homeoffice.gov.uk) + +## 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) diff --git a/docs/provide-feedback.md b/docs/provide-feedback.md index 26dbc325..d9ffb7fa 100644 --- a/docs/provide-feedback.md +++ b/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 [segas@digital.homeoffice.gov.uk](mailto:segas@digital.homeoffice.gov.uk). \ No newline at end of file +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 [segas@digital.homeoffice.gov.uk](mailto:segas@digital.homeoffice.gov.uk). diff --git a/technical-docs/accessibility/content-checks.md b/technical-docs/accessibility/content-checks.md new file mode 100644 index 00000000..85f7aee2 --- /dev/null +++ b/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. diff --git a/technical-docs/accessibility/layout-checks.md b/technical-docs/accessibility/layout-checks.md new file mode 100644 index 00000000..07ae303e --- /dev/null +++ b/technical-docs/accessibility/layout-checks.md @@ -0,0 +1,32 @@ +# 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? + - By default, on macOS tab navigation doesn't reach all links. You will need to turn on the keyboard navigation in Settings -> Keyboard to perform this step on a MacBook. +- [ ] 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%. The page should fit horizontally within the screen, not requiring any scrolling left or right to view all the content. + - [ ] If zooming the page causes the layout to change, check that the visual order still matches the focus order +- [ ] Access the page on a small screen, or use browser tools to emulate this. If the smaller view size causes the layout to change, check that the visual order still matches the focus order.