Building a design system from scratch
Scattered Sketch files, no tokens, no shared components, and a dev team re-implementing the same button in five different ways. I built the foundation (token architecture, component library, governance model, Figma-to-code pipeline) over 6 months while the product kept shipping.
The product was growing faster than the design foundation could support it.
At [Company], the product had shipped fast over the previous two years, fast enough that design consistency had never been prioritised. By the time I joined, the consequences were visible: the web app, Android app, and internal dashboard each had their own visual language, and no single person could tell you what the "correct" blue was. Developers were guessing.
The business problem wasn't aesthetic. Every new feature took longer to design than it should because designers started from a blank canvas. Every handoff sparked a back-and-forth between design and engineering about spacing, sizing, and colour values. Estimates were inflated to accommodate that rework. A design system wasn't a nice-to-have. It was a prerequisite for the product velocity the company needed at its current growth stage.
Every screen was a handwriting font: similar enough to confuse, different enough to break.
I started with a full visual audit before touching Figma. I catalogued every screen in production across web and mobile, [X] screens total, and logged every divergence in colour, type, spacing, and component implementation.
The audit revealed that the primary button alone had [X] different implementations across the codebase. Typography had no semantic hierarchy: developers were hardcoding font sizes. There was no light/dark theme strategy despite the product roadmap calling for dark mode in Q3.
I had to build the plane while everyone else was flying it.
A design system built in isolation is a design system that never gets adopted. The constraints shaped the entire approach:
- The product team could not pause feature work for a big-bang migration. The system had to be adopted incrementally, surface by surface, without disrupting live sprints.
- Engineering was split across web (React) and mobile (React Native). The token architecture had to work across both without requiring separate maintenance.
- No dedicated engineering resource was allocated for system infrastructure. Developers would adopt tokens as they touched components in their normal sprint work.
- The Sketch-to-Figma migration had to happen without dropping any fidelity on the existing design backlog. I could not invalidate work that was mid-handoff.
- Dark mode was a hard roadmap commitment for Q3. The token system had to be architected for it from day one, not retrofitted later.
The developers didn't need a component library. They needed a contract.
I ran 6 structured interviews with the engineers who would be consuming the system: two web, two Android, two iOS. I also reviewed 3 months of design-to-dev Slack threads to understand where the most friction concentrated.
The finding that shifted my approach: developers weren't frustrated by the absence of pre-built components. They were frustrated by ambiguity. When a spec said "use the primary blue," they didn't know if that meant the button blue, the link blue, or the brand blue: three things that happened to share similar hex values but had different semantic meanings.
"If you give me a component, I'll use it once. If you give me a token system with clear semantics, I'll use it forever, because it tells me the intent, not just the value."
Senior Frontend Engineer, [Company]The reframe. The primary deliverable was not components. It was semantic clarity. Components were downstream of that. I restructured the entire plan around tokens-first: get the naming, semantic layer, and theming architecture right before building a single component.
Three structural approaches explored. One built.
I pressure-tested these with the engineering team before committing any architecture.
Component-first library
Build a comprehensive Figma component library first. Define tokens as a secondary pass once the components were in use.
Adopt an open-source system (Material / Radix)
Map the product's design language onto an established system and piggyback on its token architecture and component logic.
Semantic token architecture, components second
Define the full token hierarchy (global → semantic → component-level) first. Migrate Sketch to Figma with tokens wired in. Build components on top of that foundation.
Tokens-first meant slower initial progress and faster everything after.
Committing to a semantic token architecture meant the first 6 weeks produced nothing visible to the product team. No new screens, no redesigned flows: just a naming convention document, a Figma variables file, and a token export format agreed with engineering. That required a deliberate expectation-setting conversation with the PM and engineering lead.
The trade-off I accepted explicitly: short-term invisibility for long-term zero-maintenance. I explained the compounding return: every component built on top of a token system is automatically theme-aware, accessibility-compliant to our contrast ratios, and consistent with the rest of the product. Every component built without it needs to be manually reviewed on every design change.
The system shipped in three phases: (1) token architecture and Figma variables, weeks 1–6, (2) core component library (buttons, inputs, navigation, cards, notifications), weeks 7–18, (3) documentation, governance model, and contribution guide, weeks 19–24.
What the system looked like when it shipped versus what I designed.
The initial component backlog had [X] components scoped. What shipped in v1 was [Y]: the highest-frequency, highest-divergence components identified in the audit. The long-tail (data visualisation components, complex form patterns, admin-specific layouts) were documented as backlog with severity ratings so whoever came next could prioritise intelligently.
What shipped in v1. Colour token system (light and dark), typography scale (8 semantic levels), spacing scale, grid system, icon library migration, core components: Button (6 variants), Input (text, select, checkbox, radio), Navigation (top bar, tab bar, side nav), Card (3 variants), Modal, Toast/Notification, Badge, Avatar.
What didn't. Data table components, chart theming, the admin dashboard surface, and the onboarding wizard pattern. These were scoped for v2 with full specifications drafted, not abandoned.
Governance. I wrote a one-page contribution guide covering how new components get proposed, reviewed, and merged into the system. This was the piece I spent the most time on and the piece I'm most proud of: a system without governance is just a snapshot that decays.
Measured 3 months after full adoption.
"One update reflects across all instances instantly. Before the system, changing the primary button colour meant a find-and-replace across [X] files and a week of QA. Now it's a token value change."
[Engineer Name] · Frontend Engineer, [Company]What I'd do differently. What I'll carry forward.
What I'd do differently. I underinvested in the adoption story. I built the system correctly but assumed that quality would drive adoption. It didn't. Engineers adopted tokens when it was as easy as not adopting them. I should have spent week 1 building the integration tooling (linters, Figma-to-token export scripts) alongside the architecture, not as a follow-on.
What I underestimated. The governance model. I shipped a contribution guide, but I didn't define a clear process for deprecating components. Six months in, the system had accumulated [X] "experimental" components that were in production but not officially supported. Deprecation is as important as creation.
What I'll carry forward. Semantic naming is a forcing function for design clarity. If you can't name a token semantically, if the only accurate name is a raw value like "blue-500", it's a sign you don't yet understand the token's intent. I now use token naming as a design review step, not a developer task.