Patterns for Partner Sites

Using patterns in new WordPress theme builds is essential to ensure consistency, efficiency, and usability across different websites. We will be utilizing patterns on all new theme builds going forward. This page aims to define and standardize our processes for identifying, building, and using block patterns on partner sites.

Table of Contents

Pattern Discovery

Pattern discovery is essential to creating an efficient, usable site for partners. To help support the partner with an atomic design system, there needs to be some strategy conversations to understand the partner’s content.

TAMs should review exisiting sites ahead of kickoff calls to identify repeated content that might be useful to build as patterns, and to inform the direction for the discovery questions below.

Questions to ask the partner during kickoff

What type of content will be featured?
- Will the content mainly be text/or image-led? Or a mix of both?
- Will video content be featured?
Would you like different types of content structures to be featured, for example, a separate look for varying products?
Do you have any example content currently available?
How comfortable are you utilizing patterns? Would a training call be helpful?

How to plan for patterns

Once the discovery call has taken place, the assigned designer and TAM can discuss the partner’s requirements and determine if any existing patterns can be utilized. If no suitable existing/default patterns are available, we can establish what will be required to meet the partner’s objectives.

Tracking Patterns (Project Management)

TAMs can choose to organize their pattern development process using their project management tool of choice. The recommendation of this handbook page is to use GitHub for tracking progress, but you could use P2 task lists, Slack Canvas, Google Sheets, or another project management tool.

Here are the recommended steps for tracking pattern design and development in GH:

Create an “epic” tracking issue titled [Site Name] Patterns. As TAM, you can determine if you want to track patterns in GH starting in the design phase or during the development phase after design handoff. ███████████████
- Add your Epic Pattern Issue to your Project P2 for reference and tracking. ███████████████
Group patterns together by category (if applicable). For example, create a collection of patterns
Create a task list of all of the patterns that need to be created—use the pattern name as your task name (see pattern naming)
After publishing the issue, convert all of the tasks to individual issues—your task name will become your issue title
Add a description, Figma link, or screenshot for each individual pattern issue. ███████████████
Use individual GH issues to facilitate feedback and implementation, looping in the project’s designer for QA and review throughout the process
Close issues and check off tasks as patterns are completed.
Close your Epic Issue after all individual pattern tasks have been completed and been through QA.

Pattern Design, Build, & QA

Pattern Design Process

Starter / Full Page Patterns

Patterns may consist of sections or grouping of blocks and/or full page patterns that are presented as options to select from when a new post, page, or CPT is created. Full page patterns can have other patterns nested inside. This is preferable so any updates can be made directly to the individual pattern and cascade to the full page.

Example starter page pattern from the Twenty Twenty Four theme:

<?php
/**
 * Title: About
 * Slug: twentytwentyfour/page-about-business
 * Categories: page
 * Keywords: starter
 * Block Types: core/post-content
 * Post Types: page, wp_template
 * Viewport width: 1400
 */
?>

<!-- wp:pattern {"slug":"twentytwentyfour/text-title-left-image-right"} /-->
<!-- wp:pattern {"slug":"twentytwentyfour/text-project-details"} /-->
<!-- wp:pattern {"slug":"twentytwentyfour/cta-services-image-left"} /-->
<!-- wp:pattern {"slug":"twentytwentyfour/team-4-col"} /-->
<!-- wp:pattern {"slug":"clients-section"} /-->
<!-- wp:pattern {"slug":"twentytwentyfour/text-faq"} /-->
<!-- wp:pattern {"slug":"twentytwentyfour/cta-content-image-on-right"} /-->

Pattern tracking (detailed above) may take place ahead of, during, or after design depending on preferences and project specifications.

Patterns should be identified in the Figma designs, and any relevant details documented for clarity during dev handoff.

Pattern Build Process

Tips & Tricks

This article has some great insights:
https://developer.wordpress.org/news/2024/03/19/pattern-design-tips-and-tricks-for-developers

Pattern Naming

Name with the partner and long-term maintenance in mind. Names should be descriptive and precise enough to distinguish the pattern while avoiding terms that might be confusing to the partner.

Examples of naming:

Hero section with image & CTA – Right
Three column section with icons
Headline with separator

Things not to do when naming:

Do not include the site name in the pattern name.
Do not capitalize every word – pattern names should use sentence case.

Technical Considerations

Dev handoff notes will be provided in Figma; patterns may be noted within the designs or as their own page as needed.
Patterns should be located in the /patterns folder of the theme.
File names should match the pattern names.
Pattern example resources and placeholder content like images should be added to the assets/img folder inside a patterns folder and referenced via get_theme_file_uri().
Before Launch: Patterns built or adjusted in the editor should be added directly to the theme. The block content can be copied and pasted from the editor, but database references should be removed. Necessary example resources, such as images, should be added to the theme’s /assets/img folder and referenced with get_theme_file_uri().
Use block attributes to add placeholder content to text blocks where appropriate. More details on this process can be found ███████████████.

Pattern Build Review/QA

Once pattern dev is complete, run through the following checklist to ensure created patterns adhere to our standards. These ensure maintainability.

Checklist

- [ ] Have we removed default patterns?
- [ ] Have patterns created or edited in the site editor been moved into the theme?
- [ ] Are new patterns categorized?
- [ ] Do patterns have descriptive names that reflect the purpose of the pattern? Are the pattern names using sentence case?
- [ ] Are pattern assets in the theme?
- [ ] Are images in the patterns referencing images in the theme with get_theme_file_uri()?
- [ ] Are patterns using placeholder text for headers, paragraphs, and any applicable text?
- [ ] Are colors set in patterns using theme color variables?
- [ ] If patterns represent full pages, do they have the Block Types and Post Types information set in the editor so they populate in the modal for new posts?
- [ ] Are patterns displaying in the inserter as expected?
- [ ] If any non-core plugin blocks are used in patterns, please note this in the site P2.
-[ ] Are full page patterns limited to their applicable post type?

Pattern Handoff to Partner

During the launch phase for new site builds or redesigns, incorporate how to use patterns during a handoff call or short training video. Here are some topics to cover.

Share with partners the concept of Synced versus Not synced patterns. Demonstrate the value of Synced patterns for high value CTAs that can be edited in one place and updated everywhere.
Show where patterns live in the site editor. Help the partner navigate to Appearance —> Editor —> Patterns
- Patterns created by the partner in the site editor will be found in the My patterns folder.
- Synced patterns are noted by the purple pattern icon.
Demonstrate how to create a new pattern within the site editor. Be sure to cover naming your patterns, assigning a pattern category, and double checking if the partner wants the pattern to be synced or unsynced.
Build a new pattern in a page or post and save as a pattern
Choose a page or post that is already built and demonstrate how to select blocks and save a pattern—keep pointing out the Synced-Not synced checkbox

Template Parts

Template parts are now managed in the Patterns folder in the site editor. Here are some general notes to share with partners during handoff.

Header and Footer template parts should not be edited by the partner. If they would like an update to their site Header of Footer, partners should submit those as a request to the active TAM or Special Projects Support.
Partners should avoid creating new Template Parts when creating a new pattern. In special circumstances, partners we have trained to use all areas of the site editor can manage and create templates and template parts.

Note: Synced Patterns will live in the Site Editor only. These patterns cannot be included as part of the theme.

Updating Theme Patterns

Some patterns have a lock. These patterns are built in the theme and managed by us. Partners seeking edits to locked patterns should request an update from the launch TAM or email us.
Patterns created by TAMs or partners in the site will live in the site editor only and will not be part of the theme. If any pattern(s) should be a theme pattern(s) on the partner site, the assigned TAM should facilitate adding the pattern to the theme files with the active contract dev on the project or an internal dev request.
If any pattern update needs to be reverted to a previous version, use Jetpack Backup to restore the site to an earlier version with desired pattern—double and triple check you are reverting to a version with pattern changes only and not other site updates.

References

Patterns are fluid and changing. This Pattern Handbook page is inspired by and supported by the following:

███████████████
███████████████
███████████████
███████████████
https://developer.wordpress.org/news/2024/01/31/adding-starter-patterns-to-your-wordpress-themes/
███████████████