Theme Guide

The theme must meet all requirements in the WordPress.org theme review. Along with this, it must also meet the following criteria.

Code

• Use WordPress functionality and features first, if available (This includes Jetpack features for WordPress.com).
• No frameworks or options frameworks.
• No external, non-Automattic (Jetpack, Gravatar, etc.) APIs.
• WordPress.com themes should always use the latest WordPress features.
• Do not include code that won’t run on WP.com. This includes any code for compatibility and the use of IS_WPCOM.
• Use filters to modify the output of template tags, if available.
• Use client-side feature detection, rather than server side browser detection.
• Themes must not directly access PHP super globals.
• No output buffering.
• No custom fields or post meta boxes.
• No removing or modifying Core hooks.
• Footer credits must be located in footer.php and match the format found in Underscores

JavaScript

• Protect function and variable names from conflicts in the global namespace. Always use theme slug prefixes, or wrap code in an immediately invoked function expression (IFFE), like Underscores.

HTML/CSS

• All themes must use the HTML5 doctype and contain semantic markup.
• Themes must be responsive and retina-ready.
• Use !important and inline styles only as a last resort.
• You can’t include code or scripts for extending support below IE9.

Core Functionality and Features

• All code and widgets must not replicate existing WordPress.com functionality.
• Themes must support widgets.
• Themes must support at least one Custom Menu.
• No customizing /wp-admin.

Documentation

All premium themes released on WordPress.com have a showcase page and support documentation. Follow the documentation style guide to ensure that users have a clear understanding of a theme’s features, and where to get help.

Language

•  Provide context where appropriate.
• Avoid common anti-patterns.
• Themes must provide right-to-left styles.
• Translators need to be able to deactivate web fonts that don’t support the character set of their language.
• Translation strings should be escaped for improved security. See _s (Underscores)  for examples.

Options and Settings

• Only implement theme options through the Customizer.
• Theme options must be in one section, entitled ‘Theme Options’.
• No theme options should allow users to add scripts or styles.
• Do not include any additional options for setting colors or fonts: these are handled on WordPress.com by our Custom Fonts and Custom Colors features.
• Themes need to support Jetpack Infinite Scroll.

Stylesheets and Scripts

• Don’t hook HTML or Javascript into wp_head.
• No minification; it’s impossible to audit, and WordPress.com has its own minification process.
• The theme’s primary CSS must be in style.css.
• Theme tags in style.css must be be lowercase with no spaces. Separate multiple-word tags with a dash. View a list of all allowable tags.
• Line heights must be set to relative values, so that Custom Fonts work correctly.
• Enqueue Google fonts using this format.

Templates

• Themes must respect the Template Hierarchy.
• front-page.php must respect the user’s Settings → Reading → Front Page Displays value.
• $content_width must be set to the theme’s default content width.
• Use full loops in all templates. Just calling the_post() in a template like single.php or page.php is not enough. This is a great explanatory article.

Queries

• Themes must use WP_Query.
• Don’t use unbounded queries. The posts_per_page parameter of WP_Query may not be set to -1. Also, the numberposts parameter of get_posts() (and similar functions) must have a positive value.
• Themes must not modify the main query.

Widgets

• Prefix widget titles with the themename, ie. Theme Name: Widget Title.
• Widget areas must not contain hardcoded widgets.
• Visible links to feeds must not appear in themes. We suggest that site owners use the Follow Blog Widget on WordPress.com to allow their visitors to subscribe.

Theme User Experience Requirements

We’ve put together a list of theme user-experience requirements that make it easier for people to use WordPress themes. We call it the TUX List.

Content

• On sites with multiple authors, the author name should be displayed. Note: You can also choose display the author on sites with a single author. Reason: If a site has multiple authors then it’s useful for readers to see who wrote each post.
• Themes must support both categories and tags in some capacity. Reason: Users see these in the admin areas, so they expect to see them on their site’s front end.
• Add support for Jetpack’s Content Options to the fullest extent possible. Reason: Users want to be able to change and customize what appears for each post/page.

Header

• Show the site title and tagline by default. Reason: Both site title and tagline can always be hidden via the Customizer, so hiding one by default makes for a confusing user experience.

Layout

• If the site does not have a sidebar or the sidebar has no widgets, the content line length should adjust. Reason: Long line lengths are an issue for readability.
• If a layout normally has two columns or more with widgets, the layout should adjust to a single column if a user has not added widgets to the sidebar, without displaying an empty column. Reason: This gives users flexibility to have a single-column layout without needing a page template or theme option. If a user wants widgets only on specific pages, they can use the Widget Visibility tool.

Menus

• Menu labels should specify the location and, if the theme supports more than one, its position, like Header Top, Header Bottom, Footer, etc. Reason: Without this, users are unable to know which menu refers to what area.
• Menu locations should take the format of menu-1, menu-2, etc. Reason: Consistency across themes means that a user can switch themes and not have to reassign their menu to the theme’s menu location. It also allows easier readability in code.
• Social menu should be called Social Menu. Reason: Consistency on theme switching, which again means that the site displays the user’s social menu even after changing themes.
• Drop-down menus should have an arrow indicating the direction in which the menu opens. Reason: Without an arrow, it’s hard to know if an item has a sub-menu.
• Mobile menus should have a hamburger icon and the label Menu. Reason: Users can consistently see the same mobile menu indicator and don’t have to learn a new icon or word each time they switch a theme.

Pagination

• Single-post navigation should display “next / previous” and show the post title. This also means consistent translations for translators. Reason: Users can easily know they’re looking at pagination and the experience is consistent.

Post Formats

• A theme does not need to support any post formats unless the theme is a “Tumblog”- style theme, in which case the theme should support all available post formats. Reason: Users only expect post formats from Tumblog-type themes.

Posts

• Excerpts should be followed by a “Continue Reading” link. Reason: Provides a consistent experience for users.
• Do not use the_content_more_link filter to customize Read more link text. Reason: this prevents users from customizing the More tag.

Sticky posts

• Provide a clear indication that sticky posts are different from normal posts. For example, add some text or other clear indicator to differentiate sticky posts. Also, they should not display the date. Reason: A post if sticky should have some indication of its stickiness, otherwise it’s a surprise to find it at the top.

Templates

• All templates should be in a folder called templates. Reason: Reviewers can see at a glance which templates are available, decreasing review time and improving code legibility.
• Portfolio template should be called portfolio-page.php.
• Full-width template should be called full-width-page.php.
• Grid template should be called grid-page.php.
• Testimonials template should be called testimonials-page.php.
• Food menus template should be called food-menus-page.php.
• Guestbook template should be called guestbook-page.php.
• Contributors template should be called contributors-page.php.
• Front-page template should be called front-page.php.

Reason: Consistent template naming helps reduce setup time after a theme switch and also decreases review time.

Widgets

• Keep widget names descriptive of their location, ie. Sidebar, Footer, etc. Reason: Users can more easily find them and know what area they refer to.
• Widget IDs should take the format of sidebar-1, sidebar-2, etc. Reason: Consistency across themes means that a user can switch themes and not have to reassign their widgets to the theme’s widget locations. It also allows for easier readability in code.

Color Annotations

• Add 6 featured color palettes.
• Ensure you have at least one light-on-dark palette and one dark-on-light palette. Reason: At least two color palettes must be accessible.
• Use standard color names for color palettes whenever possible, picking the strongest accent/accents, and add comment for translators. Reason: Vague/clever palette names often cause confusion for translators.

Along with these we also recommend the following items.

• All the WordPress.org recommended items.
• We encourage the use of _s (Underscores) as this helps with review time.
• We encourage the use of navigation menus to handle social icons.