Core Accessibility Standards

When creating new interfaces in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., the output and interactions are expected to conform to 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) 2.0 at level AA. But beyond that, there are some specific patterns that the 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). ( team and core team have agreed on as the preferred method for structure.

Though there are many patterns that meet accessibility standards, being consistent across the platform is a key method to ensure that WordPress as a whole is easier to use.

This document is supplemental guidance to help developers meet the WordPress Accessibility Coding Standards.

HTML Semantics

Take a pragmatic approach to 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. 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.

Top ↑

Heading structure

The H1 is the main heading representing the page title on every core page. For subsections, use a reasonable HTML heading structure — including the use of heading elements for page subsections. 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.

Top ↑

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="{your-valid-target}">. If there isn’t, it should use a <button>.

If you’re updating an existing control, button or link decision logic:

Anchors with null or meaningless HREF values: href=’#’, no href, href=’#something’ where #something does not existbutton
Anchors with meaningful on-page HREF values href=’#something’ where #something does existAnchors with meaningful on-page HREF values href=’#something’ where #something does existbutton or a href='#target'
Anchors with meaningful off-page HREF values that are renderable (but actual behavior is AJAX)Link when JS not available, button the rest of the time.
Anchors with meaningful off-page HREF values that are not renderableShould be a button, but perhaps the target should be made renderable
Buttons that direct to new locations on the same pageCould be either a button or a link.
Buttons that direct to new locations on different pages.Should be a link.

Top ↑

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 save event, for example.

Use wp.a11y.speak() for all simple AJAX responses. If you are doing a complex interaction, wp.a11y.speak() may not be the best choice. In that case, discuss your usage with the Accessibility team to determine whether extending wp.a11y.speak() or coding your own ARIA live regions is the best choice.

Top ↑

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.

Top ↑

When links can be identified as such by the context, for example because they’re part of a menu, or a set of links clearly identified as user interface controls, they don’t necessarily need to be underlined. In all the other cases, especially for links surrounded by other text (in a line or 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. of text), links need to be always underlined.

Top ↑

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.

If you can complete an action with a mouse, you must also be able to complete that action using the keyboard.

Top ↑

Images and Icons

Any image resource must include an accessible name. In some cases, the accessible name should be an empty string. An image can be represented by an actual <img> 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 have the aria-hidden attribute, with screen-reader-text in a neighbor element. If the icon is ornamental, the font icon should still have the aria-hidden attribute, but the screen reader text should be omitted.

<a href="this.html">
<span class="dashicons dashicon-thumbs-up" 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 technologyAssistive technology Assistive technology is an umbrella term that includes assistive, adaptive, and rehabilitative devices for people with disabilities and also includes the process used in selecting, locating, and using them. Assistive technology promotes greater independence by enabling people to perform tasks that they were formerly unable to accomplish, or had great difficulty accomplishing, by providing enhancements to, or changing methods of interacting with, the technology needed to accomplish such tasks. SVG elements should contain a <title> element 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 maximum compatibility, all SVG elements used to represent an image should carry the role attribute with a value of ‘img’.

If the SVG element is ornamental, then the title element should be omitted and no aria-labelledby attribute should be present. The SVG element should also carry the aria-hidden attribute.

Top ↑


Existing code uses a mixture of explicitly and implicitly labeled fields, but all new code must use an explicitly associated <label> element (using for/id attributes and not wrapping the form control). Labels are not required to be visible, but must use the .screen-reader-text class when hidden. Placeholders are fine, but are not a substitute for labels. For all labels, clicking on the field label should cause the associated field to receive focus or, for checkboxes and radio selectors, select that choice.

Don’t introduce new title attributes to convey information. Use aria-label when you need to provide an alternate label and .screen-reader-text if you’re appending additional data.

When creating forms, use <fieldset> and <legend> to group logically related form elements inside complex forms or to group radio buttons and checkboxes under a heading.

Last updated: