This guide is for anyone interested in making the best possible WordPress themes. Each public theme on WordPress.com is tested against these guidelines to ensure the highest quality. This includes security, plugin compatibility, and support for a wide variety of user-generated content.

Escaping

  1. All dynamic data must be escaped with esc_attr() before rendered in an html attribute.
  2. All dynamic urls must be escaped with esc_url().
  3. If dynamic data is rendered as the attribute of a html script element, it must be escaped with esc_js().
  4. SQL queries containing dynamic data must be escaped with $wpdb->prepare().

Internationalization

  1. All user-facing text must be prepared for translation.
  2. Avoid HTML inside strings passed to gettext functions wherever possible.
  3. The output of sprintf() must be escaped in text strings used in attributes.
  4. printf() placeholders must be escaped before included in HTML attributes.
  5. Provide context where appropriate.
  6. Avoid common anti-patterns.

Queries

  1. Do not use raw SQL queries, use a new WP_Query object instead.
  2. Unbounded queries may not be used. Basically this means that 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 also have a positive value.
  3. Expensive queries should be transient cached.
  4. query_posts() is not allowed. If you need to modify the main query it is best to use the pre_get_posts filter. If you need to retrieve posts in addition to the main query, use a new WP_Query object.
  5. Empty values may not be passed to the post__in argument used to create a new WP_Query object. If you are using a dynamic value that could be empty it is important to check for empty before using the value in the query. Code example.
  6. Term queries should be tested on an installation with 10,000 terms.

Enqueues

  1. All 3rd party, bundled files must be GPL compatible.
  2. Ensure the correct protocol is used for enqueuing 3rd-party files.
  3. Ensure that the approprite hooks are used to enqueue scripts and styles.

Scripts

  1. Use core-bundled scripts if they exist.
  2. All scripts (custom and third-party) need to be the full developer version; minified files are impossible to audit, and WordPress.com has its own minification process.
  3. Ensure all script handles are prefixed with the theme slug to avoid naming conflicts.

Styles

  1. The main stylesheet (style.css) must be enqueued during the wp_enqueue_scripts action.
  2. overflow:hidden should never be used to contain floats. The micro clearfix is a better alternative.
  3. The !important keyword should not be used where specificity would suffice.
  4. When enqueuing a Google font with multiple character sets, conditionally include the sets with gettext.
  5. Style attributes on HTML tags are not permitted.
  6. Ensure all style handles and custom image sizes are prefixed with the theme slug to avoid naming conflicts.

Plugin Conflicts

The WordPress.com environment is super-charged with an extensive set of plugins that provide functionality that is shared across all themes. To provide our users with the most consistent experience we ask that functionality that duplicates our plugins not be included on the theme level.

  1. WP-admin-dependent features, such as custom post meta boxes or menus
  2. Advertising options are handled via WordAds.
  3. Custom color options are handled by the Custom Colors plugin.
  4. Custom fonts options are handled by the Custom Fonts plugin.
  5. Favicons are handled via Blavatar plugin.
  6. HiDPI support for user-provided images
  7. Infinite Scroll is handled by Jetpack.
  8. Open Graph Protocol
  9. Twitter meta tag support
  10. Various widgets

Data Portability

Ensuring that a user’s content does not change when they switch themes is very important. The following features of WordPress core, while awesome in their own right, can cause a user’s content to change or become unreachable if implemented on the theme level.

  1. Public Custom Post Types
  2. Public Custom Taxonomies
  3. Custom Fields AKA Post Meta
  4. Shortcodes

Theme Options

If your theme includes custom options, we strongly suggest that the Customizer be used instead of a custom admin screen. Doing so has many benefits:

  1. Users can immediately see their changes as they adjust the UI.
  2. There is much less code to write.
  3. Built in user interface modules for the most common situations.

In the event that your theme needs to provide a custom options screen in the admin here are the requirements:

  1. Must be a child of the Appearance menu with a title “Theme Options”.
  2. Use of the WordPress Settings API is required.
  3. All options must be stored as a single serialized array.
  4. Default options may not be inserted into the database upon installation or http request.
  5. All values must be sanitized before saved to the database.
  6. Core functionality must be used for any file uploads.

Most, if not all of these requirements are illustrated in this Theme Options Starter File.

Miscellaneous

  1. Full loops must be used in all templates. Just calling the_post() in a template like single.php or page.php is not enough. See this ThemeShaper post for an explanation.
  2. The $content_width global must be set correctly.
  3. Visible links to feeds should not appear in themes. We suggest that site owners use the Follow Blog Widget on WordPress.com to allow their visitors to subscribe.

Template Hierarchy

  1. The Template Hierarchy must be respected and used appropriately.
  2. index.php cannot be repurposed or disabled, nor replaced with a Blog page template.

Usability Guidelines

The WordPress.org Theme Unit Test Data is comprised of multiple posts and pages designed to push your theme to the limits. Please download the data and import to your test server. Running your theme through all of the provided tests can help ensure that your theme will be flexible enough to handle a wide variety of actual user data.

Documentation Style Guide

All premium themes released on WordPress.com have a showcase page and support documentation. To ensure users have a clear understanding of a theme’s features, any setup required, and where to get help, theme sellers are expected to follow this style guide.

Resources