Designing your first Gutenberg block

A presentation at JavaScript for WordPress in July 2019 in by Mel Choyce

Slide 1

Slide 1

Designing your first Gutenberg block

Slide 2

Slide 2

I’m Mel Choyce, I’m a product designer at Automattic and I work full-time on WordPress core. I co-led the 4.9 release cycle, and am currently working on the Gutenberg block directory. You can check out updates on make.wordpress.org/design.

Slide 3

Slide 3

Composing

For most of its existence, WordPress has operated on a “document” model of writing. You have an empty container that you fill with text from top to bottom. There’s a docked formatting toolbar on top of that container.

Slide 4

Slide 4

This is an interface familiar to anyone who’s ever worked in Microsoft Word or Google Docs. The web has evolved beyond displaying digital documents, but WordPress has only just started to catch up. The introduction of Gutenberg blocks takes us beyond the document model of web authorship, towards an approach that looks less like writing and more like building.

Slide 5

Slide 5

Building

Gutenberg blocks are like Legos — each a self-contained unit that can be combined to make some pretty fantastic outcomes. Like Legos, the possibilities are only constrained by your imagination.

Slide 6

Slide 6

You don’t need to be a designer ✌

You don’t need to be a designer to make some pretty rad Gutenberg blocks. You just need to think a little bit like one. With some critical thinking and familiarity with core Gutenberg components and patterns, anyone can create a great block.

Slide 7

Slide 7

At its simplest, a block can be a paragraph. The Paragraph block has a prompt that encourages you to write. You can add inline formatting, like bold or italic text, add links, and change the alignment. If you want to turn your paragraph into a heading instead, you can do that, too. This is very similar to how WordPress has always operated.

Slide 8

Slide 8

Let’s take a look at another simple block, the List. In a document-driven editing model, you would start a list by applying list formatting, via a toolbar, to existing text, or you’d go to the formatting toolbar and click ‘List’ to create a new bullet point.

Slide 9

Slide 9

This is similar in Gutenberg. You can transform a Paragraph block into a List block, or add a new List block directly to your page.

Slide 10

Slide 10

Some blocks require more than a simple text prompt. More complex blocks require more advanced setup states. For example, the Image block creates a placeholder with buttons for uploading images, selecting existing images from your media library, and for inserting an image from a URL. Similarly, the Quote block has two text inputs: the quote, in larger text, and the citation, in smaller text.

Slide 11

Slide 11

Some blocks are much more complex and need a more comprehensive setup state. The Table block requires you to select the number of columns and rows before it can render the correct placeholders.

Slide 12

Slide 12

A Map block could require an API key to function.

Slide 13

Slide 13

Or, a block might be drawing dynamic content from a different part of your site — like a post, or a custom post type. The Latest Posts block, by default, displays the title of your most recent five posts, from newest to oldest, and requires no initial setup.

Slide 14

Slide 14

The anatomy of a block

Gutenberg blocks are comprised of a few different elements:

Slide 15

Slide 15

  • The icon
  • The content area
  • The toolbar
  • The sidebar

Slide 16

Slide 16

Block icons

Each block has an icon used to identify it across the various block interfaces, such as the block library, the toolbar, the sidebar, and occasionally a setup state.

Slide 17

Slide 17

Icons are generally displayed at 24x24 pixels, but should be scalable. Use SVGs. You can pick from an existing Dashicon, design your own custom icon, or use an icon from a third-party, GPL-compatible library. Many of the new icons in Gutenberg are based on Material Design’s outlined icons, so that’s a good source if you want your block to look like it belongs. When selecting or designing a block icon, think about your block’s primary purpose. Some blocks are obvious — an Image block should use an image icon, a List block should use a list icon, and a Quote block should use a quotation mark icon.

Slide 18

Slide 18

Some blocks aren’t so obvious. What icon should a Featured Content block use? How about a Carousel block? CTA? Pricing Table? You might need to get creative. Look through icon libraries, and see if they have anything that fits your block purpose. Search for your block name in something like IconFinder and see what imagery it pulls up. See if a website building service like Squarespace or Weebly has a comparable block, and what icon it’s using. When all else fails, go for the most generic representation you can find — maybe a shape, or something nondescript — and be happy your block will usually show up alongside its name.

Slide 19

Slide 19

Content area

Now that we’ve covered icons, let’s talk about what should appear in the content area of the block.

Slide 20

Slide 20

“The primary interface for a block is the content area of the block.” – The Gutenberg Block Design documentation

In an ideal world, the only thing you’d ever have to think about when adding content to a block is your content itself. What does this mean in practice? If a block needs specific information to render, ask for that information in a setup state. Need an API key? Ask for that in your setup state. Need posts from a specific taxonomy to display? Show a list of existing taxonomies in your setup state.

Slide 21

Slide 21

The most important settings should display inline with your block. Take, for example, the Jetpack Contact Form block. The “required” setting, which exists per-field, is displayed alongside the input label. When you select the input block, you see a toggle to turn “required” on or off. When the input field is not selected, you see a live preview of the input. Your live preview state, when your block isn’t selected, should always mimic the front-end as closely as possible.

Slide 22

Slide 22

Choose smart defaults

Choose smart defaults. It’s fine to make a super configurable block, but don’t make your users or customers have to think too hard about setting it up if they want something simple. Do some initial research, whether that’s a couple of interviews with existing customers, or finding existing, comparable research from a reputable source like the Nielsen Norman Group, and try to determine which settings most of your customers change. Make these changes the default options. This suggestion trumps the previous tips. If you can provide smart defaults, do.

Slide 23

Slide 23

Toolbar

Next up is the block toolbar.

Slide 24

Slide 24

“The block toolbar is a secondary place for required options & controls.” – The Gutenberg Block Design documentation

The block toolbar usually contains layout and alignment, or text formatting options. It’s also a good place to put any inline settings you might have, like creating a footnote, for example.

Slide 25

Slide 25

By default, the toolbar displays above the block.

Slide 26

Slide 26

You can also show the toolbar at the top of your editor if you have the Top Toolbar setting enabled. Regardless of your block settings, all toolbars show the block icon, and a “more” menu with options to duplicate, move, delete the block, etc. Everything else is optional. The toolbar is a great place to include inline formatting options, like bold, italic, strikethrough, and links, if your block contains any text inputs.

Slide 27

Slide 27

The toolbar is also the right place to include block-level alignment and layout settings for your block. In the Media & Text block, for example, there’s a Toolbar setting to display the media on the left, or the right.

Slide 28

Slide 28

The CoBlocks plugin offers this custom font menu on all text blocks, and it’s a perfect use case for adding a feature to the toolbar.

Slide 29

Slide 29

The toolbar also houses two additional options: styles, and block transforms. Block styles are alternate variations on a block which only rely on CSS. Take, for example, the Button block, which comes with three core styles: Default (rounded corners), Outline, and Squared. When these styles are available, they’re accessible via a dropdown next to your block icon. Choose a smart default, but feel free to include different styles for your custom blocks, or extend existing core blocks in interesting and unique ways. If you’re thinking about recreating a core block to add new visual options, consider adding styles instead.

Slide 30

Slide 30

You can also transform similar blocks. A paragraph can transform into a Heading, Quote, List, Preformatted, or Verse block. An image can transform into a Gallery, Media & Text, Cover, or File block. Is your block similar to another core block? Add a transform option. You can look at Jetpack or the Block Gallery plugin for good examples of transforms. Make sure that if you do include a transform, the existing content converts smoothly to the new block type. You don’t want your users or customers to lose any data.

Slide 31

Slide 31

One caveat: the toolbar is icon-based, so only add settings you can reasonably represent using an icon, or an icon group. There will be tooltips on desktop computers, but any touch-based device won’t necessarily have labeling you can rely on.

Slide 32

Slide 32

Sidebar

Slide 33

Slide 33

“The block sidebar should only be used for advanced, tertiary controls.” – The Gutenberg Block Design documentation

If your block needs information to work, don’t show it in your sidebar.

Slide 34

Slide 34

The sidebar, as you might guess, appears on the side of your editor. You can toggle it on or off, which means you can never rely on the sidebar being open. In fact, the sidebar is hidden by default on smaller screens. This makes it a good place for advanced or non-essential settings, but a bad place for any required or important settings. Settings within the sidebar should be grouped into sections based on similarity. The Paragraph block groups together text settings like font size and a drop cap toggle into a section. The Cover block groups positioning settings like ‘fixed background’ and ‘focal point’ into one section, and overlay settings like ‘color’ and ‘opacity’ into another section.

Slide 35

Slide 35

Be careful adding settings

You might be tempted to add a ton of settings to your block, since they can all fit into the sidebar. However, I’d urge you to think very carefully about what settings you add to your blocks. Firstly, once you include a setting, you’re going to have to support that setting — perhaps indefinitely. If you include a setting on a whim and then suddenly end up with a constant stream of support questions about that particular setting, you might regret including it in the first place. At the very least, you should redesign the setting to make it easier to understand.

Slide 36

Slide 36

More settings = more problems

Secondly, the more settings your block includes, the more complicated it becomes. Think about your audience — who do you expect to use your blocks? If you’re aiming for site builders and freelancers, then adding a bunch of customization options might be appropriate. However, if your block is aimed at casual users or hobbyists, you should consider paring down your settings to the minimum needed for your block to be useful.

Slide 37

Slide 37

Speaking of more advanced settings, every block comes with an “Advanced” section that houses an “Additional CSS Class” option. If a user adds a class name to this, that class will be applied to your block. If you have very advanced settings, especially developer settings that can’t easily be explained to your average user, put these in your Advanced section.

Slide 38

Slide 38

Designing your block

Now that we know all of the elements that make up a block, let’s put it all together.

Slide 39

Slide 39

A while back I designed a Restaurant Menu block. I’ve wanted a better way of making restaurant menus since working on WordPress.com’s restaurant menu custom post type a couple years ago. The custom post type method of creating a restaurant menu felt clunky and tedious. Blocks provide a perfect opportunity to redesign this process. Gutenberg blocks put the interface within the context you’ll be displaying and previewing the menu in, rather than abstracting the interface out into a separate, unrelated screen. Text placeholders allow for an easy “fill-in-the-blanks” method for content creation. It seemed like a natural fit.

Slide 40

Slide 40

Scoping the block

Going into this project, I assumed the vast majority of restaurant menus are pretty similar — but I wanted to validate those assumptions before I started to put pixels down onto my screen. I looked up the menus for over a dozen restaurants I like and jotted down what kind of information they included.

Slide 41

Slide 41

Menus were divided up into different categories, such as Appetizers, Entrees, Desserts, etc., some of which had descriptions. Almost every menu included at least a title and price for every individual menu item. Many also included descriptions. There were a scattering of other features — some menus included photos, some included how spicy a dish was, and others marked whether a dish was vegetarian or gluten free. Some menus even allowed filtering, either by category or by diet.

Slide 42

Slide 42

MVB(lock)

This is potentially a lot of features. Let’s pare it down to a minimum viable block: - Menus should be divided up into sections, each with a heading. - Each menu item should contain a title, price, and optional description. That’s all we really need for a restaurant menu. Each section could be a parent block that includes a heading, with menu items as children. Why a block per section, instead of one block for the entire menu? By breaking out the block into a menu section, your menu can be easier to rearrange, style, and scale.

Slide 43

Slide 43

Basic blocks

A few additional options would make the block more useful for many restaurants:

  1. The ability to intersperse additional headings, paragraphs, and images into a menu. This would cover a lot of the miscellaneous use cases I saw, such as section descriptions and the occasional image highlighting a specific dish.

Slide 44

Slide 44

Dietary Notes

  1. A toggle to add optional dietary notes or allergen warnings to a dish.

Slide 45

Slide 45

Columns

  1. Column support. Many of the menus I saw broke sections up into multiple columns to better use up space on the page.

Slide 46

Slide 46

Block styles

  1. Additional block styles. While the default styles would show title and description on the left, with price on the right, we could add another style in which title, description, and price are centered on the page. This was a popular style amongst the restaurant menus I researched.

Slide 47

Slide 47

Refining the settings

Now that we’ve scoped our Restaurant Menu block, let’s figure out where each piece of the block should live.

Slide 48

Slide 48

Setup state

The setup state should include placeholder text for the most important content in the menu: the section heading, and one empty menu item that includes a name, price, and description. This establishes all your baseline patterns and starts teaching people how to use your block.

Slide 49

Slide 49

For convenience, the block should default to adding a new menu item, so all people need to do to get another item is press “enter” at the end of the description field. People can still press the “down” key to get outside of the parent block.

Slide 50

Slide 50

Toolbar

Because we have a parent block and a child block, each will have its own toolbar. Looking through our scope, the only setting that seems to belong inside the parent toolbar, the “Restaurant Menu,” is our alternate menu style:

Slide 51

Slide 51

I thought about adding support for wide- and full-width layouts to the block, but the majority of menus I saw were constrained to the content width. If a bunch of people start asking for this feature later, it’s easy enough to add support.

Slide 52

Slide 52

Our child block, “Menu Items,” consists of our title, price, and description. These fields could benefit from some very basic text formatting. Bold and italic seemed reasonable, so I decided to include those. Strikethrough and link, which are available in the paragraph block, feel unnecessary in this context, so I excluded them. But once again — should they prove to be desired, we could always add support in a future release!

Slide 53

Slide 53

Sidebar

What’s left to include in our block? There are only two settings we haven’t talked about yet: columns, and our allergen toggle.

Slide 54

Slide 54

I found plenty of menus that used a one-column layout in my research, but just as many used two or more columns. It seemed like a setting worth supporting, and Gutenberg already comes with column support available. We probably don’t want to allow people to add infinite columns to the menu block, so it would make sense to limit the block to a maximum of maybe four columns.

Slide 55

Slide 55

Let’s talk about the dietary notes toggle. Toggling this setting on adds a new field underneath the item description, so you can add some extra details like “gluten-free” or “vegan”. Including a description within the sidebar setting makes it clearer what the setting does, especially when it has a more ambiguous label.

Slide 56

Slide 56

Because not every menu item will need to include an allergen, this is a setting you’d turn on for the individual menu items that need it.

Slide 57

Slide 57

Let’s not forget about the block icon! This block will need two: one for the parent block (Restaurant Menu), and one for the custom child block (Menu Item). I looked through some icon libraries, looking for inspiration. I found a clipboard that made me think of some menus I’ve received in restaurants, so I chose that for my parent block. I found a pizza icon to represent a menu item.

Slide 58

Slide 58

And of course — use existing Gutenberg components. Try to avoid rolling your own if you can.

https://developer.wordpress.org/block-editor/components/

Slide 59

Slide 59

Here’s what it looks like all-together.

Slide 60

Slide 60

Now you just need to finishing building your block! …Okay, done.

Slide 61

Slide 61

Usability testing and iteration

Before launching your block to the world, consider doing some usability testing. If you’re part of a larger team with more resources to spend on research and testing, you can pay someone to recruit and run usability tests for you — or even use your in-house team of UX experts! If you’re a lone plugin or theme developer, however, your testing doesn’t have to be super comprehensive — you can keep it small and simple.

Slide 62

Slide 62

There are better guides for telling you how to conduct usability testing than I can in our remaining time, such as Rocket Surgery Made Easy by Steve Krug. You can read a sample chapter online if you’re not quite sure if you want to invest in reading the book.

https://www.sensible.com/rsme.html

Slide 63

Slide 63

If you want something more condensed, the A List Apart article “Usability Testing Demystified,” by Dana Chisnell, is a great introduction.

https://alistapart.com/article/usability-testing-demystified/

Slide 64

Slide 64

Run at least 3 tests

Run at least three usability tests. If you have some additional resources, run five. Nothing’s better than testing live with people. WordCamps are a great place to connect with potential customers and have them run through your block. You can also run tests through video chat and screen share. If running your tests directly isn’t feasible, you can use an unmoderated online testing service. Any information is better than nothing, especially when you’re working with limited resources

Slide 65

Slide 65

Sift through your findings

Once you’ve run at least three tests, sit down and sift through your recordings or your notes. Find the biggest pain points in your block, and then iterate on them. Try to see if there are any established patterns from other blocks that accomplish the same task in a more straight-forward or intuitive way. If you have the time and budget, test again with some new volunteers and see if your changes improved the experience of using your block.

Slide 66

Slide 66

Worse comes to worse, if you’re super stressed about designing a block, use existing blocks as inspiration.

As David Bowie said, “the only art I’ll ever study is stuff I can steal from.” Nothing is ever truly original. (One caveat: don’t be a jerk and rip someone off.)

Slide 67

Slide 67

🚢 Ship it

You can iterate ad nauseam, but at some point, you need to ship. Once you have a big enough user base, you’ll probably start hearing feedback, suggestions (and of course, bugs) directly from your customers. You can use this direct feedback to make future improvements to your block.

Slide 68

Slide 68