Accessibility guidance for: - Development

What developers need to do to make digital services accessible.

Use the NHS accessibility checklist for:

  • a fuller list of WCAG 2.2 success criteria and guidance for levels A and AA
  • some success criteria and best practice for level AAA

Make sure your service meets WCAG 2.2

For: Design, Development, Product and delivery, Testing

WCAG 2.2

The Web Content Accessibility Guidelines (WCAG) 2.2 add 9 new "success criteria" for improving web accessibility. 6 of the new criteria are graded at the A and AA level, which means they're a requirement for websites and mobile apps in the NHS. Learn more about the WCAG 2.2 new accessibility requirements and criteria.

See the full list of design system changes to meet the requirements.

Avoid accessibility widgets

For: Design, Development

Accessibility widgets are plugins that display as buttons, toolbars or overlays.

The widgets let users adapt the display to make it easier to read the text or have it read out to them. Some widget providers claim they make your website accessible.

Using widgets to make your website accessible

Accessibility widgets cannot make a website fully compliant with accessibility standards and they cannot protect you from legal action.

Using widgets to let people adapt the display to make it easier to read

Only explore adding extra functionality if you have evidence that both of the following apply:

  • your users need to adapt the interface (for example, change the text size or colour) or to have the text read out to them
  • they do not have the skills or software to do it through browser settings or assistive technology

If you add this sort of functionality, test it to make sure it does not cause problems for any of your users. Please share your research findings via the GitHub issue for overlays, widgets and banners.

The problems with overlays or widgets

Widgets typically sit in the banner or a corner of the page, sometimes obscuring key functionality. They often use icons that can be difficult for users to understand.

When a user clicks on the widget, by accident or on purpose, an overlay may pop up and cover up information or create a barrier that users cannot get past. People find them confusing and unhelpful.

People with access needs often use their preferred assistive technologies across all websites. Widgets only meet some access needs and only deal with one part of a user journey. They cannot hand over from one system or site to another. Widgets can also cause problems for people who use assistive technologies.

The best way to help people with access needs

The best solution for most people with access needs is a well-designed, well-structured website or service that is:

Check keyboard accessibility

For: Development, Testing

Keyboard accessibility is one of the most important parts of accessibility. It enables other input methods, including switches, speech input and screen readers.

The starting point for keyboard accessibility is to use the correct HTML for links, buttons and form controls. Use components from the service manual, if you can. They've already been tested for keyboard accessibility.

How to test with a keyboard

Check that you can use:

  • tab to progress through links and controls
  • shift-tab to reverse
  • enter to follow links
  • space to select form controls (such as checkboxes)
  • arrows for radio buttons or tabs
Checklist for each page

Check that:

  • you can tab to all links, buttons and form controls
  • you cannot tab to non-functional elements (such as headings and paragraphs)
  • you can easily see where the focus is
  • the focus does not move to hidden elements
  • the focus does not get trapped in an element
  • scripted events (for keyboard, mouse and touch) only fire when expected
  • the visual order for tabbing progress is left-to-right and top-to-bottom

Set page titles

For: Content, Development, Testing

A good page title helps users find what they want and recognise they're in the right place. It's the link that shows in search results and the first thing a screenreader will read out when the user lands on a page.

Each page title must be unique and descriptive. Keep it concise and consider putting important keywords near the beginning.

Best practice for page titles

Best practice is generally: Page name – Site name

For example: Achalasia – NHS

The first element (here "Achalasia") is the main heading of the page.

If you can, use templates to keep things consistent and use your content management system to generate what comes after dash.

Set language

For: Development, Testing

You need a small bit of markup on every page for screenreaders (and search engines) to know what language the content (or a part of the content) is in.

How to code for language

In the HTML element, set the language for the whole page to English:

<html lang="en">
or whatever language the page is in.

If there are changes of language within the page, mark these up as well:

<p>Make sure you are treated by a state healthcare provider in France (<span lang="fr">conventionné</span>).</p>

You can apply the lang attribute to any container.

Use ARIA patterns

For: Development, Testing

ARIA (Accessibility Rich Internet Applications) adds extra information that lets people who use assistive technologies know what's going on. If a component needs more description than HTML provides, you need to mark it up with an ARIA pattern.

We use simple examples of ARIA in some of the service manual components, such as details, breadcrumbs and error messages.

How to use ARIA patterns

The W3C note on using ARIA is a good introduction.

If you have a complex component, check whether it fits into a defined pattern from the ARIA authoring practices. Patterns that might be useful are:

If you use an ARIA pattern, include the ARIA attributes, take responsibility for the keyboard interactions as part of the scripting, and test it with assistive technology.

Start with the components in the service manual. They've already been tested. Another useful resource for accessible components is the Inclusive components collection.

Read more about custom components on the development page.

Discuss any custom components

For: Design, Development

The components in the service manual are well tested and ready to use. Before you design a new component, please test an existing component and show that there's a clear need for something new.

Discuss any new components with other members of your team. You need to make sure that:

  • you have good evidence that the new component is the best way of meeting the user need
  • it will be accessible
  • you test it from a technical and usability point of view
  • you can maintain and update it
  • you share what you've learnt

Test that text sizes and zooms correctly

For: Development, Testing

People use their browser to change the size of content, and people with low vision may use that to a more extreme level. The guidelines specify a level of 320 (CSS) px wide. That is equivalent to 400% for a 1280px wide browser.

Users can also override the font-family and spacing for text, which can break a fragile layout. We use this text spacing bookmarklet to test with.

How to test text sizing and zooming
  • Check what content and functionality you can see.
  • Size your browser window to 1280px wide. (You can use the web developer toolbar in Firefox or Chrome.)
  • Zoom into 400%. (Firefox needs a tweak to do this.)
  • Check that you can still see all the content and functionality, even if it involves opening show/hide elements or clicking through to another page.
  • Activate the text spacing bookmarklet.
  • Check for missing or overlapping content and that there is no horizontal scrolling.
  • Gradually zoom out to 100%, checking the text spacing at each stage.

NHS services must use a responsive design which helps with zooming and take care with layouts that limit text expansion.

Examples of layouts that cause problems
  • Fixed height containers of text often break when text spacing is changed. Use min-height instead.
  • Sticky elements, or containers that prevent scrolling, are often unusable at higher levels of zoom in landscape orientation. Use vertical media-queries to make sure there is enough space.
  • Large data tables are allowed to scroll horizontally, but you should wrap them in an element that contains the scrolling to the table, rather than making the whole page scroll.

Give users time to read and act

For: Design, Development, Testing

If you have set a time limit for inactivity (for example, on a multi-step form), make it at least 20 hours.

If you use 3rd party content that has a time limit, it should warn users clearly how much time they have left and let them extend or turn off the time limit.

There are exceptions to this when the time limit is essential, for example, for an online test or real-time event.

Use alternative text for functional images

For: Design, Development, Testing

Some images are "functional". That means that they trigger an action. If people can't see the image, they need an alternative.

Use "alt‑text" for images like PNG or JPEG. W3C has information about how to deal with different kinds of functional image, including logos.

The NHS website (nhs.uk) prefers inline SVG files for functional images. SVGs don't have an alt attribute. Instead we use aria-hidden="true" and, if there is no link text, "visually-hidden" in span tags.

For some common NHS examples of SVG functional images, see the close and search icons in the header component in the service manual. The action link is an example with link text.

Make video and other multimedia content accessible

For: Content, Design, Development, Testing

Consider using video as well as text. Some people find it easier to understand.

With all video and animation, make sure that:

  • the interface is accessible for keyboard and screen reader users (including play/pause buttons and the location slider)
  • if the user cannot see or hear it, they can still understand it

To meet the accessibility regulations for public sector organisations, most new videos you've published or updated after 23 September 2020 must have these 3 kinds of alternative content.

Audio description

Audio description provides content for people who are blind or cannot see the video well. It is additional commentary that describes what's happening on screen in between narration, including any text, graphics or scene changes in the video.

You must include an audio description for any key information that's visible on the screen but not part of the soundtrack, for example diagrams without a verbal description. If all the visual information in the video is included in the regular soundtrack, you do not need an audio description.

If the video says the same thing as the page content, you do not need an audio description but you must make it clear that the video is an alternative to the text content. Our experience tells us, however, that even in these cases audio description can be valuable to blind people, some of whom do not read the page content.

For audio description, you can do 1 of the following:

  • publish an alternative version of the video with audio description added in relevant places
  • add a separate audio description track (if the media player supports this)

If you have a separate audio description track, make sure it includes the audio description voice-over and the original video audio (mixed and synced together). The audio description track must be the same length in seconds as the main video’s audio.

Closed captions (sometimes called subtitles)

People who are Deaf or have hearing loss may find captions helpful. Closed captions are a text alternative to audio information in video and animations that you can turn on or off.

Use closed captions rather than subtitles. They look similar but subtitles are only a text alternative for dialogue, while closed captions are a text alternative for all the audio, including important background noises.

Closed captions must include:

  • the words people say
  • who is speaking, if it's not obvious, or where they are (for example, off-screen)
  • important sounds like music, laughter or a door slamming

Check that any auto-generated captions are accurate and synchronise them with the visual content.

Use a contrast ratio of 4.5:1 for the text. If possible, use a fully opaque (no transparency) coloured box behind the text. We recommend a black background with white text. Find out more about using colour and accessibility, including colour contrast.

For caption fonts, follow the typography guidance in the design system.

Transcript

Transcripts provide audio and video content for people who:

  • are both Deaf and blind
  • people who process text information better than audio and visual information

It's best practice to provide a transcript for a video but it is not required to pass WCAG2.1 AA. You must, however, provide a transcript for any audio-only content, such as a podcast.

A transcript should include all the dialogue, relevant sound effects, and audio description content.

There are rare exceptions, and you do not have to meet these requirements with videos published before 23 September 2020.

To meet an extra AAA requirement, add British Sign Language (BSL) to pre-recorded video content. Find out about the BSL quality assurance standard.

Help us improve this guidance

Share insights or feedback and take part in the discussion. We use GitHub as a collaboration space. All the information on it is open to the public.

Feedback or share insights on GitHub

Read more about how to feedback or share insights.

If you have any questions, get in touch with the service manual team.

Updated: April 2024