Custom Block Editorial Experience
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.
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.
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
https://developer.wordpress.org/block-editor/how-to-guides/curating-the-editor-experience/