Creating a style guide for WordPress Site Editor

The equivalent of a visual style guide in WordPress is a file called theme.json. It is commonly used to:

• Define global styles and settings for the theme
• Control block-level defaults and variations
• Set up color palettes
• Set up typography
• Set up layout properties and spacing presets
• Set up site-wide CSS

Defining global styles and settings

Most commonly, the theme.json file is used to set up styles and settings that are shared across the website. It lets developers create a define-once-use-anywhere configuration that users can choose from when using text, images, sections, etc.

Setting up typography using theme.json

Theme.json supports extensive typography configurations. Using this file, developers can configure font families, font sizes, line heights, and weights to be used across the website or on certain blocks.

Figure 2.1 shows an example of two font size variations and their code-equivalent. 

Establishing color schemes using theme.json

Colors give life to the design and the theme.json file ensures that developers can codify the colors that a designer has selected. We can add as many variations as possible, such as primary, secondary, tertiary, accent, and functional colors. We can also add gradients and duotone filters using the theme.json file.

Figure 2.2 shows different types of colors and their code-equivalent. 

Configuring layouts using theme.json

In the theme.json, we can also define the basic layout configurations such content width, wide width, and default block alignments. These layouts can be used globally as well as for an individual block.

Figure 2.3 shows how these settings look on the editor side. These settings can be accessed using Site Editor > Styles > Layout.

Defining spacing presets using theme.json

Using theme.json, we can define different types of spacing we want to use in our theme. These spacings can be inter-component and intra-component. For example, in Figure 2.4, we can see three spacing variants being used between three different headings (inter-component). 

We can also define margin and padding presets to be used in the design. This makes it easier for the user to quickly and consistently add spacing, margin, and padding.

Customizing block defaults and variants using theme.json

Often, we want the blocks (core and custom; read more about core blocks here) to look a certain way. For this reason, we may want to modify their default appearance or add additional variations. This can be achieved using the theme.json. 

We can:

• Set default styles for core blocks (paragraph, heading, list, etc.)
• Define custom styles for theme-specific blocks
• Create block variations for common use cases
• Configure default block spacing, margin, padding, and alignment

In Figure 2.5, we can see that we have two variations for the core button block: fill and outline, and the code-equivalent. We have modified the fill variant to have the “Heading” font family and letter spacing of 0.2rem. On the other hand, the outline variant retains the default font family but has a border width of 1px.