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.
Themes should be responsive and Gutenberg-first.
↑ Back to topWith 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.
Use Gutenberg overrides instead of theme options and meta boxes.
↑ Back to topContinuing 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.
Themes should remain lean and have a simple codebase.
↑ Back to topThe 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.
Encourage compatibility with plugins, rather than requiring them.
↑ Back to topThemes 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.
The content in the Block Editor should look the same as on the frontend of the theme.
↑ Back to topAs 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.
Consider carefully dependencies on third-party libraries.
↑ Back to topSimilarly 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.
The visual experience should be flexible to the content provided.
↑ Back to topA 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.
Testing using the WooCommerce linter
↑ Back to topThemes 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 withcomposer 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/themenameExtensions
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/pluginnameThe report will be created in a file called phpcs-report.txt.