Author: Laurel Fulford

Web designer, front-end developer, coffee lover, Theme Wrangler at Automattic.

Styling Themes for Gutenberg

What we learned by developing three themes with Gutenberg in mind.

At the Automattic Theme Team meetup in December, we focused on several Gutenberg-related projects. The first one we’re sharing is a set of Gutenberg-friendly themes based on Underscores.

The project’s goal was to help us think about our themes differently, dig into adding theme support for Gutenberg, and as a byproduct, do some testing of Gutenberg itself.

Six team members participated in this project, and it resulted in three themes which are still in progress, and currently available on GitHub.

What is Gutenberg?

Gutenberg is the new block-based content editor currently being developed in GitHub for WordPress 5.0. Until it’s merged into core, it’s available as a plugin.

It’s really going to change the WordPress publishing experience! From the WordPress.org Gutenberg page:

The Gutenberg editor uses blocks to create all types of content, replacing a half-dozen inconsistent ways of customizing WordPress, bringing it in line with modern coding standards, and aligning with open web initiatives. These content blocks transform how users, developers, and hosts interact with WordPress to make building rich web content easier and more intuitive, democratizing publishing — and work — for everyone, regardless of technical ability.

The Themes

The three themes we developed during the meetup are called Fashion Blog, Handicraft, and Ohana. We decided to try to make these themes CSS-only to help keep the focus on Gutenberg itself and let us build on the recent work the team’s been doing with Style Packs. This turned out to be an ambitious restriction — a little more on that later — but it made for an interesting design challenge.

Fashion Blog, Handicraft and Ohana are currently available on GitHub; you can learn more about each theme there and check out exactly how they were set up. The themes are still works in progress and have some rough edges. The end goal is to get them ready for WordPress.com.

The Process

Over the course of a few days, we researched and decided on an audience for each theme, designed and built them, and added Gutenberg support.

We opted to use a one-column design for all three themes, to best accommodate the “full” and “wide” block alignment options in Gutenberg.

Though it can vary from theme to theme, this is how Handicraft styles Gutenberg’s wide alignment (on the left) and Fashion Blog styles the full alignment (on the right).

Adding Gutenberg Support

You don’t actually have to do anything to use Gutenberg with a theme, but by declaring theme support you can add two optional features: the “wide” alignments (full width and wide width), and custom colors for the block-color palettes.

The following example, when included in the setup function in functions.php, will add both:

/**
* Add support for Gutenberg.
*
* @link https://wordpress.org/gutenberg/handbook/reference/theme-support/
*/
add_theme_support( 'gutenberg', array(

    // Theme supports wide images, galleries and videos.
    'wide-images' => true,

    // Make specific theme colors available in the editor.
    'colors' => array(
        '#ffffff',
        '#000000',
        '#cccccc',
    ),

) );

Whether or not you include custom colors in your theme, Gutenberg will always include a color picker with the palette, for further customization.

Gutenberg’s default color palette, shown while editing the Button block.

Styling the Themes

In general, the default blocks don’t need styling — Gutenberg already includes styles that match each block’s functionality. For example, the Gallery block already has the styles needed to split your galleries into different columns, and the Cover Image block will place the text and image added on top of each other, without the theme’s help.

If any of the styles don’t fully suit your theme’s design, you can adjust them as needed. One thing we noticed while we were developing these themes was Gutenberg’s distinct pill-shaped button style, which might not work with every theme.

On the flip side, themes are fully responsible for figuring out how the “wide” and “full” alignment styles should be handled, if they support them. This makes sense, since support is optional, and exactly how they should look can vary depending on a theme’s individual style.

At the time of writing, the Gutenberg theme styles these two alignments by setting max-widths for specific HTML elements, with a wider max width when either the .widealign or .fullalign classes are used.

In our three themes, we approached it a bit differently, setting a max-width for the page content, and instead using CSS to stretch those wider elements outside of it. We used vw and stretched the wider elements based on the screen size:

@media (min-width: 750px) {

    .alignfull {
        margin-left: calc(50% - 50vw);
        margin-right: calc(50% - 50vw);
        width: auto;
        max-width: 1000%;
    }

    .alignwide {
        margin-left: calc(25% - 25vw);
        margin-right: calc(25% - 25vw);
        width: auto;
        max-width: 1000%;
    }

}

This approach works, but because vw includes the width of the vertical scrollbar as part of the whole screen width, you can get a little horizontal scrolling. One fix is adding overflow: hidden to one of the page-width elements further up the HTML tree.

If you didn’t want these elements’ widths to be based on screen size, you could also set a specific max-width. There’s no one “right” way to approach these styles, and I’m sure more and more examples will come out of the woodwork as more themes add styles for Gutenberg. For example, Justin Tadlock has shared his method using different calc values, and Joen Asmussen has blogged about his approach of applying max-widths to all child elements that aren’t wide or full width.

In our themes, we also kept any block-specific styles separate in their own stylesheet.

Adding Editor Styles

To make the editing experience more what-you-see-is-what-you-get, you can add Gutenberg editor styles using enqueue_block_editor_assets. It’s similar to how editor styles can be enqueued for the current TinyMCE editor. This makes sure what a user sees when building their pages best matches how the content will actually look with your theme when published.

Here’s an example of enqueuing an editor-specific stylesheet:

/**
* Enqueue editor styles for Gutenberg
*/

function theme_slug_editor_styles() {
    wp_enqueue_style( 'theme-slug-editor-style', get_template_directory_uri() . '/assets/stylesheets/editor-style.css' );
}
add_action( 'enqueue_block_editor_assets', 'theme_slug_editor_styles' );

Like with the TinyMCE editor, you can also include fonts. So for example, if your theme is enqueuing fonts from Google, you can include them in the Gutenberg editor, too:

/**
* Enqueue editor styles for Gutenberg
*/

function theme_slug_editor_styles() {
    wp_enqueue_style( 'theme-slug-editor-style', get_template_directory_uri() . '/assets/stylesheets/editor-style.css' );
    wp_enqueue_style( 'theme-slug-fonts', theme_slug_fonts_url(), array(), null );
}
add_action( 'enqueue_block_editor_assets', 'theme_slug_editor_styles' );

Unlike the TinyMCE editor, Gutenberg’s editor styles include the post title:

An example of Ohana’s editor styles.

The editor styles need to be pretty specific to make sure they’re not applied to other elements of the page outside of the editor — Rich Tabor has a good post here about his experience with this behavior. Gutenberg includes specific classes around different elements in the editor, so you can prefix selectors more generally with the class .editor-post-visual-editor, or use more specific classes to target individual blocks — for example, styles for .editor-block-list__block[data-type="core/heading"] h1 would only be applied to h1s inside of a Heading block.

What We Learned

Overall, this project was a great way to ramp up quickly on some Gutenberg-theming basics, and get our feet wet. Some specific things we learned from this process include:

  • The Gutenberg default block styles are numerous and can be a bit opinionated. This is good, in that you can rely on Gutenberg to do a lot of the heavy lifting, but there are some styles that would need to be updated to match individual theme styles.
  • It can be tricky to set up the wide and full-width styles; as more themes add styles for Gutenberg, it’ll be interesting to see all the different ways themes handle this.
  • Setting up the block styles for the back-end editing experience was more involved than any of us had anticipated. It’s very much like adding editor styles to the current TinyMCE editor, but some Gutenberg blocks have very specific classes that needed to be overridden.

We also learned a couple non-Gutenberg related things:

  • From a project-planning perspective, we could have spent more time narrowing down the kinds of themes we wanted to build — and the actual designs — prior to the meetup. This would have left more time to focus on the Gutenberg part of each theme.
  • In the end, it wasn’t possible to complete the project without making edits to these themes in addition to CSS. On top of the PHP changes needed to support Gutenberg’s optional features, we needed to make edits for common WordPress.com-functionality — like adding social menus, and more Content Options support — and for the designs themselves, like enqueuing Google fonts.

Next Steps

Our goal is to get these themes launched on WordPress.com. To get there, they still need some WordPress.com-specific functionality, like the annotations for WordPress.com’s custom fonts and colors, WooCommerce support, and styles for WordPress.com widgets.

We hope that sharing this process is helpful for your own Gutenberg journey as themers. We’d love to hear about your adventures.

 

Balancing Options vs. Overload

On WordPress.com, one thing we’ve been focusing on is making themes that just work. It’s a bit of a balancing act; it’s very tempting to allow customers to control every aspect of their theme, because it seems like the simplest way to give them what they want.

That idea may sound great to customers, but having panels of options in the Customizer and an armload of documentation to figure them out is daunting. You can change things, but you’re also faced with making dozens of small, similar decisions about various aspects of your site, and deciphering the purpose of various controls.

It is true that in WordPress themes, some options are necessary. When designing and building a theme, it’s important to distinguish what options fit the actual intent of the design, and what options are being added for the sake of adding them.

You can often figure out which is which by tracking common pain points.

One way to do this is through support requests. On WordPress.com, we have a dedicated, talented team of Happiness Engineers who interact with customers every day. As Gary Murray wrote in a recent post, support teams are an important link between our work and our customers, and an invaluable wealth of information.

For themes, the support requests often involve how to set up a theme or use different options (which is why making themes that just work from the get-go is important). But other requests have to do with customizing a theme in specific ways. Some are unique to a customer’s specific goals; others come up again and again from different customers, either in the same theme or across several different themes.

In the Ixion theme, we recently added an option to control the opacity of the overlay used on front page photos, after several customers asked about changing or removing it.

Ixion with its two new options.

One purpose of the dark overlay is to ensure the text on top is legible against the photo. But if you’re starting with a photo that’s already pretty dark, the overlay isn’t needed and can make it hard to distinguish details in the photo. We were able to add this option while maintaining the original appearance, so customers who weren’t troubled by the opacity didn’t know the change happened.

Another feature that came from frequent customer requests was Content Options. A brainchild of Thomas Guillot, Content Options are a way for customers to make small visual changes on their site, like hiding the date, author name, or featured images. Rather than adding the options to individual themes, it’s a feature available in Jetpack and WordPress.com that themes can support. That way, the options are available in several themes and implemented exactly the same way.

Both additions were guided by the goal of keeping things simple, balanced with following actual customer requests.

When looking at adding options to a theme, there are a few things that can help to keep things simpler:

First, aim to make a theme that just works on activation. If the design’s not possible without multiple options, rethink it. If options are necessary to get the theme to work well with different kinds of content, find a way to make the theme more forgiving instead. Make the theme do as much work as it can by itself.

In a similar vein, make the theme make the decision. You could allow customers to switch a sidebar position, or make the header sticky, but unless it’s a very common request it’s best left out. Chances are, one option looks best and makes the most sense for the theme you’re building — use that one.

Use existing WordPress functionality rather than custom options. I don’t mean stretch the options beyond their original intent, just don’t reinvent the wheel. For example, look to use the custom header image or featured images in the theme before adding another image upload option to the Customizer.

When adding options, rethink your approach to customization. Alright, you’ve discovered your customers can’t live without being able to change their header’s layout. Rather than having separate controls to move each individual item — logo, header image, menu, social links, site title — is there another way to approach this? Aim for simpler, more opinionated controls to limit the decisions customers have to make. Basically, make your options smart.

Last but never least, user test, talk to your customers, and work directly with them when you can. They’ll help guide you to that point where your themes can help them feel empowered, but not overwhelmed.

Photo by Patryk Grądys on Unsplash.