A component library used by multiple product teams, with no token architecture, no clear categorization, and no governance — rebuilt from diagnosis to a scalable foundation.
The company had a component library in Figma shared by several product teams, but with no consistent token architecture, no clear component categorization, and no defined governance process.
In practice, this meant constant rework, visual inconsistencies between products, and friction in the collaboration between design and development. Each team ended up solving the same problems in a different way.
I led this work over three years, together with the design and development team, combining four fronts:
Technical audit of the existing structure, qualitative research with Product Owners and developers, defining a token architecture in three layers, and reorganizing the library following scalable conventions.
An initial audit of the library revealed gaps concentrated in four main areas.
Many components didn't cover the variations the platform actually used day to day, which led the team to rebuild pieces from scratch for every new screen.
Colors, spacing, and styles were applied directly on screens, with no link to any token. Any global adjustment turned into manual work, repeated screen by screen.
No layered structure (primitives, semantic, component), which made theme support (light/dark) harder and created inconsistency between screens.
No clear conventions for page organization, naming, or what should (or shouldn't) be published for teams to consume.
Systematic review of the current library, identifying gaps in naming, component metadata, token coverage, accessibility, and consistency — organized into a four-phase, prioritized action plan.
Semi-structured interviews with Product Owners (1:1, 30–45 min) and developers, using open, behavioral questions. I avoided "defending" the library during these conversations and used silence as a tool, leaving room for pain points to surface organically.
I defined a three-layer structure in Figma Variables, with the rule that components reference the semantic layer exclusively — never the primitives directly — ensuring theme changes propagate predictably across the whole system.
I switched to Figma's native Sections — instead of plain frames — organized into five component categories, and created a Foundations page covering color, typography, spacing, elevation, border radius, and grid/breakpoints, with a clear split between what's published and what's internal documentation.
Content still in progress is now prefixed with an underscore (_) so it's automatically excluded from publishing.
Master Pages: standard pages built on top of the library to cover recurring platform needs — each one assembled entirely from Core Library components.
Three decisions carried most of the weight, and they held up the final result more than any specific tool.
Instead of treating any screen-specific visual element as an exception, I set the rule that everything appearing on the platform should become a component or widget in the library, even patterns used only once. This removed the recurring "is it worth componentizing this?" decision from the team and made the library's coverage predictable.
Whenever a pattern showed up in more than one context, it was generalized to work across the whole platform, instead of getting its own version for each product. This cut down on near-duplicate components and kept the library simpler to maintain.
No color, spacing, or style value could be applied directly to a screen. If a use case had no matching token or component, the answer was to create one, not make an exception. This rule, more than anything, kept the token architecture intact over time.
Three years in, the clearest effects showed up less in isolated numbers and more in how the teams started working together.
Less time spent recreating pieces that should already exist in the library, which sped up design work and development delivery.
Product Owners and Product Managers came to understand the components and how they work better, which made handoff conversations more direct.
Greater connection and transparency between teams, with a shared language for discussing the system instead of different interpretations of the same screen.
People joining the team could find their way around the library much more easily, since it became predictable and easy to navigate.