One design system for a
13-year-old product.

01The product and the strategic call

Vantage Circle is an employee recognition and rewards platform used by 3.2M+ users across 700 companies. Employees recognise each other’s work, earn points, and spend them on gift cards, merchandise and experiences.

Two structural facts shape everything that follows. It is thirteen years old, built and rebuilt by successive teams. And it is multi-tenant: one codebase serving enterprise customers across six regions, each setting their own brand colour, including a white-label build where Vantage’s own identity disappears entirely. Nobody on the team can see most of the interfaces this code renders.

The brief

Make every module in the app look consistent.

The objective came from the CTO, and it was one sentence. Rewards, perks, redeem, recognition, checkout, profile, admin: each built at a different time by different people, and it read that way.

The standard play is to go straight at the components: standardise the button, the card, the dropdown, module by module until the surfaces match. Before committing the team to it, I audited the product screen by screen, and the entire stylesheet layer underneath it, to establish what those components were built out of.

No screen looked broken. No button was visibly the wrong colour. That was the finding. Thirteen years of hardcoding had produced a product where surfaces almost line up, and the whole thing reads as slightly hand-assembled without anyone being able to say why, because underneath, the components were built out of nothing. Just 8,375 hardcoded values, every one decided locally.

Grouping the colours by perceptual distance in CIELAB, below the threshold at which two colours are reliably distinguishable, found 26 clusters of values nobody could tell apart on screen, holding 113 of the values and 67% of all colour usage. The largest held 23 different off-whites, every one of them meaning “the very light background.”

Twelve ways to say “click here”

There was no button component either, only habits accumulated in strata: three overlapping systems (in-house, Bootstrap and Angular Material) competing in one cascade, each with its own idea of height, radius, padding and hover.

Underneath all of it sat 2,171 !important declarations. Most existed to win specificity fights against Angular Material’s runtime-injected styles, a legitimate reason for some of them and a symptom for the rest. Either way, the cascade could not be reasoned about by reading it: you could not predict which rule would win.

So component standardisation is the wrong first move. A component is only as consistent as the values underneath it. Standardise the button while its values are still arbitrary and you have fixed one component; the next person still has 459 values to choose from and no canonical one to reach for.

I took the audit back to the CTO and proposed inverting the order: foundation first, components second. It meant a stretch of the project with nothing visible to show. The argument for it was that the alternative buys consistency you have to keep paying for. That got approved, and it reset the shape of the whole engagement.

02Mobilising the squad

Managing a team of 12 designers meant the delegation strategy mattered as much as the audit did. Several modules across one app is several hundred components, and that is more than one person rounds up in a month.

I split the work by module ownership rather than by functional silo, and sent each owner their slice of the audit with its real numbers attached.

Everyone worked on a shared design branch and raised a pull request per slice. I reviewed and merged every one, which is where the canon was enforced: a pull request that invented a value instead of reaching for an existing one did not get merged. We stood up daily for the duration, on this project only.

Why this sat with the design team

The work looks like frontend work, and some of it is. But almost none of the difficulty was in editing files. It was in deciding which of twenty-three off-whites survives. Whether a 25px radius and a 50px pill are the same intention or two. Which of eleven definitions of one button class is the real one, and what the other ten should become. Those are design decisions that happen to be written in CSS.

Run through the frontend team, the same project would have taken about twice as long. Not because it is harder for them, but because every one of those calls would have left as a ticket, waited for an answer, and come back. There are several thousand of them. Owning the code removed the round trip, which is most of where the month went.

03Human judgement vs. AI labour

The project worked because we separated the mechanical work from the design decisions. Mixing the two is how migrations become unreviewable and stall.

Rounding up: 459 values, 243 tokens

The first step was not a redesign. The rule I set: don’t change a single CSS value yet. The temptation with a mess this size is to fix it while you are in there, snap the 15px to 16px, correct the type scale. We held the line on all of it, because a migration that also improves things is a migration nobody can review.

So this stage was purely a naming job: walk the platform by eye, decide what set of values it needs, and round the existing ones up to that set. The Principal Product Designer and I worked the canon together, the canon being the token set plus the rules governing its use. Deciding which ramp step twenty-three off-whites collapse to is not something you compute: the right answer is the value that appears most on the surfaces users look at longest, not the one that appears most in the codebase.

Two of those ratios matter more than the rest. Spacing, 79 → 8, is the biggest reduction and the least interesting decision: that is not seventy-nine intentions, it is seventy-nine instances of nudging a number until it looked right. Z-index is the one category where consolidation isn’t the point at all: values ran from 1 to 99999999 with no logic, which is why tooltips rendered behind dropdowns. The win isn’t fewer values, it’s ordered ones.

Deciding what the system refuses to have

Twelve button styles collapsed to five tiers and two sizes: primary, secondary and tertiary taking colour from the tenant’s brand variable; icon-only and overlay are not tenant-aware, because they sit on photography where a brand tint fights the content underneath. The original spec had a third, larger size; we cut it after I audited every call site and found no 48px CTA anywhere in the app. A size nobody uses is a size that invites somebody to use it inconsistently later.

Six icon sources became 195 icons from one: Lucide, stroke 1.2px, 24×24, catalogued per module.

The constraint a tenant-derived ramp creates

If the brand colour is an input, contrast is not something the palette can guarantee on its own. Three rules carry it. Status colours are never tenant-derived, so success stays green whatever the customer’s brand is. Text and surface tokens come from the neutral ramp, not the brand ramp, so legibility does not move when the brand does. And the tiers that sit on photography, icon-only and overlay, are deliberately neutral. The type scale carries the same logic: 11px is the floor for anything a user has to read, and the 8px badge token is documented as decoration only, never text.

Which half a machine could do

The substitution work then split in two, and that split made the rest possible.

The mechanical half. A codemod performed ~3,876 literal-to-token substitutions under one requirement: zero pixel difference, every substitution provably lossless, a rename and nothing more. The agents did the parts that are mechanical: sweeping 347 stylesheets for every literal and clustering them by perceptual distance, running the lossless substitutions, reconciling Figma exports against the committed tokens. None of that needs an eye, and all of it used to be the reason an audit like this never got done.

That constraint sounds conservative. It is the reason the change could be reviewed at all. Substitutions that also adjust values cannot be reviewed by a human, because real regressions hide inside the cosmetic noise. Substitutions that change nothing can be verified as a class.

The judgement half went to per-module owners as handover reports rather than a rollout I performed on everyone else’s code, each with their slice’s real numbers and three permitted outcomes per literal: consolidate to the nearest token, keep as a deliberate one-off, or factor into a feature-scoped token. The calls had to be made by whoever knew the module. A system imposed any other way gets followed until the day I stop watching.

Handing the repetitive labour to the agents let four designers work directly in a production codebase at all. The shape of the project is not really a design system built in a month; it is a design team keeping the judgement and handing away the labour.

04The framework: mitigating risk

Editing a 13-year-old cascade carries a real risk of breaking things nobody touched. Partway through, that pattern emerged.

The cause was simpler and worse than the theory going around. Styling that belonged to one element lived in the global stylesheet, under a class unrelated elements also wore. Applying a token to it changed every element wearing that name, including ones that were never in the diff.

I worked with the frontend team to turn this into two blocking pre-edit checks.

Guardrail 1: is this style global or local?

Name the element, list its classes, search who else uses them. Local → replace the literal with the token; it cannot ripple. Global → don’t edit it. Surface a written proposal with the current rule, the proposed change, and the count of elements sharing the style, and leave it unapplied.

Guardrail 2: does this need a .ts change?

UI work must not touch component logic without approval. Flagged items route to a frontend-support log with symptom, file, line, root cause and proposed fix.

These two are the reason the rollout didn’t unwind. Without them, a token migration inside a 13-year-old codebase is a very large, very confident find-and-replace across a cascade nobody fully understands. They also changed how the work felt to do: a designer editing production stylesheets could tell which edits were safe to make alone and which needed a second pair of eyes, instead of guessing.

An independent regression audit across 370 changed files found zero critical and zero confirmed high-severity defects.

05Shifting the burden of proof

Nobody argued with the design system. What it ran into was harder to argue with: every check around it still validated against the old baseline, because that was the only baseline anyone had. You can persuade a person; a default has nobody to convince.

A validation sweep produced a 59-item fix plan: careful work, properly written, and exactly what the process asks for. Implemented as specified, roughly 49 of the 59 would have reverted an intentional consolidation.

That is not a testing failure, it is a gap I had left. A sweep compares a screen against the reference it was given, and I had not yet given anyone the new one. Without it, nobody looking at a screen can distinguish “this grey is a mistake” from “this grey is deliberately different from the grey it replaced.” Both read as a change, and the natural remedy is put it back, and that is what the migration existed to stop.

I triaged all 59 against two questions: is something objectively broken, and does the proposed remedy restore something the migration consolidated? That split it into about ten to take as written and about forty-nine needing a design ruling. The genuinely broken ones were worth having, including a comment in the token file stating the wrong value for --radius-pill, which had caused a run of radius regressions downstream. The bug wasn’t in any stylesheet; it was in a sentence.

The 28-entry decision log was the response, and it’s the work I’d point to first. Each entry records the production baseline, the change, the rationale and the blast radius. The value was not in the writing. It was that the default changed. Before it existed, every consolidation was one person’s preference until argued otherwise. After it, the standard was the reference, and a divergence from it was the thing needing justification.

Shifting where the burden of proof sits is most of what establishing a design system consists of. The tokens are the easy half.

06Outcomes and long-term adoption

By the close of the one-month cycle the system was merged into the release branch. The canon is now how the product gets built: buttons from the five tiers, dropdowns from the one pattern, icons from the 195, colours from the tokens.

The !important row is the one that tells you most. Clearing two-thirds of those 2,171 declarations turned the stylesheet layer back into something a person can predict by reading it. What is left is mostly the genuine Angular Material specificity fights, and each one is now allowlisted and documented rather than inherited. It is the same shift as the hex values: an exception someone recorded rather than a habit someone continued.

What is left is not leftovers. The 126 hex values still in the codebase are mostly the partner-brand palettes the canon has no claim over (Amazon’s yellow is Amazon’s yellow), plus the AI-generated chart colours the token file explicitly rules out of scope. The spacing residue is the sub-grid alignment debt, which the system declined to absorb rather than dignify a 13px nudge as a scale step. The difference is that every one of these is now an annotated exception rather than the ambient default: a literal in this codebase today is a decision someone recorded, not a guess someone made.

The measure of a design system isn’t what it looks like on the day it ships. It is whether the twenty-fourth off-white gets added next quarter. Right now it doesn’t, and not because anyone is policing it: the token library lives in the codebase branch, and reaching for the canonical value is now the path of least resistance for designers and engineers alike.

That is the first half of it. Consistency is not the same claim as usability, and a token file cannot tell you that a row has a click handler and no tabindex. What the foundation bought was the speed to go and find out. That is the subject of the accessibility story.