Woo Marketplace Theme Development Guidelines

Alongside our theme design guidelines, themes should be developed following these guidelines below. The intention of the guidelines is to ensure themes remain lean and maintainable, while also ensuring it’s as easy as possible for a customer to switch between themes without additional setup tasks and, more importantly, without any loss of data.

Note: PHP version support in themes should go back as far as possible, towards PHP version 5.2. A minimum of support for PHP 5.6 and higher is required.

Theme code should be kept simple (non-complex) and lean, to ensure backward compatibility.

With Gutenberg as the editor for WordPress, and the introduction and advancement of blocks, all themes should be Gutenberg-first. This means supporting all features offered by the core Gutenberg blocks (for example, cover blocks, images, button alignments, and styling overrides).

Additionally, themes must be responsive in their design. A responsive-first approach, with a focus on Gutenberg for content creation, should be the primary focus when architecting the theme structure. Build out desktop designs on top of the responsive codebase.

Continuing with our focus on the Block Editor (Gutenberg), themes should favor Block Editor styles and overrides, instead of theme options screens or meta boxes. This ensures store owners can customize the look and feel of their website without having to switch between “frontend” and “backend” to visualize changes. With the Block Editor, the idea of a separation between “backend” and “frontend”, when it comes to theme design, should no longer exist for a store owner.

If theme options are necessary, they should pertain specifically to the visuals of the theme (for example, show/hide a search icon in the header area), and should be added via the Customizer and kept to an absolute minimum.

The role of a theme for an online store or website is presentation of the content. While themes have a history of bundling excess functionality, this isn’t the role a theme should be performing. Thus, a theme should remain lean, and add functionality only which enhances presentation (for example, a simple breadcrumb implementation, although this should be ideally left to plugins to handle).

Theme frameworks (codebases which are dropped into a theme to add functionality) are not accepted. Frameworks quickly go out of date, and require additional maintenance and review. In themes which are intended to remain lean, adding frameworks promotes a “lock-in” effect for the customer, and hinders switchability between themes.

Themes and plugins are two parts of what makes WordPress and WooCommerce so extensible and so richly diverse. With this in mind, theme authors often add compatibility for certain plugins to their themes. This is acceptable and encouraged, provided the code involved doesn’t significantly increase the size of the theme’s codebase.

Themes should, however, not require specific plugins in order to function. In addition, adding notices or other such frameworks to encourage the installation of specific plugins is not allowed. The theme should be able to stand independently, and then be enhanced with additional plugins, rather than requiring them.

As with the Customizer, the “frontend” and “WP Admin” are getting closer together. A store owner should be able to see what a change is going to look like on their store before committing to that change.

To this end, and with a Gutenberg lens, the styles of all blocks inside WP Admin should match the styles as applied on the frontend.

At a bare minimum, font family, font size, color, and weight should match. A first prize is a perfect match, though.

Similarly to requiring plugins, and in keeping with themes remaining light and lean, it’s important to be considerate of dependencies included within the theme. Dependencies range anywhere from a JavaScript slider to a third-party PHP library. These add weight to the theme, often with little to no benefit to the store owner.

A theme’s visual experience for the customer is of paramount importance to the customer, as it enables them to sell on their online store. Sometimes, a store owner may wish to add extra items to their navigation menu, add a few more widgets to their sidebar, or even at lengthy product content. In these cases, the theme should be flexible and adapt. The navigation menu is a prime example of where this can be catered for. If a navigation menu is a fixed width, let the menu items overflow to a new line, and have the navigation menu container expand to fit the items it has been given.

Themes offered on the Woo Marketplace are tested with the WooCommerce linter rules, to ensure they comply to our overall coding standards. Here is a step by step guide to setting up this linter on your computer;

• Install PHP and Composer on your computer, or in a Docker environment.
• Inside wp-content, install the woocommerce-sniffs with composer install woocommerce/woocommerce-sniffs.
• Add a file called pbs-rules-set.xml, which contains this content.
• Inside wp-content, I then run the following (replacing “themename” with the directory of your theme):

Themes

php ./vendor/bin/phpcs --standard=pbs-rules-set.xml --warning-severity=0 --report-source --report-full=phpcs-report.txt --ignore-annotations --extensions=php,html themes/themename

Extensions

php ./vendor/bin/phpcs --standard=pbs-rules-set.xml --warning-severity=0 --report-source --report-full=phpcs-report.txt --ignore-annotations --extensions=php,html plugins/pluginname

The report will be created in a file called phpcs-report.txt.