Canonicals Figma libraries

Instead of diving in headfirst, the process started by understanding how the team actually used the libraries and where the problems were. I surveyed how designers use components, gathered feedback on problematic components in the old libraries, and organized meetings with the team to understand their needs.

The survey and feedback revealed a few important things. The biggest frustration was the baseline alignment spacing baked into the old components. Vanilla, Canonical’s CSS framework, implements a baseline alignment mechanism that adds spacing nudges to text. The old library had this built into every component, and it turned out to be one of the biggest drivers of detachment. Designers would detach components just to remove the baseline spacing.

We also found that designers often had trouble finding the component they were looking for because they could not remember the exact name. They would search using synonymous terms and come up empty. This was made worse by the fact that most designers primarily use the assets panel to find components, where search is the main interaction. Both of these findings directly shaped how we built the new libraries.

I then did extensive research into best practices for building scalable libraries. I explored approaches from other design teams like Doctolib and articles on library architecture by Nathan Curtis, particularly his concepts on design system tiers and how they could apply to the diverse product ecosystem that Canonical has.

Based on this research and the team’s feedback, I drafted an initial specification and then organized five collaborative writing sessions where the team went through every section together. The result was a 20-page specification covering library architecture, component building guidelines, contribution processes, naming conventions, and component lifecycle management.

The spec established four library types (Assets, Core Components, Domain Components, Utilities) rather than one monolithic library. It set performance focused rules around layer counts, a soft limit of seven properties per component to avoid overwhelming the properties panel, and a PR-like contribution process where libraries are read-only for the team and changes go through review before a library manager merges and publishes them.

The most contentious discussion was around baseline alignment. Some designers were adamant about maintaining it in Figma. Others, pointing to the detachment data, wanted it gone. The compromise we landed on was a Figma mode where baseline alignment is off by default but can be enabled when needed. This satisfied both camps. We also debated how many libraries to create. There was concern about ending up with too many. The compromise was to co-locate foundational elements like color, type, and spacing with the core components for now, keeping the number of libraries manageable while leaving the door open to separate them later if needed.

Before releasing the libraries more widely, I recognized that better metrics were needed than what Figma natively provides. Figma’s built-in analytics were insufficient for the team’s needs, so I developed a custom metrics tool, taking inspiration from approaches shared by the Pinterest and Uber design teams in their public materials. The tool is a TypeScript script that runs in a GitHub Action, generates a JSON file of library usage data from the Figma REST API (using the tracking pixels baked into each component), and commits it to a repository. A small website then reads this data and displays it as visualizations. This gave us the ability to track component usage frequency, library adoption rates across teams, and most importantly, component detachment rates, which told us which components designers were frequently modifying and therefore needed improvement.