Theme Switcher: Accessibility test result

Accessibility test results of the new Customizer Theme Switcher

Customizer Theme Switcher Beta Version 0.7
On WordPress 4.2-Alpha nightly build

@afercia (keyboard, screen-reader, code review, report)
@trishacupra (keyboard)

The report is divided into:

  • Must have
  • Nice to have
  • General Customizer issues
  • A11y unrelate issues

Must have

1. The accordion title

The accordion title doesn’t convey enough information about the purpose of this section. The text just says, for example:

Theme: Twenty Fifteen
Press return or enter to expand

OK, that’s nice to know… but what I can do there when it’s expanded?
Text should say also something like “preview more themes” or similar. This is a UI issue for all users: I just clicked on “Customize”, I know I’m in a place where I can customize things. So what I understand is I can “Customize Site Title & Tagline”, “Customize Colors” etc. and for analogy with other titles the information I get here is that I can “Customize Theme: Twenty Fifteen”. Nothing about a “preview”.

2. Empty tab stop after “Add New” and before search.

Just on first load, ‘.theme-overlay’ has display: block meaning is visible (though empty) AND is focusable:

<div class="theme-overlay" tabindex="0"></div>

Empty tabs stops are confusing for users, they can’t figure out what’s in there. What happens after you open and then close the modal? fadeOut() sets display to none and ‘.theme-overlay’ is no more focusable: no more empty tab stop. Should be display: none also on first load, to avoid the empty tab stop.

3. Missing label

#themes-filter “search installed themes…” has no label

4. Focus + Enter on “Theme Details”

Focus + Enter on “Theme Details” doesn’t trigger the details modal.

Everything must be operable with a keyboard.
Elements need to be focusable to receive keyboard events. Why binding keydown event on ‘.theme-screenshot, .more-details, .theme-name’ when they’re not focusable. No focus, no keydown event. What about to bind keydown directly on ‘.theme’ which is already focusable? And then move ‘.theme-actions’ out of ‘.theme’ and position it absolutely?

5. ARIA role and aria-label on the details modal

ARIA role and aria-label on the details modal, to give feedback a modal is currently open.

<div class="theme-overlay" tabindex="0" role="dialog" aria-label="<?php esc_attr_e( 'Theme details' ); ?>"></div>

This way, when the modal opens, screen reader will read out:
“Theme details dialog”
Without this, screen readers will start reading out all the content of the dialog, with no feedback about a dialog is actually open, e.g.:
“out of list” (meaning it’s exiting from the themes list)
“Show previous theme button, Show next theme button, Close overlay button, Twenty Fourteen Version: 1.3” etc…

Important: to be done together with point 2.

6. Close button.

For consistency with 5., change the close button text in ‘Close details dialog’.
Current text ‘Close overlay’ doesn’t help me to understand what an “overlay” is, that’s developers language.

7. Contain keyboard navigation inside the modal.

When a modal is open, keyboard navigation must be contained inside the modal.

WordPress already does this for almost all of its modals. Every modal has its own way… we should standardize this sooner or later.
We can provide a working code example, not a real patch, we’ve just patched the plugin locally. Code borrowed from media-views “”.
It’s just an example, this feature can be implemented in many different ways, see for example other modals (wplink, etc.). Little concerned about jQuery UI :tabbable performance, maybe not an issue.

8. The preview <iframe>

The preview <iframe> should have a title attribute.

9. Focus on Add New Theme box

Focus on Add New Theme box (the last one in the left sidebar). Recommended: make focus style same as hover.

Nice to have

10. Tabbing in the modal

Tabbing in the modal, there’s no easy way to find information about the theme! for example in this text:

Twenty ThirteenVersion: 1.4
By the WordPress team

only “the WordPress team” is a link, when read out of context has no useful meaning. Would be nice to have some more text in the link (maybe using screen-reader-text) with the current theme name. Needs .org API change?

11. Collapse/expand link

Tester’s report: “Can’t figure out how to navigate to the ‘expand’ arrow after collapsing the customizer.”

Important: when the sidebar panels slide out and are out of view, they’re still focusable and “tabbable”. You can tab through them and also activate their controls, just focus one of them and press Enter.

Recommended: when panels slide out and their animation ends, they should really be hidden with display: none to make their controls not focusable.
Similar to what currently happens in media views, see: #30599

12. Collapse/expand link focus style

Improve the collapse/expand link focus style

13. Jump from the sidebar pane to the preview pane

Consider having some sort of mechanism to quickly jump from the sidebar pane to the preview pane and vice-versa.

Say you’re a keyboard user, you choose a theme and you press Enter on the “Live Preview” button. Page is updated and focus is lost. To navigate with the keyboard to the preview pane, you have to tab through all the sidebar controls first.
Same when you want to return to the sidebar pane after finally getting to the preview pane.

Tester’s report: “Can’t find a way to skip straight across to the theme preview pane on the right in order to explore the new theme preview, scroll up and down to check out the theme, etc.”

Important note:

Say you choose a theme and finally tab to the preview pane: there’s a chance you’re previewing a totally inaccessible theme.
Tester’s report: “You’re tabbing and you have no idea where you’re in that case.”
As a screen reader user you may be totally lost, as a keyboard users you could fall in some keyboard trap.

Recommended: add a way to easily exit the preview pane and move focus back to the sidebar.

14. Giving focus to iframes. (related to 13)

Some browsers, especially when in combination with some screen readers, have issues giving focus to iframes.

Tester’s report: “When I tab between the Collapse link and the Preview pane, there isn’t a smooth transition, which is the ‘gap’ where I’m getting lost. I suggest a link that appears on focus to go to the Preview pane just before the Collapse link.”

General Customizer issues

15. The .theme-screenshot image

The .theme-screenshot image in “You are previewing” accordion section needs an alt attribute, see customize.php

<img class="theme-screenshot" src="<?php echo esc_url( $screenshot ); ?>" />

16. Headings

Missing first level heading. todo check header hierarchy.

17. Orphaned/misplaced label, examples

“Background Color” (and all the ones for picking colors with Iris)
there’s a label that wraps 2 input fields, one gets revealed when picking a color. We understand this is how iris works, BTW screen readers won’t get the association between the label and a form element.

“Background Image”:

 <label for="background_image-button">
 <span class="customize-control-title">Background Image</span>

The “background_image-button” button is the “Change Image” button.
Result: click on what appears to be a title: “Background Image” and a modal opens.

18. Empty links (Customizer or underlying panes?)

Several empty links (some of them maybe img without alt? some just empty). See several add widget toggles a.widget-action with no text or aria-label, just empty. They should have some text that makes sense also when read out of context.

19. Buttons

Buttons should be buttons (see primary button is an <a>).

20. Color contrast

Color contrast: active/focus state, accordion toggle arrows, etc.

21.  .theme-overlay .theme-version has user-select: none;

Why .theme-overlay .theme-version has user-select: none; ?
As a user, I want to be able to select that text.

A11y unrelated

22. Attributes

Attributes should be escaped? see e.g.
placeholder=”<?php _e( ‘Search installed themes…’ ); ?>”

23. <button> elements

All the <button> elements need type=”button”.

24. Event namespaces

Consider the use of event namespaces?

25. “Update Available”

On hover,the cursor is a pointer but clicking it doesn’t do anything: consider using default cursor style

26.  Maybe .theme-header should not be rebuilt on each prev/next

Enhancement: maybe .theme-header should not be rebuilt on each prev/next ?
With .theme-header being “fixed”, focus would not be lost on each prev/next action, this would save focus handling via JS.

27. Bug in Chrome when focusing the close button.

Couldn’t reproduce using Firefox, looks like it happens just in Chrome.
See attached screenshot: as soon as you tab on the “Close” button, the sidebar pane underlying the details modal slides out and the main accordions gets in.

See: .wp-full-overlay-sidebar-content
it inherits overflow: auto from theme.css so it can scroll horizontally.

When focusing any focusable element on the right side of the details panel (close button or links in the content) it will scroll thus moving the sidebar on the left.

Notice it gets also overflow-y: auto and overflow-x: hidden from customize-controls.css
Need to reset both to visible, just when the details modal is open, using something like:

.modal-open .in-themes-panel #customize-controls .wp-full-overlay-sidebar-content {
overflow: visible;


customizer theme switcher tabbing

customizer theme switcher tabbing


Test Chat Summary, January 26

After a few months of having a test session on Monday’s we gathered a group of people discussing and fixing tickets and patches.
But limiting the testing to a weekly one hour session turns out to be not pracical.

Not eveyone has the time to be there and work on that exact hour, we are a global group.
@afercia is doing a ton of work on the tickets at the moment and we need more testing and more feedback.

So here’s a proposal for making better use of our time, coders and testers.

The Monday session will be a meeting to discuss the tickets/patches, like:

  • what are tickets we need to work on, what has priority
  • what tickets have a working, tested patch and needs dev feed back or assigned a milestone to
  • what tickets need to be tested and on what AT and who can we ask for that
  • what are the test results, and can we change / approve a patch
  • people can ask for functionally to test or ask questions on how to fix stuff

Then after/during the test session we can install a patch on the test server in the trunk website and assign testers.
During the week the testers can look at the changes and report back as a comment with the ticket or to the #a11y team in slack or by e-mail. Then everyone can test in their own time, we can give specific small tasks to test.

We can also ask the testers to look at specific functionality in the current version of WP to find what’s wrong or needs to be changed.

In this meeting we discussed:

Ticket #28599 (Better Visual Focus Indication in Admin Menu): This ticket has a working patch and needs dev and designers feedback. @ryan will also take a look at it this week. In it’s current state the patch is’t ready for production, for example it misses all the parts related to color schemes and SASS.

Ticket #30589 (Comments navigation template tags): We discussed if the landmark <nav> is appropriate for the comment navigation, <nav> is meant for main navigation. Now there is a risk that we overload a theme with nav’s @afercia will respond to that ticket with outline examples in Twenty Fifteen.

Ticket #29955 (Section 508 issues found on WordPress 4.0 admin page): This ticket will be closed and divided it into new separated tickets.

The patch on the test server this week will be for Ticket #28599 (Better Visual Focus Indication in Admin Menu). If you want to join in the testing, please contact @rianrietveld.

Screen Reader Text support:

This is an ongoing discussion and commented on by some of us in:

In the codex WordPress Generated Classes there is an example on how to implement the screen-reader-text class. We advice to remove the


because they have no use in this context. Just keep the focus.
Clip is due to be deprecated in favor of clip-path, but clip-path is not very well browser supported yet. So lets stick to clip for the time being. Maybe a note of that in the codex will be useful.

@joedolson will discuss a11y with @drewapicture this week, we also hope to get more dev feedback on some of the patches.

In the weekly Accessibility Chat next Wednesday we want to discuss ticket priority.


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!

#commhub, #poll

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:

WordPress Theme Pattern Library for Accessibility

We want to make creating accessibility-ready themes as easy possible. To do that, we’re working on building a library of accessible patterns for themes. That way, theme authors can learn about and implement accessibility in their themes with ease.


The goals are simple:

  • Become a central resource for WordPress theme developers to learn about and how to implement accessible patterns for accessibility-ready themes.
  • Patterns should be self contained and have as few dependencies as possible.
  • Be a codebase that gets tested rigorously, evolves constantly and keeps it simple.

Pattern Ideas

I have a handful of pattern ideas that should be included, most of which help meet the current accessibility-ready requirements. This isn’t an exhaustive list, of course, and other patterns would be needed and welcomed.

  • Skip link (in Underscores)
  • Mobile menu toggle (in Underscores)
  • Menu drawyer, expand from side
  • Menu overlay
  • Continue reading links (in Underscores, partly)
  • Form label and field patterns (start with Core markup and expand on that.)
  • Outline/:focus style examples
  • Tabs
  • Accordion


After feedback from the Accessibility team, especially in a recent meeting, I think the best way to implement is:

  • Giving each pattern its own repository: Each pattern (including whatever HTML, CSS, JS and PHP needed) would be in a self-contained repository under this Github organization. Theme authors could just download the repos, drop in the code and go.
  • A page that explains the different patterns and their purpose. This would probably be a page in our future handbook or on our Make site.
  • A link to a demo. Showing the working pattern would be nice, but not a requirement. I would like to see different patterns created first before we worry about this aspect. To me, this comes later.

What’s Next

This is only a rough list of basic steps:

  • Start working on patterns needed for accessibility-ready themes.
  • Establish a code contribution policy.
  • Develop a testing policy.
  • Test patterns as they get created.
  • Release patterns.

We can release one pattern at a time really, as we create and test them.


I have an idea for a pattern. Can I work on it? Yes, just let me know in the comments, so I can keep track of who’s doing what and make sure we don’t have people working on the same pattern. That way, I can connect people for collaboration.

How do I get access to the WPAccessibility repositories so I can commit code, etc.? You should develop the pattern on your own Github account or locally first. Once I have a list of patterns being worked on, we’ll create repositories for them and go from there. We will likely adopt the fork and pull method.

What about theme frameworks? Can I submit a pattern for it? Yes, we’d like to cover as many methods of theming as possible.

Can I include Sass, Less, Grunt, Gulp, build tool, etc.? For now, please create patterns with as few dependencies as possible. Accessibility can be intimidating and we want keep the barrier to entry as low as possible.

If you want to be involved, make sure you’re following this blog. You’ll see updates here. If you have other ideas or questions, let us know in the comments.


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