A design system that put design and code back in sync
What looked like a styleguide was really entropy: every developer adding their own hex. I built a tokenized system in parallel with delivery, without stopping the product, and turned it into the single source of truth between what's designed and what ships.
The problem: every developer had their own color
What I found looked like a styleguide (a page of colors, fonts and buttons), but it was a visual guide, not a system: vague labels, no component names, no usage rules, nothing ready to be consumed by development.
The decision: build the system without stopping the train
Delivery couldn't pause to "tidy up", so I built the design system in parallel, a project inside the project. One premise: it would be built for development to consume, not to organize Figma.
Each token was documented twice over: first its grammar, then its full spec, with the code reference sitting beside the visual:
type · name · variation → font-heading-h1. A naming convention, not a nickname.
color-primary-green, #1ABC9C, the H1 sizing) beside the visual.The tool migration was part of the system
The project lived in Adobe XD, capable, but a poor collaborator for shared libraries and handoff. I moved it to Figma: a system only works where the whole team can consume it. A second designer joined to accelerate the build.
The proof: when the dev library changed version
The real test came when PrimeNG migrated to a new version: the team updated its components against the design system, not the chaos.
Today, what's in the design system is what's in the code.
Outcome
1 source of truth
Between design and development, in use to this day
XD → Figma
Tool migration carried as part of the system
PrimeNG synced
The system survived a full version migration of the dev library
Outlasted the team
The knowledge lives in the system, not in one person's head
Shorter handoff, less front-end rework, and UI decisions that no longer restart from zero each feature, because the system makes the invented color and the duplicated component impossible.
What this project taught me
That a design system isn't a design deliverable: it's team infrastructure. Its value isn't in the pretty documentation pages, but in what it makes impossible: the invented color, the duplicated component, the style that exists on only one screen.
The right moment to build one rarely exists. I built ours in parallel with delivery, under pressure, without a formal mandate, because the alternative was watching the debt grow.
In hindsight, it was one of the highest-return decisions of the whole project.
