Planning for keyboard navigation

Carolina

The theme review team is requiring all themes to implement keyboard navigation in two months time, around the third of september 2019.

Because this may be a complex task for many authors, we encourage you to start planning for and working on this as soon as possible.

We want to point out that this requirement does not only include menus. All functionality should work using a keyboard only. Any action you can complete with a mouse must also be performable via keyboard.

Theme authors must provide visual keyboard focus highlighting in navigation menus and for form fields, submit buttons and text links. All controls and links must be reachable using the keyboard.

First, please read the requirement found here: https://make.wordpress.org/themes/handbook/review/accessibility/required/#keyboard-navigation

As well as the background for this requirement: Techniques for WCAG 2.0
G202: Ensuring keyboard control for all functionality

We would like to collect examples for the keyboard navigation, including menus. If you know of a good resource that is not already included, please add a comment and link.

Navigation menus and controls

Drop down menus and controls must be available when tabbing, using keyboard only.

Both forward and backwards tabbing must work. To test backwards tabbing, hold down Tab and Shift at the same time.

Controls also include open and close buttons for modals such as off canvas sidebars or search forms.

Form fields

Don’t break the browsers default focus by removing the outline. Other kinds of decorative changes are also allowed. Only showing the marker inside the field is not enough.

Submit buttons

Submit buttons may be hidden during it’s normal state but visible on focus.

A high contrast color change, an outline, a border, or a text decoration change will assure that visible submit buttons pass the requirements.

Text links

Make sure you can see visually which link is focused. Focus should either incorporate a visual change that is not based on color (background change, underline, shape) or a color change where the difference between the two colors meets the WCAG 2.0 level AA contrast ratio (4.5:1) .

Basically, don’t break or remove the browsers default focus by removing the outline.

Resources

https://make.wordpress.org/accessibility/handbook/test-for-web-accessibility/test-for-web-accessibility-frontend-code/#keyboard-navigation

For those interested in AMP:
https://amp-wp.org/documentation/playbooks/keyboard-accessible-navigation-menus/

Example menus:

https://wordpress.org/themes/twentynineteen/

https://wordpress.org/themes/twentyseventeen/

https://github.com/Automattic/_s ( https://underscores.me/ )

https://github.com/wprig/wprig/

Musik 2.0 and 2.1

Carolina

In the past weeks I have made two updates to Musik. Most of the changes where made to make sure that the theme is more accessible, and there has been some color changes. The theme now passes the WordPress.org accessibility-ready review.

There has also been some bug fixes. Thank you for continuing to report bugs!

Version: 2.1 2019-02-12

  • Added the flex height parameter to the custom logo option so that the logo can be shown in any size again.
  • Added the accessibility-ready and block-styles tags to style.css.
  • The header images have been further compressed to reduce the size.

Version: 2.0 2019-02-05

  • Made sure that the social menu, if used, shows next to the main menu by default.
  • Made sure that the page footer is only used if there is actual footer content such as footer widgets and footer credit text.
  • Removed a redundant headline from the author archive.
  • A minor style change for the “Read more” link, moving it to new line.
  • Accessibility improvements:
    • Added underlines to links in the widget areas.
    • Changed the text color and background image of the comments to increase the contrast.
  • Added a new screenshot to reflect the changes of the widget areas.

Another just for fun theme -Mardi Gras

Carolina

The Mardi Gras theme is now available on WordPress.org. Yes, another holiday theme!

Mardi Gras a fun, colorful theme for the carnival season. The theme has four widget areas, two menus including a social menu, and displays your posts in a 3 column grid. The default colors are the traditional New Orleans Mardi Gras colors green, purple and yellow. You can change the number of columns and select your favorite colors and fonts in the customizer. The theme is responsive and also supports the new block editor with wide and full width blocks.

Speed up reviews with autocomplete snippets

Carolina

When reviewing themes for the WordPress.org theme directory, you will find that there are mistakes that are more common than others. This means that we often use the same type of messages in different tickets and reviews.

We can use this fact to make our reviews faster. I have done so many reviews that many of the texts are in my muscle memory, but I still save some of my reviews with the purpose of being able to copy paste them into other reviews later.

But we can improve on this further by using the code editor of our choice to add the most common texts for us.

I use VS code, and I followed these instructions to create my own review specific snippets:

In VS Code, go to File, Preferences, and select user Snippets

Now you can choose to create a snippet for a specific language, or a global snippet file. I write my reviews in a simple .txt file so I created a global file.

Documentation for how to create a new snippet is included in the file header of the new file, which made it very easy.

Place your global snippets here.
Each snippet is defined under a snippet name and has a scope, prefix, body and description. 
Add comma separated ids of the languages where the snippet is applicable in the scope field. 
If scope is left empty or omitted, the snippet gets applied to all languages. The prefix is what is used to trigger the snippet and the body will be expanded and inserted. 
Possible variables are: 
$1, $2 for tab stops, $0 for the final cursor position, 
and ${1:label}, ${2:another} for placeholders. 
Placeholders with the same ids are connected.

Example:
"Print to console": {
	"scope": "javascript,typescript",
 	"prefix": "log",
 	"body": [
 		"console.log('$1');",
 		"$2"
 	],
 	"description": "Log output to console"
 }

I decided not to use a scope, here is an example of one of my custom snippets:

"Missing license": {
	"prefix": "missing license",
	"body": [
	"Themes are required to be 100% GPL compatible.",
	"Reviewers can not confirm that a theme is GPL compatible unless all the license information is included in the theme.",
	"Missing license information for:",
	"(Placeholder: include additional information like a script name or image used in screenshot)",
        "$0",
	],
	"description": "Missing license information for included assets."
},

So when I write my review, all I need to do to add the information about the missing license is to start typing “license” or “missing” and press enter.

Here is the first iteration of the file: Download.

Cherish 1.5

Carolina #

Version 1.5 contains some bug fixes that I missed in the latest major update. When I added the font family option, I forgot to also add the font names to the block editor and the WooCommerce pages. *blush*

There was also a bug where the larger menu covered the page titles of the 404 page and author archive. This has been fixed in 1.5.

I created a new setup help page for the theme:

== Changelog ==

=1.5 2019-01-11=

  • Code style changes to better comply with WordPress coding standards.
  • Improved escaping.
  • Added a setup help page.
  • Added a social menu.
  • Fixed an issue where the titles did not show for author archives and 404 pages.
  • Increased the size of the avatar on the author archive.
  • Fixed an issue where the editor would not show the correct font for the title.
  • Fixed an issue where hiding the site title would also hide the Call to Action.
  • Changed the description of the widget areas, since they are shown on all pages, not only the frontpage, oops :P.
  • Changes related to WooCommerce:
    • Increased color contrasts, increased the size of some input fields and font sizes, added underlines to some links to improve accessibility.
    • Adjusted the width of the product page.
    • Changed the number of products per row from 4 to 3.
    • Fixed a problem where the selected font did not display correctly on shop and product pages.

Musik 1.9

Carolina

In version 1.9 of Musik, I wanted to optimize the theme to make it faster. I also wanted to make the theme more accessible.

-It is always a bit scary to update old themes, because I do not want to break any child themes or existing sites.

For those who are using a child theme together with Musik, note that the markup for the header and the main navigation has been updated. The code for the header image has also been moved from index.php to header.php.

  • Updated readme.txt file. Updated outdated links. Improved documentation.
  • Reduced background image size and file size.
  • Fixed a problem with the select list text color.
  • Updated navigation.js so that jQuery is no longer needed.
  • Moved WooCommerce styles to a separate file and made sure the file only loads if WooCommerce is active.
  • Added support for header video (requires WordPress 4.7 or later).
  • Added a social menu, and options to select where to display it.
  • Added a skip link focus fix for IE11.
  • Added rtl styles.
  • Improved comment area styles for smaller screens.
  • Added styles and fonts for the block editor so that the editor better matches the front.
  • Updated author.php using get_the_author_meta.
  • Changes to better comply with accessibility requirements:
    • Added underline to content links.
    • Increased color contrast, some font sizes and line heights.
    • Reduced the number of colors used.
    • Made sure that there is one H1 heading on all pages, and that heading levels are not skipped.

My Theme Review Process 2018

Carolina

Updated december 2018

The Theme Review Team on WordPress.org encourages reviewers to find their own flow and tools that work for them. There is no right or wrong way to review a theme, as long as the requirements are checked and the author receives useful feedback.

My personal review process require a lot of manual effort.

Tools:

Since 2017, I have gone from VVV, via Local by flywheel which I used for a long time, to Docker.

While I liked the GUI of flywheel, it was just way too slow and sometimes buggy. I also found that it was not suitable for me when I wanted to do other projects than WordPress. Which happens about 3 times per year 🙂

Docker was easy to get started with, but there was a bit of a learning curve for me to get things exactly the way I wanted them. I now use two very basic docker compose files (with a persistent theme and plugin directory).

Sometime during the year, there was a big update to Sublime Text which broke all my settings. I could not get my extras like the PHP Code Sniffer to work again and truth be told, I gave up. I switched to VS Code, and I love it.

I often switch between different PHPCS standards. I use the WordPress-Coding-Standards and the WPThemeReview standard.

I still use Poedit to check translation files, and the tiny program called GifCam to create gifs of broken themes.

I use the theme unit test data, and we have also created a new version of the Theme Unit Test which includes blocks.

Plugins:

The Theme Sniffer and Themecheck

Preparations:

I always import the Theme unit test and I keep the requirements page and the WordPress developer reference open.

Process:

Normally it takes me 5-10 minutes to see if a regular sized (or underscore based) theme needs to be closed because there are 5 distinct issues, or if the review can continue.

But summarizing the findings and adding references, explanations and images to help the author fix the issues takes a little longer.

I try to consider whom I am writing the review for:

  • -Do I need to add references?
  • -Do I need to help them find a solution, or is it enough if I mention the issue?

Not all steps are performed on all themes, it depends how the theme is built.

I also split large themes over several reviews, because I don’t always have enough time to check several hundred files in one go.

If I quickly find 5 distinct issues I may close the theme as not approved without doing a full review.

First I check if the screenshot in the ticket is reasonable and not a logo or mockup.

Then I check the Theme and author URI before I download the zip file.

I look through the theme files before I install the theme.

If I do not recognise the theme author, I normally start by checking the license information in style.css and the readme.txt file, and check the theme and author URI.  This is to make sure that I am not spending time on reviewing a theme if the theme is not GPL compatible.

Then I continue by opening functions.php, header.php and footer.php:

  • Are there hard coded scripts?
  • Is there text that is not translation ready?
  • Is everything escaped?
  • If there is a footer credit link does it match theme or author URI?
  • Are the functions in functions.php prefixed and are scripts and styles enqueued correctly?
  • Are menus, widget areas and theme support added correctly?

Then I check if there are folders named js, css, dist, assets or similar, and if there are minified files. I also check if there are any plugins, demo files or similar included in the theme folders.

  • If there are minified files, is the non-minified version included as well?

This is when I start making notes and adding items to the review.

I already have texts written for common errors that I can add and adapt for the specific theme.

Run the plugins.

  • Are there any errors reported?
  • Check any warnings manually.

Then, depending on the theme, I use my code editor to search the entire theme folder for the following:

  • get_theme_mod -This helps me find theme mods that are not escaped.
  • remove -This helps me see if the author has removed any customizer settings or non-presentational hooks.
  • function, -This gives me a handy list to help me check prefixes and whether custom functionality is used in place of WordPress functionality.
  • script -This helps me find hard coded scripts.
  • alt=, title=, placeholder= -This will help me find translated texts in attributes and make sure the texts are escaped.
  • add_theme_support – This helps me check if the author has added support for title (required), custom logo (instead of using their own) etc.
  • If there are multiple post formats and templates I might also search for wp_link_pages, query and reset.

Then I install and activate the theme to make sure that:

  • There are no php or js errors.
  • There is no redirect on activation.
  • Notices are not global and can be dismissed.
  • Plugins are not required, only recommended.

Testing the theme layout and custom options.

  • Is the correct number of posts displayed?
  • Are comments displayed correctly?
  • Are there any php or js errors?
  • Perform a search.
  • Test the 404 page.
  • Test the navigation.
  • Set up a menu, is it working? Test the menu in a smaller window, is it working? Make sure that it is not overlapping or in other ways disturbing the admin bar.
  • Test custom widgets and make sure there are no php notices, warnings or errors.
  • Make sure that there is only minor content creation.

When I go to the customizer and test the options, I also open the customizer.php or related files in my editor and make sure the options are sanitized and set up correctly.

  • Check to see if there is demo content, content creation or plugin territory functionality.
  • Is the upsell reasonable and is it added with the customizer API?

Go to the post editor and double check if any meta fields has been added, and that they are for presentation, not content.

  • Test the meta options and repeat for pages.
  • Test page- and post templates.
  • If there is starter content, reset the install to fresh and test it.
  • Does the theme match the tags and description in style.css?

Whether I find issues or not, I still open each file in the theme folder manually and review them quickly, including minified files. This is still the fastest way for me to check for untranslated texts and anything that stands out.

When the review is finished, I save it as a .txt file and then cut and paste the text in the Trac ticket.

Random thoughts about Gutenizer Phase 2

Carolina

Some early (and early morning 🙂 ) thoughts about Phase 2.

I’m still a bit confused about what will go into earlier updates, and what will go into phase two. I mean there was a ton of block ideas that got postponed, will these blocks or some of them be added in phase 2?

Simplicity is important. Having a lot of visible elements (and in different colors) on the same page editor can be stressful.

I’m finding it difficult to picture if -or what part of, the current customizer sidebar will be visible at the same time as the new editor toolbar/inspector.

I think that having both the customizer sidebar with the panels and settings visible, and also have visible toolbars for selected blocks; and on top of that, the customizer shortcuts, could be too distracting. The visible panels and settings has to be carefully selected.

How will the customizer shortcuts be used, when many but probably not all elements will be editable directly? If we don’t use the customizer shortcuts, how do we show the user which elements that are editable?

This might not work…

Would the customizer only be used to edit the front page, or would we be able to edit the search results page, 404, archives, single pages, shop pages etc?

Because when we talk about layouts and in an extension, block page templates, all these inner pages are likely to look different from the front page and from each other. For example, a header image and large site title and tagline might be a visible editable area for a front page, but might not be visible in a single post view.

Currently, the customizer panels can have unlimited options. It would not make much sense, to have a panel with a setting that selects the sidebar position for my single posts, if I am currently viewing and editing blocks for the front page.

Perhaps the theme would declare support for different views which can be edited?

It would be nice to have a simple option where we can choose whether we want to show the full content, excerpts, or even just the titles on the blog, archives and search result pages.

I sometimes receive support requests from users who are asking why the full content is showing, even when they set the feed to only display the summary.

No, this setting is not for the blog.

I want to be able to create reusable block templates, and not only for custom post types.

We might need several different kind of templates:

  • Layouts where we select the position of our widget areas, header images, adverts, menus etc.
  • Layouts for individual content blocks, recommending a specific order of blocks for individual content.

In phase 2, will we really need both pages and posts? If we are able to change the visibility of the meta information like the post date etc, the difference between the two types will continue to be blurred out.

If I want a front page of ten posts, then I don’t want to manually have to drag and drop ten individual post blocks and order them in the customizer.

I want to be able to add the latest ten posts in one go, but maybe I don’t want to use the current latest posts widget either. That block has a different purpose.

Then again, if I added post block(s) to my front page that I am editing in the customizer, and I spotted a typo, then I would want to be able to edit it directly in the customizer and save it, instead of having to leave my view and open the individual post.

I want to be able to edit everything in the post. Like title, permalink, images…

I want to be able to add a simple one page menu. A menu that checks what posts or pages that I have added to the current page view, and automatically creates the links for me.

I think adverts is something that have been forgotten. Today you might install a plugin, or a few plugins, or add a code to a theme setting (!) in order to include your ad code, but displaying the adverts correctly on the page is still not that easy. We could greatly improve this and help users optimize their adverts.

Social media links with icons is something that nearly every theme adds, either as link options in the customizer, or as a menu. There should be one simple, recognizable way to include social media links. If a menu system is used, I still think it needs to be a lot simpler than it is now.

It should not be more difficult than adding any other type of link, and the visual feedback must be better. The icon should be visible immediately, not only on the front.

My first custom block plugin

Carolina # # #

Well, my first ever plugin to be submitted to WordPress.org actually 🙂 .

Last Christmas, I added a custom, static image block with Christmas decorations to my theme Christmas Sweets. This was the first theme in the directory to include blocks for the new block editor.

Later, the Theme Review Team on WordPress.org decided that themes are not allowed to include blocks, and I removed them.

Now that WordPress 5.0 has been released, the plugin with updated blocks and a few additional images has been approved and added to the plugin directory. You can download the plugin here.

The blocks are basic and I did not need to change much of the code from last year to make them work again.

Unfortunately a lot of the documentation that is available is out of date, and I was not able to add alignment toolbars, so the images are now centered by default.

I admit that the mix of ES5/ESNext examples and tutorials that are available are confusing. (And I’m not a fan of React error messages.)

Even though I have taken Zac Gordons Block Development course, I ended up sticking with ES5 and build on the existing code instead of rebuilding the blocks.

Submitting the plugin to the directory was nothing but smooth, and it was approved after a few hours. I was able to use svn for the first time in many years to add the plugin files to the directory, so I’m happy with that :). Now I just need to add some images to market the plugin.