Quick start guide

Below are the web essentials you’ll need to make your site accessible. Other handbook pages explain why these standards are critical to your site. This page tells you how to quickly implement the standards, with WordPress-specific code examples, guidelines, and best-practices.

Webpage Navigation Webpage Navigation

Assistive Technologies (AT), such as screen-readers, offer multiple ways to navigate a webpage. These include a linked-list of all the page’s HTML Headings, another list of the page’s Links, and a third of its Landmarks (ARIA roles).

The better your page’s structure and semantics, the more navigable and understandable it is for users and search engines.

Headings Headings

  • Put your document title in an h1 element.
  • Nest your page sections and subsections in a sequential hierarchy of h2h6.
  • Don’t skip levels: For instance, always follow an h2 with either a h2 (child subsection heading) or a h2 (sibling section) but never an out-of-sequence h3.
  • Never use headings for visual effects only, e.g., to bold text or increase font size.

Top ↑

  • Use meaningful link text to describe the resource: Never “click here” or “more info”.
  • Avoid the title attribute in anchor elements (<a>).
  • Avoid the target attribute in anchor elements.
  • Provide :focus and :active link highlighting.
  • Underline links if they are outside navigation menus. Do not rely on color alone.
  • Include the document title in “Read More” links (can be screen-reader-only text).

This is an example of “read-more-links” from the WP Accessibility theme patterns.

<?php
/* translators: %s: Name of current post */
the_content( sprintf(
    __( 'Continue reading %s', 'theme_text_domain' ),
    the_title( '<span class="screen-reader-text">', '</span>', false )
    )
);
?>

These are screenshots of a screen-reader’s Links navigation panel:

Screen-reader: Links navigation panel: useful link text

Useful link text

Screen-reader: Links navigation panel: useless link text, e.g., click here

Useless link text

Tip: The Theme Handbook discusses link text and styles in greater depth.

Top ↑

HTML5 sectioning elements HTML5 sectioning elements

  • Use HTML sectioning elements: <header>, <nav>, <main> (only once per page), <aside>, and <footer>.
  • Put all parts of a webpage inside one of the above elements (leave nothing orphaned).
  • Add an aria-label to distinguish the same sectioning element used more than once (see navigation in example below).
  • On a search form: add the role search (discussion about where to add the role=search)

Here’s a simplistic <body> structure with sectioning elements matched to landmarks (along with each’s typical location in a WordPress theme template):

<header><!-- header.php -->
  <nav aria-label="Primary Menu"><!-- header.php --></nav>
  <form role="search"><!-- searchform.php --></form>
</header>

<main ><!-- singular.php -->   
  <article><!-- content.php --></article>
</main>

<aside ><!-- sidebar.php --></aside>

<footer><!-- footer.php -->
    <nav aria-label="Footer Menu">
</footer>

Note: Your actual theme template code will have other features like CSS attributes and internationalization.

Examples of HTML sectioning elements when used in a WordPress theme:

<nav id="site-navigation" class="main-navigation" aria-label="<?php esc_attr_e( 'Primary Menu', 'textdomain' ); ?>"
    <!-- Nav menu items. -->
</nav>

<article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
    <!-- Article content. -->
</article>

Top ↑

Landmarks (for older browsers) Landmarks (for older browsers)

Older browsers (i.e. Internet Explorer 8 or less) don’t support HTML sectioning elements. If you need to support them you should use ARIA landmarks:

  • Identify the regions of a page with the ARIA landmark roles: banner, navigation, main, complementary, and contentinfo.
  • Apply these landmarks only once per page: banner, main, and contentinfo.

Examine the Twenty Sixteen theme files for examples of how to use HTML sectioning an ARIA landmarks.
Landmarks have been removed from the underscores theme in June 2017.

Top ↑

Skip link at Skip link at WebAIM,org visible in focus state

Skip link in focus

AT browsers need to way to quickly skip from the top of a page directly to the content. These “skip-links” are often hidden visually (via CSS) but readable by AT browsers and visible when accessed via keyboard.

  • Provide a keyboard-accessible link above the page header that goes to the main content section.
  • Confirm the link is visible when in :focus state (test using keyboard navigation).

For example, in your header.php theme file, close to the <body> tag, you could place this code (adapted from Twenty Sixteen):

<a class="skip-link screen-reader-text" href="#content"><?php _e( 'Skip to content', 'theme_text_domain' ); ?></a>

See the Twenty Sixteen styles for the .skip-link, .skip-link:focus, and .screen-reader-text classes.

Top ↑

Images Images

  • Give all HTML img elements an alt attribute.
  • Use CSS to insert images that are only decorative, like a logo or icon.
  • Give any decorative images in an img element an empty alt (alt="").
  • Describe (for non-visual readers) the contents and purpose of the image in the alternate text .

An example:

WordPress Attachment Details window, with Alt Text field

The following alt text describes this image to non-visual visitors (and search engines):

<img src="wordpress-alt-text.png" alt="WordPress Attachment Details window, with Alt Text field" width="520" height="270" />

Top ↑

Color Contrast Color Contrast

The WordPress project aims to maintain color contrast accessibility at the WCAG AA level. This requires a minimum contrast between background and foreground colors (4.5:1; 3.1:1 for large text). These rules also apply to neighboring text, such as the color difference between linked text and adjacent unlinked text (when there is no underline or other differentiating feature).

  • The contrast between the background and foreground colors for text should be a minimum ratio of 4.5:1.
  • The contrast ratio applies to differently colored adjacent text, like link-text.
  • The contrast ratio applies to all states of text, including :focus and :hover, and :visited for links.
  • For font-sizes 24px or larger, or 19px when bold, the color contrast ratio must be a minimum of 3:1.
  • Test your design palette in a color blindness simulator.
  • Avoid using color alone to distinguish important elements.

Top ↑

Forms Forms

  • Add a <label> element to all form inputs. (Labels can be visible only to screen-readers.)
  • Use placeholder text, if needed, to augment but not repeat label text, and never as a substitute for a label.
  • Use an aria-label to provide an alternate label and screen-reader-only text to append additional data.
  • Do not introduce new title attributes to convey information.
  • Group related radio buttons, checkboxes, and connected form elements (e.g.: name, address, email) logically with a <fieldset> element and under a heading using <legend>.
  • View the default WordPress comment and search forms for examples of forms that pass the accessibility-ready criteria.
  • Avoid using of a positive tabindex attribute — it hijacks the browsers natural tab order (tabindex=-1 is allowable in certain cases).
  • Post-submission responses, such as errors or confirmations, must be perceivable to all types of users. Create feedback mechanisms (such as via AJAX) that expose responses to screen readers. Practical ARIA Examples demonstrate how to use ARIA in scripted interfaces.

Top ↑

Semantic HTML Semantic HTML

Choose the most accurate elements, such as <p> for paragraphs, <blockquote> for quotes, and <time> for times and dates. You can use the horizontal rule tag, <hr />, as a visual separator.

Top ↑

Text Text

  • Lists: Markup all lists as either <ul>, <ol>, or <dl>.
  • Quotes: Wrap a quote meant to display as a block (e.g., as its own separate paragraph) in a <blockquote> tag, and a quote meant to display inline (e.g., within a paragraph) in a <q> tag.
  • Abbreviations: Define acronyms and abbreviations in the title attribute of the abbr element. For example, the markup of A11y is:
    <abbr title="Accessibility">A11y</abbr>

Tip: Consider adding CSS style: abbr { cursor: help; }.

Top ↑

Language Language

  • Declare the document’s primary human language in the head: <html <?php language_attributes(); ?>>.
  • Wrap the text of any other languages in the body, e.g., <span lang="es">Código es Poesía</span>.

Top ↑

Tables Tables

  • Use tables for tabular data
  • Avoid using tables for layout (use CSS)
  • Opt for the simplest table configuration that best conveys the data
  • Add a <caption> to the table, if needed
  • Identify row and column headers with a <th> element
  • Use the <scope> attribute to associate headers with their data cells

Note: See also “Tables” in this handbook.

Top ↑

Controls Controls

  • Use the HTML controls with a native keyboard interaction: <button>, <input>, or <a>. Choose the most semantically accurate element.
  • Do not use a div, span, or link element as a button.
  • Use a link only for a valid URL. This is not an accessible link: <a href="#">.
  • Use a button for a control that triggers an action, possibly via CSS or JavaScript (i.e., a control that is not a link or an HTML form input).
  • Add machine-readable text to indicate the purpose of a control — don’t just use an icon. This text can be visible only to screen-readers.
  • See the WP Accessibility theme patterns repositories at GutHub.

For instance, a control that triggers a dropdown menu is not a link; it’s a button:

<button class="menu-toggle">Menu</button>

Here’s the same button with an icon and screen-reader only text:

<button class="menu-toggle">
	<span class="dashicons dashicons-menu" aria-hidden="true"></span><span class="screen-reader-text">Menu</span>
</button>

Tip: Screen-readers voice any content you add to the :before and :after CSS selectors.

Top ↑

Multimedia Multimedia

Just as images need alternative text, your audio and video needs transcripts and captions. Providing alternative presentations of time-based media expands your audience and makes your content searchable by users and search engines. Video captions are also useful for sighted users who watch the video with the audio off.

Top ↑

Audio and Video Audio and Video

  • Avoid auto play.
  • Provide controls to start, stop, and pause media.
  • Offer transcripts of audio, with summaries of sounds (e.g., “[laughter]” or “[explosion]“).
  • Offer captions for video, with summaries of sounds, settings, actions, text, and facial expressions necessary for understanding the content.
  • Consider offering extended audio descriptions of movies, a longer audio-only version that tells the same story and presents the same information.

Top ↑

Animations Animations

  • Provide controls to pause movement or scrolling.
  • Restart a pause from where the user stopped it.
  • Allow users to finish an activity without any time limit.
  • Provide a text version of any visual information critical to understanding a webpage.
  • Avoid animations that blink more than three times per second.
  • Provide ways to stop or remove any potentially distracting elements.

0:00 [cheerful guitar music plays]
0:04 Digital technology has created amazing opportunities
0:07 for communicating, sharing information, and
0:10 banking and shopping.
0:11 But users of your digital technologies have different needs.
0:15 Keep this variety in mind, otherwise millions of people
0:19 will find it hard or impossible to use your content
0:22 people you want to reach.
0:25 Accessibility is important to at least 60% of your audience
0:28 and getting it right means you’ll build something
0:31 that is better for everyone,
0:33 so it’s good for business!
0:34 Digital accessibility is also a regulatory requirement.
0:37 There have been legal cases launched against websites
0:40 that exclude users, who may be colour blind, or have impaired use of arms or hands,
0:46 cognitive differences, or visual or hearing impairments.
0:49 It’s best to think about accessibility from the start of a project.
0:53 Here are some tips:
0:55 Tip 1: If you are commissioning an app, software or website,
0:58 make accessibility part of the contract - refer to
1:02 the Web Content Accessibility Guidelines version 2 (WCAG 2.0)
1:06 and British Standard 8878.
1:10 Ideally, include disabled users in your testing.
1:13 Tip 2: If you are using an online platform to create your website, use ‘accessible’ themes and plugins,
1:18 and keep the following in mind:
1:20 Tip 3. Design pages so that users may customise
1:23 their experience of them - changing colours, the size of text, or buttons.
1:27 Use responsive layouts that will work on different devices
1:31 Tip 4: Always let users know where they are
1:33 and how they get to somewhere else.
1:35 Create alternative routes to suit different requirements,
1:38 like a ‘skip to main content’ link.
1:40 Tip 5: Make sure that every action that can be performed using a mouse
1:44 can be achieved using the keyboard alone.
1:46 Keyboard only users need to see where they are
1:49 at all times when they navigate using the TAB key,
1:52 and tabbing should follow a logical order.
1:54 Test how easy it is to navigate using only
1:56 the TAB, ENTER, SPACE and ARROW keys.
2:01 Ever get frustrated by moving objects, adverts popping up...? It isn't just annoying
2:05 - flashing content can cause seizures, while some people with cognitive impairments
2:11 find it really hard to concentrate if there are distractions.
2:14 Tip 6: Give the user control - provide a pause button,
2:18 and don’t set audio or video to play automatically.
2:21 Tip 7: Choose a video player that allows you to add captions, and provide a text transcript,
2:26 to make audio and video content accessible.
2:29 Include descriptions of any important visual
2:32 information as well as speech.
2:34 Tip 8: If an image is important, contains text or is a link,
2:37 explain this with ‘alternative text’
2:39 that screen reader software can read out to users with visual impairments.
2:45 Tip 9: Is your text in easy-to-understand language?
2:48 Use short, simple sentences to aid readability
2:52 and engage a wider audience.
2:55 Tip 10: Give each page a title, and
2:56 organise the text using headings, paragraphs and lists.
3:01 Add 'mark up' to enable easier navigation
3:04 and explain features to people who can't see them -
3:07 this applies to documents in Word or PDFs
3:10 as well as webpages.
3:11 Tip 11: Make sure that links stand out clearly
3:14 from surrounding text and
3:16 let users know if the link will open in a new window
3:18 or download a document.
3:20 Links need to be concise and descriptive
3:23 so that if they are read on their own,
3:24 people will still know where they go.
3:27 Tip 12: Test text and background colour combinations and contrast online
3:31 to ensure text can be easily read
3:33 by people who are colour-blind or have impaired vision.
3:37 If your webpage ‘times out’ before
3:38 people are able to complete forms,
3:41 this can be a very frustrating experience -
3:43 Tip 13: Give visitors time to extend their session if they wish.
3:47 Tip 14: Explain accessibility improvements you’ve made
3:49 and why, in an accessibility statement
3:52 and provide easy ways for people to contact you
3:54 if they are having difficulty.
3:56 Spam protection like CAPTCHA may shut out
3:59 potential customers not just spam robots.
4:02 Tip 15: Please use alternatives [to CAPTCHA] -
4:04 such as text-based logic problems,
4:06 or simple human user confirmations.
4:09 Let’s make sure digital technologies are as usable and inclusive as possible.
4:12 We will all benefit!
4:15 This video can’t cover everything,
4:17 and technology and best practice are always evolving.
4:20 For more help and information go to
4:22 citizensonline.org.uk/accessibilitytips
4:27 Thanks to the Digital Accessibility Centre [digitalaccessibilitycentre.org]
4:29 DIG Inclusion [diginclusion.com]
4:31 and the Fix the Web Steering group [fixtheweb.net]
4:33 for this animation, made by Tinmouse.

Top ↑

Keyboard Navigation Keyboard Navigation

Test your pages by navigating only with your keyboard:

  • Tab: Navigates to links and form fields.
  • Shift + Tab: Navigate backwards.
  • Enter: Activates links and buttons.
  • Spacebar: Activates checkboxes and buttons.
  • Arrow keys: Selects radio buttons, select-menu options, sliders, tab panels, autocomplete, tree menus, etc.

Tab through your pages’ links and forms to conduct these tests:

  • Confirm all links can be reached and activated via keyboard, including any in dropdown submenus.
  • Confirm all links get a visible focus indicator (e.g., a border highlight).
  • Confirm all hidden screen-reader-only text (e.g., “Skip to content”) becomes visible when in focus.
  • Confirm all form input fields and buttons can be accessed and used via keyboard.
  • Confirm all interactions, buttons, and other controls can be triggered via keyboard — any action you can complete with a mouse must also be performable via keyboard.

Top ↑

Web Standards Web Standards

Following web standards gives your site enormous benefits. It improves accessibility, device compatibility, code efficiency and maintenance, and discoverability via web crawlers and search engines. The web standards model proscribes separating your document’s structure, presentation, and behavior layers:

  • Use HTML to structure content (into headings, paragraphs, etc.).
  • Use CSS to format and layout content for different devices.
  • Use JavaScript to add dynamic behavior and interaction.

Alert: Do not disable the pinch-to-zoom function built into mobile browsers and tablets. Remove these attributes from your meta viewport tag: maximum-scale, minimum-scale, user-scalable=no, or user-scalable=0.

WordPress themes typically use:

<meta name="viewport" content="width=device-width, initial-scale=1.0">

Top ↑

WordPress A11y WordPress A11y

Explore accessibility in greater depth with these WordPress pages, plugins, and projects: