Accessibility code standards for WordPress core

During the WCUS community summit 2015 in Philadelphia we made a start with accessibility code standards for WordPress core. Joe Dolson put a concept for the a11y code standards together (see below or as Google Doc).
These are the standards expected from new code (like feature plugins) at the time it’s to be merged into core. Our target for released code is WCAG2.0 AA.
Proposed place to put them is the Core Handbook: WordPress Coding Standards, we aim for a short list of very basic things with references to the Accessibility Handbook.

Feedback (in the comment section below) is very welcome.

Concept Accessibility code standards for core:

This document is a list of standards that a WordPress feature plug-in should meet for accessibility in order to be merged into core. These standards are focused on best practices and easily testable concerns.

The expectations for all code released in WordPress is conformance with WCAG 2.0 at the AA level.

  • HTML Semantics
  • Headings Hierarchy
  • Definition of HTML for Controls
  • Usage of ARIA
  • Color Contrast
  • Keyboard Accessibility
  • Images and Icons
  • Labeling

HTML Semantics

Take a pragmatic approach to HTML semantics. Don’t add semantics purely for the sake of semantics; but if there is an HTML structure that clearly matches the content, use that element. For example, if you have a group of links, it should most likely use a list element.

Heading structure

The H1 is the main heading representing the page title on every core page. For sub sections, use a reasonable HTML heading structure — including the use of heading elements for page sub-sections. Heading markup should not be used for presentational purposes.

  • Use H2 through H6 to give internal structure to the page.
  • Don’t skip heading levels.
  • Don’t add extra functionality inside a heading, like links or buttons.

Semantics for Controls

Controls with a native keyboard interaction (buttons or links) are always preferred. If there is a valid target link for the control, either an in-page reference or a link, then the control should use an <a href=”url”>. If there isn’t, it should use a <button>

Related ticket: #26504 Semantic elements for non-link links

Dynamic Content

When there are dynamic changes within a page without a page reload you must provide audible feedback with ARIA for important changes, like a successful saving for example.

[Provide documentation and links for aria-live, wp.speak, etc.]

Color Contrast

In most cases, feature plug-ins are not expected to add or modify colors in core. However, if a feature plug-in needs to add new color combinations, those combinations must meet minimum contrast requirements. Minimum contrast requirements are 4.5:1 for font sizes rendering smaller than 24px or smaller and 3.0:1 for font sizes larger than 24px or 19px and bold.

[in detailed reference, comment on why we’re referencing as pixels]

Keyboard Accessibility

Users must be able to reach and successfully interact with all elements on the page that are actionable, including all form inputs, buttons and links by using the keyboard. They must be able to see a visual indicator of keyboard focus. You should be aware that keyboard events may operate differently when a screen reader is running.

Images and Icons

Any image resource must include an accessible name. An image can be represented by an actual element, an icon font, or an svg element; but any graphical representation is considered an image for these purposes. Different types of elements use different types of accessible names.

For <img> elements, the accessible name should be in the alt attribute. If the img is ornamental, the alt attribute should still be included, but left empty.

For icon fonts, the font icon itself should be aria-hidden, with screen-reader-text in a neighbor element. e.g.

<a href=’this.html’>
<span class=’dashicons dashicon-something’ aria-hidden=’true’></span>
<span class=’screen-reader-text’>Something</span>


For SVG, the SVG should be inline, so that accessible information isn’t hidden from assistive technology. SVG elements should contain aelement with the accessible name of the image. For cross-technology support, the title element should be associated with the svg element via aria-labelledby. For more information, see


All form inputs must include an explicitly associated <label>