Required

Topics

Keyboard Navigation Keyboard Navigation

Who does it benefit? Screen reader users and users of keyboards or alternative input devices who are sighted.

Theme authors must provide visual keyboard focus highlighting in navigation menus and for form fields, submit buttons and text links. All controls and links must be reachable using the keyboard.

Example:

  • Fails: Dropdown navigation menus are hidden using display:none; and brought into view on :hover
  • Passes: Dropdown navigation menus are hidden using position: absolute; and brought into view on :hover and :focus, and are navigable using the tab key
  • Better: Dropdown navigation menus are hidden using position: absolute; and brought into view on :hover, :focus, and are navigable using either the tab key or by using the keyboard arrow keys.

How to test:

  • Using tab key, tab forward through site. Test to make sure that links, buttons, form fields, and drop down menus are available using the tab key.
  • Make sure you can see visually which link is focused. Focus must either incorporate a visual change that is not based on color (background change, underline, shape) or a color change where the difference between the two colors meets color contrast guidelines.
  • Make sure that focus doesn’t move in unexpected ways around the page. In general, the travel path between links must match the text direction of the content language, e.g, traveling from left to right and top to bottom for LTR content. All tab stops within a visual region must be visited before the next visual region is moved into.
  • Test shift+tab to move backwards and confirm that works, as well.
  • Tools: browser tab key, shift + tab

Keyboard navigation must be supported in all responsive views. While the native interaction on mobile devices is touch, the use of a keyboard to navigate mobile devices is an important tool for many users. Be aware that since responsive modes are triggered based on content width, screen reader users who operate without a monitor or low vision users at high levels of zoom are likely to trigger these modes.

Top ↑

Controls Controls

Who does it benefit? Screen reader users, keyboard users, and users with alternate input devices.

All theme features that behave as buttons or links must use <button>, <input>, or <a> elements, to ensure native keyboard accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) and interaction with screen reader accessibility APIs.

All controls must also have machine-readable text to indicate the nature of the control.

Example:

Fails:
<span class="menu-toggle"><span class='dashicons dashicons-menu'></span></span>

Passes:
<button class="menu-toggle"><span class="dashicons dashicons-menu"></span><span class="screen-reader-text">Menu</span></button>

Better:
<button type="button" class="menu-toggle"><span class="dashicons dashicons-menu"></span>Menu</button>

See Links are not buttons; neither are divs and spans for more information.

How to test:

  • Find buttons: search form input, comment form input
  • Switch into responsive mode if theme is responsive, test responsive toggles:
  • test visibility on focus, type of control, keyboard availability
  • Tools: browser tab key, browser inspector

Top ↑

Who does it benefit? Screen reader users and keyboard navigators.

Themes must include an in-page link that helps users navigate directly to content after arriving at a new page. These links may be positioned off screen initially but must be available to screen reader users and must be visible on focus.

A minimally conforming skip link must:

  • Be the first focusable element perceived by a user via screen reader or keyboard navigation.
  • Be visible when keyboard focus moves to the link.
  • Move focus to the main content area of the page when activated.

There is an outstanding bug in WebKit-based browsers that prevents focus being moved to elements that aren’t natively focusable. You can either enqueue JS to patch this bug or assign tabindex=-1 to your main content region to handle this issue.

How to test:

  • Verify that skip link is present.
  • Verify that skip link is first focusable object on the page when not logged in
  • Verify that skip link becomes visible when it receives focus
  • Verify that skip link points to the content area of the site correctly
  • Tools: browser tab key, browser inspector

Top ↑

Forms Forms

Who does it benefit? All users, but principally screen reader users and keyboard-dependent users.

Comment forms must have appropriate field labels and all content within form tags need to be explicitly associated to a form control. Post-submission responses (errors or confirmations) must be perceivable. If you are using the default WordPress comment or search forms, these pass the accessibility-ready criteria.

Placeholder attributes are not valid replacements for a label, as they cease to be available after information is added to the field and can easily be mistaken for completed content.

If you are replacing the default WordPress forms or form behavior (such as to handle responses with AJAX), you MUST:

  • Use form inputs that have explicitly associated <label> elements.
  • Create feedback mechanisms (such as via AJAX) that expose responses to screen readers. Look at techniques with ARIA for further information.

Example:

Fails:

<input type='text' name='s' value='<?php echo trim( get_search_query() ); ?>'>

Passes: (label is hidden)

<label for='s' class='screen-reader-text'><?php _e( 'Search', 'textdomain' ); ?></label> 
<input type='text' name='s' id='s' value='<?php echo trim( get_search_query() ); ?>'>

Better: (label is visible)

<label for='s'><?php _e( 'Search', 'textdomain' ); ?></label> 
<input type='text' name='s' id='s' value='<?php echo trim( get_search_query() ); ?>'>

How to test:

  • Look at search form and comment form
  • Verify that all form fields are labeled correctly; implicit labeling is allowed on search but not comment fields
  • Verify that all forms have submit buttons. Can be hidden, but if so must be hidden using screen-reader-text correctly.
  • Tools: browser inspector

Top ↑

Headings Headings

Who does it benefit? Screen reader users, SEO, voice recognition users

Theme templates must use a reasonable 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. heading structure — including the use of heading elements for page sub-sections. Heading markup must not be used for presentational purposes. Heading elements for structure may be positioned off-screen if they would appear redundant to sighted users.

Specifically, sub-sections defined by your theme must use heading elements. This includes wrapping your post title in a heading when used in an article context and wrapping widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. titles in headings.

Failure criteria:

These are specific criteria that are used to judge whether your hierarchy meets our requirements:

  • No H1 element present on the page.
  • Multiple H1 headings on a single page.
  • Headings do not skip levels when descending. H1 cannot be followed by H3, etc.

See Semantic Structure from WebAIM for more information.

Tools

Use the standard headings option, not the HTML5 outline option.

How to test:

  • Find any skipped heading levels
  • Test whether h1 missing
  • Test whether all headings are the same
  • Tools: HeadingsMap add-on for Chrome or Firefox

Top ↑

ARIA Landmark Roles ARIA Landmark Roles

Who does it benefit? Screen reader users. Landmarks provide a method for screen readers to navigate directly to large structural regions of a site.

Assign landmark roles to the main content areas of your site. All content on your site must be wrapped in at least one landmark role; any content not wrapped in a landmark role is ‘orphaned’, and may not be found by screen reader users.

Appropriate usage of roles:

  • role="banner" = headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. (<header> element)
  • role="main" = main content (<main> element)
  • role="complementary" = sidebars (<aside> element)
  • role="contentinfo" = footer (<footer> element)
  • role="search" = search form
  • role="navigation" = navigation menus (<nav> element)

At least one of the above must be used. It is not required to use both the role attribute and the element, though using both will expand support.

If a particular role appears more than once on a page, provide an ARIA label for that role:

<nav aria-label="<?php esc_attr_e( 'Primary', 'textdomain' ); ?>">
<nav aria-label="<?php esc_attr_e( 'Secondary', 'textdomain' ); ?>">
<nav aria-label="<?php esc_attr_e( 'Social', 'textdomain' ); ?>">

It’s impossible to specify how many landmarks any page must have, but keep in mind that too many landmarks can create confusion for users who need to remember what information is in a landmark section. If you have more than 10, you may need to remove or consolidate regions.

Themes are required to use the ‘navigation-widgets’ option to add support for the HTML5 navigation widgets added in WordPress 5.5 to provide landmark semantics for navigation widgets.

add_theme_support( 'html5', array( 'navigation-widgets' ) );

How to test:

  • Verify that all content is contained inside at least one aria landmark.
  • Verify that aria landmarks are appropriately chosen
  • If a major landmark, such as navigation, is used more than once, ensure each is labeled uniquely.
  • Verify presence of ‘navigation-widgets’ in the theme support declarations.
  • Tools: ARIA Landmark Inspector bookmarklet

Top ↑

Content Links Content Links

Who does it benefit? Sighted users

Links within large sections of text (e.g., post content or comments) must be underlined. When links appear within a larger body of blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.-level content, they must be clearly distinguishable from surrounding content. Links in navigation-like contexts (e.g. menus, lists of upcoming posts in widgets, grouped post metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. data) do not need to be specifically distinguished from surrounding content.

The underline is the only accepted method of indicating links within content. Bold, italicized, or color-differentiated text is ambiguous and will not pass.

How to test:

  • When using the Theme Unit Test data, navigate to the “Markup: HTML Tags and Formatting” page in your WordPress test installation.
  • Look at the examples for links.
  • Review the overall design of the theme to identify any other large block-level content that could also require a check.

If links within the content are not underlined, the theme does not pass this check.

Top ↑

Repetitive Link Text Repetitive Link Text

Who does it benefit? Screen reader users

Links must avoid repetitive non-contextual text strings such as ‘read more…’ and must make sense if taken out of context. Bare urls must not be used as links. Supporting text may use a screen reader class to hide text visually.

The coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. ‘read more’ links fall under this guideline. The post title must be used in addition to the string used for “Read more” text.

It is also an acceptable option to exclude ‘read more’ links entirely, as long as the post title is linked to the full post.

Example:

Fails:

the_content( 
	__( 'Continue reading', 'textdomain' ) 
);

Passes:

the_content( 
	sprintf( 
		__( 'Continue reading%s', 'textdomain' ), 
		'<span class="screen-reader-text">  '.get_the_title().'</span>' 
	) 
);
  • Find ‘read more’ link in data (Search for ‘read more’, find read more test post. If not visible on post, look at read more tag archive.)
  • Test whether link is present
  • If present, test whether link includes extended text
  • Tools: browser inspector

Top ↑

Contrasts Contrasts

Who does it benefit? Color blind users, users with age-related eye issues, users in bright sunlight or glare.

Most themes provide methods to modify colors or change color schemes. The principle of this guideline is that if a user does not change any default colors their site will be accessible.

Theme authors must ensure that all background/foreground color contrasts for plain content text are within the level AA contrast ratio (4.5:1) specified in the Web Content Accessibility Guidelines (WCAGWCAG WCAG is an acronym for Web Content Accessibility Guidelines. These guidelines are helping make sure the internet is accessible to all people no matter how they would need to access the internet (screen-reader, keyboard only, etc) https://www.w3.org/TR/WCAG21/.) 2.0 for color luminosity.

If a change in color is the only visible change when the link state changes:

  • The text color on hover must have a contrast ratio of 4.5:1 against the default link text color and against the focused link text color.
  • The text color on focus must have a contrast ratio of 4.5:1 against the default link text color and against the hovered link text color.

If there is no text decoration on linked text, there must be a 3:1 color contrast between the link text color and the surrounding non-link text color, in addition to the other color contrast requirements.

Default settings will be the only colors checked.

There are many tools for testing color contrast:

Web:

Firefox Add-ons:

Chrome Add-ons:

How to test:

  • Do automated test for color contrasts throughout the page.
  • Manually look at every color combination that fails and verify that the test matches the results.
  • If the color contrast failure is over an image, check what the background color is behind the image.
  • Tools: WAVE for Chrome from WebAIM, browser inspector + Chrome Accessibility add-on

Top ↑

Images Images

Who does it benefit? Screen reader users.

Where theme authors add non-decorative images to template markup or provide a method for end users to add images, theme authors MUST incorporate an appropriate alt attribute or the means for an end user to provide one.

All decorative images must be marked up such that they will be ignored by screen readers.

Example:

  • Featured Images: The alt attribute for featured images is defined in the media manager. In any case where a featured imageFeatured image A featured image is the main image used on your blog archive page and is pulled when the post or page is shared on social media. The image can be used to display in widget areas on your site or in a summary list of posts. is displayed unlinked, the alt attribute must be included with the image.
  • Icons (SVG, images, or icon fonts): if the icon is representing text (e.g., there is no visible text), the icon must include fallback text for screen readers that indicates what the icon means. If the icon is supplementing text (e.g., it appears with text that indicates function or purpose), then the icon must not include fallback text, and be hidden from screen readers using aria-hidden.

How to test:

  • Look at featured image presentation, make sure alt attributes are included with image
  • For linked featured images, verify that there is text within the link, and that the text is not duplicated. E.g., a block-level link wrapping both the featured image and the post title must have an empty alt attribute; a link wrapping only the featured image must use the post title as an alt attribute.
  • Look at any icon fonts or decorative images in use on the site. Ensure that icon fonts have fallback text alternatives when needed (e.g. when icon font is a link on itself), or are hidden if not (e.g., ornamental icons connected to other links)
  • Tools: browser inspector

Top ↑

Media Media

Who does it benefit? Screen reader users and users with cognitive impairments.

Media resources must NOT auto start or change without user action as a default configuration. This includes resources such as audio, video, or image/content sliders and carousels.

How to test:

  • If a special feature (such as a content slider) is enabled by default, ensure that the feature is accessible using all of the guidelines and applying them to that feature. (This is very rare)

Top ↑

Screen Reader Text Screen Reader Text

It is not required to use screen reader text in your theme to meet accessibility-ready guidelines. Any text which is commonly hidden visually and provided for screen readers can legitimately be made visible for all users.

If you are making text available only for screen reader users, there are two valid ways to do this. You can either use text hidden in a valid screen-reader-text class or use aria-label or aria-labelledby attributes to provide an accessible name for what you’re labeling.

If you use .screen-reader-text, then you must use one of the recommended techniques for hiding that text visually.

Top ↑

Not Allowed Not Allowed

Who does it benefit? All users. These are features that can create problems for any user.

Inclusion of any of the following is NOT allowed:

  • Any positive tabindex attribute. Negative or zero value tabindex is allowed in specific circumstances (assessed on a case-by-case basis).
  • The inclusion of the accesskey attribute.
  • Spawning new windows or tabs without warning the user.

How to test:

  • Search for any occurrence of target attributes in the theme. (target=”_blank” appears in the theme unit test content, so ignore those.)
  • Search for any occurrence of tabindex attributes in theme. (tabindex=1 occurs in adminbar, so ignore that. tabindex=-1 may be allowable, most other uses won’t)
  • Search for any occurrence of accesskey attributes in theme.
  • Tools: view source, browser inspector

Last updated: