Gutenberg design basics

Have you ever wondered what something is called within Gutenberg? This guide is meant to help by giving the names and the expected behaviour of some of the basic design elements. If you want to build blocks and extend Gutenberg, knowing what to use or not is important. This is meant as a starting point, not a full description of all design elements.


There are two toolbars:

  • The Editor toolbar: This controls document tools like undo and information. Also within this toolbar are preview, publishing and saved state.
  • The Block toolbar: This controls block specific behaviour, for example in a paragraph block bold/italic and adding a link. As a guide, place common settings that a user would want for every version of that block in the block toolbar.


These are also referred to as 'advanced settings' when linked from the block toolbar.

There are two settings:

  • Document: This gives you global settings for the entire document like visibility and reviewing. Think of this like your settings panel for your content.
  • Format: This is per block and changes depending on the block and if it even has settings. These differ from the toolbar as are secondary block settings, for example adding a CSS class (in most blocks) and doing styling that isn’t as common. 

More menus:

These come in 2 locations:

  • Document: These contain document settings such as switching display modes, position of toolbar. Anything that is not specific to a block or the document would go here, for example display modes or something like a spell check.
  • Block: When beside the block there are commonalities found in all blocks:
    • Hide Advanced Settings (if visible) or Show (if hidden)
    • Edit as HTML
    • Remove
    • Convert to Reusable Block
    • Convert to another Block and a list of those blocks.

As a guide you’d not be adding to these menus in a custom block. You’d ideally use something like the advanced settings here.


It's worth noting that insert is changing to add potentially. There are multiple ways to add a block in Gutenberg to content:

  • Toolbar (although this may be removed)
  • Above a block: a ‘+’ appears on hover
  • Below the block: a ‘+’ shows all the time to interact with


The library appears when you click to add and then you see all blocks available. You can also search for the block by name. Blocks are in sections both through tabs and in within each section there are categories.

Recent blocks

Recent blocks also shows all the blocks a user has been using frequently.

Document outline:

You can view information about a block by clicking ‘i’. This contains helpful document information like number or words written.






8 responses to “Gutenberg design basics”

  1. […] Gutenberg design basics – by Tammie Lister. A guide to the names and the expected behavior of some of the basic Gutenberg editor design elements. […]

  2. […] Gutenberg design basics: Thanks to Tammie Lister, a user experience designer at Automattic, here’s a closer look at designing with Gutenberg. […]

  3. […] Gutenberg design basics […]

  4. Rob McClellan Avatar

    Thanks for this, Tammie. Will there be options for other views/behavior of the editor?

    For example, right now there is just this basic “Medium-ish” block based editor which allows for the orderly placement of blocks, but has limited ability (if any, it’s barely been discussed) to pull theme style information to help make it a little more WYSIWYG. Will this be improved? Can we get a more accurate WYSIWYG picture when building a page/post?

    Also, the placement of editing icons is constantly flowing from block to block and place to place. Even when the option to keep the editing icons at the top (instead of at the block) is chosen, as the entire iconography is so reactive – the flickering of those controls, to me, is unnerving and highly distracting (not to mention confusing, the entire editor has a steep learning curve). Will there be a way to just put the “kitchen sink” up at the top of the page and keep it stable? In what I’m sure was an effort to be simple and contextual by flowing the controls, has created an effect that makes me constantly feel like I’ve broken this new editor or that something has gone wrong. And, when I move my mouse across blocks options keep popping up and changing and are rarely what I expect. The combination of the flickering and the changes in menu options that is just… well, it freaks me out, to be honest. It’s deeply unsettling. The ability to stabilize that would be very, very welcome.

    The block interface, with the plus sign, is, for me at least, becoming overwhelmed. There are currently over 50 items and options shoved inside of that plus sign, and developers haven’t really even gotten started creating blocks – that number could easily go over a hundred for many sites. Funneling everything – including all forms of text – through that plus sign is going a bit overboard to me. While the plus sign does start to provide prompts (three last/common used block types), that is also distracting – one more thing floating around on the editing screen. Is this interface going to expand beyond that single plus sign? Can the various blocks and options be spread out across a menu bar that allow for a more dispersed and itemized method for identification and selection (ie more Google Docs and less Medium)?

    And, then, there is the counter-intuitive insistence that everything be a unique block, something that has been shown repeatedly (in my own experience and the few “user test” videos I’ve seen, at least) to be very confusing due to the alien nature of that method (no common text editor or document program uses blocks to that extent aside from Medium). Is there a roadmap to address the actual editing of text? Or will it remain “super-blocked” as it is now, with every element (text, images, blocks, and… meta?) a unique block?

    Its undeniable that Gutenberg is an exceptional bit of code – but the interface and implementation of blocks is certainly galvanizing. A Medium-style interface works very well when the content being made is stripped down with very few options. WordPress, by it’s nature, is not stripped down and has many, many options. The Gutenberg editor, to me at least, seems like its becoming confusing and complicated in its effort to remain “simple”. I, personally, feel that the current Medium/Block interface type Gutenberg employs is overwhelmed – there are just too many options for that single “plus” and its resulting modal.

    And, we’ve barely even gotten into the many, many Metabox options and all that they contain.

    I would love to see an interface that is more based around a document editor set-up than Medium. As well as something with optional views, such as a WYSIWYG view where the stylesheet is pulled and users can see the whole site canvas as it appears. Or a view where it’s just the text editor, or a view where it’s current Gutenberg. Maybe a toggle option to show the page/post how it would appear on a laptop, tablet, or phone so people can more easily see what they have assembled, like a “Preview” built right into the editor and not requiring a new tab to open (much like the Customizer allows).

    At the very least, it should allow for a true WYSIWYG view. That is one of the main selling points of services like Wix and SquareSpace and it has been voiced over and over by WordPress users. If we’re going to all of this effort to overhaul the editor, it seems it should at least get that part down.

    Where can the WordPress community gather to discuss the UI/UX of the Gutenberg editor? Is there a thread dedicated to discussing UI/UX in GitHub or on Make.WordPress or elsewhere? Have alternative designs been discussed? If so, what were some of the other options and how was this one decided on? Will there be hooks built into the 5.0 Core to allow plugin/theme designers to create their own custom editors?

    1. tam Avatar

      I think it’s important to note this post is about the design language not really anything more right now.

      As far as WYSIWYG goes there are 2 phases of Gutenberg and that’s important to remember, the editor and then the Customizer. Getting towards that comes more in the Customization one and relies a lot on the theme.

      I would point you to look at making issues for things you find a problem with Rob and in doing so also observe others using Gutenberg. This is where you can go to comment and I’ve seen you there so encourage you continue that path. It’s when we observe others we can either prove or adjust our own headspace.

  5. […] Tammie Lister of Automattic authored a comprehensive guide on the basic design principles of the blocks of Gutenberg. In her introduction: […]

  6. […] I’ve also appreciated the work she’s been doing on a Gutenberg starter theme and her own theme called “Logical Gutenberg“. If you are a theme designer/developer, make sure to read Tammie’s articles on “Gutenberg inspired redesign” and “Gutenberg design basics“. […]

  7. Chris Bryant Avatar

    Thanks Tam!

    Just starting to get my head around Gutenberg. No better place to start than learning the language and logic of it. So this post was extremely helpful. All the best.

Leave a Reply

Your email address will not be published. Required fields are marked *