Improvements to the Figma Libraries

The Design Team is in the process of updating our WordPress Figma libraries. For those that aren’t aware, these design files provide community designers and developers creative resources to help build their projects using the latest WordPress design patterns and elements.

While there have been past efforts to keep these maintained, we’ve been iterating and adding new features faster than we can update them. Also, these haven’t been given a consistent priority and focus. As a result, these files have lost alignment and in many cases, relevance.

Below is a summary of where we are currently, and where we’re looking to go. I’d like for us to consider what would be most helpful for us in terms of how they’re organized, as well as how we contribute to them. I’ve included some starter discussion with topics from previous discussions (here’s a post from last year).

Keep in mind: the goal for this initial phase of work is to establish direction and make meaningful progress without overthinking the process. We want to be able to start addressing concerns now, but also keep our sights set on the longer-term goal. A


Lack of Discoverability & Structure

It’s hard to find what you’re looking for and lacks accommodation for varying use cases.

Lack of Consistency & Trust

Due to the velocity of iteration and exploration by both designers and developers, without a workflow in place to regularly fact-check, these files can very quickly grow out of date.

Lack of Standardization

While we want to stay flexible to accommodate the fluid nature of designing and exploring, we’d like to have a standardized structure for our components to assist with intuitive and rapid iteration.


Create a flexible and well-structured Figma library that fully mirrors our code base components; is consistently, meticulously and collectively maintained; and is scalable with the increasing velocity of iteration and explorations by both designers and developers.


  • Establish a mutually shared and understood structure for the Figma library.
  • Establish and maintain appropriate workflows for tagging and managing Figma changes.
    • Determine how proposals are handled in Figma.
    • Determine process and cadence for tagging and tracking changes in GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner., and aligning those changes with Figma.
    • Determine process and cadence for transferring design decisions from other Figma files.

Let’s look quickly at how we’re currently structuring our libraries.


The goal of these libraries is to provide contributors an easy and effective way to build prototypes and explore new ideas, using the latest WordPress design patterns and standards. This means making sure things are easy to find (good library structure), understand (proper documentation) and use (building the Figma components that make it easy to explore ideas).

Current Structure

Our libraries are available as 3 separate Figma files:

  • Styles – The coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. qualities of elements (i.e: color palette, typography).
  • Components – The smaller elements/building blocks (i.e: buttons, tabs, the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. toolbar)
  • Patterns – Groups of components (i.e: block inserter, side panels, navigation)

Each Figma file uses pages to help with organization. In addition to the page(s) containing the main elements of that file, we’ve included other pages that help with more process-related functions:

  1. Getting Started – Documentation around the use of the elements
  2. Proposals – Ideas/changes that can be shared with and considered by the Design Team
  3. Deprecated – Elements that are no longer in use

The current structure seems to work okay for the most part. However, it’s possible that co-locating these elements into a single library; a single source of truth could help improve discoverability (everything is together so you don’t miss anything) and overall usability (having to jump back and forth between files can be tedious and unnecessary).

Move to a Single File?

It’s a good question, and worth the consideration. There are a few benefits to a single file approach:

  • Elements live together in one file. No need to share several links to multiple files, or risk the visibility of those links by stuffing them in the Getting Started documentation.
  • The library can become the one source of truth without the risk of an element in a related library going rouge.
  • Visually, a single file gives a holistic view of the patterns and elements.
  • In terms of the published library, the structure of components are handled similarly, making both approaches equally usable.

Another case for moving to a single file is that two of our three libraries are pretty sparse. For example, the Patterns library only has a single page in the library where the elements live (the Getting Started page can be ignored as it’s a duplicate of what’s in the Components library). Since the elements here are just grouped components, it would make sense for them to live alongside their other parts.

In terms of other aspects of a single file experience:

  • Documentation from the Getting Started pages would be brought together into a single read.
  • All of the Proposals pages would become a single location where contributors can propose changes.
  • The Deprecated pages would be removed entirely, or elements therein relocated to another file. It’s important that we only keep the relevant elements here, as we work towards a source of truth.

Here’s what that would look like:

Here, the Patterns library becomes its own page. The Styles library breaks out into its own pages (or possible into a single page). And with a better build-out of patterns, it’s possible to create an additional page called Views where patterns are put together to form some of the more common views within WordPress (like the editor view, dashboard, etc.).

Altogether, we’d have four types of elements living in a single location:

Circling back to our objectives, achieving good structure get us half the way there. The other part is making sure library elements are updated and managed sufficiently.


Maintaining a design library is never a one-and-done effort. It takes consistent effort and prioritization. To avoid repeating past frustrations, we need implement practices that are clear, easy to follow and involve everyone. We all need to champion Regardless of , our focus should be on two things:

  • Keeping these libraries aligned with components in GitHub.
  • Keeping these libraries up-to-date with approved proposals, as well as design decisions made within other Figma files.

All of these processes need to be a part of a collective undertaking. Each designer working on a given project involving visual updates/additions to components should find responsibility for updating these libraries, or at the very least communicating the request. Without a unified effort, much like past attempts, this too will falter.

GitHub Updates

The designer working on a given feature/component should update the Figma library accordingly, or address the commits with the label “Needs Figma Update” added by others on their respective projects.

Adding/changing components:
  1. Contributor makes a visual change to a GitHub component.
  2. Contributor tags the commit with label “Needs Figma Update”
  3. Designer closest to the effort/project updates Figma library.

As a backup initiative, the team could/should tackle this label via a weekly triage.

Explorations & Proposals

Contributors have the ability to propose changes to components and design patterns, or suggest new ones from within the library.

Making a proposal:
  1. Create or revise a component and add it to the Proposals page for discussion (via Figma comments). During this phase, feel free to work on the component until the component is finalized in the GitHub repo.
  2. Iterate on the component until it matches the coded component.
  3. Once the coded component has been finalized, it’s time to review the Figma component and prepare it for publishing. The Design Team will review the component to ensure it meets standards, requesting edits where necessary.
  4. Once approved, and after the code component has been released to wordpress/components, the Design Team will merge the component into the master Components page.

Share Your Thoughts

If you’ve been using the WordPress Figma libraries and would like to contribute to the current direction, please share your thoughts below. Specifically, we’d like feedback on:

  • Do you like the current approach of having separate files for each library, or should we pursue a more unified approach with better workflow and organization?
  • Any other ideas you feel would help improve the way we organize and maintain our design library?

A big thanks to @mapk and @ibdz for their assistance with the content and formatting of this post!

#figma, #wordpress-components