How we improved our project and file structure in Figma
How the Onfido design team structured our projects and files in Figma to optimize for discovery, portability, and product autonomy.
Like many design teams, Onfido made the transition from Abstract + Sketch, to Figma in the last couple of years. One of the common resistance points internally before making that switch, was Figma’s lack of Git-style branching that Abstract enabled. The design team had come to rely on branching and had built a lot of our processes around it.
During the transition we tried to structure our files, projects, and design system in a way that would help maintain some (though not all) of the benefits we got from branches.
I hope some of the ideas here spark inspiration for ways you could improve your project and file structures, however keep in mind that this system was designed for our specific needs (yours are probably different) and that these decisions should change over time in a culture of continuous improvement. I highlight some of our learnings at the end of the article. As always, your mileage may vary!
Structure
We are on a Figma Organisation plan, and structure our teams in a way that roughly maps to our cross-functional product teams.
Each team has three main types of “projects” (folders, if you prefer):
Source files
Work in progress (WIP)
Archive
Source files
A source file is like our main
branch. They are one or more files that contain a reasonably up to date version of each screen in the product, and typically not a lot more. We try to keep these files as slim as possible, with as little screen duplication as possible. We do this to reduce the impact of breaking changes further down the road, and to simplify manual effort when merging.
The rule of thumb is that if someone can look at a screen in the live product, and put together an accurate version of that screen in Figma in under 2 mins, then what’s in the source file is enough. We don’t need an exhaustive lists of all the error states for a form, as long as there’s one solid example of what an error looks like.
These files are often the starting point for design work on existing products. Streamlined source files enable us to quickly duplicate flows and have them be immediately useful without a lot of busy work removing edge and error cases.
Work in progress
This is usually where the Figma part of the design process starts. We have a project template file which specifies a basic page structure, and a standardised cover sheet. This will be copied into the work in progress folder and named with the project name, and JIRA ticket number where applicable.
This file acts as our branch. Branching is unfortunately very manual right now, but not too difficult at our scale of two to three designers per product.
Screens are copied from the source file (which should be up to date), and design exploration is done from there. Our template specifies an Exploration
page, which carries the expectation of no pre-defined structure, as messy and exploratory as the designer wants to be. We don’t critique people’s exploration pages.
We also specify a Handoff
page, where engineers know to look for final screens, design specs and flows. Redlines (using Figma Measure), and custom annotation components are commonly used here.
Between those two pages, the designer can add as many pages as they need. Typically these progress in order, and new pages are often created at points where feedback is required. We’ll limit pages to only the stuff we want feedback on, so design dead ends and exploratory screens don’t distract people away from what you need actual feedback on.
UI kits
In our design system team we have a UI Kits
project. These UI kits contain any commonly used UI components that are more product-specific than our Design System supports. Each product has a UI kit that’s owned and managed by that product team.
A note on naming: You’ll see the UI kits have an 05
in front of their name. This is part of our design system’s naming convention that I’ll dig deeper in with another article. We use this numbering system throughout our files to keep libraries in a consistent order in the library panel. Themes first, then assets, components, patterns, and UI kits.
When it comes to how we structure our files, one of our few hard rules is:
WIP and Source files should not contain any local components
The reasons we do this are to:
Reduce library management noise
If every WIP or Source file is published as a team library, trying to find the right libraries to enable/disable to get a particular version of a particular component becomes a nightmare very quickly.Make all screens easily portable/reusable by designers
If local components are in a file, but aren’t published as a team library, when someone copies a screen to another file, all links to that main component are lost. The result is an orphaned instance that doesn’t update when the main component is updated because changes aren’t published & pushed. This is totally invisible to the designer, as it visually appears like a standard instance.
Merging
Once a design has been approved and development is in progress or completed, the new screens will be copied back to the Source file, replacing existing screens where necessary. Because no published components exist here, screens can be replaced safely without worry of affecting other work in progress.
For changes in UI kits, components will often be labelled as [BETA] while in progress, or given a version number, or something similar that lets us manage multiple versions of a component existing simultaneously while the work is in progress. When the screens are merged and we want to clean up those UI kit duplicates, we will follow the process here: How to deprecate old components in Figma design systems.
Archiving
Once complete, the work in progress file has the cover status changed to Archived
and it is moved to the Archive folder. The archive then acts as an easy way to see the process behind a piece of work, the comment discussions, and document experiments and directions that could potentially be drawn on later.
Things we’ve learned so far
Cover status badges are a huge pain to maintain and keep up to date. No one remembers to change them to the right status, so they’re effectively useless. Occasionally we’ll do a big batch-change of everything in the Archive folder, as having these visibly well marked is really beneficial for searches. Some kind of background API integration that synced files with JIRA in real-time would be amazing here. *dreams*
There can be some confusion around what the right level of detail is to keep in a source file. We suggest keeping an open mind, and working with your teams to find the right balance for each team, as their products may have different needs.
Figma’s new Branches feature does not really meet our needs as it is currently designed. Once merged, the process part is a lot more hidden and difficult for others to find than our archived files. That archival side may not be an issue for you, which is fine. The other issue is that our styles and components live in separate libraries. If we need to make a change that includes both a style and component change, that can‘t be done in a single branch. There’s also no good way of testing the effect your branch changes will have on linked instances in other files right now. Again, a multi-file branch system would solve these.
Having a JIRA ticket number in file names is really useful for search, however search only returns results from teams you are a member of, making cross-team discoverability a lot worse than it should be. This is especially true for larger orgs with more teams, or stricter permissions than we have (anyone is free to join any team at Onfido).
I hope that’s sparked some ideas about how you could structure your own teams and files. If you have any questions, or there are things you’d like to see deeper dives on, please reach out on Twitter or find me in the Design Systems, or Friends of Figma slacks.
Thanks to Mark Opland, Raemarie Lee, and Luis Ouriach for helping make this article better.
Originally posted on Medium.