Block Directory in WP-Admin: V1

This is an update to the #block-directory project. You can see the first round of concepts and feedback in this previous post. Feedback from that post was used to update the mockups in this round of iterations.

See all mockups in Figma


Building the new Block Directory in wp-admin presents us with a couple opportunities to redesign certain existing patterns, and turn them into reusable components. When we revisit future admin pages, we’ll have these components available to replace the older patterns.

Here’s some updated patterns we can turn into components for this project.

Page Headers

There are tons of pages in the WordPress admin. None of them are consistent.

I’d previously explored a consistent header for admin pages, but it still felt subpar:

When I started working on the Block Directory, I wanted to take another stab at a header that could work across the entire admin. These were roughly based off of Material’s headers, then adjusted and improved to fit our use cases.

Page headers consist of the following elements:

  • The page title.
  • A short description of what this page is and what it’s for, ideally only a sentence or two long.
  • Action buttons on the left (add new, upload, etc.).
  • Meta buttons on the right (help, settings).

Rather that opening Help and Screen Options (now “Settings”) in tabs, we can use the modal component:

This is a more portable approach than the existing pull-down tabs, and also makes the longform help content much easier to read, since the modal constrains it to a much better line-length for readability.

Note: the modal header and panels don’t line up in the mockups due to some conflicts in the Figma files, but should in real life.

List Tables

Y’all, List Tables are as old as dirt. They’ve done a good job for the past decade and whatever, but they could use some modernization. Lists Tables would be a way to bring all of the list actions together into one single container, rather than floating above and below, disconnected from the table. I’ve kept the table items themselves the same, but made adjustments to the header, footer, and external table elements.

List Tables are composed of the following elements:

  • A table heading with optional bulk select checkboxes.
  • Rows, same as the existing list table pattern.
  • A table footer that instead of repeating the header, has meta information (# of pages, previous/next navigation). When items are selected, bulk actions take the place of the navigation:

This is similar to how we handle bulk deletion in the Media admin screen.

Empty States

There isn’t currently a consistent “Empty” State for admin pages (like when you don’t have any posts, pages, comments, etc.). This new component take a stab at one we can reuse for all pages in the future.

Empty States are composed of three elements:

  • A “not found” graphic.
  • Text stating there are no items.
  • An action, like a button, to help resolve that there are no items.

You can see more component documentation for the Block Library in Figma.

Next Steps

Per this 2019 projects recap, the Block Directory is slated for inclusion in WordPress 5.5. Development will hopefully start soon.

In the meantime, if you have a block you’d already like to include in the directory, you can already submit it! Check out this post on Meta for more information.

Thanks to @tinkerbelly for taking my sloppy mocks and making all my one-off elements into reusable Figma components!

Block Directory in WP-Admin Concepts

You may have spotted during @matt‘s Summer Update at WCEU a new wp-admin section for Blocks. I wanted to share those early concepts here.

View Figma Prototype

About Blocks

Rather than jumping straight into a list of blocks, I wanted to explore what an introduction to blocks could look like as a landing page. This page could feature some links to tutorials (that could open either externally, or in a modal), some basic FAQs, and a support link.

You’ll notice the new header style, inspired by the new Health Check screen and built on some concepts from the Design Experiments plugin. This new section provides a good opportunity to expand on this pattern, and to show how it could benefit WordPress users by providing context to each screen.

Add New Blocks

This section is largely inspired by wp-admin plugin cards, and the plugin details screen.

I also think we should update across wp-admin as well, since the current modal feels very outdated and doesn’t present information as cleanly or as organized as the .org modals:

Inside the modal, you’d also be able to demo a block before installing. @ck3lee has figured out how to make this possible 🎉

We’d tap into the Shiny Updates framework to make installation and activation quick & easy.

The upload flow would work the way plugins do — I’ll flesh out some designs around that in future iterations.

Installed Blocks

This screen would be a list of all installed third-party blocks, so you can activate, deactivate, delete, etc. in bulk, using a traditional list table. I’ve added an “instances” link, which would show all posts and pages the third-party block is being used in.

Manage Blocks

This is the screen I’m most “meh” about, which is pretty much a duplication of the block management modal inside the editor. I think we need to have this management available within this section, but I’m not sure if this is the best approach to tackling it.

Reusable Blocks

Currently, the only way to reach the Reusable Blocks screen is through either the block library inside the editor, or a link in the settings dropdown in the editor. Putting it in a new Blocks section gives it an easier-to-find home.


These are still early concepts, so it would be good to get some early impressions. Specifically, I’d like everyone’s thoughts on:

  • Thinking through the flow of managing blocks on your site, does it feel like any important tasks are missing from these concepts?
  • Would you expect any of these screens to be combined?
  • Can you think if any stress cases these screens will need to account for?
  • What would you like to see next for the Block Directory? Are there any other block management features you would benefit from?


Block Library Installation Design Hand-off

@karmatosed and I recently chatted about the next steps for the block installation flow from within the block library, and decided that it would be better to test this feature in code, rather than testing the static prototype.

I’ve put together a hand-off document on Github so the development team (@tellyworth and @ck3lee) can start building it out. You can follow along and get involved with the development process there.

Call for Testing

We’re going to need some folks to get involved in testing the feature, once the initial version is built out. I’d like to start thinking about that now, so we can prepare a script and start figuring out where we should be testing sooner rather than later. If you’re interested in getting involved in testing this feature, please let me know in the comments.

#block-directory, #block-library

Block Library: Mockups & Prototype

This is an update to the Block Library project that’s in-progress. Feedback has been taking place on GitHub and in Figma. My thanks to all the folks who have chimed in to help improve these mockups!


A screenshot from the Figma file, for illustrative purposes.
Figma: Source File / Prototype

Installing a block

Installing a third-party block from the block directory, via the block inserter

Search Results

If you search for a block, but nothing installed in your block library shows up, you’re presented with third-party blocks that show the block icon, title, author, and rating. Pressing on a block brings up more details.


The Details screen is similar to the plugin cards we see in the Plugin Directory. It’s an abridged version of the block information, showing icon, title, author, star rating, and description. (This would ideally use the short description that plugins provide for cards.)

“More Details” would bring you to the full details screen in the Block Directory, and “Add” inserts the block into your content.


Once the block is inserted into your content, WordPress would ideally start silently installing it in the background while you fill in placeholders and change settings. If you change your mind and decide this block doesn’t work for you, WordPress would deactivate and delete the block when you remove it from your content so you don’t end up with a junk drawer of discarded blocks in your library.

What happens if your installation fails

In some cases, the installation won’t work — for example, if your internet cuts out while trying to install the block. In these cases, WordPress needs a way to recover from that error. This flow explores when a block isn’t able to be silently installed.


If you have the pre-publish panel enabled, you’ll see another reminder that you’ve added new blocks to your site, and another Details link that’ll take you into the Block Directory, in case you want to review it again.

Next Steps

  • The design team will look at creating tests for this (or testing it out themselves) during the WCEU Contributor Day; look for a recap on this p2 afterwards.
  • Between now and then, the prototype will continue to be open for feedback and iteration. I’d like to have all feedback for round one of testing in by Wednesday, June 19th, so I have time to iterate before WCEU.
  • You can comment with feedback here, or directly in Figma, if you’re a part of our team account (You can ask for access in #design).

#block-directory, #block-library

Block Library: Initial Explorations

Wanted to give an update on the Block Library project that’s in-progress!

Experience Flowchart

Tried to map out every part of the experience flow for this project:

GitHub Issue

h/t @babbardel for your help!


Sketches are now up for the following flows:

Please take a look and give feedback. Each issue also has a set of questions associated with it that I’d love thoughts on.

#block-directory, #block-library

Block Library: Competitive Analysis Recap

Over in GitHub, contributors have been exploring potentially related “competitors” for inspiration we can apply to the Block Library project. I’ve pulled those out into groupings:


I’m not convinced we need a browsing interface within the Editor, but it’s important to explore how it could potentially work if we did decide to go in that direction. It’s especially important for us to look at what other people are doing within our space, like Ghost Kit and the Gutenberg Blocks Template plugin.

Outside of WordPress, discovery and browsing sections of apps provide interesting ideas for how we can tackle exploration. For example, I really like Medium’s “New from your network,” and can see something like that translating into something like “more blocks from developers you trust.”


Snapchat and Vine

I think how Snapchat and Vine combine(d) results from people you follow, along with people you don’t follow, is pretty analogous to searching for blocks in your library — and especially useful if you have no results:

The Monday app also makes use of animation when searching, which provides an extra layer of delight.

No Results

Bear and Reddit have cute No Results screens, but none of them make suggestions for what to do next, which I think is going to be the critical hook for suggesting new blocks to install. No one should ever get “stuck.” This is where I think the “Browsing” examples are key — rather than showing an empty screen if there aren’t results, we could showcase downloadable blocks instead.



Having some sort of details screen can provide opportunities to persuade people to install your block. Like plugins, we should consider letting block creators add screenshots, descriptions, and more details to help market blocks.

Path in particular took a really nice approach with their detail dialogue — it’s visually appealing, makes great use of animation, and provides plenty of space for information.


The Jetpack examples are obviously a bit more of a direct comparison. The last two mockups, especially, are a good example of using existing core patterns to preview blocks within the editor. I can easily see this extending to our use case, where “upgrade” is instead “install.”

I think it’s going to be very important for people to preview new blocks in-context — a “try before you buy,” if you will — and so we’ll want to further explore how we can make that a seamless experience.

Based on these explorations, I think it would be good to tackle our next phase, Exploration, by breaking it up into different tasks:

  • Discovering blocks through searching, or maybe browsing
  • Previewing a block in-context
  • Installing a block
  • And even what happens when loading a page with missing blocks (we already handle this, but it’s not connected to re-installing or re-activating the missing block)

Does this approach make sense?

Does anyone have any other examples that could provide inspiration?

#block-directory, #block-library

Block Library: Installing Blocks from Within Gutenberg

With the introduction of Gutenberg and blocks comes the need for a way to install new blocks, just like plugins or themes. Step one in this project, for the design team, is installing blocks contextually within Gutenberg. Check out this thread for more details and prior explorations.


The API will provide an endpoint for searching for blocks by name and description, and return metadata similar to that of plugins. Gutenberg’s Inserter could use that endpoint to also show relevant block plugins that are available to install, with a button and process for seamless installation.


This project is limited to installing one block at a time from within the Gutenberg editor. That might encompass:

  • How people discover blocks from within the Gutenberg editor
  • How to give users enough detail to make an informed decision about which block to install
  • How uninstalled blocks are previewed
  • What the Install process would look like
  • What happens if the installation fails
  • Removing installed blocks
  • How to manage installation requests by non-admin users

This scope is intentionally kept small so we can focus on shipping an iterating. A larger exploration of how to download or install blocks from within a Blocks screen in wp-admin, and, will take place in a future project.


Task Stage Facilitator Due Status
Create repo Scope @karmatosed April 26
Create project board for design tasks in GitHub Scope @karmatosed April 26
Create issues in GitHub for design Scope @karmatosed April 26
Make/design kick off post Scope @melchoyce April 26
Make/meta kick off post Scope @tellyworth May 3
Competitive analysis Research @melchoyce May 17
Competitive analysis summary post Research @melchoyce May 17
Experimental explorations Exploration @melchoyce May 24
Flow diagram Exploration @melchoyce May 24
Iterate on experimentations Refine @melchoyce May 31
Make/design post of designs Refine @melchoyce June 7
Prototyping (click prototype/Figma) Prototyping @melchoyce June 7
Testing/feedback on prototype Prototyping @melchoyce July 5
Update GitHub issue to start development Development @melchoyce July 5
Prototype (technical prototype) Development @tellyworth TBD
Testing/feedback on prototype Development TBD TBD

See the complete timeline on Google Drive.

Where to Follow Along

  • There will be weekly or biweekly updates here on make/design.
  • There will be time during each weekly Design meeting on Slack for updates.
  • Design tasks will exist as issues on GitHub; you can follow along on on our project board.
  • Development will also be happening on GitHub.

Get Involved

Interested in joining @iviolini and I on this project? Let us know in the comments, and follow along on GitHub.

If you don’t have time to devote to working on design tasks, that’s cool — feedback is always welcome, and a great way for you to contribute.

#block-directory, #block-library

Call for design: Installing blocks from within Gutenberg

The Problem

Gutenberg needs to provide a way for users to discover and install new third-party blocks without ever leaving the editor. We are looking for a volunteer to lead the design part of this project.


Currently, new Gutenberg blocks can be provided by plugins, which often register many blocks, and which are managed from outside the editor. The Block Directory proposal outlines a new type of simple block-based plugin that is intended to be seamlessly installed from within Gutenberg itself. This is one of the 9 priorities in the 2019 roadmap.

The API will provide an endpoint for searching for blocks by name and description, and return metadata similar to that of plugins. Gutenberg’s Inserter could use that endpoint to also show relevant block plugins that are available to install, with a button and process for seamless installation. Some early sketches of ideas have been made, such as these:

(Note that these are all merely explorations and visual ideas, not set in stone)

It will be important to give users enough information about available blocks in order to make an informed decision – which might include the author, review ratings, and so on – without overloading them with too much information.

One key feature that might help improve the user experience is to allow users to insert a preview of the block into their document first, before installing the plugin, and then use the preview to make their decision about whether or not to install it.

Decisions to be made

As of now, there are some ideas sketched out and some general requirements as outlined above. There is work already on the block management feature, which is tangentially related. But there are many decisions yet to be made. Work needs to begin soon if this is to be ready in time for the WordPress 5.3 release later this year.

Some of the main design issues that need to be resolved include:

  • How and where to show search results within the Inserter
  • How to give users enough detail to make an informed decision about which block to install
  • What the Install process would look like
  • How to display a preview placeholder
  • How to manage installation requests by non-admin users

Get Involved

We are looking for a volunteer designer who can manage this project and commit enough time to see it through to completion in time for the 5.3 release. Responsibilities would include:

  • Solving the experience and designing the interface
  • Collaborating with other designers, soliciting feedback and reviewing submissions
  • Creating issues, wireframes, posts, and designs
  • Working with Gutenberg and Meta developers
  • Organising and running user tests
  • Iterating the design based on feedback and results
  • Meeting the deadlines to include the necessary changes in the WP 5.3 release

Given the nature of the work and the time frame, we expect that this is a project that will need a minimum commitment of at least a day a week, and possibly considerably more at times.

If you think you might be the right person for the task, please make yourself known to the Design Team during the weekly meeting, Wednesday 18:00 UTC in #design. Or alternatively, leave a comment below.

#block-directory, #design, #plugins, #ux