Quick start guide

Below are the web essentials you’ll need to start making 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

Assistive Technologies (AT), such as screen-readers, offer multiple ways to navigate a webpage. These include a linked-list of all the page’s HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. Headings (H tags), 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.

Top ↑


  • Put your document title in an H1 element. WordPress usually does this for you for page and post titles.
  • Nest your page sections and subsections in a sequential hierarchy of H2H6.
  • Don’t skip levels. In properly nested headings an H4 should always come under an H3, and you would not skip from an H2 to an H4.
  • Never use headings for visual effects only, e.g., to bold text or increase font size.
More about headings in this handbook: Heading structure in theme development and Headings in the content.

Top ↑

  • Use meaningful link text to describe the link: Never just “click here” or “more info”. The text of the link should clearly indicate what clicking the link does even if it is read without the context of any surrounding text. (Screen reader users often listen to a list of links for navigation.)
  • Avoid the title attribute in anchor elements (<a>).
  • Avoid the target attribute in anchor elements.
  • Provide :focus and :active link highlighting.
  • Underline links in the content. Do not rely on color alone.
  • Include the document title in “Read More” links (can be hidden by the screen-reader-text CSS class).
More about links in this handbook: Good link texts, Link destinations, Post excerpts for an archive template
The Theme Handbook discusses link text and styles in greater depth.

Top ↑

HTML5 sectioning elements

  • Use HTML sectioning elements: <header>, <nav>, <main> (only one <main> 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.For example
  • On a search form: add the role search (discussion about where to add the role=search)

Top ↑

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.

Mode about landmarks in this handbook: ARIA Landmarks.

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.

More on skip links in this handbook: Skip Links.

Top ↑


  • Give all HTML img elements an alt attribute (this is sometimes referred to as “alt text”).
  • 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.
More on images in this handbook: Alternative text for images.

Top ↑

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 24 pixels or larger, or 19 pixels 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.
More on color, and how to test this, in this handbook: Use of color.

Top ↑


  • 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

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 ↑


  • 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>
Consider adding CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. style: abbr { cursor: help; }.

Top ↑


  • 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 ↑


  • 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
See also “Tables” in this handbook.

Top ↑


  • 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 GitHub.

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>
Screen-readers voice any content you add to the :before and :after CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. selectors.

Top ↑


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

  • 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 ↑


  • 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

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 ↑

W3C Web Standards

Following W3C 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.

Top ↑

WordPress A11y

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

Last updated: