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 November 2025, scoped through an SOW (not 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. 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. The team couldn't move, because nothing in design reflected what existed in the build. Designers worked in one language, developers in another, and the gap between them was where time leaked. There was back-and-forth over what a component was meant to be, delays while someone interpreted a screenshot crop, and inconsistency creeping in because there was no single source of truth.

Design and code had drifted apart, and no shared system existed to pull them back together. That was the problem to solve, more than the portal looking dated.

My role

This was a solo build, but it ran in close contact with the team, so here is what was mine and what was 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 and which I didn't deliver.

The decision I'd point to as most mine was anchoring the entire system to their existing code instead of designing in a vacuum and asking developers to catch up. That choice 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 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. I built 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, with no hunt through the file. I ended up with 240+ design tokens and 85+ components. They cover all the real states (error, success, disabled) across light and dark modes, plus patterns and templates.

Everything was built around design-to-code alignment. Their developers were already fluent in Tailwind, so I matched my token names and spacing scales to their conventions exactly. That meant no translation friction when they built. The thing in Figma and the thing in code were the same thing, named the same way. I carried the same conviction into later work on machine-readable design systems. The measure of a design system is how well it works at the handover between design and engineering, and a tidy Figma file on its own doesn't tell you that.

The last piece was handover. I walked the Head of Product through how the system worked, and documented what I'd built as well as how to think about adding to it without breaking it. The goal was autonomy. A pretty library they'd be afraid to touch wouldn't have got them there.

Constraints & tradeoffs

• Anchor to the existing build. I constrained my own design choices to their real Tailwind values instead of proposing a cleaner-slate system. That cost me some freedom to "improve" the foundations, but 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. Visible portal progress was slower as a result. The slower start was worth it, because a foundation that's subtly wrong causes problems in everything built on top of it.
• Document for independence. I spent real time on documentation and a walkthrough, on top of shipping the file. More of the engagement went on enablement than on raw output, and that was the point of the brief.

What shipped

A complete, documented design system in Figma: 240+ tokens in a three-tier primitive/alias/semantic structure, and 85+ components with full state and light/dark coverage, plus patterns and templates. All of it 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. They could pull components instead of building from scratch. 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 was that the Growth Marketer, who isn't a designer, could put together his own page mockups without waiting on design support. That mattered more to me than the percentage. 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 in the code, the guessing games between design and development stopped: everyone was working from the same source of truth.

Reflection

What 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. Then the headline outcome would rest on data instead of a well-placed estimate. The work was sound. The measurement of it could have been tighter.