A design system that actually matched the code

Context

Addressfinder is a New Zealand and Australian address-autocomplete and data-verification SaaS. They had a modern, clean public website but their customer portal looked like it belonged to a different company: dated, off-brand, disconnected from the polished front door.

This was a freelance engagement, July to September 2025, scoped through an SOW rather than a permanent role. The newly appointed Head of Product is a capable designer but was stretched thin with no design-system foundations to lean on. Their Figma was a mix of screenshot crops and rough mockups, so developers were left guessing what was intended, and work kept slipping. The brief was to give them foundations that would let the team move on their own without quality falling over.

The problem

The portal needed to be redesigned to match the website, but the team couldn't move because nothing in design reflected what actually existed in the build. Designers worked in one language, developers in another, and the gap between them was where time leaked: back-and-forth over what a component was meant to be, delays while someone interpreted a screenshot crop, inconsistency creeping in because there was no single source of truth.

So the real problem wasn't "the portal looks dated." It was that design and code had drifted apart, and no shared system existed to pull them back together.

My role

This was a solo build, but it ran in close contact with the team, so I want to be precise about what was mine versus theirs.

Mine end-to-end: the audit of their existing site, the token architecture, the full component library and its documentation, and the handover that set the team up to maintain it.

Theirs: the Tailwind codebase I aligned to (I matched their conventions, I didn't set them), and the eventual portal redesign itself, which my system was built to enable rather than something I delivered.

The decision I'd point to as most mine was anchoring the entire system to their existing code rather than designing in a vacuum and asking developers to catch up. That's the choice that made the whole thing usable.

Approach

I started by auditing what they already had, using browser dev tools to read how their key pages (homepage, pricing, contact) were actually built in Tailwind. That mattered: instead of inventing a token scale and hoping developers would adopt it, I could see their real spacing, colour, and type values and build the system to match what was already shipping.

I recreated their website components first, before touching anything portal-specific. That was the test. If I could rebuild what already existed and have it match perfectly, I knew the system was sound and could extend to the portal with confidence. Only once the foundation held did I expand into the components the portal redesign would need.

Collaboration & method

The token architecture was a three-tier model: primitives, then aliases, then semantics. Concretely, spacing-4 = 4px becomes space-xs = spacing-4 becomes card-border-radius = space-xs. The payoff is that a change to card corners is one edit to a semantic token that cascades everywhere, rather than a hunt through the file. I ended up with 240+ design tokens and 85+ components, covering all the real states (error, success, disabled) across light and dark modes, plus patterns and templates.

The thread running through all of it was design-to-code alignment. Their developers were already fluent in Tailwind, so I matched my token names and spacing scales to their conventions exactly, which meant no translation friction when they built: the thing in Figma and the thing in code were the same thing, named the same way. This is the same conviction I carried into later work on machine-readable design systems: a design system earns its keep at the seam between design and engineering, not in how tidy the Figma file looks on its own.

The last piece was handover. I walked the Head of Product through how the system worked and documented not just what I'd built but how to think about adding to it without breaking it. The goal was genuine autonomy, not a pretty library they'd be afraid to touch.

Constraints & tradeoffs

• Anchor to the existing build, not an ideal. I constrained my own design choices to their real Tailwind values rather than proposing a cleaner-slate system. Trade-off: less freedom to "improve" the foundations, accepted because a system developers can adopt with zero friction beats a more elegant one they have to reinterpret.
• Recreate before extend. I rebuilt their existing website components first as a correctness check before designing anything new. Trade-off: slower to visible portal progress, accepted because a foundation that's subtly wrong poisons everything built on top of it.
• Document for independence, not just delivery. I spent real time on documentation and a walkthrough rather than just shipping the file. Trade-off: more of the engagement spent on enablement than on raw output, which was the actual point of the brief.

What shipped

A complete, documented design system in Figma: 240+ tokens in a three-tier primitive/alias/semantic structure, 85+ components with full state and light/dark coverage, plus patterns and templates, all mapped to their existing Tailwind setup. Alongside it, documentation and a process for the team to add new components themselves, and a walkthrough handover with the Head of Product.

Outcome

The portal went from looking like a different company's product to matching the polished website, with consistent branding throughout.

On speed: the Head of Product told me directly that the team was designing roughly 30 to 40% faster, because they could pull components instead of building from scratch. I want to be honest about the basis: that figure is her estimate from working in the system day to day, not a formally measured study, and I'd present it that way.

The clearest signal to me wasn't the percentage though. It was that the Growth Marketer, not a designer, could put together his own page mockups without waiting on design support. When a non-designer can work independently in your system and stay on-brand, the system is doing its job. And because the components matched what was actually in the code, the guessing games between design and development stopped: everyone was finally working from the same source of truth.

Reflection

The thing I'd carry forward, and did, is that auditing the real codebase first is what made this work. It would have been faster in the moment to design a clean token system from scratch, but it would have created exactly the design-versus-code drift I was hired to fix. Matching the system to the build is slower up front and pays back every sprint after.

If I were doing it again I'd push harder to get a lightweight way of measuring the speed improvement in place at the start, so the headline outcome rested on data rather than a well-placed estimate. The work was sound; the measurement of it could have been tighter.

What this proves

I build design systems as engineering-aligned infrastructure, not decoration. I'll constrain my own design freedom to match the realities of the codebase, I architect tokens so changes cascade instead of multiply, and I measure success by whether the team can work without me, including the non-designers. This is the foundation the machine-readable, AI-context design-system work I do now is built on.