Make WordPress Accessible

Updates from Joe Dolson Toggle Comment Threads | Keyboard Shortcuts

  • Joe Dolson 9:38 pm on January 24, 2016 Permalink |
    Tags: , , standards   

    Accessibility code standards for WordPress in draft 

    The accessibility code standards for WordPress have been added to the core handbook and are open for feedback over the next two week. Also see the Core blog announcement and the draft standards themselves!

  • Joe Dolson 9:22 pm on January 21, 2016 Permalink |
    Tags: ,   

    Updates to WordPress theme accessibility guidelines 

    The accessibility-ready guidelines for WordPress themes were updated today. There are no explicit changes to the requirements, but the order of the guidelines has been changed so that it corresponds more effectively to how it makes sense to run tests on the guidelines.

    Additionally, I’ve added some information on how to run tests for each guideline into the guidelines, so that theme developers are more easily able to find information on how to self-test when they’re creating an accessibility-ready theme.

    Review the guidelines.

  • Joe Dolson 4:39 pm on August 28, 2015 Permalink  

    Congratulations to Andrea Fercia on gaining guest committer privileges for the WordPress 4.4 release cycle! This is great news for WordPress and accessibility!

  • Joe Dolson 7:46 pm on April 27, 2015 Permalink
    Tags: 4.3-early, , priorities   

    Accessibility Priorities for 4.3 

    For the development of WordPress 4.3, we’ve got a handful of major issues we want to work on to create a smoother and more predictable experience for users with disabilities.

    Reconcile Heading hierarchy throughout admin & clean-up heading contents

    #31650: Missing H1 headings in admin (fixed)
    #26601: Inappropriate content in headings on admin screens.

    Use Semantic elements for non-link links

    Tracking ticket: #26504
    Individual tickets (so far): #31487, #31476
    Related: #26550

    Reconcile search methods

    WordPress incorporates 5 different search interactions in the admin. For usability, accessibility, and maintenance reasons, this should be made more uniform. We’d like to see this reduced to two basic interactions.

    #31818 Uniform Search Form Display/Experience

    List table issues

    We gathered a ton of data on the List table navigation experience during 4.2, and those are being turned into tickets.

    #32028 List table pagination: text improvements for screen readers (fixed)
    #32150 List table: better indication for “no taxonomy” (fixed)
    #32152 List table: Comments column accessibility improvements (fixed)
    #32147 List table: headings for pagination and views links
    #31654 List tables: Select All shouldn’t be a column header (fixed)

    Color contrast issues in admin:

    #31548, #31713, #28599

    Improve editor experience:

    The editor is the single most frequently used part of most WordPress installations – and the experience with this interface should be more consistent.

    #29838: Editor focus order issues.

    Throughout the cycle, we’ll also be picking away at the dozens of other smaller tickets we want to fix, but these are large issues that will have a deep impact on WordPress, and will require a community effort to make progress.

  • Joe Dolson 6:09 pm on April 15, 2015 Permalink
    Tags: ajax, ARIA, javascript   

    Let WordPress Speak: New in WordPress 4.2 

    Written by Andrea Fercia & Joe Dolson

    WordPress 4.2 is shipping with a useful new JavaScript method: wp.a11y.speak(). This is a utility to make it easy for WordPress core to create consistent methods for providing live updates for JavaScript events to users of screen readers – with the side benefit that developers of plug-ins and themes can also make use of it either on the front or back end.


    In modern web development, updating discrete regions of a screen with JavaScript is common. The use of AJAX responses in modern JavaScript-based User Interfaces allows web developers to create beautiful interfaces similar to Desktop applications that don’t require pages to reload or refresh.

    JavaScript can create great usability improvements for most users – but when content is updated dynamically, it has the potential to introduce accessibility issues. This is one of the steps you can take to handle that problem.


    When a portion of a page is updated with JavaScript, the update is usually highlighted with animation and bright colors, and is easy to see. But if you don’t have the ability to see the screen, you don’t know this has happened, unless the updated region is marked as an ARIA-live region.

    If this isn’t marked, there’s no notification for screen readers. But it’s also possible that all the region content will be announced after an update, if the ARIA live region is too large. You want to provide users with just a simple, concise message.


    That’s what wp.a11y.speak() is meant for. It’s a simple tool that creates and appends an ARIA live notifications area to the <body> element where developers can dispatch text messages. Assistive technologies will automatically announce any text change in this area. This ARIA live region has an ARIA role of “status” so it has an implicit aria-live value of polite and an implicit aria-atomic value of true.

    This means assistive technologies will notify users of updates but generally do not interrupt the current task, and updates take low priority. If you’re creating an application with higher priority updates (such as a notification that their current session is about to expire, for example), then you’ll want to create your own method with an aria-live value of assertive.

    How do I use this?

    • enqueue ‘wp-a11y’ from your plugin or theme or set it as a dependency of the script that generates updates
    • on DOM ready, pass a translatable string to wp.a11y.speak(): wp.a11y.speak( mystring );
    add_action( 'wp_enqueue_scripts', 'yourprefix_a11y' );
    function yourprefix_a11y() {
    	wp_enqueue_script( 'wp-a11y' );


    add_action( 'wp_enqueue_scripts', 'yourprefix_ajax' );
    function yourprefix_ajax() {
    	wp_enqueue_script( 'yourprefix.ajax', get_template_directory_uri() . '/js/ajax.js', array( 'wp-a11y' ) );

    For an implementation example, take a look at wp-admin/js/updates.js. An important note: wp.a11y.speak() is only available after DOM ready, so be sure not to call it earlier!

    If you’re intending to use this in your theme, you should take note that your theme should also support the core class .screen-reader-text, which is used in the inserted content. Read more about screen reader text.

    References and further reading

  • Joe Dolson 4:16 pm on February 9, 2015 Permalink
    Tags: classes, , ,   

    Hiding text for screen readers with WordPress Core 

    WordPress introduced the class .screen-reader-text in 2009. Since then, it’s been the canonical way that WordPress handles any HTML output that is targeted at screen readers. Introducing new HTML in the admin that uses this class has never been an issue; but adding more hidden text to output into themed content has been an ongoing problem.

    Starting with WordPress 4.2, core will be making greater usage of the .screen-reader-text class in front-end code, so theme and plug-in developers need to know how to work with it.

    It’s easy to hide text — but the .screen-reader-text class is not about hiding text. It’s about providing text to a targeted audience that’s using a non-visual method to access it. So the simplest methods of hiding text – display: none; and visibility: hidden; aren’t an option. These techniques really do hide the text – from all devices, and all assistive technology.

    How to use screen-reader text

    The purpose of screen-reader targeted text is to provide additional context for links, document structure, and form fields. Usually, that context is readily available to a sighted user because of visual cues and familiar patterns.

    Screen reader text has many specific applications. One common example of this is a link that says “read more”. On its own, this link lacks context in a screen reader. While a sighted visitor can easily identify the context from the surrounding text and images, a screen reader user benefits from including the title of the target in the link:

    <a href="{article.permalink}#more">read more<span class="screen-reader-text"> of the title of {article.title}</span></a>

    Another use of .screen-reader-text is to hide labels in forms. Search forms are a common place where designers use placeholders and image buttons to convey the purpose of the form. Adding a label that’s available to screen readers make the form usable for screen reader users, without altering the design.

    Defining the class

    When you define classes for .screen-reader-text, there are two common methods: absolute positioning and clipping.

    The clip method is used by WordPress core, and is the preferred method.

    .screen-reader-text {
        clip: rect(1px, 1px, 1px, 1px);
        position: absolute !important;
        height: 1px;
        width: 1px;
        overflow: hidden;

    The absolute positioning method is simpler, but requires you to provide alternate styles for right-to-left and left-to-right languages:

    .screen-reader-text {
        position: absolute !important;
        left: -999em;

    It’s common to see the absolute positioning method also using negative positioning on the top margin — this is not recommended. While the arbitrary measurement of -999em is effective almost 100% of the time off the left margin, almost no value will be universally usable off the top margin. Additionally, if any object that can receive focus (such as a link, button, or form input) is positioned off the top of the screen, it will cause the browser to automatically scroll to the top of the window if that element receives focus. This can be disorienting for anybody using a keyboard to navigate the page. It’s also worth noting that the off-left positioning method can have a negative impact on web site performance.

    Bring Hidden Text into Focus

    In some cases, it’ll be necessary to bring your hidden text into view when it receives keyboard focus. This is relatively rare, and primarily effects Skip links, which need to be made visible for keyboard users. You shouldn’t apply a focus state on most screen reader text; if that text doesn’t need to be seen in order for the context to be understood by a sighted user, don’t make it visible on focus.

    If you do need to bring screen reader text into focus, you can use these base styles to move the text into view when using the clip method:

    .screen-reader-text:focus {
        clip: auto !important;
        display: block;
        height: auto;
        left: 5px;
        top: 5px;
        width: auto;
        z-index: 100000; /* Above WP toolbar. */

    Using the absolute positioning method, it’s simply a matter of changing the value of the left positioning so that the text is on screen.

  • Joe Dolson 8:15 pm on January 26, 2015 Permalink
    Tags: commhub, poll   

    Community Hub Poll 

    If you haven’t seen it yet, please take a quick break to fill out the Community Hub poll. The poll closes at midnight on January 29th, so act quickly!

  • Joe Dolson 8:46 pm on January 15, 2015 Permalink  

    Better Support for Accessibility Issues 

    The support team’s weekly meetup today invited representatives from the Accessibility and Theme Review teams to share information about how we could better support each other. As a result of that meeting, we’ve officially agreed on the use of ‘a11y’ as the tag for accessibility issues in the Support forums.

    In the support forums, anybody can add tags to any thread – so if you see a thread that requires a11y help, be sure to add the tag so that people who monitor accessibility issues can easily find it.

    In parallel with this, anybody who’s interested in helping out on the support end of WordPress accessibility issues, you can monitor the accessibility tag to watch for new issues. You can check that page periodically, or you can subscribe via RSS or email.

    If you’ve got experience with accessibility and any of the other areas of WordPress information, helping out in the support forums is a great way to get started making a difference.

    For more information on WordPress support and tagging, here are a couple relevant resources:

    • Andrea Fercia 9:58 pm on January 15, 2015 Permalink | Log in to Reply

      ahem the link to “weekly meetup today” is not a link 🙂

    • Joe Dolson 9:59 pm on January 15, 2015 Permalink | Log in to Reply

      Grah. Forgot to paste it. (I copied it…just didn’t finish the process!)

    • Rian Rietveld 2:49 pm on January 16, 2015 Permalink | Log in to Reply

      Maybe it’s also a good idea to check all the accessibility and accessible tags and decide if they need to be removed or changed into a11y tags, then we have the lot together

    • Joe Dolson 4:02 pm on January 16, 2015 Permalink | Log in to Reply

      Anybody can go in and add a11y tags to any support post that needs it; there’s no particular need to remove other tags. All registered WordPress.org users can add tags, however.

    • Rian Rietveld 6:56 pm on January 26, 2015 Permalink | Log in to Reply

      Was just wondering how people asking support know they can use the a11y tag as preferred before accessibility and accessible

    • Joe Dolson 6:58 pm on January 26, 2015 Permalink | Log in to Reply

      They don’t; but that’s intentional. The idea is that forum moderators can add the tag when it’s necessary, so that people who are accessibility specialists can find the info.

  • Joe Dolson 8:09 pm on January 7, 2015 Permalink  

    Accessibility Ticket Priorities for WordPress 4.2 

    Here we are again, at the beginning of another great rendition of WordPress! As is normal at the beginning of a cycle, here are a few big issues that the WordPress Accessibility team would like to see focused on at this stage. These are mostly large areas where usability and accessibility need some concerted effort, in addition to some major decisions that need to be pinned down.

    Media Library

    The media library views have gotten a lot of good work recently, but there’s still a long ways to go. And it’s not just accessibility that’s needed here, but also some general usability questions for all users, as pointed out by Ryan Boren. Some work needs to go into the flow for all users; while all features need to be available via keyboard, it would be nice to explore a user flow that allows the work flow to be smooth, as well.


    • #30512 – Improve media views accessibility
    • #30599 – Media views: improve keyboard accessibility avoiding confusing tab stops
    • #28820 – Focus isn’t clear when previewing an oEmbed from Add Media Panel
    • #30392 – Focus moves out of insert media overlay when tabbing beyond Insert into post button – Fixed
    • #30386 – Keyboard user has to tab through all uploade dimages to insert an image
    • #23562 – Using speech recognition software with the add media panel
    • #28864 – Cannot access edit menu options with keyboard inside Image Editor
    • #26550 – Some anchor links should be buttons in media microtemplates
    • #25103 – Submit buttons on form fields in the Add Media Panel

    Post Editing and Authoring

    There are a number of outstanding issues relating to authoring and editing posts, largely relating to some confusing tab order and needed improvements in flow both for mobile and users with disabilities. The current set up provides an extremely easy tab navigation from the title to the post content fields, but accessing anything in between via keyboard can be quite confusing. See also the flow comments from Mark Jaquith.


    • #29838 – Post editing area: keyboard accessibility, tab order, and focus
    • #23760 – Cannot use spacebar to trigger OK button or links in Publish widget
    • #30368 – Issue with category selection using voiceover
    • #27555 – Make tag post meta box more accessible
    • #30407 – Add keyboard shortcut for switching between Visual and Text editors
    • #30490 – TinyMCE: switch editor tabs focus style
    • #30619 – The wpView toolbar is not accessible by keyboard
    • #30345 – Quick edit: form submitted when activating cancel via keyboard – Fixed
    • #28431 – There’s no way to close the “keyboard shortcuts” modal with the keyboard – Fixed

    Use of .screen-reader-text in front-end

    This is a long-standing issue in handling some front-end accessibility issues. Numerous proposals have been floated, but there’s no strategic goal right now. Among the proposals are to add a theme support registry for the class .screen-reader-text, to set up core styles for the front-end that implement a .screen-reader-text class, or to simply add new information with that class and leave it to theme authors and site admins to handle the changes in front-end HTML output. This effects several other tickets. (I may not have caught all of them.)

    Part of the question here is for any future needs to add contextual references to core output: at what level is it necessary for us to avoid HTML changes on the front-end?

    • #29699 – add_theme_support( ‘screen-reader-text’ );
    • #18650 – Accessible dropdown widgets
    • #26553 – Comments popup link

    Visual focus indication in Admin Menu

    This ticket has gotten a lot of design attention but was not completed in time for 4.1. It needs further UI feedback.

    • #28599 – Better visual focus indication in Admin Menu

    Miscellaneous outstanding issues

    There are a large number of HTML inconsistencies, such as missing labels, links used as buttons. Not all of them have outstanding tickets, but I’m aiming to spend some time clearing out these minor issues so that we can better focus on more complex issues. Most of these are very small issues that with simple HTML/JS/PHP changes, but might require some CSS updates. And we all know how fun it is to spend time in the WP admin stylesheet.

    I know that there are some issues that don’t yet have tickets; I’ll be raising those, as well.

    • #28873 – Javascript code for adding bookmarklet Press This is hard to access with keyboard only
    • #30486 – Missing label associations throughout network admin
    • #29715 – Not-unique accesskey values may break quick edit and bulk edit form submission
    • #26562 – Remove title attributes class-wp-admin-bar.php
    • #26600 – Search installed themes input has no submit button
    • #29955 – Section 508 issues found on WP 4.0 admin page
    • #26504 – Semantic elements for non-link links
    • #30685 – Better Login Error and Message displaying
    • #21221 – Image title and alt attribute content should be texturized
    • #30914 – WP List Table: improve table footer tab sequence
    • #26601 – Inappropriate content in heading on Themes page
    • #29022 – Screen reader text and link title isn’t updated when plugin update count is updated
    • #26167 – Plugin activation links need to contain plugin name and the Plugin column should be marked as row header
    • #26550 – Some anchor links should be buttons in media microtemplates
    • #30706 – Add aria-describedby to autofocused fields
  • Joe Dolson 6:07 pm on December 15, 2014 Permalink

    Taking Steps for More Accessible Themes 

    We’ve been working with the Theme Review team to coordinate sharing more information about making themes accessible, with an eye towards the goals in our Accessible Themes Roadmap. The first step in that roadmap has been published today, Three Easy tips for Accessible Theming, published at the Make/Themes blog.

    Read it, share it, and most of all, build accessible themes for WordPress!

compose new post
next post/next comment
previous post/previous comment
show/hide comments
go to top
go to login
show/hide help
shift + esc
Skip to toolbar