Help needed from accessibility experts with the development of Gutenberg

Are you an accessibility expert? We need your help!

At the moment work is done to improve the WordPress content editor. This project is called Gutenberg. The goal is to improve the interface and make it ready for the future. The new editor is now available as plugin and the work is done on Github.

The accessibility team needs help to safeguard it’s accessibility and we can’t do this alone.

If you are a developer, accessibility tester or work for company that specialises in web accessibility, please help testing or join the work and discussions on Github. WordPress is used by +27% of all websites, so this will have a huge impact on the way people (can) publish on the web worldwide. And we need all the help we can get at the moment.

Related links:

WordPress goes WCAG

With great pride the WordPress Accessibility Team can announce:

All new or updated code released into WordPress core and bundled themes must conform with the WCAG 2.0 guidelines at level AA.

On February 15th, 2016, the WordPress Accessibility Coding Standards were approved and added to the Core Handbook as a part of the code standards WordPress developers are expected to meet when contributing to core.

What does WCAG 2 AA mean?

WCAG stands for Web Content Accessibility Guidelines, created by the World Wide Web Consortium (W3C). These guidelines ensure that people with disabilities can use the web. The current WCAG standards are version 2 and AA refers to the level of accessibility reached. Level A is the most basic standard, while Level AA is used as a reference for a legal standard in many countries worldwide. Level AAA is most commonly only addressed for special dedicated software.

What does this mean for WordPress core?

With every release WordPress gets more accessible for users with disabilities. We’re not there yet — a lot of work still needs to be done on current functionality and interface. We need all the help we can get! The accessibility of the Admin (the administration area of WordPress) is getting better and better. We are researching, testing and fixing accessibility issues in the Admin together with the core developers and our great test team.

What about themes?

The bundled themes, like Twenty Sixteen, already make it easy for you to create a web site that complies with WCAG 2 AA, so when you set up a new installation of WordPress, you’re already on the right track out of the box.

In the WordPress theme repository you can search for themes with the “accessibility-ready” tag. These themes have gone through much the same testing process as the bundled core themes. For every theme with this tag, a member of the WordPress accessibility team has personally checked the theme for keyboard accessibility, color contrast, and a variety of other specific accessibility guidelines. We don’t currently have the depth of reviewers to test every theme update, however, unlike with the core themes, so we can’t guarantee that each theme will continue to meet these standards in future updates.

What about plugins?

The accessibility of plugins is the responsibility of each plugin author. Neither the accessibility team nor the plugin review team have the resources to review each of the more than 40,000 plugins currently in the repository. If you are a theme or plugin author, please take a look at our handbook for best practices and documentation.

What’s next?

Today, 25% of the web runs on WordPress and our mission is to democratize publishing. That is why we will keep moving forward on the accessibility of WordPress: to give everyone, including people with a disability, an excellent and easy to use tool so they can maintain their own website or application.

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> 

Testing Twenty Sixteen

By now, I’m sure you’ve noticed Twenty Sixteen has been released on Github and the theme repository to spur development and testing. If you haven’t tested the theme for accessibility, now’s the time! I mentioned it in a recent chat, and a members from the community have already tested it, but the more the merrier!

What do I test?

Test the theme according to the accessibility-ready requirements. Since this is a default theme, you should test for the recommendations too. Also, it’s a good idea to look at the applicable WCAG 2.0 requirements (Link is not the official WCAG requirements, but a more readable version), and test the theme according to those, within reason. This way, the theme can be its best accessibility-wise.

How do I test?

The accessibility-ready requirements give some information on how to test. We also have a list of tools that will help when testing.

How do I report bugs, issues or make a enhancement request?

What information do you need to know when creating an issue?

Here’s a good format to follow when creating a bug report:

Title: Accessibility: ISSUE SUMMARY HERE

What I Did:

What I Expected:

What Actually Happened:

I’m not a developer, how can I help?

No problem! You don’t have to be a developer to help out. Test the theme on your favorite operating system with assistive technology. This way, we get a better idea of how the theme works with different configurations. Try to break the theme! Note anything that is confusing, and makes the theme harder to use on the front end.


Team Chat Summary August 10, 2015

New Structure Proposed

Rian Rietveld wrote a proposal on how to structure our work better and plan ahead longer and we discussed it. What follows is examples from the proposal.

Goals and Issues

This will be a separate page on make/accessibility and also a main menu item. It gives an overview of our goals for the accessibility of WordPress, the work we (want to) do, how this is organized, how we test, a roadmap for the next year and how we track the progress of issues we are working on. An example of the roadmap for release 4.4:

Release 4.4 (December 2015, Scott Taylor)
  • Finish still open issues focus from 4.3
  • Semantic heading structure Admin
  • The customizer
  • Handbook
  • Twenty Sixteen (?)

Central Ideas

Some central ideas also included in the proposal are keyboard focus, work on the handbook, color contrast, system to better follow tickets including splitting up tickets among team members on which to concentrate, and continue to develop code pattern library. Much more is included in the proposal and for now we will continue to work on the proposal to make it a more formal document to cover our activities over the next year.

We also talked about the fact that having a planning document to refer to does not obviate the need to address all new features since there is a tight turn around towards the end of a cycle because that’s when the features going into the release are announced. If we don’t follow all new features we might miss one or more that advance to release at the very end.

When we have it shaped up we will add the planning documentation to this blog in the form of pages and sub-pages to make it a community resource.

#accessibility-team-meetup, #team-reps, #weekly-meetings

WordPress Accessibility Ticket priorities for 4.1 early

WordPress 4.1 development is just started. From an accessibility perspective, this means that we know almost nothing about what new features and UI changes will be taking place, but it gives us a great opportunity to work on resolving older outstanding issues or addressing concerns arising out of version 4.0.

This is a grouping of the tickets currently in the Accessibility Focus report; no new tickets were opened for the purpose of this list.

One general recurring topic in these tickets is the handling of focus in modals. This is something that could stand some global work: all WordPress modals should be initiated and closed in a standardized way: focus should be assigned to the first focusable item in the modal when it’s opened, focus should be restricted to within the modal while it’s open, and the modal should be closable using ‘Esc’. A thorough review of all modals would be valuable.

Group 1:

These tickets have an impact on the front-end use of WordPress. They are very unlikely to be relevant to any new features in development for 4.1, but are longstanding issues and improvements. Because they alter front-end code, they may require more time in trunk to address impact on plugins or themes.

  1. #15926 Add alt attribute support for Custom Header functionality
  2. #24148 Add aria-labelledby attributes to comment form (fixed)
  3. #21221 Image title and alt attribute content should be texturized.
  4. #27402 Add aria-describedby to image gallery output (fixed)
  5. JS #27645 MediaElement.js player & playlist not keyboard accessible (see Issue 1262 and Pull 1090 on MediaElement for reference)
  6. #16433 Extend function to optionally include commenter name in comment_reply_link
  7. #18650 Make archives and categories widgets dropdown ada compliant (depends on #29699)

#18650 is a particularly long-standing issue which has significant challenges due to the way the front-end HTML would need to change to make the feature accessible. Other features should all be able to be addressed without any major front-end impact.

Group 2:

These are areas that received a lot of attention in 4.0, but have outstanding issues. #26167 doesn’t directly relate to the plug-in work done in 4.0, but would be a good area to get resolved. It should be an easy fix.

  1. JS #28892 Customizer – Widgets – Feedback for screen reader users when Moving widgets + other actions
  2. JS #28888 Customizer – Widgets – Screen Readers Don’t Announce Widget Names
  3. #20880 Keyboard navigation in Appearance > Header is broken
  4. #26167 Plugin activation links need to contain plugin name and the “Plugin” column should be marked as row header
  5. JS #29371 Media Library: Focus keeps jumping to URL field
  6. JS #29455 Plugin Info Modal Close Button Does Not Announce for Screen Readers
  7. JS #29326 Improve accessibility of edit-selection mode

Group 3:

General issues relating to the author experiences, that can impact a user’s ability to author content.

Add Media Experience:

  1. JS #25103 Submit buttons on form fields in the Add Media panel
  2. JS #23562 Using Speech Recognition Software with the Add Media Panel
  3. JS #28864 Cannot access edit menu options with keyboard inside Image Editor


  1. JS #29838 Post editing area: keyboard accessibility, tab order and focus
  2. JS #27642 Keyboard Accessibility for TinyMCE image panel
  3. #27553 Make WP editor toggle focusable
  4. #21414 Use the “Keyboard Shortcuts” checkbox in the user profile to turn on/off all custom shortcuts
  5. #29358 Remove the ‘accesskey` attributes from Quicktags buttons


  1. JS #27555 Make tag post meta box more accessible
  2. #26600 Search installed themes input has no submit button
  3. #26550 Some anchor links should be buttons in media microtemplates

Group 4:

Administrator/Designer experience:

These issues will effect a smaller number of users on fewer occasions because they primarily effect issues related to site set up and configuration. #18801 could really stand some major work; the settings pages in WordPress have a large number of miscellaneous accessibility issues, but I think that the ticket is too all-encompassing as is; we need to open some individual tickets handling specific issues in the settings pages or in the API, so that the issue is more readily addressed.

  1. JS #27592 Screen Reader Users Do Not Know Widgets are Expandable
  2. #27593 Widgets: Toggle arrows on focus need an indicator beside color alone
  3. #18801 Accessibility Enhancements to Settings API

These are issues that make features more difficult to use, but don’t prevent the usage of the feature.

  1. #26758 Edit Tags form on submission does not stay at the same page and gets redirected
  2. #28873 JavaScript code for adding bookmarklet Press This is hard to access with keyboard only
  3. #25111 Keyboard focus does not stay within Full Screen Editor modal
  4. #26562 Remove title attributes: class-wp-admin-bar.php
  5. CSS/HTML #26504 Semantic elements for non-link links
  6. JS #26601 Inappropriate content in heading on Themes page
  7. #26551 Remove title attributes: link-template.php
  8. #26560 Remove title attributes: rss.php

Group 5:

These are tickets we recommend for closure.

  1. #29475 Adding ARIA roles in wp_nav_menu
  2. #26553 Remove title attributes: comment-template.php

#4-1, #a11y, #tickets

WordPress 4.0 Release Candidate Testing

The first release candidate for WordPress 4.0 is out. If you’re interested in testing for accessibility, here’s what to focus on:

New features in 4.0

  1. Oembed
  2. Insert from URL
  3. Plugin installation
  4. Editor scrolling
  5. Media Library Grid
  6. Customize Panels

Regressions from 3.9

We don’t have a definitive list for this, but keep an eye out for anything that’s not working that you know worked in the last version.

If you run into bugs, follow the instructions from the announcement post:

Think you’ve found a bug? Please post to the Alpha/Beta area in the support forums. If any known issues come up, you’ll be able to find them here.

To test WordPress 4.0 RC1, try the WordPress Beta Tester plugin (you’ll want “bleeding edge nightlies”). Or you can download the release candidate here (zip). If you’d like to learn more about what’s new in WordPress 4.0, visit the awesome About screen in your dashboard ( → About in the toolbar).

Things to Watch

We want to keep things simple at this point. Look for any big blockers, like:

  • keyboard traps
  • confusing or non-existent tab order
  • content that can’t be accessed via keyboard
  • content that can’t be accessed via screen reader


Remove title attributes trac tickets

I’ve created all new tickets for each file referenced from the original remove title attributes trac ticket ( I originally split it up into 17 separate tickets, but closed 3 of them already, because they had already been committed into 3.8 or earlier.

I’ve added comments and/or patches, as relevant, on all of the remaining tickets – so please chime in with opinions as relevant! Many of these incorporate situations where a 2nd opinion would be valuable, because the title attribute incorporates relevant information and some alternative handling may be necessary.

Tickets: – 2nd opinion – 2nd opinion – 2nd opinion – 2nd opinion – 2nd opinion – 2nd opinion – 2nd opinion – 2nd opinion – 2nd opinion – 2nd opinion

Analysis of what gets into the alt and title attributes when adding an image into a page/post

There was some debate in last night’s IRC chat about trac ticket 26270 raised by @yaelkmiller. Her original point was that when adding images to pages and posts, the Alt text box should have more prominence than the Title box – the alt attribute being an important accessibility feature.

Personally, I think the idea is a good one, but discussion and comments by @helen also revealed some interesting behaviour when inserting images concerning what text ends up in the title attribute of the image, and what text ends up in the alt attribute.

I’ve done a series of tests using different use cases and they are presented in the tables below – including my expected results and the actual results.

Uploading images

Test No. Use Case Graham’s Expected Result Actual Result in Page
1 Upload image, add it to page with no change to Title box or Alt text box Title attribute set to image name minus suffix Title attribute absent, alt attribute set to image name minus suffix – ie what the Title box was set to
2 Upload image, add it to page but change Title box, not Alt text box Title attribute set to amended value Title attribute absent, alt attribute set to amended Title box value
3 Upload image, add it to page but change Alt text box, not Title box Title attribute set to image name minus suffix, alt attribute set to amended value Title attribute absent, alt attribute set to amended Alt text box value
4 Upload image, add it to page but change both Alt text box and Title box Both title and alt attributes set to amended values Title attribute absent, alt attribute set to amended Alt text box value

Using images from media library (previously uploaded) without amendment

Test No. Use Case Graham’s Expected Result Actual Result in Page
5 Add image from media library that has Title box set but not Alt text box Title attribute set but not alt Title attribute absent, alt attribute set to whatever Title box was before
6 Add image from media library that has Alt text box set but not Title box Alt attribute set but not title Alt attribute set but not title
7 Add image from media library that has both Title box and Alt text box set Both attrubutes set Title attribute absent, alt attribute set to whatever Alt text box was before
8 Add image from media library that has neither Title box nor Alt text box set Title attribute absent, alt attribute empty Title attribute absent, alt attribute empty

Using images from media library (previously uploaded) but making amendments

Test No. Use Case Graham’s Expected Result Actual Result in Page
9 Add image from media library, that has just Title box set, update Title box Title attribute set but not alt Title attribute absent, alt attribute set to whatever Title box was amended to
10 Add image from media library, that has just Alt text box set, update Alt text box Alt attribute set but not title Title attribute absent, alt attribute set to whatever Alt text box was amended to
11 Add image from media library, that has neither Title box set nor Alt text box set, update Title box Title attribute set but not alt Title attribute absent, alt attribute set to whatever Title box was amended to
12 Add image from media library, that has neither Title box set nor Alt text box set, update Alt text box Alt attribute set, no title attribute Title attribute absent, alt attribute set to whatever Alt text box was amended to
13 Add image from media library, that has both Title box and Alt text box set, update Alt text box Both attributes set Title attribute absent, alt attribute set to whatever Alt text box was amended to
14 Add image from media library, that has both Title box and Alt text box set, update Title box Both attributes set Title attribute absent, alt attribute set to whatever Alt text box was originally set to

Looking at the results

Using the Add Media Panel to insert an imageThe first revealing thing about these tests is that my own view of how I thought WordPress worked is at odds with the actual results in most cases.

The second thing that’s become obvious is that it’s actually impossible to set the title attribute for an image whilst using the Add Media panel. The title attribute never appears in any of the results.

Actually the only way to set a title attribute image within pages and posts is to use the older image edit dialogue box once the image is placed within the page (or to manually update the HTML obviously).

I think the confusion comes from the labeling of the Title input field in the Add Media Panel. Helen refers to this in her comments on the trac ticket I believe. Maybe to avoid confusion this box should be given another label – ‘Image name’ maybe. I confess that I hadn’t noticed this change in WordPress behaviour – it did used to be possible to directly influence the title attribute of an image when uploading and adding it to a page/post.

I’m sure that I’m not the only one who didn’t appreciate this situation. There is a plugin called Shutter Reloaded that I’ve seen on a couple of sites, which uses the title attribute from the image to provide a caption beneath the image when the full size is shown. Obviously this plugin is broken if site admins don’t realise the title attributes aren’t being written into the <img> tags – and the plugin author perhaps doesn’t realise either. I can’t comment on other lightbox plugins.

What do you think? Is this what you expected? Is this the right way to go?

#images, #media-manager, #testing

Title Attributes Galore

The patches for Trac ticket 24766 are slated for addition to WordPress 3.7. This is great news for assistive technology users who have been forced to wade through a sea of unnecessary title attribute verbiage. But we need to ensue that the patches cover all unnecessary title attributes and that those deliberately excluded from the patches do not present any accessibility issues.

Currently, the excluded methods, functions and scripts are:

  • the_author_posts_link()
  • rss.php
  • wp_fullscreen_html()
  • get_adjacent_post_rel_link()
  • _walk_bookmarks()
  • get_image_tag()
  • the_shortlink()

Continue reading

#tabbing, #trac-2, #ui