Exercise: Experimental-theme.json

Level: Beginner, intermediate

Prerequisites: To make the most of this lesson, first read the lesson about Global Styles.

For this full site editing lesson you will need:

  • A WordPress installation with some test content and the Gutenberg plugin.
  • A block-based theme with at least one header and one footer template part.

If you created a theme with template parts in the previous exercise, you can continue using it for this exercise.
If you have not already set up a theme, you can download part two of the lesson files.

If you just want the final code from the project created in this lesson, you can download it here.

Estimated reading time: 8 minutes

This lesson has been updated for Gutenberg version 10.3 on April 8 2021

In this exercise, you will learn how to create a configuration file for block-based themes. You will also add some basic styling to the theme.

With the help of the experimental-theme.json file, we are going to turn this:

A preview of the theme without styles. The theme has a white background, black text and purple links.

into this:

The front of the website with styles applied. The background is dark grey, and the text is white with turquoise links.

Creating the experimental-theme.json file

In the theme folder, create a file called experimental-theme.json.

The file will have three sections: settings, styles, and templateParts. But because one single error in the file will cause all other settings to break, we will add one section at the time.

First we will add the default settings. Default settings applies to all blocks but can be overridden on per-block basis. Start with the opening and closing brackets:

{
}

Inside these brackets, add the settings section with the defaults sub-section:

{
	"settings": {
		"defaults": {
		}
	}
}

Color palette

Next, add the first colors to the color palette.
Remember to encase the colors with brackets, and separate them with a comma. There should not be a trailing comma after the last color.

This setting is the equivalent of the editor-color-palette theme support.
The slug is what will be used in the CSS class, and the name is the visible name in the editor.

{
	"settings": {
		"defaults": {
			"color": {
				"palette": [
					{
						"slug": "black",
						"color": "#000000",
						"name": "Black"
					},
					{
						"slug": "white",
						"color": "#FFFFFF",
						"name": "White"
					}
				]
			}
		}
	}
}

Add a few more colors that we can use in the design of the theme:

{
	"settings": {
		"defaults": {
			"color": {
				"palette": [
					{
						"slug": "black",
						"color": "#000000",
						"name": "Black"
					},
					{
						"slug": "white",
						"color": "#FFFFFF",
						"name": "White"
					},
					{
						"slug": "dark-grey",
						"color": "#121212",
						"name": "Dark grey"
					},
					{
						"slug": "medium-grey",
						"color": "#383838",
						"name": "Medium grey"
					},
					{
						"slug": "cyan",
						"color": "#00838f",
						"name": "Cyan"
					},
					{
						"slug": "light-cyan",
						"color": "#4fb3bf",
						"name": "Light cyan"
					}
				]
			}
		}
	}
}

After the palette, inside colors, add a gradient using the custom color presets you just created.

--wp--preset--color--light-cyan
--wp--preset--color--white
"gradients": [
	{
	"slug": "light-cyan-to-white",
"gradient": "linear-gradient(135deg, var(--wp--preset--color--light-cyan), var(--wp--preset--color--white))",
	"name": "Light cyan to white"
	}
]

This setting is the equivalent of the editor-gradient-presets theme support.

Typography

The typography sub-section covers font families, font sizes and line-height.

Font weight, font styles, text decoration and text transform were removed in December 2020.

Add typography after color (the code is truncated):

{
	"settings": {
		"defaults": {
			"color": {
				"palette": [...],
				"gradients": [...]
			},
			"typography": {
			}
		}
	}
}

Font families

With this code example I am adding three sets of font families: system fonts, sans-serif and serif.
The Name property is the visible name in the editor. If name is not included, the fontFamily value will be visible instead.

To use a third party font like google fonts, you need to enqueue the font both for the editor and the front, and add the name as a value for fontFamily.

"typography": {
		"fontFamilies": [
				{
				"fontFamily": "-apple-system,BlinkMacSystemFont,\"Segoe UI\",Roboto,Oxygen-Sans,Ubuntu,Cantarell,\"Helvetica Neue\",sans-serif",
				"slug": "system-fonts",
				"name": "System Fonts"
				},
				{
		                "fontFamily": "Geneva, Tahoma, Verdana, sans-serif",
				"slug": "geneva-verdana"
				},
				{
				"fontFamily": "Cambria, Georgia, serif",
				"slug": "cambria-georgia"
				}
		                ]
	}

Font sizes

This setting is the equivalent of the editor-font-sizes theme support.
The size property can be any CSS that is valid for font sizes, for example pixels.
The Name property is the visible name in the editor.

Adjust the font sizes that you would like to use in your theme. For the sake of simplicity, you can copy and paste the following example from the TT1 Blocks theme:

"fontSizes": [
		{
		"slug": "extra-small",
		"size": "16px",
		"name": "Extra small"
		},
		{
		"slug": "small",
		"size": "18px",
		"name": "Small"
		},
		{
		"slug": "normal",
		"size": "20px",
		"name": "Normal"
		},
		{
		"slug": "large",
		"size": "24px",
		"name": "Large"
		},
		{
		"slug": "extra-large",
		"size": "40px",
		"name": "Extra large"
		},
		{
		"slug": "huge",
		"size": "96px",
		"name": "Huge"
		}
            ]

Line height

The global styles equivalent of add_theme_support( 'custom-line-height' );.
Enable custom line heights by adding:

"customLineHeight": true

Padding

Inside Settings > Defaults, enable support for custom padding for cover and group blocks:

"spacing": {
	"customPadding": true,
	"units": [ "px", "em", "rem", "vh", "vw" ]
}

Layout

I have mentioned the layout section previously and it is one of the recent changes to global styles. In this setting developers defines the width of the content, and the width of blocks that has the wide align setting enabled.

"layout": {
	"contentSize": "840px",
	"wideSize": "1100px"
}
View the complete code for the settings section
{
	"settings": {
		"defaults": {
			"color": {
				"palette": [
					{
						"slug": "black",
						"color": "#000000",
						"name": "Black"
					},
					{
						"slug": "white",
						"color": "#FFFFFF",
						"name": "White"
					},
					{
						"slug": "dark-grey",
						"color": "#121212",
						"name": "Dark grey"
					},
					{
						"slug": "light-grey",
						"color": "#383838",
						"name": "Light grey"
					},
					{
						"slug": "cyan",
						"color": "#00838f",
						"name": "Cyan"
					},
					{
						"slug": "light-cyan",
						"color": "#4fb3bf",
						"name": "Light cyan"
					}
				],
				"gradients": [
					{
						"slug": "light-cyan-to-white",
						"gradient": "linear-gradient(135deg, var(--wp--preset--color--light-cyan), var(--wp--preset--color--white))",
						"name": "Light cyan to white"
					}
				]
			},
			"typography": {
				"fontFamilies": [
					{
						"fontFamily": "-apple-system,BlinkMacSystemFont,\"Segoe UI\",Roboto,Oxygen-Sans,Ubuntu,Cantarell,\"Helvetica Neue\",sans-serif",
						"slug": "system-fonts",
						"name": "System Fonts"
					},
					{
						"fontFamily": "Geneva, Tahoma, Verdana, sans-serif",
						"slug": "geneva-verdana"
					},
					{
						"fontFamily": "Cambria, Georgia, serif",
						"slug": "cambria-georgia"
					}
				],
				"fontSizes": [
					{
						"slug": "extra-small",
						"size": "16px",
						"name": "Extra small"
					},
					{
						"slug": "small",
						"size": "18px",
						"name": "Small"
					},
					{
						"slug": "normal",
						"size": "20px",
						"name": "Normal"
					},
					{
						"slug": "large",
						"size": "24px",
						"name": "Large"
					},
					{
						"slug": "extra-large",
						"size": "40px",
						"name": "Extra large"
					},
					{
						"slug": "huge",
						"size": "96px",
						"name": "Huge"
					}
				],
				"customFontWeight": true
			},
			"custom": {
				"spacing": "14px"
			},
                        "layout": {
	                       "contentSize": "840px",
	                       "wideSize": "1100px"
                        }
		}
	}
}
View the CSS output
:root {
	--wp--preset--color--black: #000000;
	--wp--preset--color--white: #FFFFFF;
	--wp--preset--color--dark-grey: #121212;
	--wp--preset--color--light-grey: #383838;
	--wp--preset--color--cyan: #00838f;
	--wp--preset--color--light-cyan: #4fb3bf;
	--wp--preset--gradient--light-cyan-to-white: linear-gradient(135deg, var(--wp--preset--color--light-cyan), var(--wp--preset--color--white));
	--wp--preset--font-size--extra-small: 16px;
	--wp--preset--font-size--small: 18px;
	--wp--preset--font-size--normal: 20px;
	--wp--preset--font-size--large: 24px;
	--wp--preset--font-size--extra-large: 40px;
	--wp--preset--font-size--huge: 96px;
	--wp--preset--font-family--system-fonts: -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen-Sans,Ubuntu,Cantarell,"Helvetica Neue",sans-serif;
	--wp--preset--font-family--geneva-verdana: Geneva, Tahoma, Verdana, sans-serif;
	--wp--preset--font-family--cambria-georgia: Cambria, Georgia, serif;
	--wp--custom--spacing: 14px;
}
:root {
	--wp--style--color--link: var(--wp--preset--color--light-cyan);
	background-color: var(--wp--preset--color--dark-grey);
	color: var(--wp--preset--color--white);
	font-family: var(--wp--preset--font-family--system-fonts);
	font-size: var(--wp--preset--font-size--normal);
	line-height: 1.7;
}
.has-black-color {
	color: #000000;
}
.has-black-background-color {
	background-color: #000000;
}
.has-white-color {
	color: #FFFFFF;
}
.has-white-background-color {
	background-color: #FFFFFF;
}
.has-dark-grey-color {
	color: #121212;
}
.has-dark-grey-background-color {
	background-color: #121212;
}
.has-light-grey-color {
	color: #383838;
}
.has-light-grey-background-color {
	background-color: #383838;
}
.has-cyan-color {
	color: #00838f;
}
.has-cyan-background-color {
	background-color: #00838f;
}
.has-light-cyan-color {
	color: #4fb3bf;
}
.has-light-cyan-background-color {
	background-color: #4fb3bf;
}
.has-light-cyan-to-white-gradient-background {
	background: linear-gradient(135deg, var(--wp--preset--color--light-cyan), var(--wp--preset--color--white));
}
.has-extra-small-font-size {
	font-size: 16px;
}
.has-small-font-size {
	font-size: 18px;
}
.has-normal-font-size {
	font-size: 20px;
}
.has-large-font-size {
	font-size: 24px;
}
.has-extra-large-font-size {
	font-size: 40px;
}
.has-huge-font-size {
	font-size: 96px;
}

Styling the website with root styles

Now that we have created some presets, we can add styles to the website. At the root level, below settings, add the styles section and the root sub section:

The presets are defined in the settings, but the code in the example is truncated.

{
	"settings": { ... },
	"styles": {
		"root": {
		}
	}
}

Set the body background color to a pleasant dark grey using the preset
--wp--preset--color--dark-grey. Set the text color to white, and the link color to light cyan:

{
	"settings": { ... },
	"styles": {
		"root": {
			"color": {
				"background": "var(--wp--preset--color--dark-grey)",
				"text": "var(--wp--preset--color--white)",
				"link": "var(--wp--preset--color--light-cyan)"
			}
		}
	}
}

For the fonts I am selecting a default font size of 20px, which has the preset slug of “normal”, and the system fonts:

{
	"settings": { ... },
	"styles": {
		"root": {
			"color": {
				"background": "var(--wp--preset--color--dark-grey)",
				"text": "var(--wp--preset--color--white)",
				"link": "var(--wp--preset--color--light-cyan)"
			},
			"typography": {
				"fontSize": "var(--wp--preset--font-size--normal)",
				"fontFamily": "var(--wp--preset--font-family--system-fonts)",
				"lineHeight": "1.7"
			}
		}
	}
}

And the resulting CSS output is:

:root {
	--wp--style--color--link: var(--wp--preset--color--light-cyan);
	background-color: var(--wp--preset--color--dark-grey);
	color: var(--wp--preset--color--white);
	font-family: var(--wp--preset--font-family--system-fonts);
	font-size: var(--wp--preset--font-size--normal);
	line-height: 1.7;
}

Assign content to the template part areas

Finally, add a new section called templateParts.
The theme that we created in the previous lesson has two template parts, header and footer.
Assign the header.html template part file to the header area, and footer.html to the footer area:

"templateParts": [
	{
		"name": "header",
		"area": "header"
	},
	{
		"name": "footer",
		"area": "footer"
	}
]

Preview

With the styles added, preview the theme on the front to see the result.

A screenshot of the front of the website with styles applied, displaying wide and full width columns blocks.

Download the example theme for this lesson from GitHub.