Why instance counts don't tell the full adoption story

Most design systems teams measure success by looking at code. At Pinterest, the Gestalt team ships web components for engineers, so tracking how many of those components make it into production code is a familiar kind of metric. Code-based measurement is concrete: whatever ships ends up in the codebase, so it is a reliable place to inspect usage.

But code adoption has limits, and two in particular stood out for the Gestalt team. First, it only works on web, since Gestalt's engineering team only ships web components while design components serve iOS, Android, and web. Second, it lags: a brand-new component can take a while to show up in production, and if designers have not used it in Figma yet, movement on the metric is slow.

Code adoption does not tell the whole story. Adoption starts in the design phase, in Figma — yet Pinterest's design systems team had little visibility into what was actually happening inside its Figma files. Without that visibility, the team couldn't answer questions like: are designers even reaching for Gestalt components? And if so, how much of a given design is actually built from the system?

Defining design adoption

Figma's built-in library analytics report component instances and insertions. Those are raw counts, which are hard to interpret: getting 245,123 instances of a button sounds good, but is it? Consider a large file with over 1,000 nodes, only 10 of which come from the Gestalt library. That file shows component usage but only 1% of the design is built from the system. What the Gestalt team wanted was a relative measure: the proportion of a design that uses library components compared to everything else on the page.

Pinterest's Gestalt design adoption score is calculated per frame. If a page has 15 layers and 7 originate from the Gestalt Figma library, the score for that page is 7 ÷ 15, or 46.6%. Scores are tallied frame by frame to reach a file-level figure, and from there a team-level and organization-level picture.

FigStats: measuring at scale

Pinterest has eight design teams shipping across Android, iOS, and web, with designers touching hundreds of files weekly. The first thought was a Figma plugin that designers would run manually — but that would have created a separate plugin adoption problem. The better route was Figma's REST API, which lets you pull file data without involving designers in the measurement itself.

The team built FigStats, a service that runs nightly across all of Pinterest's Figma files. It tallies totals and computes an adoption percentage for the whole organization, with the ability to drill down from organization level to a single file. The dashboard shows not just adoption scores but the composition of files, giving context on how individual files influence the total.

Beyond components, FigStats also checks how designs use text and color styles, flagging one-off hex codes or off-brand fonts as losses for the system.

Boundaries that keep the metric honest

Figma files are noisy. They accumulate hidden layers, unused nodes, and stray text. In the last year Pinterest had 1,853 active Figma files — too many to scan indiscriminately, and old files would drag the metric down even if everyone adopted Gestalt tomorrow. So the team set two hard boundaries on the measurement:

  • Files edited in the last two weeks. This keeps the measure rolling and reflects how new designs handle adoption.
  • Pages marked "handoff." Figma files contain scratchpads and explorations, but handoff pages are curated and typically the only part of a file that gets built.

Handoff pages are a deliberate choice: designers tidy them before sharing with developers and stakeholders, so they are the best proxy for what is about to become product.

From metric to action

A year ago, the Gestalt team's insight into Figma activity was mostly survey feedback. With FigStats, they have quantitative answers about where designs happen and what goes into them. The team is still experimenting with how to weave the metrics into its broader design operations story, but three use cases have emerged:

  • Adoption: Understanding where components are used (or not) reveals where the system is easy or hard to work with, and can pinpoint teams that struggle to incorporate it.
  • Quality: Cloud linting checks file hygiene, such as whether text nodes use text styles and whether fills come from style tokens rather than hex codes. Since Figma's API can't edit files in the cloud, the team is building a companion plugin for designers to clean up files locally.
  • New components: When designers build local components and reuse them across files, that pattern now shows up in the data. Enough distribution is a signal the design systems team should consider promoting that component into the official Gestalt library.

Design adoption works as a complement to code adoption. The team saw that PageHeader had low adoption measured in code — they traced that back to a limitation in the code component. But FigStats told a different story: designers were actually reaching for the component. The pair of metrics gives a fuller read on system health than either alone.

Running it yourself

The Gestalt team has open-sourced the calculation in the figma-calculations npm library, and there is a REPL available for trying it out with your own Figma API token and team IDs. Expect processing to take a while across all your team's files. When gaps show up between teams — say, 50% adoption in one group and 2% in another — those are the files worth opening to see what successful teams are doing differently.