Block editorial experience best practices

This document covers best practices and recommendations for creating a good editorial experience for our blocks.

Seamless integration

Our intention is to leverage Gutenberg as much as possible with our block development process. We want our custom blocks to seamlessly integrate within the Gutenberg editor.

Consistency

There should be some consistency from editing one block to another. We should use the same type of labels, field types/components, and naming when possible; so that editors can quickly work with our blocks.

Labels & help text

Fields should have labels and help text should be added to provide additional context if needed. The wording of the helper text should be coherent and understandable for editors.

Open

In this example, we are telling our editors that the editorial experience slightly differs from what will be shown in the frontend.

Lock your content

If you create a complex pattern it can be beneficial to lock your content to prevent editors from inadvertently breaking your design. You can lock your blocks from being removed and/or moved.

Keep options simple

Only include fields and options that editors will actually use. It can be easy to get carried away with adding more options than necessary to your blocks. This can add unnecessary bloat and over complicate the editorial experience.

Leverage conditional fields

Think about implementing conditional options when appropriate to minimize the amount of options shown at once.

Example: On a Slider block I have some options like Enabling Autoplay, speed, and showing a progress bar. If I choose to disable Autoplay, I should also hide the autoplay speed and progress bar options because those are no longer relevant.

Open

The image on the left displays how the Animation & Autoplay settings appear by default. The Image on the right displays additional Autoplay options when the Autoplay option is toggled on.

Define interface and design options

Define options like colours, fonts, and typography, etc. for your blocks. Setting default options keeps customization of your blocks within brand guidelines, helps with accessibility, and gives you more control over how editors interact with your blocks.

Example: My global theme palette has the colors lavender, yellow, black, and charcoal. For my Paragraph block, rather than having all four colors available as options, I should limit the text color palette to black and charcoal to ensure that my paragraphs are accessible and easy to read.

Remove unnecessary interface options

Along with defining options, you can also remove options from a block altogether. We should give our editors access to customization options within restrictions. While we want to empower our editors, we also want to limit their ability to alter the site’s original design.

Example: There are many typography options available for Heading blocks by default: color, font-family, custom font-sizes, etc. To ensure that our headings look consistent throughout the site, we should remove unnecessary options.

Restrict which inner blocks can be used in your block

It's beneficial to restrict the inner blocks that can be inserted in your custom blocks. This provides your editors more guidance and removes clutter in the block inserter.

Block categorization & naming

To ensure that our editors can easily find our blocks:

• Assign the block to the theme category so that editors can find our blocks in one place. The category should be the name of the theme.

  • Example: KalaPress.

• Add the category name before the block title so that editors can easily search for our blocks.

  • Example: KalaPress - Card

Resources

Curating the Editor Experience – Block Editor Handbook | Developer.WordPress.org