I have resigned as the WordPress accessibility team lead. Here is why.

Update December 5, 2019:
As I am no longer part of the accessibility team and don’t follow closely what is happinging in WordPress core anymore, I’d like to add to following.

This post was about the state of WordPress end 2018. In the meantime other people have stepped up and there have been made improvements to the accessibility and there are effords to change the workflow of a new release and of new features. If you want to know more about the current state of the accesibility of WordPress core, please contact the current WordPress Accessibility team.

Update October 12, 2018:


This post is written with the Gutenberg editor version 3.9.0.

Disclaimer: This post is my opinion and mine alone.

After several years of working on WordPress and accessibility and being part of the accessibility team, I have taken the very difficult decision to leave the WordPress accessibility team. I owe it to the team to explain why I have made this decision and how I hope things can improve for the future.

The last year, especially the last few weeks have been too politically complicated for me. It’s better that someone else takes the lead now.

In this post I’ll try to give an analysis of what the WordPress Accessibility Team (wpa11y team) did during the development of Gutenberg and what the problems are with working on  its accessibility.

Gutenberg

When the development of Gutenberg started, the wpa11y team followed its progress and tested what was there. And we discovered there is much to improve. So Andrea Fercia started to open tickets and tried to find solutions. And that was a huge task.

Codebase

We had four big problems:

  • The codebase of Gutenberg is difficult for all of us, because no one in the wpa11y team is a skilled React developer. So it was hard to implement changes and write PRs ourselves. What we could do is test, tell what’s wrong and what it should be and hope a developer would pick it up. A lot of a11y work has been done by the Gutenberg team but major issues still exist.
  • There was no React developer with accessibility experience in the community, and no React accessibility experts from outside the community willing to work on the issues for free.
  • Functionality that was tested, improved and then approved by Andrea, changed in a later stage, breaking the a11y improvements again. This had quite an impact on Andrea.
  • New functionality was not keyboard tested before implementation (e.g. the date picker).

I used my network to try to get the accessibility experts, companies and developers that know React and accessibility involved. We did a test round in March this year, after asking to the Gutenberg lead when it was ready to do a full test. The results are with the test procedure and with the issues on GitHub.

A complete overview of the test results, with video demos are in the post:
Accessibility of Gutenberg, the state of play.

The results indicated so many accessibility issues that most testers refused to look at Gutenberg again.

Education

Because we could not code all Gutenberg issues ourselves, I decided to help and educate the developers and designers.

Sami Keijonen and I started to extend and reorganise the WordPress Accessibility Handbook adding good practices and ways to test code, content and design. We did a lot of writing, so when filing a GitHub issue, the author can now point to a handbook URL to say: “this is how it’s done”.

This handbook is still being worked on by Jaap Wiering and Daniel Koskinen. See the #accessibility-docs channel in Slack for the discussions about this.

We did research on automated testing. This is still a work in progress as it’s difficult to set up. I wrote a blogpost with my research in Automated accessibility testing during development on the Human Made website and I was gathering the troops to get this on a higher level.

Also, we started a series of dev talks about a11y on meetups and WordCamps.

One good thing to say about all of these Gutenberg preparations is that they increased the visibility of the accessibility team, and it is very good to see them finally getting recognition for their work.

Assistive Technology Manual

For users that depend on assistive technology (AT), like a screen reader or voice recognition software, the learning curve of Gutenberg is very high. If you don’t have a full view of the whole screen or are depending on keyboard focus to perform tasks, Gutenberg is hard to learn.

Claire Brotherton has started to write this manual and she needs AT expert help. See the GitHub issue Manual for users of assistive technology #10373.

5.0 is near

Now Gutenberg is close to release: how accessible is Gutenberg?

In Andrea’s words (and I agree):

“While the Gutenberg team has worked hard to implement some fundamental accessibility features (e.g. focus management, navigate landmark regions), the overall user experience is terribly complicated for users with accessibility needs at the point the new editor is barely usable for them.

The main reason for this lack of overall accessibility is in the overall Gutenberg design, where accessibility hasn’t been incorporated in the design process.

Feedback from accessibility users has been constantly evaluated and Gutenberg is actually a regression in terms of accessibility level, compared to the previous editor.”

Andrea Fercia

What went wrong?

I got feedback this week that we should have written the GitHub issues differently. I was told we should have explained more why they are an issue, so that the developers are more motivated to solve them. Also I got feedback that some accessibility issues are too big, that we should have made them smaller.

It would have been great if this feedback had been added with the issues themselves in a timely way, as some issues are now more than a year old.

In hindsight, what I would have done differently:

  • communicate more often and louder we needed a skilled Gutenberg/React developer way earlier in the process
  • convince the developers that keyboard testing is a must
  • support Andrea more when he asked for a second voice and for testing
  • convince the AT testers to give it a go again
  • invest more effort in recruiting accessibility experts and companies to help

Full time dev

I’m happy that there is now a dedicated developer from Automattic 100% on the accessibility issues. I wish Matthew MacPherson all the best, as he will need it. I hope the accessibility team will help him with everything he needs.

To Matt Mullenweg

To Matt Mullenweg I want to say: please take better care of your community, because WordPress is nothing without it. Cherish the people who dedicate their (own) time and who work very hard to make WordPress the best it can be. Don’t ignore or make fun of them, but talk to them, guide them, inform them. Don’t be disconnected from the community, be part of it.

Thank you

It has been a privilege to work in the accessibility team. I cannot thank them all here. But there are a few people I want give a huge thanks to:

  • Andrea Fercia, who works hard against the odds and often alone on the GitHub issues. I wish I could have provided you with more support for testing.
  • Claire Brotherton, who does a lot of testing and started to write the manual for assistive technology. Claire, you are the unsung hero here, you did so much, and in your own time. You rock girl.
  • Adrian Roselli, who flew several times from the US to WordCamp Europe and London, to help the accessibility team test and find solutions.
  • Eric Wright, who made an excellent video on how difficult it is to use Gutenberg with Dragon NaturallySpeaking.
  • Sami Keijonen, Jean-Baptiste Audras, Laken Hafner, Nic Bertino, Amanda Rush, Rachel Cherry, Chetan Prajapati and all the people in the #accessibility channel, for their contributions and discussions.
  • Morten Rand-Hendriksen, for his help, support, networking, inspiration and time, and for letting me smoke all my cigarettes in his face at the after party in Belgrade.

What now?

I’m not leaving WordPress nor accessibility, and in fact maybe now I can actually work on accessibility again. I will keep giving talks and workshops. I also want to do research and work on tickets. But in my own pace.

I will join the a11y table if asked on contributor days, but maybe I’ll just go to a museum instead.

For Level Level, the company I now work for, I’m setting up workshops and trainings to teach web accessibility and good code practices. Also I will help the designers, content managers and developers of Level Level to become the best agency for accessible WordPress websites there is. Stuff I enjoy to do and that gives me positive energy.

I wish you all the best, and please reach out if you need my expertise or just want to have a chat or share a glass of wine.

Love,
Rian


Keyboard test Gutenberg, a first try

Goal of this Gutenberg test is to see where currently the problems are and collect data to write a manual for keyboard users. Also I want to learn and construct a standard test for other assistive technology. The test is set up to do the most common tasks for a content manager (who is not a developer). Like add and modify text, headings, images, lists, tables, and embeds.

The test results are part of the large scale Gutenberg  testing for Accessibility, organized by The WordPress Accessibility team.

Continue reading Keyboard test Gutenberg, a first try

Accessible custom styled form elements

The challenge

HTML elements like check buttons, radio buttons or select options can be hard to style with CSS in a custom design. There are many workarounds for this, based on two different approaches:

  1. Hide the form elements from sight and apply the styling on a container or related element
  2. Hide the form elements from sight and rewrite the functionality, using styleable elements like <div>s and JavaScript

Continue reading Accessible custom styled form elements

Looking back on 2015 and forward to 2016

Last year I changed the focus of my company. I wanted to do web accessibility related work only. The plan was to:

  • build and maintain accessible websites only
  • give accessibility training to web developers and graphic designers
  • help developers and companies fixing accessibility issues
  • give talks on WordCamps and Meetups
  • keep contributing to WordPress

Continue reading Looking back on 2015 and forward to 2016

Fix the accessibility of your Genesis responsive menu

The Genesis Framework is my favorite tool to build a WordPress website. And with the next update (version 2.2) a lot of accessibility features and fixes will be added. But a framework is no child theme.
The HTML5 themes you can purchase with StudioPress have a beautiful responsive menu for the primary navigation. And that menu is completely inaccessible for keyboard and screen reader users.

What’s wrong?

The HTML code to show the responsive menu is:

 <div class="responsive-menu-icon"></div>

A div is not focusable, if you tab though a page the menu is skipped and you have no way to open it, only by using a mouse. And also the div is an empty container, with no content.

What needs to be changed?

  1. Change the <div> to a <button>, a button is focusable and clickable
  2. Add some text inside the  <button></button> to tell a screen reader user what the button is about. You can make this visibly hidden by using the screen-reader-text class
  3. Tell a screen reader user if the menu is open or closed by adding dynamically aria-expanded=”false” or aria-expanded=”true”

How can you do that?

The Genesis child themes use js/responsive-menu.js (GitHub) to show the responsive menu.
Change this JavaScript into for example:

jQuery(function( $ ){

 $(".nav-primary .genesis-nav-menu").addClass("responsive-menu").before('<button class="responsive-menu-icon" aria-expanded="false"><span class="screen-reader-text">Menu</span></button>');

 $(".responsive-menu-icon").click(function(){
 var _this = $( this );
 _this.attr( 'aria-expanded', _this.attr( 'aria-expanded' ) === 'false' ? 'true' : 'false' );
 $(this).next("header .genesis-nav-menu, .nav-primary .genesis-nav-menu").slideToggle();
 });

 $(window).resize(function(){
 if(window.innerWidth > 768) {
 $("header .genesis-nav-menu, .nav-primary .genesis-nav-menu, nav .sub-menu").removeAttr("style");
 $(".responsive-menu > .menu-item").removeClass("menu-open");
 }
 });

 $(".responsive-menu > .menu-item").click(function(event){
 if (event.target !== this)
 return;
 $(this).find(".sub-menu:first").slideToggle(function() {
 $(this).parent().toggleClass("menu-open");
 });
 });

});

See an other accessible example of an Accessible Genesis responsive-menu.js at GitHub. With the visual text “Menu” (I hate hamburgers) and a leading heading.

You have to add the screen-reader-text class and maybe change the CSS .responsive-menu-icon to style the button so it fits your theme.

So: by changing a few lines of JavaScript and adding a few lines of CSS you turn your responsive menu into a perfectly accessible awesome responsive menu.

Discussion

Yes, this is a quick and dirty fix. There’s now untranslatable hardcoded text in the JavaScript, this could be done way better and cleaner. But you’ve got the picture of what needs to be changed. If you are a JavaScript pro: all help is welcome 🙂

The screen-reader-text class, why and how?

Imagine you are blind, how do you understand a website? You would use a screen reader. All the text in a website is read out loud for you, from top to bottom. To navigate a site you can call a link list and a headings list.

The headings list you can use to navigate inside the page. Jump to a heading of interest and read from there. With the link list you can choose where to go next. There are more ways to navigate a site, but links and headings are most commonly used by screen reader users.

How can you decide where to go, when a lot of the links in a page are called “Read more”. Read more about what?

So, if you are a web developer, how can you help your blind visitor to understand your website? First of all: use headings that make sense. And second: use link texts that tell where they are linking to. And here the screen reader text comes in: it hides text from screen, but not from a screen reader.

For example links with the text “Read more”, “Continue reading” or a plain “>” or a font awesome icon. Looks neat and small and is incomprehensible for your blind visitor. But writing the whole post title in the read more link is long and ugly.

How to fix the “Read more” link?

Say you have the HTML:

<a href="url-here">Read more</a>

You can change this into:

<a href="url-here">Read more<span class="screen-reader-text"> about cute kittens</span></a>

For WordPress for example:

<a href="<?php the_permalink(); ?>">Read more<span class="screen-reader-text"> about <?php the_title();?></span></a>

And then you add the CSS in your stylesheet:
Note: this CSS is update on October 2017

/* Text meant only for screen readers. */
.screen-reader-text {
  border: 0;
  clip: rect(1px, 1px, 1px, 1px);
  clip-path: inset(50%);
  height: 1px;
  margin: -1px;
  overflow: hidden;
  padding: 0;
  position: absolute;
  width: 1px;
  word-wrap: normal;
}

The element with the class screen-reader-text is made very small with clip, which needs the position absolute. Not visible for the eye, but read out load by a screen reader.

Don’t use display: none; or visibility: hidden. Screen readers don’t speak those, so that’s no use in this case.

Font awesome and other icons

How about your social media icons:

<i class="fa fa-twitter"></i>

It’s just an empty container and the <i> has a semantic meaning: text in an “alternate voice”.

Better use:

<span class="fa fa-twitter" aria-hidden="true"></span><span class="screen-reader-text">Twitter</span>

By the way: You can help changing this inaccessible way of implementing Font Awesome by joining the discussion in the Font Awesome GitHub.

Richard Senior did an excellent write up about WordPress, Font Awesome and Accessibility.

Labels in forms

A form input field needs a label. It’s just good practice and it tells a screen reader user what to fill out. A placeholder is no label, screen readers don’t read them well. But a label takes up space and maybe you don’t want that in your theme. So hide it with screen-reader-text.
For example in the WordPress search form:

<form role=”search” method=”get” class=”search-form” action=”url-here”>
<label for=”search-id” class=”screen-reader-text” >Search this website…</label>
<input name=”search” type=”text” value=”” placeholder=”Search this website…” id=”search-id”>
<input type=”submit”  value=”Search”>
</form>

Hiding links

As a service to screen reader users and keyboard only users you can add skip links at the top of a page. That way a visitor can quickly jump to e.g. the content, without having to tab though the navigation.

They look something like this:

<ul class="skip-link">
 <li><a href="#nav" class="screen-reader-text">Jump to main navigation</a></li>
 <li><a href="#content" class="screen-reader-text">Jump to content</a></li>
 <li><a href="#footer" class="screen-reader-text">Jump to footer</a></li>
</ul>

Some JavaScript is necessary to make skip links work properly.

If a visitor can see, it’s nice if the skip links are visible when they come in focus while tabbing though the links. So you can add the CSS to do that:

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

The screen reader text in more detail

Clip versus absolute positioning


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

This technique is pretty solid and works in all browsers however there are two main issues with this technique – its relatively easy to break, and it can cause a page “jump” if applied to focusable elements (like skip links and read more links), which can be very confusing to sighted keyboard users. [Reference:  Jeff Burnz and Jonathan Snook]

Different ways of doing it

Gary Jones collected a few different ways of hiding text with clip. And there are more variations. Pick the one that suits your theme or adjust it to your needs.

What about:

clip: rect(1px, 1px, 1px, 1px);

versus

clip: rect(0, 0, 0, 0);

I couldn’t find a specific reason to use 0 or 1px, they both seem valid.

Back and forward compatibility

Clip is deprecated in CSS3, but supported by most browsers, it’s replaced by clip-path. Internet Explorer below version 8 doesn’t want a comma as separator and up to version 11 it doesn’t support clip-path yet, so you end up with:

clip: rect(1px 1px 1px 1px); /* IE6, IE7 */
clip: rect(1px, 1px, 1px, 1px);
clip-path: polygon(0px 0px, 0px 0px,0px 0px, 0px 0px);

The other way around: hide from a screen reader

The other way around is also possible. If you have an element that’s not relevant for screen reader users, you can hide it by adding aria-hidden=”true“.
This is used for example in the WordPress Admin for hiding a separator in the main menu.

<li class="wp-not-current-submenu wp-menu-separator" aria-hidden="true">

</li>

ARIA roles (Accessible Rich Internet Applications) are instructions for screen readers you can add to your HTML.

WordPress and the screen-reader-text

The name of the class is up to you, but “screen-reader-text” is the standard name for WordPress, and is used by WordPress core in the Admin and the front end and in the bundled themes like Twenty Fifteen. As from version 4.2 this class is WordPress generated CSS, so it’s important that you add it to your theme before updating to WordPress 4.2.

The screen-reader-text wil be used for the get_search_form, the comments_popup_link, the archives and categories dropdown widgets and will be used in more cases in future releases.

If you are a WordPress developer and want more controle over this, please support Gary Jones by commenting on his ticket add_theme_support( ‘screen-reader-text’ ).

Plugin

And if you can’t add the screen-reader-text class yourself to a WordPress theme: there’s a plugin for that.

Read more screen reader text: I knew you would check

  1. Hiding content for accessibility by Jonathan Snook
  2. CSS in Action: Invisible Content Just for Screen Reader Users on WebAIM
  3. Hiding text for screen readers with WordPress Core by Joe Dolson
  4. Clip Your Hidden Content For Better Accessibility by Thierry Koblentz
  5. Understanding the CSS Clip Property by Hugo Giraudel
  6. Using CSS clip as an Accessible Method of Hiding Content in Drupal, by Jeff Burnz
  7. WordPress plugin “.screen-reader-text” theme support by Jaime Martinez

Photo Read More tattoo: Cory Doctorow.

How I Stopped Worrying and Learned to Love the WordPress Community

WordPress and Accessibility. It has always been a difficult discussion. The developers wrote code, without knowing what’s important for someone that doesn’t see a website like they do. And the WordPress Accessibility team could not find the time or voice to help them fix the problems. So we asked members of the WordPress community for help, and they answered!

Continue reading How I Stopped Worrying and Learned to Love the WordPress Community

Accessible HTML5 heading structure in WordPress

How to get a WordPress developer all emotional and fanatic: discuss about heading structure.

Here’s my point of view on how headings should be set up in a WordPress theme. And an overview of the pros and cons brought up in discussions.

Continue reading Accessible HTML5 heading structure in WordPress