Gutenberg Theme Development – Tips for Success

The new NexRep website is built completely with the Gutenberg block editor.

We’ve built dozens of WordPress sites just like NexRep that rely on the block editor for rich, engaging landing pages that are easily maintained by non-technical editors with a consistent style guide.

These are my tips for success with Gutenberg theme development.

Start with Atomic Design

If you are working with a designer, make sure they are familiar with the block editor and use an atomic design approach.

We start with the atoms of our style guide – headings, paragraph, link, and button. These are then built into molecules, like a Post Summary (post title, category, excerpt). These are then built into organisms, like a Post Listing (section header, 3 column grid of posts).

The launch of Gutenberg was the final push I needed to no longer work with client-provided designs. Every website I build is now designed by my two design partners, Duane Smith and Andrew Pautler, who have a deep understanding of the Gutenberg block editor.

An atomic design approach empowers content creators with the full power of the Gutenberg block editor, rather than fighting against it and trying to maintain an old template-based design approach.

Editor Styles

To ensure the best content editing experience, the backend editor should match the frontend as closely as possible. Here’s what the block editor looks like for the page shown in the first screenshot.

Use an editor stylesheet to load a separate CSS file in the editor with your unique block styles. Create an editor-style.css file in your theme, and add the following code to your theme’s functions.php file to load it:

// Editor Styles
add_theme_support( 'editor-styles' );
add_editor_style( 'editor-style.css' );

You can use the editor font sizes feature to define different font size options for paragraph text. The defaults are Small, Normal, and Large, but you can load any number you’d like.


SASS comes in handy here. Rather than trying to maintain two separate stylesheets, you can break your main stylesheet into SASS partials and build both stylesheets with the relevant partials.

When you update a style that applies to the block editor, it automatically updates both style.css and editor-style.css.

Take a look at my starter themes for examples of how I structure my stylesheets.

Color Palette

You should also update the Gutenberg color palette to use your theme colors. We use the color options for changing button colors and for adding background color to full width sections.

We’ll typically have two versions for each color: the normal (darker) version which will have white text, and a lighter version that will use the standard text color.

Additional editor scripts and styles

If you use the add_editor_style() feature described above, WordPress will automatically prefix your styles so they only affect the content area. h2 {} becomes .editor-styles-wrapper h2 { }.

In some instances, you may want to load scripts or styles that are not modified by WordPress. You can use the enqueue_block_editor_assetshook.

On the NexRep site, we’re loading a stylesheet to change the content area width based on the selected page layout (ex: Full Width Content vs Content Sidebar).

Block Styles

You can add style variations to core blocks using block styles. On the NexRep site, we have two button styles (Default and Feature), and have removed unnecessary block styles from the separator and quote blocks.

wp.domReady( () => {

		[ 'default', 'outline', 'squared', 'fill' ]

				name: 'default',
				label: 'Default',
				isDefault: true,
				name: 'feature',
				label: 'Feature',

		[ 'default', 'wide', 'dots' ],

		[ 'default', 'large' ]

} );

Remove core blocks

You can also remove core blocks using wp.blocks.unregisterBlockType. We typically remove core blocks when we’ve built a custom block that’s very similar, to minimize confusion for the client.

On NexRep, we have custom blocks that are similar to the core Media & Text, Cover, and Latest Posts blocks.

wp.domReady( () => {

	wp.blocks.unregisterBlockType( 'core/verse' );
	wp.blocks.unregisterBlockType( 'core/cover' );
	wp.blocks.unregisterBlockType( 'core/pullquote' );
	wp.blocks.unregisterBlockType( 'core/media-text' );
	wp.blocks.unregisterBlockType( 'core/latest-posts' );

} );

Custom blocks

I’m a huge fan of Advanced Custom Fields. We use it on every website for custom blocks, site options, term meta, and more.

One of the most common questions I’m asked by WordPress developers exploring Gutenberg is whether they need to build custom blocks natively with React or use a plugin like ACF.

I personally think of it along the same lines as custom metaboxes. For single use blocks built for a specific website, it makes sense to use a tool like ACF for rapid development. If you plan to distribute your block publicly in a plugin, you’ll want to build it with React so there isn’t a dependency on another plugin.

Most of the websites we build include 10-20 custom blocks. The NexRep site included these custom blocks:

  • Hero Header
  • Call to Action
  • Icon Bullets
  • Content & Image
  • Content & Video
  • Content & Icon
  • Content Image Overlay
  • Percent Bullets
  • Featured Logos
  • Nexrep Medallion
  • Quick Links
  • Post Listing
  • Staff

Try to leverage core blocks as much as possible, and keep your custom blocks simple. In the quick video below, you’ll see how we use the Group block for the full width section with Heading and Icon Links block inside.

Client Training

The final step to a successful project is training the client so they are comfortable with the new theme. This is especially important when it comes to the block editor as this is likely the first time the client has interacted with it.

We provide WP101 video tutorials to all of our clients. On websites like NexRep that include a fairly complex design with custom blocks, we record custom videos to include alongside the standard WordPress videos.

Bill Erickson

Bill Erickson is the co-founder and lead developer at CultivateWP, a WordPress agency focusing on high performance sites for web publishers.

About Me
Ready to upgrade your website?

I build custom WordPress websites that look great and are easy to manage.

Let's Talk

Reader Interactions

Comments are closed. Continue the conversation with me on Twitter: @billerickson


  1. Beth says

    This is GOLD. Thank you!

    What if there is a section that’ll never be used again? I’m developing a site and making custom blocks, but there’s a section on the About page that is so specific that the client would never use it again.

    Do you make it a custom block anyway because it needs to be the flow of other blocks?

    • Bill Erickson says

      Yes, I typically build those one-off sections as custom blocks so they have the flexibility to use all the other blocks on that page as well.

  2. Jon Schroeder says

    Bill, I have a dumb question – where do you place the javascript code snippets used above (I’ve typically used php in the past to do most of these same sorts of things, and I’ve been building site for the last year using essentially the same method, but I haven’t been removing unused core blocks, which is probably a good practice). Do you enqueue these scripts in the admin using enqueue_block_editor_assets, or is that for something else?

  3. Peninah says

    Firstly, your articles on Gutenberg have been so helpful, thank you!

    In your video example under the Custom Blocks section, you use a group block, but then a custom block to handle the icon/text layout. That could also be done with the core columns + image and text blocks. Did you use a custom block here to give the client fewer options? To give you control over styling?


    • Bill Erickson says

      We use SVG icons rather than images because they’ll load faster and look better on high resolution devices. We also package all of the available icons in the theme itself so the client has a selection of similar icons to choose from.

      Also, I try to avoid the core Columns block. Almost any time we need to display content in multiple columns, we build it as a custom ACF block. This lets us ensure the columns match the grid of the rest of the site and control the mobile breakpoints. It also removes layout decisions from the content editor so the client can focus on content creation, not ensuring a consistent visual layout (that’s what the theme is for).

      • Peninah says

        Thanks so much for that explanation.The merger between the flexibility of blocks and the can’t-mess-it-up of custom fields/blocks is something I’m still working through.

  4. Jay says

    Bill – loving the tutorials on the block editor. In all of your posts that show the editor, i never see the title block at the top. Do you do anything special with it? Or do you just leave it and train clients that it may not show on the page?

    The title section in the editor, to me, is distracting if you’re doing anything full-page. Any tips on that area specifically/

    • Bill Erickson says

      In most cases we display the title on the page since it’s important an h1 appear on every page. If they have included an h1 in the post content somewhere (ex: in a Hero Header block) we disable the automatically output h1 from the top of the page.