Improving the Settings API for accessibility and ease-of-use

On January 2nd the first meeting to discuss improvements of the well-known, but not well-loved Settings API took place in #accessibility. After a healthy discussion the next meeting was set to take place last Monday. Since the suggested improvements are not solely related to accessibility, the location for the meeting was moved to #core. This post is a recap of what was decided during these two meetings.

Archives of the full conversations:

Attendees: @afercia, @flixos90, @helen@joedolson, @johnbillion, @rianrietveld, @sc0ttkclark

First Meeting

The original reason for calling these meetings were several accessibility problems on WordPress settings pages. To quite some extent, these are related to the table markup that is automatically printed by the current Settings API. On a related note, it was mentioned that being required to write callback functions for rendering each and every field is a major drawback. Providing default callbacks would thus not only make it easier to work with the API, but also further improve accessibility as these callbacks would all be reviewed by the team. So the two main goals that were figured out were:

  • Add some basic support to automatically render fields so that plugin developers no longer need to write their own callback functions for basic fields.
  • Get rid of the table structure to improve accessibility. Furthermore the accessibility team should also ensure that the markup generated as the core field output is accessible.

The first meeting was also centered on whether these improvements should be tackled through means of the Fields API project, a new “Settings API v2” or improving the existing Settings API. In the end it was decided to continue working with the existing API, mainly for the following reasons:

  • The Fields API project is a huge effort that will still take a while until it can possibly be merged into core. Still, it will follow up with the changes that will be introduced in the Settings API, as @sc0ttkclark pointed out. While printing fields is certainly the focus of the Fields API, introducing a few technically simple callbacks in core at this point will not be a problem as these can be migrated to the Fields API ones at any time.
  • While the existing Settings API has its problems, it appears to be possible to handle the necessary improvements without running into backward-compatibility issues. A completely new Settings API could have further benefits, but it would leave many users behind that would need to manually migrate, and furthermore would take much longer to scaffold and implement.

After the meeting, a general ticket for the task was opened at #39441. The ticket description provides more information on how the two identified goals should be accomplished. In addition to the technical details, the first part of the accessibility measures will be to create an HTML-only prototype of what a better settings page would look like. It should be created without the limitations of the Settings API, so that the result can be the best possible example for what the enhanced Settings API should produce.

Second Meeting

@rianrietveld had four items on the agenda for the second meeting.

  • At first, everyone was asked to review the patch that @flixos90 provided on the above ticket. The patch only applies to introducing default field callbacks, so it still lacks adjustment of the table markup and a proper accessibility review, but it shows a possible technical approach.
  • Related to the patch, a tiny plugin was created and uploaded to the ticket as well. This plugin allows for easy testing of the functionality. For easier collaboration and possible iterations, that plugin has now been moved to GitHub. Feel free to try it out with the patch applied.
  • Some results of an accessibility test for form elements that was conducted by the accessibility team were revealed as a preparation for the prototype settings page in HTML. A few major issues to consider were discussed, for example the requirement of IDs on every field, the proper usage of fieldset and legend elements and the problematic usage of <input type="number"> for Dragon NaturallySpeaking speech recognition software. For creating the HTML prototype, it was decided to focus on replicating the core settings pages “General” and “Discussion”.
  • For the next step of the efforts, @afercia volunteered for creating the prototypes. As of now, the field markup he created for the two replicated settings pages can be inspected on GitHub (last two items in the list). These will probably be discussed in the next meeting.

If you are interested in helping out, there are several ways for you to do so: Please review the suggested improvements, the HTML prototypes and/or the technical approach. Feedback can be provided on the ticket, this post or by participating in the upcoming meeting/s. The Settings API meeting takes place biweekly on Monday at 17:00 UTC, so feel free to drop by. The next meeting will be on Monday, January 30.

#accessibility, #settings

Improving accessibility of image alternative text in 4.7

WordPress 4.7 includes a change to the way image alt attribute values are generated. Formerly, any time WordPress created the markup for an image with an empty alt value, it would attempt to use either the caption text or the image title—in that order—as a fallback value.

In 4.7, we have removed this fallback behavior.

To ensure your images having meaningful alternative text, you should make sure to set a value for alt text in your media library.

How removing fallbacks improves accessibility

The intent of the fallbacks were to ensure each image included alternative text. In practice however, this fallback behavior often resulted in poor user experiences for people using screen readers. As counterintuitive as that may seem, let’s take a look at some common examples.

Consider a situation where we’ve uploaded an image named “edbc4ef7.jpg” without changing any additional information. WordPress will generate the image title from the file name as shown in the following screenshot of the insert media modal.

Attachment details for an image shown in the insert media modal.

Formerly, inserting this image in a post would result in HTML similar to this (simplified slightly for clarity):

<img src="https://example.wordpress.org/wp-content/uploads/2016/11/edbc4ef7-1024x683.jpg" alt="edbc4ef7" width="700" height="467" />

A person using a screenreader on this page would end up hearing the file name read to them, which is not the most helpful experience, and can be quite frustrating when the file name is lengthy.

For another example, setting a caption value but no alternative text would result in markup that looks something like this:

<figure id="attachment_1741" style="width: 660px" class="wp-caption alignright">
    <img src="https://example.wordpress.org/wp-content/uploads/2016/11/edbc4ef7-1024x683.jpeg" alt="This is a caption." width="660" height="440">
    <figcaption class="wp-caption-text">This is a caption.</figcaption>
</figure>

Notice that the alt value and the figcaption text are redundant? WebAIM describes two ways of presenting alternative text:

  • Within the alt attribute of the img element.
  • Within the context or surroundings of the image itself.

The same article goes on to explain that an alt attribute value may be omitted when an identical figcaption is present, to avoid redundancy; but best practice when using a figcaption is to provide a separate and different alt attribute to describe that image to users of screen readers.

In each case, omitting the alt attribute entirely may result in screen readers reading the file name from the src attribute, so WordPress includes an alt attribute with an empty value, i.e. alt="", whenever the alternative text hasn’t been explicitly set—a technique that is common when an image is decorative.

This change will not affect content already published, but will be the expected behavior for any new content published after upgrading to 4.7. For more background on this issue, see ticket #34635.

#4-7, #accessibility, #dev-notes, #media

Categories and Tags screens changes in 4.6

In WordPress 4.6 the Categories and Tags screens (and all the custom terms screens that use the same edit-tags.php page) will change in order to make the visual order of the main elements match the tab order. This change is focused on helping people who use the keyboard to navigate the content or use assistive technologies such as screen readers.

If you’re a plugin or theme author and you’re providing custom functionalities in these screens, there are a few things you should check.

Why it matters

For accessibility, the visual order should always match the tab order. The main functionality in a page should just be the first thing in the source markup and other parts of the user interface should never be “skipped”.

The screenshot below illustrates the current Tags screen. The main content is split in two columns. The first element in the source is the right column with the table to list the terms followed by the tag cloud for the popular tags and the form to add new tags.

Tags screen visual order and tab order

The current order of the main content elements in the Tags screen.

On page load, the initial focus is set on the first focusable field in the form which is the third and last block of content in the page.

When using the keyboard or a screen reader, content navigation is a linearised process. Starting from the form to add new terms makes sense since this is the main task on these screens. But then users will move forward and they will find just the footer of the page. When relevant parts of content are skipped, it’s more likely for screen reader users to be confused or experience difficulty navigating pages. They just don’t have a clue there is something “before” their navigation starting point. Keyboard users will have to tab backwards to get to the previous content.

What is going to change

The two columns in these screens will be swapped. The first one in the source will be the left column, followed by the right column. Also, in the Tags screen, the tag cloud will be moved after the form. Visually, this change will make these two screens more consistent. From an accessibility point of view, the content structure and organization will be easier to understand and navigate.

The new categories screen

The new Categories screen.

The new tag screen

The new tag screen.

Things you should check

  • if you’re using CSS or jQuery selectors for your added functionalities, you should consider the order of the elements in the markup has changed
  • there are a number of action hooks and filters in these screens but basically just one will have a different order, see the related ticket for more details

Note: For more in-depth information see the related Trac ticket: Edit term screens: tab order should match visual order.

#4-6, #accessibility, #dev-notes

Get ahead of 4.6 and update now!

If you’re a theme or plugin developer: now is a great time to check your code! Help us to make the Web a place designed to work for all people. Any feedback and thoughts are more than welcome, please let us know in the comments below.

#4-6, #accessibility, #dev-notes

Headings hierarchy changes in the admin screens

For a number of years, the headings hierarchy in the admin screens have been setup without careful thought. WordPress 4.4 aims to fix this. This work is mainly focused on helping those users of assistive technologies such as screen readers, and is a continuation of the work started in 4.3 on restoring the H1 (heading level 1) to the admin screens.

If you’re a plugin or theme author and you’re providing custom admin screens for settings, etc., there are a few things you should check and update.

Why it matters

Headings provide document structure, which can directly aid keyboard navigation. Users of assistive technologies use headings as the predominant mechanism for finding page information. When heading levels are skipped, it’s more likely for these users to be confused or experience difficulty navigating pages.

Putting it simply, one of the first things screen reader users do in a web page to find relevant content is to press the 1 key on their keyboard to jump to the first <h1> heading and then they will try the key 2 to find the <h2> headings and so on. Thus, it’s extremely important for WordPress to provide a correct headings hierarchy, ensuring no headings levels are skipped.

How to fix your Plugin or Theme

Restructure the document headings hierarchy to ensure that heading levels are not skipped. The main heading should be a <h1> and any subsequent headings should (likely) be bumped one level up. There should be no skipped levels. Check your headings in the Admin, for example in settings pages, list tables, screen options, (dashboard) widgets, and meta boxes.

See for example the screenshot below, the first heading (Sharing Settings) should be a <h1> followed by a <h2> for Sharing Buttons.

main h1 heading example

Your plugin screens should start with a H1!

List Table headings

List tables (such as on wp-admin/edit.php ) have now additional headings added, though you won’t see them. These headings are hidden with the .screen-reader-text CSS class and are intended to allow users to jump to the relevant sections in these screens.

Note: For more in-depth information on using the core .screen-reader-text class, the Accessibility team has a great write-up on it.

#4-4, #accessibility, #dev-notes, #example-flow, #user-anecdote, #visual-comparison

The screenshot below illustrates the new headings in the Posts and Categories screens.

In the screen wp-admin/edit.php the heading structure is now:

  • H1: Posts
  • H2: Filter posts list (visually hidden)
  • H2: Posts list navigation (visually hidden)
  • H2: Posts list (visually hidden)

In the screen wp-admin/edit-tags.php?taxonomy=category the heading structure is now:

  • H1: Categories
  • H2: Categories list navigation (visually hidden)
  • H2: Categories list (visually hidden)
  • H2: Add new category
hidden headings for default posts and taxonomies lists

The hidden headings in the default posts and taxonomies lists.

If your plugin or theme provides custom post types or custom taxonomies, these new headings will use their default values “Post” and Category”:

hidden headings for custom posts and taxonomies lists

The hidden headings in the custom posts and taxonomies lists.

New post type and taxonomy labels in 4.4

In order to provide for better heading text, some new labels have been added for use with register_post_type() and register_taxonomy().

For register_post_type():

'filter_items_list'     => __( 'Filter your-cpt-name list', 'your-plugin-text-domain' ),
'items_list_navigation' => __( 'Your-cpt-name list navigation', 'your-plugin-text-domain' ),
'items_list'            => __( 'Your-cpt-name list', 'your-plugin-text-domain' ),

For register_taxonomy():

'items_list_navigation' => __( 'Your-tax-name list navigation', 'your-plugin-text-domain' ),
'items_list'            => __( 'Your-tax-name list', 'your-plugin-text-domain' ),

Here’s an example for a custom post type:

custom posts list with proper headings

Using the new labels to provide proper headings for a custom post.

Screen Options tab changes

Some plugins add custom options in the Screen Options tab. Previously, a h5 heading was used for the options “title”. In WordPress 4.4, the Screen Options tab has been revamped and together with other changes, it has been decided to remove the h5 heading which didn’t allow for a good headings hierarchy.

Each group of options is now within its own form fieldset and uses a legend element as “title”. You’re strongly encouraged to change the HTML you use for your plugin options and use the new markup.

the new Screen Options tab

The new Screen Options tab: each option is in a separate fieldset.

Dashboard widgets and meta boxes changes

All Dashboard widgets and meta boxes headings changed from an H3 to an H2.

<h2 class="hndle ui-sortable-handle">
	<span>your-widget-title</span>
</h2>

If you are a theme or plugin developer: please check the heading structure in the content of your widgets and meta boxes, use an H3 and lower in the right order and context.

Get ahead of 4.4 and update now!

Now is a great time to update your plugins and themes! The power of the Web is in its universality. Help us to make the Web a place designed to work for all people. Any feedback and thoughts are more than welcome, please let us know in the comments below.

#4-4, #accessibility, #dev-notes, #example-flow, #user-anecdote, #visual-comparison

Headings in Admin screens change in WordPress 4.3

Are you a theme, plugin or framework developer for WordPress? Take note: the heading structure in the Admin screens will change in WordPress 4.3.

From H2 to H1

Currently, in WordPress 4.2 and before, the main heading in admin screens is an <h2>. However, if you want to have a correct, semantic heading structure, a page should an <h1>, but only one, which describes what the page is about.

People using assistive technology use the <h1> to identify a page and quickly know where they are. Further, proper HTML5 dictates that an <h1> should be the initial heading.

Therefore, in WordPress 4.3 the headings of all admin screens have been changed from <h2> to <h1> (see #31650).

Related CSS changes

If your theme or plugin still uses <h2> for admin screens, don’t worry; styles for <h2> are still supported in the admin CSS so that, visually, nothing changes during the update to 4.3. However, a new class was introduced to properly style <h1>s, page-title-action. Here’s an example of the new class in use:

<h1>Posts <a href="[..]/wp-admin/post-new.php" class="page-title-action">Add New</a></h1>

The old class .wrap .add-new-h2 is still supported but has been labeled deprecated. It has been replaced by: .wrap .page-title-action.

More changes ahead

After the release of WordPress 4.3, the accessibility team will continue making changes to heading so that they are semantically correct. Current <h3>s will become <h2>s, <h4>s will become <h3>s, and so on.

Check your code

Does your plugin, theme, or framework have admin screens? Check the heading structure. Change the main heading from an <h2> into an <h1>. If you’re feeling generous, check the rest of your heading structure to ensure it’s semantic.

Making these semantic changes will ensure your plugin or theme is in sync with WordPress and that people using a screen reader can understand your admin screens better.

If you have any questions, ask them in the comment section below, or contact the WordPress accessibility team in the #accessibility channel in WordPress Slack.

#4-3, #dev-notes

Today in the Nightly: Site icons in the customizer, editor patterns, more accessible comment bubbles, row toggle focus styling

Install the nightly, and try out this fresh batch of shiny.

Site Icons in the Customizer

I’ve long wanted site icons in the customizer alongside site title and tagline. The identity information that I always want to edit when first setting up a site are now all together in the customizer.

For more visuals, see these visual records.

See #16434.

Editor Patterns

Create bulleted lists, ordered lists, and blockquotes using markdown like patterns. I find this particularly handy on phones when the editor toolbar is offscreen.

Screen Shot 2015-07-14 at 4.39.12 PM

See #31441.

Better focus styling for list table row toggles

See #32395.

Better accessibility and design for the comments bubble

The comments columns in our list tables were among the most confusing for screen reader users. Accessibility and visuals are now improved.

See #32152.

Eliminate content overruns on small screens

An audit of content overruns on small screens resulted in many fixes.

After:

Before:

See #32846.

Styling improvements on small screens for Right Now in the network admin

See #32962.

Improved header information in Network Admin Edit Site tabs

  • Use the site’s name rather than URL in the Edit Site header.
  • Provide “Visit” and “Dashboard” links for the site on all tabs.

After:

Before:

See #32525.

Disambiguate “Automatically add new top-level pages to this menu”

In the customizer, a menu’s auto-add pages option is now separated from the preceding menu location checkboxes.

See #32820.

 Passwords UI Improvements

Passwords received a couple of improvements. The show/hide toggles look better, and passwords ui is on the install screen. Passwords on the install screen still needs a little more flow work.

See #32589 and #32925.

For more visuals, see these visual records.

Reduce link noise in media library list view

This is visually subtle but removes confusion for screen readers.

KL_7dmW58c

See #32254.

 

Previously: Today in the Nightly: Customize in the Toolbar, Passwords UI, List Tables on Phones, Dashicons

#accessibility, #bubbles, #comments, #content-overrun, #customize, #edit-site, #editor, #list-tables, #media, #menus, #multisite, #network-admin, #right-now, #site-icons, #today-in-the-nightly

Letting WordPress Speak: New accessibility feature in 4.2

One new accessibility feature in WordPress 4.2 is the new JavaScript method wp.a11y.speak(). The essence of this feature is to provide a consistent methodology for announcing dynamic JavaScript updates to assistive technology. For more information about how this works, why it exists, and how to use it, read the complete post at Make/Accessibility.

#4-2, #accessibility, #dev-notes

Support for Screen Reader Text in Themes

Support for Screen Reader Text in Themes.

#accessibility, #themes

I put out a call from the @wordpress…

I put out a call from the @wordpress Twitter account yesterday asking for accessibility volunteers. Already getting some helpful feedback. Anyone not working on a 3.2 feature already could help out by working on one of the accessibility issues.

#accessibility

Menus UX Manifesto

A Menus Manifesto?

Now that the new menu system patch is in and working, I’ve been able to start going through it for UI stuff. The are some things I think we should consider changing to fit into the WP UI, though based on timing I’m also okay with letting some of it slide until next release if needed. Here are the things on my mind, which hopefully we can touch on during today’s dev chat.

  • Icons. The edit/delete/view icons are inconsistent with the way we handle actions everywhere else in WordPress. We have two options here: we can have icons made that will match WP core icons, or we can get rid of the icons and change the UI a bit to match existing interaction models. If we go with icons, I’ll ask Ben to make us some that match better, which might be the better part of valor to get 3.0 out on time, rather than trying to make everything perfect. Release early and keep iterating, right?
  • Accessibility. The menus function as it stands now is completely inaccessible. There doesn’t seem to be a no-JavaScript version, which we have to have. It will be clunky and ugly, like widgets, but we NEED to do this. Icons for actions rather than text is an accessibility no-no, which is another reason to move away from them eventually, but the bigger problem is that we need a no-JS version. I’m emailing the accessibility list to see if anyone there is willing to pitch in and help.
  • Little arrows on the left of each item. These should be removed. We use little arrows everywhere else to indicate an open/close functionality. If we need a symbol to indicate hierarchy we could use dashes like some other plugins do, or better and more attractive, just indent the bar itself? We also need to get rid of those little mini-arrows in the modules on the right when you click on View All.
  • Everywhere else in the admin, the right-left convention is opposite of how it is on this screen. For example, in Widgets, the available widgets are on the left and the completed sidebars are on the right. On categories and tags, you add on the left and see the updated list on the right. It would probably make sense to swap the menu and the menu controls so the controls are on the left and menus are on the right.
  • Buttons. The Save button should use the primary button class (blue). It should also be furthest to the right. Delete should not be a button, but a red link, and to the left.
  • Display. Like some other people, I’m wondering why each menu has to have its own screen, when it’s generally a pretty narrow column.
  • Default menu. When you first go to the menu screen, it says you don’t have any menus, to create one, but that’s both confusing and incorrect. There is a default menu in place using pages (or categories, in some themes). We should either a) (and preferably) Display the pre-existing menu as Main Menu or some such, or b) change the default text to explain that they currently use the default menu, and this screen is for customizing. It’s also highly unclear how someone should name a menu, or what the relationship is between menus and themes. If someone creates 20 menus but none are supported by the theme, what will happen? It should really pre-fill what menus you have available to you, just like it does with sidebars on the widgets screen.
  • The click to add icons perform the same action as the page/category titles themselves. The icons impair accessibility. If we are to have a second addition mechanism, it should be a text link, not an icon.
  • The mechanism for adding URL and adding page/category is inconsistent. Pages and categories have a list from which you can add, while links are added to menu directly. It would be more consistent to create link rather than add link when it’s first entered, then have link appear in a list below, as the pages and categories do, so that links could be added to/removed from menus without just deleting them. This would also follow the principle we established in widgets that you shouldn’t lose settings when you deactivate something like that.
  • The metaboxes down the right all show the on-hover gray arrow in the right header corner, but the boxes don’t collapse. Either make the boxes collapsible or get rid of the hover arrows.
  • Instead of the edit icon, each menu item should have the hover arrow, which would open it to the edit view. Then we should use save/close/delete as in widgets, thus getting rid of the delete icon as well. This is the interaction model for this type of metacontent and should be followed.
  • I don’t really see the need for a View link (icon) from each menu item.
  • Whatever we do in terms of these changes, hooks need to be included so that Woo can get their own current look back if they choose, as that was part of the agreement.

This is the kind of thing that we need a styleguide for, which the UI group has recently started working on. 🙂

#accessibility, #interaction-models, #menus, #navigation, #ui, #ux