New handbook page on WordPress components

There is now a page in the handbook that explains both what WordPress components are and also how to add and edit them.

WordPress Components are the set of interface elements that make up the Block Editor and other projects. This includes several user interface (UI) components like buttons, menus, and text fields. 

As a team, using these components is going to become essential to our work. Having a clear handbook page should help everyone.

A bonus extra workflow on how to get Figma access also now exists to go with this page.

Just like any handbook page, this should be a living document, so if you feel something needs adjusting please comment or start a discussion in #design on Slack.

#wordpress-components #handbook-update

Project: Reviewing WordPress Components

What are WordPress Components?

Put simply, WordPress Components are the set of UI elements that make up the Block Editor and other projects. You can find them in the Gutenberg GitHub repo or in the Block Editor Handbook.

As I’ve mentioned in our team chats over the past few weeks, I’ve been working on reviewing WordPress Components. To help make sure as many people can be involved as possible, I’m summarizing the work so far in this post.


Along with a new editing experience, the Gutenberg project has created a growing library of UI components like buttons, menus, and text fields. Although these components were introduced with the Block Editor, they’re generic enough to be useful in various contexts outside of it. I hope that we see them being used more throughout WordPress.


There’s an opportunity to make sure these components are flexible enough for all WordPress experiences, not just the Block Editor. In a related issue on GitHub, @matveb mentions that the components are now at a point where they can be re-examined in a long-term, holistic way. I think the Design team can help with that.

There’s one focus in particular where we can have an immediate impact — a component review.

Component review

A component review is what I’ve been focusing on the past few weeks. It’s a check of each component to evaluate naming, properties, and documentation. I’ve also noted gaps that could prevent the components from being useful. While this review isn’t necessarily visual design, it does help provide design guidelines for future work.

Specifically, this is what I’ve been checking and documenting:

  • Naming, composition, structure, and visual properties (e.g. “size” and “appearance” options for Button).
  • Expanded guidelines for design, development, and accessibility.

For more information on the basics of one of these reviews, and for some examples, check out the links under “How to get involved”.

How to get involved

Ready to get started? There are a couple of different paths to choose from:

  1. Design and Semantics: the most immediate need is feedback on the issues in the “Needs feedback” column of the GitHub project.
  2. Documentation: be on the lookout for issues labeled with “[Type] Documentation” in the coming days.

Right now the review aims to just get the basics right, but the Gutenberg project and its components are an opportunity to inform the future design of WordPress. Some discussions that started in the Gutenberg project have been a catalyst for change in the rest of WordPress. For example, icons that were designed for the Editor sparked a discussion to revamp Dashicons, the icons used in WP Admin. If you want to have an impact in this way, the component review is a great place to start!

I hope this excites you as much as it excites me! Please leave a comment on this post or join the #design Slack channel if you have any questions.


Discussion: How do we organise Figma libraries?

During Wednesday’s design meeting, the design team started discussing how to better organise Figma libraries.

The problem

Because the WordPress Components (aka “WordPress for Figma/WP5.0_Library”) file has been expanding on an as-needed basis, the file is beginning to get a wee bit messy. It’s turned into something of a grab-bag of different elements: logos, colours, Gutenberg UI, wp-admin UI, icons, type styles…

There isn’t a consistent structure to the components and several different naming conventions are in place. As the library grows and expands, it’s likely this problem will get worse.

The solution

By establishing shared guidelines for how the design team organises, builds, and adds new library components and resources, it will be simpler and more straightforward for all design contributors to find what they’re looking for or contribute new patterns.

This breaks down into three different improvements:

  1. Splitting one library into a few smaller libraries.
  2. Establishing naming conventions for components.
  3. Establishing an organisational structure for components.

Once an approach is determined, the design team will document these guidelines in the Figma files themselves as well as in the handbook, so they’re easily findable.

Let’s dive into the details!

#figma, #wordpress-components