Design tokens rollout for a superannuation member portal

The member portal had survived three brand refreshes, and each one had been applied over the last like paint — the codebase held about 1,900 component-level style overrides, four slightly different primary blues, and spacing values that disagreed within the same screen. The client's in-house designers were producing Figma specs that matched none of the existing components, so every feature started with an argument about which grey was correct. The retainer brief was to make the portal consistent without visibly changing it, which is a much stranger job than a redesign.

Frontend developer, one of four frontenders on a twelve-person distributed team, for about eight months. Our agency ran the engineering side from Cebu with morning overlap into Australian hours; the client kept design in-house in Melbourne, so the token naming sessions happened at 7am my time with coffee and screen-shared Figma files.

I owned the token pipeline end to end — the export from the designers' Figma variables through a build step into CSS custom properties — and the migration of the core component set: buttons, form fields, cards, tables. I also set up and owned the visual regression gate, which is what made a 'change everything, change nothing' project reviewable at all.

Tokens landed as CSS custom properties rather than a JavaScript theme object, mostly because the portal server-renders and I refused to ship a flash of unthemed content to people checking their retirement savings. For the migration itself I wrote codemods for the mechanical cases — the hardcoded spacing and colour literals with unambiguous token equivalents — and only hand-migrated the genuinely ambiguous ones, which turned a year of tedium into about three months. The decision I had to defend most was making the visual regression suite block merges: it flagged four hundred false positives in week one and the team wanted it advisory, but tightening the thresholds instead is why the last five months of migration shipped without a single unintended visual change reaching members.

No visible change without a design defect ticket — 'identical but tokenized' was the acceptance bar, reviewed screenshot against screenshot. Releases rode the client's fortnightly train with a compliance sign-off we could not accelerate, and one section of the portal sat inside an older server-rendered app we could not rebuild, so the tokens had to work there too, which killed several elegant approaches early.

Component-level style overrides went from about 1,900 to under 200, and the four blues became one. New screens assemble from the tokenized components in roughly half the time the client's own delivery metrics showed before, and their designers now write specs that reference token names directly — the arguments about which grey moved from every feature kickoff to one naming session, where they belong. The visual regression suite caught eleven real regressions during migration; members, as intended, noticed nothing.

Two designers in Melbourne co-owned the token naming and were the reason the names describe intent rather than colours. The other three frontend developers migrated feature screens against my component set and filed the bugs that improved it, and the client's compliance reviewer taught me more about superannuation disclosure rules than I expected to know.