Codex

Theme Review

Languages: English • 日本語 • (Add your language)

For more information, refer to the WordPress Theme Review Team website.

Contents

Guidelines

(Last Edited: 2011-12-24)

  • Code Quality:
    • Themes must not generate any WordPress deprecated-function notices, PHP errors, warnings, or notices, HTML/CSS validation errors, or JavaScript errors.
  • Functionality:
    • Whether implementing required, recommended, or optional functionality, Themes are required to support proper WordPress core implementation of all included functionality.
  • Template Tags and Hooks:
    • Themes are required to implement WordPress template tags and hooks properly.
  • WordPress-Generated CSS Classes:
    • Themes are required to support WordPress-generated CSS classes.
  • Theme Template Files:
    • Themes are required to utilize Theme template files properly.
  • Theme Settings and Data Security:
    • Themes are required to implement Theme settings properly, and to ensure proper data security
  • Licensing:
    • Themes are required to be licensed fully under a GPL-compatible license.
  • Theme Name:
    • Themes are required to use appropriate Theme Names.
  • Credit Links:
    • Themes are recommended to use credit links. If used, credit links are required to be appropriate.
  • Theme Documentation:
    • Themes are required to provide sufficient documentation to explain the use of any custom features or options.
  • Theme Unit Tests:
    • Themes are required to meet all requirements in the Theme Unit Tests
  • Theme Obsolescence:
    • Themes are required to be kept current once accepted into the Theme Repository

Code Quality

PHP, JS, CSS, HTML

Doctype Declaration

  • Themes are required to have a valid HTML document HEAD:
    • Valid DOCTYPE declaration
    • <html> tag includes language_attributes()
    • Correct XFN profile link in <head> tag: <head profile="http://gmpg.org/xfn/11"> or <link rel="profile" href="http://gmpg.org/xfn/11" /> (Exception: Wholly HTML 5 themes must not have the profile, as HTML 5 does not support it.)
    • Correct content-type meta declaration: <meta http-equiv="Content-Type" content="<?php bloginfo('html_type'); ?>; charset=<?php bloginfo('charset'); ?>" /> OR <meta charset="<?php bloginfo('charset'); ?>" /> declared before <title>
    • <title> includes bloginfo() for title and description, as appropriate

Theme Namespacing

  • Themes are required to use theme-slug as textdomain for translation
  • Themes are required to use a unique slug as a prefix for all custom function names, classes, public/global variables, database entries (Theme options, post custom metadata, etc.)
    • Themes are recommended to use theme-slug as this unique slug

Note, when using a theme slug for text translation methods, the slug must be a string and not a variable or constant. Using a variable or constant will work fine in PHP, but causes problems for automated text translation tools. For more information, see Mark Jaquith's post on this topic. This guideline is required to be followed for all uses of the I18N translation mechanisms.

Functionality

Theme is required to incorporate the following WordPress core functionality:

Theme is recommended to incorporate the following WordPress core functionality, but is not required to do so. However, if incorporated, functionality must support the core WordPress implementation:

Theme may optionally incorporate the following functionality. If incorporated, functionality must support WordPress core functionality where applicable:

Template Tags and Hooks

All template tags and hooks used in a Theme are required to be implemented properly.

Required Hooks and Navigation

The following template tags and hooks are required to be included where appropriate:

Including Files

  • If incorporated into the Theme, standard template files are required to be called using the correct template tag.
  • If incorporated into the Theme, custom template files are required to be called using get_template_part() or locate_template()
  • Legacy Theme Support
    • Themes are required to include all template files called within the Theme, rather than relying upon legacy Theme support. If a Theme uses any of the following functions, it is required to include the appropriate template file:
      • get_footer(): footer.php
      • get_header(): header.php
      • get_sidebar(): sidebar.php
      • comments_template(): comments.php

Including Stylesheets and Scripts

  • Themes are required to enqueue all stylesheets and scripts, using wp_enqueue_style()/wp_enqueue_script(), and hooked into an appropriate hook via callback function, rather than hard-coding stylesheet/script links or tags in the template.
    • Themes are recommended to hook stylesheet and script enqueue callbacks into `wp_enqueue_scripts`
    • Themes may optionally link the default stylesheet (style.css) directly in the document head, or via wp_enqueue_style()
  • Themes are required to use core-bundled scripts, if using such scripts
  • Themes must not use TimThumb

Including Other Resources

  • Favicons
    • Themes are recommended not to implement custom favicon functionality.
      • If implemented, favicon functionality is required to be opt-in, and disabled by default.
      • If implemented, favicon functionality is required to support user-defined favicon images

Site Information

If incorporated into the Theme, site information is required to be called using the correct template tag:

  • Themes are required to use *_url() template tags, rather than bloginfo() equivalents.
    • See Trac Ticket #9008 for additional information related to this use of get_option() versus *_url

WordPress-Generated CSS Classes

Themes are required to support the following WordPress-defined CSS classes, or similar elements:

  • Alignment Classes:
    • .aligncenter
    • .alignleft
    • .alignright
  • Caption Related Classes:
    • .wp-caption
    • .wp-caption-text
    • .gallery-caption
  • Post Classes:
    • .sticky
  • Comment Classes:
    • .bypostauthor

While needing to be present in the stylesheet, .sticky and .bypostauthor can remain empty (unstyled) if desired. The intent is simply to ensure that theme developers have considered all classes generated by WordPress.

Theme Template Files

Note: at present, Child Themes are not currently eligible to be hosted in the WordPress Theme Repository. All Themes submitted must be stand-alone Themes.

Theme is required to include, at a minimum:

  • index.php
  • comments.php (via comments_template())
  • screenshot.png
    • Recommended 4:3 W:H ratio, size 300x225px.
    • Maximum size: 320:240px
    • Should be a "reasonable facsimile" of the Theme after it is initially activated with default options
  • style.css

Theme is recommended to include:

  • 404.php
  • archive.php
  • page.php
  • search.php
  • single.php
  • header.php (via get_header())
  • footer.php (via get_footer())
  • sidebar.php (via get_sidebar())
    • Note: header.php, footer.php, and sidebar.php include variations such as: sidebar-left.php, sidebar-right.php, sidebar-footer.php, etc.

Theme may optionally include:

  • attachment.php
  • author.php
  • category.php
  • date.php
  • editor-style.css
  • image.php
  • tag.php

Themes are recommended to use core markup for the following forms, using the indicated template tag:

  • Login Form: Must be included using wp_login_form()
  • Search Form: Must be included using get_search_form()
    • Themes may optionally customize the search form, as searchform.php

Submitted theme are recommended not to include files named like the following. However, if such files are used, Themes are required to provide end-user documentation explaining how to use them:

  • page-foobar.php
  • category-foobar.php
  • tag-foobar.php
  • taxonomy-foobar.php

Note: The reason to avoid this template naming convention for publicly released Themes is to avoid surprising users that create a page with the "-foobar" slug and expect the default template. See Template_Hierarchy#Page_display.

Theme Settings and Data Security

  • Themes are required to prefix all options, custom functions, custom variables, and custom constants with theme-slug (or appropriate variant).
  • Theme are required to implement Theme Options and Theme Settings pages deliberately, rather than relying on copy-and-paste scripts from website tutorials.
  • Themes are required to use the add_theme_page() function to add the Theme Settings Page to the Appearance menu, rather than using add_menu_page() to add a top-level menu.
  • Themes are required to use the edit_theme_options capability for add_theme_page(), rather than rely on a role (e.g. "administrator"), or a different capability (e.g. "edit_themes", "manage_options") for the capability to add the settings page.
  • Themes are required to save options in a single array, rather than create multiple options for its settings page. Use of set_theme_mod and get_theme_mod handles this for you, as does using the Settings API.
  • For checkboxes and select options, Themes are required to use the checked() and selected() functions for outputting checked="checked" and selected="selected", respectively.
  • Themes are required to validate and sanitize all untrusted data before entering data into the database, and to escape all untrusted data before being output in the Settings form fields or in the Theme template files (see: Data Validation)
  • Themes are required to use esc_attr() for text inputs and esc_html() (or esc_textarea() in WP 3.1) for textareas.
  • Themes are required to provide explicit Settings-page nonce checking, if not using the Settings API (see: WordPress Nonces)
  • Themes are recommended to use the Settings API to get and save form input data rather than rely on $_POST and $_REQUEST data directly.
External References

Licensing

  • License:
    • Themes are required to be 100% GPL-licensed, or use a GPL-compatible license. This includes all PHP, HTML, CSS, images, fonts, icons, and everything else. All of the theme must be GPL-Compatible.
    • Themes are required to declare their license explicitly, using the following method:
      • Declare License and License URI header slugs to style.css, using this format: 
License: GNU General Public License v2.0
License URI: http://www.gnu.org/licenses/gpl-2.0.html
  • Themes may optionally include a full-text license, referenced as license.txt, or else link to a reasonably permanent URL that contains the full-text license

Up-Sell Themes

  • Commercial versions of free Themes (i.e. "freemium" or "up-sell" Themes) are required to be released under GPL-compatible licenses
  • Commercial versions of free Themes must not lock core WordPress functionality behind the commercial paywall
  • Up-sell Themes may be subjected to more rigorous or additional Theme-Review requirements, at the discretion of the Theme Review Team

Bundled Resources

GPL-Compatible Font Licenses

The GNU Foundation and the Fedora Project maintain lists of acceptable licenses for use with GPL (see also: this list).

Fonts bundled with Themes submitted to the WordPress Theme directory are required to be licensed under one of the following font licenses:

  • Arphic Public License (Arphic)
  • Baekmuk License (Baekmuk)
  • Bitstream Vera License (Bitstream Vera)
  • Creative Commons Attribution License (CC-BY)
  • GNU GPL (with font exception) (GPL)
  • GUST e-Foundry Font License/LaTeX Project Public License (LPPL)
  • IPA Font License (IPA)
  • Liberation Font License (Liberation)
  • LaTeX Project Public License (LPPL)
  • mplus Font License (mplus)
  • ParaType Font License (PTFL)
  • SIL Open Font License (OFL)
  • STIX Fonts User License (STIX)
  • Wadalab Fonts License (Wadalab)
  • XANO Mincho Font License (XANO)
GPL-Compatible Icon Sets

Some compatible icon sets include the following:

Theme Name

Theme Name Guidelines are required for new Themes, and recommended for existing Themes.

  • Themes are not to use WordPress in their name. For example My WordPress Theme, WordPress AwesomeSauce, and AwesomeSauce for WordPress would not be accepted. After all, this is the WordPress Theme repository.
    • Themes are not to use the term Theme in their name, such as: AwesomeSauce Theme. Same reason as above ... it's a Theme repository.
    • Themes may use the WP acronym in the Theme name, such as WP AwesomeSauce.
  • Themes are not to use version-specific, markup-related terms (e.g. HTML5, CSS3, etc.) in their name.
  • Themes are not to use Theme author/developer credit text in their name. For example AwesomeSauce by John Q. Developer (makes for a much better credit link); or, SEO/spam-seeded text, such as: AwesomeSauce by Awesome Free WP Themes (this is just not going to pass).

Also note, theme names as defined in the style.css header block will be used as the theme slug in the WordPress Extend Theme repository. All names will be turned to lower case and spaces will be replaced with hyphens. For example: 'CamelCase Name' would be 'camelcase-name'.

Credit Links

  • Themes may optionally designate Author URI and Theme URI in style.css.
    • Theme URI, if used, is required to link to a page specifically related to the Theme. If a demonstration site or page is being used, the content must be related to the theme itself.
    • Author URI, if used, is required to link to an author's personal web site or project/development website.
    • Themes are recommended to provide at least one of these two links, in order to ensure Theme users have a point of contact for the Theme developer.
  • Themes may optionally include a public-facing credit link in the Theme footer.
    • If used, Themes are required to include no more than one such footer credit link.
    • Credit link, if used, is required to use either Theme URI or Author URI.
    • Credit link anchor text and title are required to be relevant and appropriate with respect to the linked site. Spam or SEO-seeded anchor text and titles may subject Themes to automatic rejection.
  • Themes may optionally include a Theme Option to display additional credit links or text.
    • If used, such options are required to be opt-in (i.e. disabled by default, rather than enabled)
    • If used, such options are recommended to provide user-modifiable text/links, rather than merely providing an enable/disable option
    • In general, such opt-in credit text/links are exempted from above-listed requirements regarding relevance and appropriateness. However, the Theme Review team reserves the right to prohibit such optional text/links if, at its sole discretion, a Theme abuses this option.
  • Since Themes are GPL (or compatible), Theme authors are prohibited from requiring that these links be kept by Theme users. An appropriate way to ask for Theme users to keep a link to the author's website is as follows: 
 "It is completely optional, but if you like the Theme I would appreciate it if you keep the credit link at the bottom."
  • Any exception to these requirements must be approved by the Theme Review team.

Theme Documentation

  • Themes are required to provide end-user documentation of any design limitations or extraordinary installation/setup instructions
  • Themes are recommended to include a readme.txt file, using Plugin readme.txt markdown.
  • In lieu of a readme.txt file, Themes are recommended to include a changelog, indicating version-to-version Theme changes.

Please be clear about the following in the documentation included with your Theme. The following helps many users over any potential stumbling blocks:

  • Indicate precisely what your Theme and template files will achieve.
  • Adhere to the naming conventions of the standard Theme hierarchy.
  • Indicate deficiencies in your Themes, if any.
  • Clearly reference any special modifications in comments within the template and stylesheet files. Add comments to modifications, template sections, and CSS styles, especially those which cross template files.
  • If you have any special requirements, which may include custom Rewrite Rules, or the use of some additional, special templates, images or files, please explicitly state the steps of action a user should take to get your Theme working.
  • Provide contact information (website or email), if possible, for support information and questions.

It is also recommended, both for standardization and to minimize any risks that may be associated with other file extensions, a readme.txt text file be used for documentation not made in comments within the template and stylesheet files. Other forms of documentation may be included in addition to the readme file at the Theme author's discretion such as "Contextual Help" within the Theme's "option" page(s).

Theme Unit Tests

The Theme must meet all the requirements of the Theme Unit Test.

Theme Obsolescence

  • Themes must be kept current once submitted, approved, and accepted into the Theme Repository.
  • Any Theme not updated to the current theme review process as of the most recent release of WordPress may be subject to temporary suspension.
Retrieved from "http://codex.wordpress.org/Theme_Review"

Codex Resources