Accessibility in the Age of the Headless CMS


A few months ago I asked in the Human Made general Slack channel: “What shall I talk about at WordCamp Europe?”
And the honourable Ant Miller replied: “Accessibility in the age of the headless CMS.”

React logoGreat, I thought. A new subject, much to learn and tell about, I started to read up on the subject. And then I realised: oh no, I have to learn React!

I’m way out of my comfort zone here.

Learning React in a few months, next to my other work was kind of too ambitious. Thankfully I have some great colleagues who know a lot about this subject. So much possibilities: one page (app like) sites, fast and dynamic, integration with the REST API. Fun to learn!

And while learning, I realised what my talk should be about: how to handle dynamic changes with assistive technology.
But first of all I want to talk about what struck me the most: the loss of true coding craftsmanship.

So: I will start with how to safeguard the quality of your code in the frontend, after that how to handle dynamic changes in the content for screen readers and will finish with some ideas about performance and usability.

1 The DOM

Code is poetry

If you take yourself seriously as a developer you ask someone to review your code. The PHP code must comply with WordPress Code standards, you know: escape all the things, give the code air to breath by adding spaces, Yoda conditions, document the code. The JavaScript must be without errors.

Maybe you also have to check for VIP code standards to check for performance. You have to get creative and go through great lengths if you are not allowed to use get_terms().

If we take so much effort in getting good quality code: Then why don’t we validate what ends up in the DOM (the Document Object Model)?
It seems like a forgotten craft, writing true semantically correct meaningful HTML5.

This is not the fault of React, this totally due to the ignorance or lack of knowledge of the coder. So, what to do?

Use semantic, meaningful HTML5

Yes, I told this before, in previous talks. But while learning React it struck me that using HTML5 wrong is getting worse and worse.

These are code examples in online courses and code I found in the wild.

Don't copy this, this is wrong code. Don't add inline CSS and don't add an onClick to a list element. 
    style={lang === props.selectedLanguage ? {color: '#d0021b'} : null}
    onClick={props.onSelect.bind(null, lang)}
Don't copy this, this is wrong code. Don't add inline CSS and don't add an onClick to a div element and don't use all divs in your HTML5. 
render: function() {
        return (
                    style = {{
                        background: this.state.color,
                        width: 100,
                        height: 100
                    onClick = {this.changeColor}

For crying out loud: div and span don’t get keyboard focus!

Having the a click action on an <li> element only works for mouse or touch interaction. And not for keyboard users, but also all the other devices that interact with your site, like for example voice control.

Inline CSS is something we did in the 90’s, before the invention of the stylesheet. Separate your CSS from the HTML, use classes. It’s so easy to stay in your JavaScript bubble, but take pride in the quality of the code that ends up in the DOM.

  • use the <a> element for a change of location (this also can be an internal link, like #about)
  • use the <button> element to invoke an action

Then you get all behaviour for free!

Google the words “React div onClick” and be amazed how creative people can get ignoring the obvious: use a button …

All DIVs create a meaningless DOM

React coders seem addicted to the <div> element. This creates a flat meaningless DOM.

<sarcasm>Just put everything in a <div>, add the CSS styles inline and you’re done. Why? Because you can get away with it. And it works for you. Why use separate CSS if you just can stay safely in your JSX bubble.</sarcasm>

What happened to “user first”? Get out of your JavaScript bubble! Don’t JavaScript all the things! Please don’t use inline style because you can’t be bothered writing an extra class.

Personally I don’t get this.
React is difficult to learn. Especially if you dig deep into it. It is hard work.
Then why don’t you pay any attention to the quality of what ends up in the DOM? Because the DOM is what the user interact with. Use meaningful HTML5.

Code is poetry.
Take pride in your workmanship.

HTML5, that’s what served to all the technology that reads your page.
Not only your desktop, laptop, tablet, smartphone, iWatch. In the future maybe also your refrigerator, car or whatever ways we invent to interact with the interwebs. This is not only important for accessibility, but also for sustainability. Build for the future.

HTML5 logoSo: Learn HTML5 deeply.

It’s not rocket science. If you can master React, learning HTML5 is easy. A very good resource is Maintained by people who also write the HTML5 specs. With documentation on all HTML5 elements and posts about recent developments.

Accessibility is not holding back the speed of development of WordPress, it safeguarding the code quality and sustainability. We go far to make our PHP, JavaScript and performance perfect, please take as much care of what ends up in the DOM.

Validate the DOM

There are a few ways to validate the DOM:

  1. Keyboard test
  2. Run your page though the HTML validator of 3WC
  3. Run your page though the CSS validator of W3C
  4. Use test software like aXe, by Deque Systems

I particularly like aXe. I use the browser extension that adds a tab to your inspector with an option to analyse the page for HTML and accessibility errors.

axe tab in the inspector

But you also can use aXe-core as NPM module and integrate it in your Gulp or Grunt routine.

Dynamic changes

So: here the fun starts.

Dynamics is what makes React and integrating the REST API valuable and so much fun. No page reload, all the data is already there, super fast and flexible.

If your eyes work you can see the changes. But what if you can’t see that well? Then the changes need to be announced to you, so you can hear them. Or feel them, if you use a braille line.

How to do this? Here ARIA comes to the aid. WAI-ARIA means “Web Accessibility Initiative – Accessible Rich Internet Applications“, also known as ARIA.

ARIA are attributes you can add to HTML5 elements to give assistive technology information on what’s going on. ARIA is supported in the latest versions of all major browsers and assistive technologies support ARIA. Increasingly, JavaScript widget libraries such as jQuery UI include ARIA markup as well.

First rule of ARIA: don’t use ARIA!

This seems contradictive, but ARIA is not to fix bad or over complex HTML5.

Rule of thumb: If there is a pure HTML5/CSS solution: use that! You get all functionality for free. Keep it simple.

When is ARIA useful?

It’s all about giving the user of the device feedback:
What happens on the page, what does it mean, how can I interact?

I want to give you an example of 2 uses of ARIA for dynamic pages


<div aria-live=“polite”>

    <p>This is where the magic happens</p>


What changes inside an element with aria-live will be announced by a screen reader.

Aria-live has two different behaviours:

  • aria-live=“polite” : updates announced if the user is idle
  • aria-live=“assertive” : updates announced as soon as possible


Is a menu open or closed? You can add this information to the button that toggles (show/hide) the content with jQuery (for example).

<button aria-expanded="false" class="expandable">Great quote</button>

<div aria-hidden="true" class="expanded-content">
        <p>Make our planet great again</p>
             — <cite>Emmanuel Macron</cite>

The aria-expanded is put on the button, because that’s what gets focus and is announced. The user can decide to open the content and read from there, or don’t open it and then the content stays hidden.

Good resources for ARIA:

3 Progressive enhancement

There is much to say about this, and also much to research!

To say it simple:
Progressive enhancement means:

  • serve content first (HTML)
  • then add the presentation (CSS)
  • and after that add the client side scripting (JS)

first content, then presentation, then client-side scripting

But what decisions to make, when the content is heavily depending on the scripting, as it is with a one page site?

What I would like to propose for now:

  • build the HTML5 framework first
  • have all CSS in a separate css file and never inline
  • determine what is dynamic and script for that only
  • serve initial content

This will ensure the user will get meaningful content served before the JavaScript kicks in.

Last take away from my research

Niet omdat het moet
maar omdat het kan

This is a Dutch saying meaning:
“Not because you must, but because you can”.

If you are a clever, hardworking coder, spending much time learning, studying how to build complex applications. Please take a step back and look at your work, and ask yourself: Am I serving my user or my ego?

The W3C HTML Design Principles state:

over authors
over implementors
over specifiers
over theoretical purity

Or, to speak with Jeff Goldblum in Jurassic Park:

Jeff Goldblum in Jurassic Park

Developers are so preoccupied with whether or not they could,
that they didn’t stop to think if they should.

Don’t create a monster.

Code is poetry
Write a poem with your HTML5

WordPress, state of the Accessibility 2016

How accessible is WordPress now (2016), which improvements were made in the last years and what still needs to be done? Where can you find help and documentation to improve your code? What are the new Accessibility Standards, added to the WordPress Coding Standards?

How accessible is WordPress now, which improvements were made in the last years and what still needs to be done? Where can you find help and documentation to improve your code? What are the new Accessibility Standards, added to the WordPress Coding Standards?


This post is written for my presentation at WordCamp Europe 2016 in Vienna. You can find the Slides at Slideshare and the video on

How accessible is WordPress core at the moment?

Well… It depends…

It depends on

  • How smart you are using the internet
  • What assistive technology you are using (like keyboard only, zoom text, a screen reader, adjusted colours, voice recognition software)
  • How well you can use your assistive technology
  • How good your internet connection is
  • Which browser and device you use
  • Where you live: who tests for Opera Mini, a mobile browser widely used in Africa?

But overall, if you don’t get too fancy and keep it simple: the accessibility of WordPress core is pretty good!

If we look at the front end

And the Admin

If you are a keyboard only or screen reader user you can:

  • Add and edit content and markup, with now also editor shortcuts and in WP 4.6 an improved Tag and Category management
  • Add and edit a menu
  • Add and remove a widget, in the screen options you can enable the accessibility mode, which makes it keyboard accessible

So, overall

Publishing and maintaining an accessible website can be done, sometimes with more explanation and training for content managers using assistive technology.

But the basis: an accessible front end theme, adding and maintaining content and setting up a menu: all totally doable.

Work that still needs to be done

But there is still a lot that needs improving and is work in progress. At the moment we have more than 100 tickets in WordPress trac labelled accessibility.

Colour in the Admin

The colour contrast between text and background in the admin can be improved. This is work that needs to be done together with the design team. We don’t want to end up with something ugly or totally different from the official WordPress colour scheme.

But besides this: what about adding an additional very high contrast Admin Colour Theme? This would help many users with difficulties seeing contrast.

Legacy code

How to improve the HTML we inherit from previous releases and that is also heavily used by plugins? We can’t just change this into something decent, it will break plugins or themes.

For example:

  • The Settings API is still in HTML-tables and we all know now: tables are for displaying data and not for handling layout.
  • The “add new” link inside the headings of admin screens.
  • The title attribute in the tag cloud widget. To remove that we may need extra CSS in the front end of a theme, like screen-reader-text class support.

Solving this need the cooperation of the design team and core team, but also the help from theme and plugin authors. If we change code like this we need to communicate this with them very carefully. We don’t want to break stuff while trying to fix it. Broken stuff isn’t accessible at all…

Consistency within the admin screens

“Don’t make me think” is a universal rule in web development. People expect things to work in a certain consistent way. This is not only the case for people using assistive technology, it is the same for all of us.

For example the Search in the admin.
In list tables like all posts and all pages, the search input field is on the right together with a submit button.


On the search theme page it is on the left next to the title, without a visual submit button, but with a placeholder.


On the search plugins on the right again, also without a visual submit button, with a placeholder.
How many times have I unintentionally installed JetPack because the “install now” button was the first button in site, as I am used to press a button to start the search.


A good read on how to design plugins (and featured projects) is by Tom McFarlin Improving WordPress Plugin User Experience:

Try to make sure that your project tightly integrates with the core WordPress user interface

Review of accessibility-ready themes

Not a code issue, but a workflow issue is the way we are reviewing themes submitted for the accessibility-ready tag in the repository.

A theme developer submits a new theme, takes pride in making it beautiful and also accessible. And then has to wait up to 5 months to get a response. That’s way too long.

When eventually the theme author gets a response about the accessibility they’ve already moved on and abandoned the theme. Or dropped the accessibility-ready tag altogether.

So if a review is delayed, in a lot of cases it’s time wasted. We need to find a way to turn this around. This is not the fault of the people who do the reviews. They are volunteers, doing this besides their full time job, and reviewing takes time, also there are a lot of themes submitted.

So we now have a situation where themes are submitted and withdrawn or abandoned for the accessibility-ready tag, that is such a pity!
What we need is a better workflow, more reviewers and a way to automate the process. If you know how to solve this and want to contribute to this, please reach out to us in the #accessibility Slack channel.

Subtitles and translations

During the last year work has been done for to make the video’s more accessible for screen readers and keyboard users. That’s wonderful! So lets take this to the next level:

On May 18, 2016 there were 4648 videos of presentations on, of which 246 have subtitles.

That’s 5%.

We can do way better than that!

Maybe, from now on, every speaker should add subtitles to their own presentation (or organise someone who does that for them). We all hate it to hear our own voice and listen to the mistakes we made. But subtitles and translations give you a larger audience and that’s why you were speaking in the first place anyway.

And then there is the Media

Where to start.

In my opinion the Media needs to be a featured project, we need to rebuild the Media, new, from scratch.
We need to research how to add and maintain images, galleries, files, audio, video, subtitles, translations, captions, descriptions. How to do this in a beautiful, usable, consistent and accessible way.

All the accessibility repair work we do now is like solving problems with duct tape instead of building for sustainability.
The Media is complex functionality and at the moment people using keyboard only or a screen reader have major difficulties using, understanding and navigating it.

Changing the Media will be huge effort, will take time and team work. Not only from the accessibility team, but also from the design team, the core team and the people working on Images Flow project. If you have ideas on how to start and manage this, please contact us.

We need to keep focused

WordPress is constantly changing and being improved on. We are lucky to be part of such an active,  enthusiastic and knowledgeable community.
We all need to stay alert and keep focussed on the accessibility of what we build.

If not, we end up with functionality that is built from a visual and mouse driven point of view only, with no respect for semantic HTML or W3C code validation or accessibility.
Where accessibility is added later with duct tape solutions. This results in ugly code that is more difficult to maintain.

Like recent big developments based on React in the WordPress world, stating that we can keep and use the old Admin as fallback is not the way to go. Good code works for everyone.

To be clear: JavaScript is not the enemy, we just need to do more research and keep testing new functionality. Aim to keep everything as accessible as we can for everyone.

For example: the Customizer is an accessibility challenge and a playground where we tried out improvements limited to the Menu Customizer.


And now for the good news: 2015 and 2016 have been amazing!

WordPress goes WCAG

To start with the best news:

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. So: WordPress goes WCAG.

In short:

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

Wat does this mean?

In April this year the European Union agreed on an accessibility directive for websites, intranets, digital documents like PDFs and mobile apps. Heather Burns wrote an excellent overview on what this means: Bigger, better, and brilliant: EU approves a new #a11y directive.

When your country makes this directive into law (as many already have or soon will do), governement and public sector web sites must be WCAG 2 AA accessible. So by adopting WCAG, WordPress is getting ready for laws within the EU.

Implementing this will mostly be an effort for theme and plugin developers and we need to reach out to them and help. Coders and designers need to learn the how and why. We can’t expect everyone to know all the WCAG guidelines by heart.

So the accessibility team started to provide help with:


Last December, at the community Summit before WordCamp US 2015, Trisha Sales and
Barrett Golding laid out the framework of our new Handbook, to provide developers, designers and content managers with good resources on accessibility. The aim was not to rewrite every document there already is on the web, but to guide you to the resources already there and also give specific WordPress info.

This is still work in process and the documentation will change and improve over time. But if you need a place to start your study, read the Handbook and go from there.

Let WP speak

A useful new JavaScript method was added in WP 4.2: wp.a11y.speak().
According to Joe Dolson:

This method provides 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.

Test team

You might not realise this, but WordPress is used as a content management system by many people using assistive technology. And when we called for testers we got responses from many of them. They finally could speak their minds and were eager to help, to make their own life and that of others easier.

We now have a test team with more than 75 people: users, accessibility experts, WordPress developers. They get an email regularly with an issue to test and we report the results back to the core developers.
For this we have a dedicated test server, kindly sponsors by Nimbus Hosting Ltd.


If you are doing work for WordPress core, and want your work tested for accessibility, please contact us in Slack. We can set up a test and get the result back to you with  recommendations on how to improve your work.

Where do we stand now?

We’ve got a great accessibility team and the support of the core developers and release leads. We have time on our side: Web accessibility has became an important worldwide topic, with countries changing their laws to ensure government and public service sites become accessible. WordPress is following that trend thankfully.

Better communication

The Accessibility team works more effectively and we communicate better with the other teams. Last year Andrea Fercia did a ton of work on fixing and researching issues in core. By doing this he earned rock start credits for 4 releases in a row, and is now a core committer. Very well deserved!

Going to the yearly Community Summit, WordCamp US, other WordCamps and contributor days proved to be very useful.

Life outside WordPress

Not only inside, but also outside the WordPress community, people are reaching out to us, for discussion and research.  Together we can test and research the issues we share, like we did for Select2, a jQuery based replacement for select boxes.

And I discovered: WordPress can push buttons.

With such a large percentage of the web running on WordPress, it is also important for browsers and assistive technology companies that their software runs well with WordPress.

For example: When we called for testers with Dragon NaturalSpeaking, Alex Korik, the head of Software Quality at Nuance, offered to help.

And the best thing ever: WordPress developers and designers start to learn a11y and take responsibility. Like developers in the Genesis Community.

We are no longer a standalone group easily to be ignored, but we are integrated in the teams and accepted as a part of the workflow.

So… what can you do?

While you are learning JavaScript deeply,
please learn accessibility deeply too!

Workshop Keyboard Navigation

Short workshop on how to navigate a website with a keyboard only.

The basics

  • Tab: Move forward from link to link or to controls
  • Shift + Tab: Move backward from link to link or to controls
  • Enter: Activate links, buttons, or other interactive elements
  • Arrow: Navigate radio buttons and select boxes and scroll up and down a page
  • Spacebar: Activate radio buttons and check boxes and buttons

Keyboard Navigation Overview on WebAIM

Focussable elements

  • a
  • button
  • input
  • textarea
  • select

Demo: Codepen Navigate with keyboard

Note: Activate Keyboard Navigation in Mac Browsers

Visible Focus

Browsers add a visible focus to an element but some CSS resets add: outline: 0;
This makes it very hard to navigate a site.

No visual focus: Donald J. Trump

Add :focus where you add :hover in your CSS.

Tab index

Add focus to an element:

  • tabindex: 0 gives focus to items that wouldn’t normally get focus and includes them into normal tab order
  • tabindex: -1 gives focus to items that wouldn’t normally get focus and/or removes items from the normal tab order
  • tabindex: any positive integer gives focus and overrules normal tab order

Avoid hijacking the tabindex: it makes it very hard for keyboard users to access the menu.

In Gravity Forms

Skip Links

Special links to help keyboard users to jump quickly to content.


Fixing “Skip to content” links

Dropdown menu

Do the sub menus show on focus?

Code example:

Hamburger menu

Use focusable elements to toggle


Close with Esc!

The Incredible Accessible Modal Window, Version 3

Avoid a keyboard trap