The token rollout with a Harness Design layer

I closed Milestone 1 and Milestone 2 of the Harness Design System Project in the previous articles. The token foundation is ready, the governance is defined, the harness schema is applied in Figma. What was left was the part no technical article usually tells properly: taking all of that out of the controlled environment and putting it in front of the code our customers use every day.

That happened. React web is live with the new tokens. And what I learned along the way matters more than the confirmation that it worked.

The rollout happened, with technical debt bought on purpose

We rolled out React to production. Doing it on a Saturday was no accident. Changing color and typography on a large number of screens at once, in production, calls for a window in which as few people as possible are touching the system.

Before that came validation. And here a practical problem showed up that we hadn't sized properly: how do you validate a change that affects the color and typography of practically every screen in the system, without opening them one by one by hand? The answer the devs came up with (here the Front-End React work of Rodofo Ferreira was exceptional) was to build, on top of an existing base called Argos CI, a system that shows the current screen side by side with the screen after the new tokens are applied. Without it, validating would have meant going screen by screen, environment by environment, hoping not to miss anything.

Even with Argos, the validation didn't come out perfect. And that was expected. We did the rollout knowing technical debt would be left over: places with hardcoded color the automated process didn't catch, components outside the main flow that were left out of scope, typography that didn't migrate in some specific corner. Buying that risk was a conscious decision, not a surprise that showed up later. The alternative would have been not to do the rollout until everything was perfect, and that would mean postponing indefinitely the moment the foundation starts being worth something in production.

The divergence the foundation had already predicted

In "Before AI-first, human-first" I wrote about the risk of publishing new tokens in Figma while the code still runs on the old ones. That was confirmed in practice, only in a more specific way than I expected.

React migrated first. Flutter didn't. That created a concrete situation: the designers working on app screens have to keep prototyping from the old version of Glorp, our design system in Figma, while those working on web screens already consume the new version. We had to keep both versions of the library available at the same time, one active for those who migrated and another as a backup for those who haven't yet.

Publishing the whole library at once also exposed a structural problem that had been hidden: not every component had a clear distinction between the variant used on mobile and the one used on web. The same component name, two different contexts, no explicit separation in the file. That didn't show up as a rollout bug. It showed up because the rollout forced everyone to look at the file in a way nobody had looked at it before.

There was also the most annoying side effect: screens that were already finished with the old tokens and had to be redone by hand to follow the change, because otherwise Figma would show one thing and the code another. That is real work, done after the fact, that wasn't in the original plan.

For the customer, almost nothing changes. For now

This is the point most worth naming honestly. Internally, this was a big change: two weeks of almost full-time dedication, an entire infrastructure layer built from scratch to make token updates semi-automatic, a bind plugin built and adjusted over several iterations, validation tests covering dozens of components.

For the people who use the product, the visible impact is small. Some will notice that a text became a little more legible, or that a warning color looks a little different. Most won't notice anything.

That isn't an execution failure. It is the nature of this layer of the project. The real gain the customer will perceive doesn't live in the tokens, it lives in the components the next phase of the project will produce with more speed and more consistency because of this foundation. Tokens are what makes that gain possible, not what delivers it directly. I explained this to internal stakeholders a few times throughout the project, and I still find it strange to have to defend team time on something that, from the outside, looks like just a change of color palette.

What actually changed

It's worth breaking down what this foundation carries, because taken together it is more than it looks.

On accessibility, the numbers confirm the gain, with an important caveat: not everything improved equally. The contrast of tertiary text, which is the most used tone in the whole system, went from approximately 4.3:1 to 8.0:1. The secondary neutral icon went from 2.70:1, which failed, to 10.00:1.

The error red family is the case that needs the most context. When we planned the new tokens, we noticed that the old red looked too similar to yellow and orange tones in some variations, which made it hard to tell the three colors apart in certain interface contexts. The decision was to shift the red toward magenta, pinker, to open a clear distance between the three families. That solved the differentiation problem, but it had a cost that only showed up later, in the contrast measurement: the red got lighter in this new position, and the most critical pair in that family started failing by a small margin. We have already identified the spot and it is in the queue to be refined, without losing the distance we gained from yellow and orange.

The orange used for links and actions also keeps failing, both before and after: 3.31 to 3.24. This is a different case from the red. The tone didn't change because it is the brand's visual identity color, and touching it wasn't a decision that fit within the scope of tokens. But we already understand the path: for interface use, in buttons and links, we will need to apply a tone one level darker within the same orange scale, keeping the brand color recognizable and solving the contrast. It isn't done yet.

And the focus indicator remains practically invisible against a white background, around 1.18:1, when the recommended minimum is 3:1. We gained real ground on text and icons. Error, link and focus are still open items, not victories I'm inflating.

On typography, we switched the font used in Prompt paragraphs to Figtree. That switch had been decided months ago, during an earlier review of the brand's visual identity, but it had never reached the design system. In other words, the system was behind the brand itself, not just behind good accessibility practices. Figtree is about 5.6% narrower than Prompt at the same size, and the body text weight went from 300 to 400, which helps people with low vision read text that used to be too thin. In a good share of cases this saves a whole line of height in the paragraph, which matters on small screens. The trade-off is that the larger headings, which still use the old font, ended up proportionally taller after the leading change. The space gain isn't uniform across the screen.

Beyond color and typography, we expanded the token set on several fronts that had no coverage before: borders, stroke width, shadow, spacing. Each of these families gained variants that simply didn't exist, which reduces the amount of loose, hand-typed values still left in the system.

What this foundation left ready

There is a gain that doesn't show up on any screen, and it may be the most important of the three: there is now a way to manage and update tokens that didn't exist before. Before, changing a token meant someone going manually into every place where that value was used. Now, the flow goes through Figma, through an export and bind plugin, and through an infrastructure layer that distributes the update to React and Flutter. That makes testing, adjusting and improving a process much cheaper than it was two months ago.

The React rollout happened. Flutter's is still in progress, with no fixed date. The divergence between Figma and code, which we knew would appear, appeared, and is being resolved little by little. It isn't a perfect migration. It's the migration we could do, with the risk we decided to buy, and with the foundation the project's next step will need.