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.

1. Splitting up into multiple libraries

Splitting one big library into a few smaller libraries could help to keep things structured and organised by ensuring components are organised according to their purpose.

Here’s a suggestion:

  • Foundation → The core elements that make up visual design across the project. These are design tokens (like variables, but for design!) and core styles that don’t change often once established.
    Colours, type styles, icons, spacers, etc.
  • Components: The smallest UI components, broken down into pieces. Ideally, this file would be a direct mirror of the @wordpress/components package in terms of naming, structure, and content.
    Buttons, inputs, checkboxes, etc.
  • Patterns: Larger patterns made up of individual UI components combined.
    Blocks, navigation bars, Gutenberg’s sidebar, etc.

You can think of this as a progression, with foundation containing the smallest core tokens, components making use of those tokens to create discrete UI elements, and patterns containing compositions of those elements:

Prefixing these all with “WordPress:” so it reads “WordPress: Components” or “WordPress: Patterns” may make it easier for users who belong to multiple Figma organisations.

There’s also a “Utilities” library that stores things like Figma covers, sticky notes, and diagram and wireframing components, but let’s discuss that later.

2. Establishing naming conventions

Components should ideally use the same naming conventions. Right now, components are a bit all over the map:

  • Core/Publish-Title/Save_Draft
  • 1_New_Post_Shell
  • wrapper/admin-nav/default-state
  • button/blue
  • Icon/More-Options

Let’s agree on a shared approach. Here are some options to consider:

  • lowercase-with-hyphens: Easier to type, harder to read. Creates good file names when exported. Matches folder name in wordpress/components package, but not component name.
  • Title Case With Spaces: Harder to type, easier to read. Matches how WordPress tends to use capitalisation of labels in the interface (Title Case, not Sentence case). Matches component names in wordpress/components more closely, but not exactly.

3. Folder structure & organisation

This one is going to be the trickiest!

Here are some options:

  • Forward slash naming (Buttons/Contained/Hover): This is the method Sketch uses. It can result in longer component names and can be hard to find individual components in the library file since they’re all on one page.
  • Pages and frames: Use Figma pages and frames to define top-level organization for components. Components can be found via the headings and collapsible subheadings in Figma’s asset panel..
  • Combination of the above: This would allow us to reap the benefits of both the above approaches. Component names might still end up long, but they’d be better organised and it would remain clear what component you’re using at a given time.

Ideally, the design library should be as close as possible a mirror to the code it represents. This establishes a shared mental model between devs and designers, making it easier to communicate and know everyone’s talking about the same thing.

With that in mind, it’s worth noting that the @wordpress/components package is a flat structure, with all components at the top level. A more aspirational approach to library organisation could be required here so that it’s easier to find things.

Further reading

Figma provides some guidelines and best practises for shared component libraries.

What do you think?

Have you been using the Figma library? The design team would ❤️ your feedback!

  1. Should the library be split into three smaller libraries? Do the three libraries suggested here seem logical?
  2. What naming convention makes sense for components?
  3. How should the libraries be structured?
  4. Is there anything else the design team can do to make these resources easier to use?

Please share your feedback by Wednesday, 22 March, and the design team will determine next steps in the weekly meeting.

#figma, #wordpress-components