Customizing Gutenberg blocks with block styles

Block styles are a simple way to get started with Gutenberg development: With a few lines of CSS, you can build something that feels like a whole new custom block.

A few years ago, Matt Mullenweg urged us all to “Learn JavaScript Deeply.” Becoming more familiar and comfortable with JavaScript is increasingly important for those of us who build the web. In the world of WordPress, projects like Gutenberg have begun taking a major step into a JavaScript-powered future.

For designers and developers who are still getting used to these new languages and workflows, creating and customizing Gutenberg blocks can be somewhat intimidating. There are excellent toolkits like Create GutenBlock to help you get started, but even using those, building a block requires quite a bit of JavaScript familiarity. You also have to make sure you’ve got the right version of Node, learn some terminal commands, install some dependencies, etc. There’s quite a bit of up-front work necessary before you can jump in and start actually building something.

Despite these hurdles, we’ve seen an inspiring number of new block plugins surface lately: CoBlocks, and Atomic Blocks are great examples. They each add a variety of rich blocks, and truly enhance the site-building experience.

There’s a much simpler way to start customizing Gutenberg blocks though, and it’s something we haven’t seen utilized much at this point: block styles. They take only a few minutes to pick up, and mostly just require you to know CSS.

You’ve likely noticed block styles while using Gutenberg. The Quote, Pullquote, Separator, Table, and Button blocks ship with some alternate styles by default.

Block styles are an excellent but relatively unused area of Gutenberg customization. They’re a simple way to get started with Gutenberg development: With a few lines of CSS, you can build something that feels like a whole new custom block. Also, since they’re reusable across multiple sites, block styles help pave the way for a more flexible system of components that make up a site’s theme.

Technically, block styles are very simple. They’re composed of two things:

  • A few lines of JavaScript to declare the block variation and give it a custom class name.
  • CSS styles to fine-tune the appearance.

That’s it. A block style is a custom block class, with some styles applied.

Implementation

A block style can be implemented anywhere you can enqueue a little JavaScript and some CSS. For this example, I’m going to focus on implementing a custom block style via a plugin. One of the benefits of using a plugin is that it’s not tied to the user’s theme. This allows your block style to be used across any site, running any theme — as if you had built an entirely new custom block.

The first step to implementing block styles is to create a few files:

  • index.php to set up the plugin and enqueue the other files
  • blocks.js to declare the block style
  • style.css to house the actual styles

index.php

By default, index.php just needs to initialize the plugin with a DocBloc, and enqueue the JavaScript and CSS files:

<?php
/**
* Plugin Name: Block Styles
*/

/**
* Enqueue JavaScript
*/
function block_styles_enqueue_javascript() {
wp_enqueue_script( 'block-styles-script',
plugins_url( 'block.js', FILE ),
array( 'wp-blocks')
);
}
add_action( 'enqueue_block_editor_assets', 'block_styles_enqueue_javascript' );

/**
* Enqueue Stylesheet
*/
function block_styles_enqueue_stylesheet() {
wp_enqueue_style( 'block-styles-stylesheet',
plugins_url( 'style.css', FILE )
);
}
add_action( 'enqueue_block_assets', 'block_styles_enqueue_stylesheet' );

block.js

The JavaScript file is where you’ll let Gutenberg know you’re declaring a new Block Style. That requires a few lines of code:

wp.blocks.registerBlockStyle( 'core/paragraph', {
name: 'blue-paragraph',
label: 'Blue Paragraph'
} );

The first line tells Gutenberg which existing block to start with. In this example, we are going to create a block style for the Paragraph block. Any existing block can inherit a block style*, so if you were to target a different block, you’d change core/paragraph to the name of a different block. Technically, these names are found in the Gutenberg block source code, but they’re usually easily guessable. For example: core/cover, core/separator, etc.

The name: field on the second line here creates the custom class that’ll be assigned to the block. In this case, I’m calling it a blue-paragraph, but it can be anything you’d like. Since this will be used for a CSS class, be sure not to use any spaces.

The final field corresponds to the label for your block style. This will be shown in the interface when someone opens the “Block Styles” panel.

style.css

The last file is pretty straightforward. Use the custom class name you created in block.js (along with a is-style- prefix), and insert your styles inside:

.is-style-blue-paragraph {
// Custom CSS styles go here.
}

Your styles here will build off of the default block styles, and will be loaded in before a theme’s editor styles. So be sure to keep your selectors specific enough to override those potentially competing styles.

Block Styles Plugin Boilerplate

To help you get started, I’ve created a GitHub repository that you can clone and use to get started. It contains the three files detailed above, along with some light documentation.

https://github.com/Automattic/gutenberg-block-styles

Out of the box, the repository is a small plugin that adds a “Blue Paragraph” block style to the Paragraph block:

With a few small adjustments, it’s possible to change this into something drastically different. There’s another branch on that GitHub repository that includes a Music theme-style cover block variant:

I’ve included a third branch that adds a somewhat ridiculous animation to the text (or emoji) inside of a Cover block:

Both of these are accomplished by changing about a dozen lines of code in the repo. They took minutes to create, and work across any site that uses Gutenberg, regardless of the theme it’s using.

What will you create?

Block styles are ripe with possibility. I’d love to see a CSS Zen Garden-style plugin someday that showcases dozens of different ways to customize blocks through block styles.

In the meantime, have you built something cool using block styles? If so, I’d love to hear about it. Please share your explorations in the comments.


*Note: At the time of writing, blocks that accept InnerBlocks (like the Media & Text and Column blocks) have a bug which causes them to crash when custom styles are assigned. There’s an open issue on GitHub to address this.

A schema for Gutenberg blocks

At Jetpack we recently created a new Gutenberg block which displays “Related Posts”. This block is similar in content to the “Latest Posts” block in WordPress.org; it’s just a list of posts. The difference is the way the posts are displayed:

There are plans afoot to update the “Latest Posts” block, so that it contains an image and a post summary (see image below).

As these two blocks grow they seem to be converging on similar layouts, but with different content.

There are similar overlaps with other blocks. For example the layout of the WordPress.org gallery block could also be used to display a list of posts, as could the recently launched Tiled Gallery block. Evidently there are many layout possibilities for a list of posts!

The problem

As the number of Gutenberg blocks grows these overlaps become more obvious. As we start to build pages with Gutenberg it starts to become apparent that this is going to get very messy very quickly.

Essentially blocks have a content and a presentation element. Taking the example we began with, we can see overlap between many different types of content:

Lists of content

One type of content is a list of text, images and links. These come in many different forms, but they share the same structure:

  • Latest posts
  • List of posts in a category
  • List of post in a tag
  • Archive of posts by month/year etc
  • List of categories/tags
  • List featured posts
  • List of images
  • List of authors
  • List of [custom post type]

Similarly, all of the above types of content could be displayed in any of the following ways:

Layouts

Here are some examples of the different types of layout that this content could use:

The challenge is that each of these different types content can be displayed in each of these different layouts. If we wanted to create blocks for each of these combinations we’d end up with over a hundred different blocks. On the other hand we could build one single block which was so complex that it could display all these combinations within one block. Neither of these would be sensible solutions.

Can we use Block Style Variations?

Block Style Variations offer an API which allows us to modify the CSS for a block – they let us overlay a presentation layer on top of an existing block. This is ideal when modifying the way a block looks. However many of the layout variations I have examined above require more than just a different CSS, they need different markup and additional JavaScript.

Separating Content and Presentation

One solution to this problem could be to separate content from presentation in our blocks. What if we were able to define semantics for the content in our blocks, which could be interpreted by different layouts? This would mean users would first think about the content they wanted to show, and then all display options would be open to them.

A Shared Data Structure

The overlap between these blocks occurs because they all share the same data structure (an array of text, image and link). It would be possible to define a standard data structure that blocks can use. When blocks share a data structure, then it should be possible for them to share common layouts. This would mean a photo gallery display could be reused to display a list of posts, or a block that displays a list of recent posts could be reused to show a list of authors.

How Could this work?

“Block Transformations” are an existing mechanism which converts one block into another. At present every transformation has to be coded separately.

Could we re-imagine the way that transformations work, so that if blocks share a common data-structure, they can easily be transformed into each other, without writing custom transformation code?

Similarly, could we make changes to the way “Block Style Variations” work, so that they can apply a layout to our structured data?

Feedback

What do you think? Is this a problem? Are there other solutions I haven’t considered? Leave a comment!

Blocks, templates, and styles: architecture for a Gutenberg world

Exploring ideas about the evolution of layout and presentation in a post-Gutenberg world

What described below is an broad idea, some thoughts on one way the WordPress ecosystem might evolve in response to the new capabilities of Gutenberg. Huge thanks to Kjell Reigstad and David Kennedy for helping me think through these concepts!

Traditionally, themes have been the only authority when it came to the layout and presentation of a WordPress site. They provided the entire page structure, typography, the color scheme, the menu functionality, the responsive rules, and more. Themes generally had the full power to dictate if and how users could customize each of those elements. 

With the advent of Gutenberg, we’ve seen some of those responsibilities shift. Regardless of their theme, users can now add responsive column-based layouts to any page, assign custom colors to most of their content, and insert rich elements anywhere within a post or page. As a result, some of the responsibilities for the design of a site are blurred: The theme takes care of some aspects, while Gutenberg handles others. Much of that architecture is still to be defined as Gutenberg moves into Phase 2 and beyond. 

Gutenberg brings many opportunities to WordPress, but the biggest impact comes from the way it can enable a much clearer product architecture — one which enables modularity, consistency, and interoperability — and the positive impact that can have on the end user experience of WordPress. 
To that end, it can be helpful to think of layout and presentation not as the “Theme”, but as a set of interrelated pieces, each with their own set of responsibilities, working together to create a site.

Blocks

A block is a component that exists visually a page. It can be a “simple block”, like a paragraph or an embed; or it can be a “complex block”, which has a layout of multiple nested blocks, like a testimonials section. This distinction doesn’t necessarily matter to the user as there’s a unified insertion and discovery mechanism. Blocks can contain placeholder content that is neutral — in other words, they start as a “blank slate”, except for placeholder content that guides users as to how to add content to the block. 

A block can contain layout information, including media queries that define how the block behaves responsively in different viewports. A block could conceivably define styles that would override the ones provided by the template or the global styles, in order to create a unique presentation for a particular block.

Templates

While Gutenberg makes it easy to create a custom, complex page layout from scratch, the process of starting with a blank slate and designing a layout that looks good will likely still be daunting for many users. Giving users access to a collection of pre-built Gutenberg page templates would enable them to get started more quickly and simply tweak the template to their needs. 

A template would define a collection of blocks in a particular order and layout that make up an entire page. In addition, templates can contain “starter content” — editorial boilerplate text and media so that a user can simply tweak and replace rather than having to start from scratch. The concept of a template library would mean that there could be a core library of basic templates, in addition to non-core templates that can be developed by anyone and installed separately (similar to how blocks work). 

Styles

Styles would define the global aesthetics of the site, and would provide a central definition for typography, colors, spacing, icons, and more. Brent Jett has suggested some interesting ideas for how this might manifest on the user-facing side. Styles may also provide some global guidelines for layout, such as global settings for responsive behavior, etc. Layout that is specific to a page template or a block should be defined locally by that element, though.

Themes

Given all the new controls over layout that blocks and templates can provide, what does a theme mean in this new world? It seems that themes can become more lightweight. Perhaps a theme is simply a JSON wrapper that defines the components of that theme — identifying the blocks, templates, and styles that make up the theme. Rather than bundling all of the parts of the theme in a tightly coupled piece of software, the theme could simply be a high-level definition that identifies the modular dependencies (styles, templates, blocks) that need to be installed. When a theme is deactivated, a user could even have the option to keep the templates and blocks in their library for future use. This could allow for greater flexibility but also greater standardization, creating a consistent and modular framework for shaping how sites get built in the future.

We all know that themes will evolve, and this is just one early idea. As we move forward together, WordPress will surely benefit from the sharing of ideas and explorations around the future of themes. If you have a vision yourself, please share it! Feel free to use the comments below, your own blog, Twitter (use the tag #gutenideas), or wherever you can get the word out. 

Designing a Gutenberg-Powered Theme: Music

Kjell Reigstad walks through his experience designing a block-powered theme.

Last week, Allan Cole and I shared a new Gutenberg-powered theme called Music. In this follow up post, I’m going to take you through the design process for the theme. At its core, this felt a lot like a typical theme design process, but I did learn a lot about block-based design along the way. 

Blocks

When Allan and I decided to make this theme, we already had a homepage comp featuring a handful of blocks. That comp did a great job of setting the tone for the design aesthetic. To get things going, I decided to apply that aesthetic to the other default Gutenberg blocks. I worked through the Gutenberg Blocks Sketch document from my last post, updating styles as I went.

 

Working this way was great for a couple reasons. First, it helped me focus — I’d never designed a block-optimized theme before, and this kept my design explorations squarely on the blocks themselves. I thought,  “Gutenberg is all about blocks, right? I’ll design some blocks.”

Second, the Sketch file allowed me to see every single block style in one place. In effect, I was creating a sort of pattern library as I went. I thought this was pretty cool, and figured it’d come in handy later on when we began development.

As I got further through these block designs, I realized the need to see all of these individual blocks in context; I’d design a wide-width cover image block, but I had no idea how it’d look in use. So I began dragging blocks around and stacking them up to get a sense of how they’d feel together.

Testing-Ground.png

This helped a little bit, but still wasn’t enough. At this point, I realized something that should’ve been obvious: blocks are not a theme. They’re just part of a theme. By designing blocks first, I’d been avoiding the big picture. Users will never see blocks all by themselves — they’ll exist within full pages. I needed to design more pages. 

Pages

My initial homepage design comp introduced a rough idea of a header and an off-centered text column. I began by duplicating that initial page and clearing out all the blocks on it, then pulled together some sample content. Looking at the project through the lens of my imagined client (the band Superserious), I was able to think through examples of blocks and block combinations that might exist on a real site: the columns block to display album information, the table block to display tour dates. This felt much more effective than randomly placing blocks on a page.

Around this time, I hit my stride, design-wise. I’d lay out a page using my existing blocks and the sample content. Then I’d iterate and experiment with everything on that page. Once things looked right, I’d migrate any new block tweaks back to the global symbols and start fresh on the next page. After a little while, I ended up with a solid set of sample pages.

 

Backing up and thinking about page design helped me shift focus to other, more traditional components that needed to be designed too: archive pages, page footers, post headers, etc. Designing these wasn’t all that different than it would’ve been without Gutenberg. In a way, we’ve all been designing with blocks all along — we just hadn’t called them blocks. Take a look at this entry summary:

Entry-Summary.png

If I’d designed this theme pre-Gutenberg, I still would’ve designed each one of those pieces — they’re all fairly standard parts of a theme. But thanks to Gutenberg, each piece is part of a clear pattern library, to be reused throughout the design by me and by the user. That’s pretty cool.

I’d gone into this project thinking I’d spend most of my time styling individual blocks, but I ended up splitting my time pretty evenly between designing block variations and overall page elements. In that sense, this wasn’t as drastically different from a traditional theme design as I’d anticipated.

Prototypes

I’d been getting ongoing feedback from Allan throughout the process above, but once we were happy with the page designs above, we gathered  with the rest of the Theme team to get broader design feedback. To help with that process, I pulled all my comps together into a prototype. This took just a few minutes to do, and really helped others get a sense of how the theme will work in practice.

I created two separate prototypes with Invision: one for desktop and one for mobile. If my transition from block design to full-page design was about looking at the bigger picture, these prototypes stepped back still further: they showed us the context around that big picture. We were all able to see the designs on-device and test some basic interactions. 

The team’s feedback was (as usual) very helpful — we made some subtle revisions to text contrast, adjusted a number of margins, and kicked off a lot of iteration on the mobile menu treatment.

Development

Allan had been focused on the build from the beginning, and had the majority of the framework in place at this point. After our design feedback session, I jumped into the code too.  

From the development angle, we’d already determined a few things in the design that we couldn’t do, or that would take too much effort. For instance, in my initial design comp I’d had a series of backgrounds run down the page. Gutenberg doesn’t have a method for doing something like that today; despite my wishful design thinking, there’s no method for layering a background behind a group of blocks. We could’ve accomplished it through customizer settings, but we shelved the idea in favor of keeping things simple. We also abandoned a bunch of the play buttons I’d originally included, since those’ll require some custom blocks (more on that later). 

Once I jumped into the code, my main revelation was that there were way more block options than I’d originally anticipated. A number of blocks had options I’d never noticed before. I hadn’t realized that paragraph blocks could be set to full width, or that cover image blocks could be floated left or right.

In addition, I realized some design decisions I’d made were actually supposed to be user-editable: I’d overlooked the fact that users can edit the text alignment and image opacity for the cover image block. This required more design exploration, but it guided us towards a much more customizable theme — definitely a win in the end.

Beyond those updates, the majority of the design-oriented development work involved minor fixes and adjustments — polishing up the CSS to make sure it aligned with the intent of the original design. 

Next steps

Now that we’ve had our initial release, Allan and I plan to build a separate plugin with complementary music-centric blocks, like a tour dates block and a mashup of a cover image and an audio player. We’ll hope to showcase those at some point in the future.

In the meantime, keep an eye out for the next post in the series: Allan’s experience from a development perspective.

 

Music: A Gutenberg-Powered Theme

Announcing the Music theme: an exploration of how Gutenberg can transform theme design and development.

A couple months ago, I created a Sketch document to assist with the design of block-driven themes. I posted about that here on Themeshaper, and provided a couple short examples of how it could be used in a theme design workflow.

Since then, Allan Cole and I have been working to make one of those examples — a site for an imagined band named Superserious — into a working example of a Gutenberg-powered WordPress theme. We named the theme “Music.”

Allan and I set out to experiment, learn, and create a resource for the community. We’ve documented our experience designing and building this theme, and will be publishing our notes in a series of posts here on Themeshaper.

To kick things off, we’re releasing Music on GitHub today. We’d love for you to give it a spin, tinker with it, and explore how it works with Gutenberg. Here are a few things to look out for:


Design

Our design goal for the theme has been to show that it’s possible (and encouraged!) to make a Gutenberg theme that doesn’t necessarily look like Gutenberg. We wanted to create something bold and a little experimental; a theme with somewhat aggressive, non-standard styles.

Gutenberg gives users unprecedented control over their site design, opening the door for variety and experimentation. Our favorite example of this is our cover image blocks. They look great out of the gate, but users can adjust the image, alignment, and color to achieve a wide range of looks:

cover-images.png

 


Development

You’ll be happy to hear that the overall theme development process wasn’t all that different with Gutenberg. Common patterns like headers, footers, and loops work just as you’d expect in a Gutenberg-powered theme.

In many areas, Gutenberg makes things easier for both users and developers. For instance, full-width header images used to require a custom-built customizer or theme option solution, but now they’re essentially built in. This was important to keep in mind while building the theme, and was a very positive change for development.

Creating stylesheets for blocks was pretty straightforward. Expanding on the built-in stylesheets in _s,  we added a blocks.scss file to the SASS directory and placed all of our block-specific styles and overrides there. This kept everything nice and organized and is likely to appear in _s in the future.

Since Gutenberg is output by the_content(), we learned to take special care with any wrapper divs that might clip or obstruct the expected behavior of Gutenberg blocks. We’ll talk more about that in a follow up post.



Block Styles

We’re truly excited about the custom editor styles that ship with Music. These styles are a breakthrough: they give users a much clearer sense of what their visitors will see on the front end.

Best of all (for theme developers at least), the editor styles were a breeze to integrate! We built all of these in over the course of just a few hours.



Like most of the work we do, the Music theme is open source. You can find it on GitHub:

https://github.com/automattic/musictheme/

If you’d just like to see the front end, feel free to click around our demo site here:

https://musictheme.mystagingwebsite.com/

In many ways, designing and building this theme was similar to the way we’ve made themes in the past — but we did carve out a few new practices along the way. Allan and I will be sharing them with you in upcoming posts. In the meantime, we encourage you to download, install, and experiment with Music yourself!

 

Read part two of this series: Designing a Gutenberg-Powered Theme: Music

Designing Themes with Gutenberg Blocks and Sketch

Follow Kjell Reigstad’s process as he explores designing a block-driven theme with Sketch, for the Gutenberg era.

There’s been an exciting discussion happening around the changes that Gutenberg will bring to themes. At Automattic, we’ve begun to prepare for Gutenberg by reevaluating our theme design and development processes.

As part of that work, I did some thinking about how I might start designing a block-driven theme today and what sorts of resources I’d want to have. The most important thing that came to mind was a way to access and customize all of the core Gutenberg blocks with a few clicks. This would allow me to quickly test and iterate on block design without having to dig into code. I do a good deal of my design work in Sketch, so I began to search for a way to make this possible there.

Luckily, there are already a few Gutenberg-related Sketch files in the wild. The Gutenberg Contributors page on GitHub and the Design Principles & Vision page on WordPress.org are great places to start. These are mostly aimed at the Gutenberg editing interface, however, and didn’t quite accomplish what I was looking for, so I ended up building a new file instead:

Gutenberg-Sketch-File.jpg

This new Sketch file contains symbols for all of the default Gutenberg blocks (with the exception of all the embeds, since those aren’t very customizable). With this set of symbols, it’s possible to quickly build a layout composed entirely of Gutenberg blocks using Sketch:

It’s actually pretty fun to use! In a way, it’s Gutenberg — but for Sketch. 😄
From here, it’s easy to start customizing styles:

I took this method for a spin and tried to mock up a theme for an imagined restaurant. To get started, I built out the page structure using default Gutenberg blocks:

From there, I started doing some light customizing. I cut myself off after a while, but the end result looked fairly decent:

I find this pretty cool. It’s an example of what a block-driven theme might look like with just a little bit of CSS customization.

From here, I could easily keep going and put together a complete, modular design system for this theme by customizing the rest of the Gutenberg blocks. I could view the blocks all at once on the Symbols page, and quickly build out a wide variety of layout options to make sure my styles held up to intense layout customization.


I almost ended there, but I decided to confront a lingering concern I’ve had about Gutenberg: I’ve feared that if we lean too much on Gutenberg for theme layout, we’ll end up with lots of very similar, “blocky” themes. The restaurant site I designed above looks fine, but it’s also clearly made of blocks. I wondered if it’d be possible to create something more experimental using this same Sketch file as a base.

So I took another stab at a pretend site design (this time for a band named Superserious), and forced myself to break out of the blocks a little more. Again, I began with a pure-Gutenberg layout:

But this time, I was much more aggressive in my customization and aimed for a more tailored mobile experience with bold typography:

This was a fun exercise, and it helped allay my fears a bit. That first Cover Image has all the usual pieces, but they’re styled in a very opinionated way. The rest of the blocks are fairly standard, but they still stand out because they exist within a heavily stylized, off-balance frame. The overall effect is drastically different from the theme in the previous exercise.


This process was very useful for me, and I’d love to see if it’s useful for the rest of the community as well. You can download and contribute to the Sketch files here:

https://github.com/Automattic/gutenberg-themes-sketch

The repository includes a basic Sketch file with just the symbols, plus all the text hierarchy styles (H1, H2, etc). I also created a library file in case that’s preferable for anyone. We hope to update these files periodically, and would love to hear feedback from others who use them.

In the meantime, we’ll keep experimenting with ways to design themes in this new Gutenberg-based future.

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.

 

Lodestar Launches

Lodestar is now launched on WordPress.org. Designed by Mel Choyce and developed by Laurel Fulford, Lodestar is a precursor to Twenty Seventeen, and you’ll see echoes of that default theme throughout, starting with its multi-panel front-page layout. A filterable portfolio section is available through Jetpack, along with a stylish testimonials page.

Mel shares a bit about Lodestar’s origins:

Lodestar started as a restaurant theme named “Porterhouse.” I designed it before we had a good solution for multi-panel homepages, so it was tabled. Once we had a couple solid multi-panel homepage themes, I redesigned it as a more generic business theme.

Explore the Lodestar demo, study the setup guide, or download and give it a try.

Lodestar screensnshot

Studying TextBook

We’re pleased to announce the launch of TextBook in the WordPress.org directory. Created by Allan Cole, TextBook helps schools, colleges, and other non-profit organizations to distribute and archive information in an easy way. Supported by Jetpack, it includes a Featured Content area for highlighting key posts or pages, a social menu, and Testimonials, ideal for showcasing quotes from alumni, staff, and students.

When designing TextBook, Allan researched some of the challenges facing schools when creating their sites, and noticed that many educational sites had little access to good photography. TextBook minimizes that problem:

One of the main goals for TextBook is how it’s designed to look great when you only have a limited amount of content. Even if images are smaller, or low quality, it doesn’t take away from the design.

Check out the TextBook demo, peek at the setup guide, or download and take it for a spin.

TextBook screenshot

The Promise of Gutenberg: Themes as More Design, Less Baggage

Gutenberg promises the vision you have takes shape in the editor, instead of something you can’t see. Why’s that so powerful?

It happened again.

I sat with a potential WordPress themer, who wanted to know how to get started the right way with theme development. He’s a user experience professional by day, looking to up his coding skills.

He pointed to the WordPress editor, and said something like, “I understand HTML and CSS, but I’m not sure how to make something beyond putting it in there.”

We’ve all been there. Having that vision of what you want your site to look like, and not knowing how to get there. Gutenberg promises the vision you have takes shape in the editor, instead of some PHP file or a special plugin that isn’t truly native to WordPress. That’s powerful! It shifts much of the customization control from the themer to the person using the theme.

Today, if you’re trying to get into WordPress development, you might start by tweaking an existing theme. Then making a child theme. Then diving into a custom theme. My user-experience professional friend did just that. He’s already customized a theme and made a child theme. But the whole world of specialized WordPress theme knowledge can intimidate even professional web workers. Imagine how it feels to new users of WordPress who have never built a website before?

But with Gutenberg, people – professionals and beginners alike – can begin building what they want. Now, Gutenberg will no doubt need its own specialized knowledge. But at its heart, it will transform what a theme means to WordPress. They can become more about pure design, powered by the simplicity of CSS.

You might be saying, “But you can already use CSS now to change a theme’s design.” That’s true, but much of a theme’s structure gets determined by and locked away in template files. Hard to change unless you start learning how to “theme.” But with much of that structure and markup becoming blocks that can be added to a theme, it becomes easier for people who aren’t themers to see different possibilities.

Say goodbye to lots of custom widgets and theme options. Oh, and to limiting page templates. The future of WordPress themes can become more about empowering users to work on their vision instead of always having to learn how to “theme.” It starts in the editor and not with the theme.

Photo by Dmitri Popov.