/ Partner Guides

For Developers & Designers

If you’re an experienced WordPress developer and/or designer, then you’ll be glad to know that we like to follow all of the best practices for WordPress theme and plugin development, coding standards, security and performance. If you’re less familiar with WordPress design and development, here are some guidelines and recommendations to keep in mind:

Design

  • Design for Web. We prefer that designs be delivered in an accessible format suited for web design, ideally in Figma (Sketch is also accepted but not preferred). Adobe formats are discouraged.
    • Note that any any important information, like developer notes, should not be left in Figma comments (comments are wiped when files are duplicated).
  • Create a Style Guide. A style guide or pattern library that outlines all of the design elements for the site — including but not limited to colors, fonts and type sizes, buttons, hover states, image treatments, tablet and mobile layouts.
  • Include Development Notes. Add notes for the developer for any non-obvious functionality or custom features, such as fixed image sizes, transitions, or UX triggers.
  • Include Standard Views. It would be good to take into account the design for all of the common WordPress views. This includes (at minimum):
    • Front/Homepage
    • Blog page
    • Single blog posts
    • Static pages
    • Archive page (tags/categories)
    • Search page
    • 404 page
    • Important views for the major plugin features, if applicable, that will be used on the site (for example, WooCommerce shop sections, forum views, course page views, etc).
  • Utilize Gutenberg Blocks. Utilize WordPress’s native block editor, Gutenberg, for common interface patterns (this includes things like image galleries and recent post modules). You can view and test block capabilities via this online Gutenberg playground.
  • Test for Different Image Layouts. If the design will include grids or blocks with featured images, it would be helpful to take into account how the design will look when:
    • Featured image is absent
    • Featured images are multiple sizes/aspect ratios
    • Featured image is smaller than allocated size
    • Content in grid blocks is of varying lengths
    • On mobile views
  • Design for Consistency and Efficiency. Try to re-use modules throughout your designs instead of creating multiple different versions that accomplish the same function. For example, avoid using five different variations of image sliders when a single design would suffice.
  • Design for Accessibility. See https://codex.wordpress.org/Accessibility for more information and tools to ensure a WordPress site is accessible for all.
  • Use Open-Source or Licensed Fonts and Icons. Fonts and icons that are not from Google Fonts or other free/open-source sources should be licensed by the partner for use on their website and provided before development. Use of Adobe fonts will require the partner to have their own Creative Cloud account.
  • Design for all Screen Sizes. While it’s not necessary to provide mobile mockups for the entire site, we do like to have mobile views for the homepage, menu, and any other key sections that are less straightforward for a developer to translate to mobile. As a baseline, consider phones, tablets, as well as widescreen desktops.
  • Design for Real-World Content. The designs should reflect the reality of the real-world content as much as possible, and to the best of your knowledge at time. For example, avoid placing a play button icon over an image unless you know for sure that that item will be a video.

Development

  • Plan for Traffic. We will want to make sure that the site’s features are optimized for performance under a high traffic load, both on mobile and on desktop. If features involve grabbing data from an API, we have to take usage limits into account, for example. If there will be multiple queries that display posts and content on a page, we’ll need to make sure appropriate caching is in place.
  • Avoid Non-WordPress Software. Given that we work exclusively with WordPress, all functionality for the site should either be accomplished in WordPress or have a suitable WordPress integration (see above).
  • Use GPL v2.0 or Greater License. We follow the spirit of the GPL v2.0 License (the license that WordPress is released under) and as such, all of the assets we use on the site should be in compliance with the GPL v2.0 or greater.
  • Keep it Simple. We avoid complex themes and frameworks which are often overengineered and add a lot of bloat (e.g. page builders, extensive page-level customizations, complex libraries, proprietary or premium themes, and extensive theme options panels). When we write themes from scratch, we usually use Seedlet.
  • Theme Selection. There are many themes available for WordPress. While not required, basing the design on top of an existing theme could be one way to approach the build process. WordPress.com has many themes that could pose as a great starting point for customization: http://wordpress.com/themes/ (even if we don’t host the site on WordPress.com, we can download or purchase any of these themes for use on self-hosted WordPress sites). Seedlet, developed by the WordPress.com Theme Team, is the new base for all themes on WordPress.com, and can be a great parent or starter theme.
  • Use the WordPress Template Hierarchy. An outline / page structure for the site that takes the WordPress template hierarchy into account. The Special Projects team can advise in this area as needed. See https://developer.wordpress.org/themes/basics/template-hierarchy/ and https://wphierarchy.com
  • Specify Custom Post Types. Out of the box, WordPress comes with two main content types: “Posts” – which carry a date stamp and are suitable for blog posts, and “Pages”, which are static (no date stamp), suitable for “About” or “Contact” pages. There’s also the ability to create custom post types (also called custom content types), such as “Videos”, “Books”, etc. A site’s design specifications should clearly indicate which content types will be needed, and their associated metadata. https://codex.wordpress.org/Post_Types.
  • Specify Custom Taxonomies. WordPress uses taxonomies to classify data, and you can link taxonomies to custom post types. For example, out of the box, WordPress comes with “categories” and “tags”, two types of taxonomies that you can use to classify posts. Design specifications should clearly indicate if any custom taxonomies will be in use, and the custom post types with which they’ll be associated. See: https://codex.wordpress.org/Taxonomies.
  • Consider Collaborative Development Workflows. The Special Projects team typically uses the GitHub workflow described at https://guides.github.com/introduction/flow/ and having the site’s theme and custom plugins in a GitHub repository means that we can easily create and maintain local development environments, staging sites, and a production deploy process.
  • Consider Security. If any aspects of the design involve will user-submitted data (such as forms), it’s a potential security risk and so the design will need to specify which type of data is being collected and how, so that Special Projects team can offer guidance and plans of action during the design phase. Likewise, site admins embedding inline Javascript into the page editor within WordPress (or any CMS) is also a potential security risk, so we will want to make sure the design is done in such a way that avoids the need to embed Javascript into the page editor. All sites we work with have an SSL certificate installed and HTTPS enabled by default. We use the Two-Factor Authentication plugin to secure user logins.
  • Consider User Roles. WordPress comes with several user roles out of the box. The design should specify if any custom user roles will be needed, and their capabilities on the site. https://codex.wordpress.org/Roles_and_Capabilities.
  • Avoid Hard-Coding Curated Content. For features or sections of a site that partners will need to curate or update regularly, default to building a way for partners to configure these settings on their own instead of hardcoding them into the theme (unless there’s a good reason not to). Adding an options panel to the Customizer is our typical way of doing this. Some example scenarios include:
    • Curating content that appears on the front page of the site. This includes panel-like pages, news sites, grid-page templates, featured content areas, etc. We prefer to use Gutenberg for these features.
    • Utilizing Gutenberg blocks (both core or custom blocks) to allow the site owner to manage curated content. Of course, everything doesn’t need to be a block. The main thing is to consider which content the partner will most likely need to update or curate on a regular basis, and use that as a starting point.  When in doubt, please ask us!

All partner guides