The Trunkrs Design System

Tokens, components, accessibility standards and the words in the UI, for a company whose products are a merchant platform, a consumer tracking app, an operations app and a legacy planner. I proposed it shortly after I was hired and built most of it. What has changed twice since is where it lives.

The problem

What I found when I arrived was in Adobe XD. I proposed replacing it and pushed the move to Figma, built most of what followed, and the rest came from design collaborators working to the same guidance, with the team's agreement on each piece. One real upheaval since: the corporate typeface moved from Clan Pro to Red Hat Text and Red Hat Display around 2023.

As a Figma library it worked. Tokens and components, slightly fewer variants than now, and designers had a source of truth. The trouble was everything downstream of it. A Figma file hands a developer a picture and a set of values to retype, and between the picture and production sits an act of interpretation. Sometimes that reads as a judgement call, sometimes as a shortcut, and months later you can stand in front of a screen and see exactly where it happened without being able to say why. Production drifts, nobody decided to let it, and the design file goes on being correct in isolation.

Then it started slowing me down at my end too. Once I was building prototypes in real code, drawing the screen first began to feel like an in-between step on the way to the thing that actually had to exist.

So the second move, out of Figma and into a repo. It came out of the period when we started working with AI in earnest, with input from the engineers who would have to read whatever replaced the handoff. AI moved where design work happens: I build prototypes in production code now, directing coding agents, and a Markdown spec beside the code is what those agents read. A repo is also transferrable where a Figma file is locked to one vendor's format. The system still depends on AI and agents. It no longer depends on Figma.

What it is, and what it deliberately is not

It is documentation-first. The deliverable is a set of Markdown specs paired with rendered HTML previews: 32 component documents, 5 patterns, 62 rendered previews, 177 icons, and the foundations underneath them. There is no component library to import, because the consuming apps do not share a framework: a legacy Material-UI planner, Next.js apps in a monorepo, and standalone prototypes cannot take delivery of the same package.

Values are the exception, and that exception is the whole distribution story. Copying a hex by hand was always going to drift, so tokens.json is the single source and generates the artefacts a consumer actually imports: plain CSS, a Tailwind 4 and shadcn preset, a resolved map for Figma, and a typed JavaScript module. 278 values, one origin.

Four artefacts, four audiences, each with a distinct job: DESIGN.md is the condensed brief written for coding agents, the per-topic specs are for designers and engineers, the previews are the visual proof that renders with no build step, and the tokens are for the apps and for Figma. The one rule that keeps it coherent: code owns values, prose owns meaning.

Decisions worth naming

Specs go out, implementations do not come back. The coded React layer lives in the engineers' own monorepo and they maintain it. This repo sends it tokens and specs and never takes values back from it. A system that accepts values in both directions has two truths and no way to tell which is current.

A prototype is a question, not an artefact. This one I learned by being wrong, below.

Ship the values where the values are needed. Four of the five token artefacts are CSS or data, and none of them can be read by JavaScript. Anything assembling a colour into an SVG string, handing a prop to a map layer or drawing to a canvas had nothing to reach for, which is plausibly why the map files in the operations app had drifted further from the palette than anything else in it. A fifth artefact, a typed module, closed that gap in August 2026.

Figma kept the jobs it is good at. Moving the system out of Figma did not mean leaving it. It still holds the icons and the illustrations, it is the archive and the backup for tokens and components, and it is where a new design gets staged and worked out before it is real. What it stopped being is the thing engineering builds from. Those were always separate jobs and only one of them was going badly.

Onboarding friction is a defect, not a documentation problem. The system is meant to be extended by anyone on the team without asking me, so a governance file that nobody can find their way into is a broken component. Every entry path is role-based: designing a screen, building a screen, or changing the system each get an ordered reading list.

Guard the drift three ways, and know what none of them catch. A script holds the previews to the palette, the token build fails on a stale artefact, and the previews themselves are the only guard that catches a value that is present and wrong. Rendering the input spec found a read-only field specified as a fill and a warning icon at 1.54:1 contrast. But every one of those compares an artefact to its source, and not one can see a value that is internally consistent and still wrong for a human: an error red at 3.55:1 was correct in four documents, correct in the CSS, and generated correctly by the build. Only a written rule catches that, and only if the rule sits where someone looks. Ours was two sections away from the value it governed and went unread for months.

The audit, and the part I did not expect

Rather than assert the system was working, I vendored a copy of the engineers' operations app and counted. Component inline styles held 52 distinct hex literals, 36 of them off the palette: fourteen sites of primary text on one near-black, nine of muted labels on one grey, and a cluster of thirteen near-identical violet-greys that collapsed onto two tokens. That is now zero.

Eight of those thirty-six came from us. All eight trace back to one of my own distribution-monitoring prototypes: four from the live file, three from an iteration I had already archived, and one that exists nowhere but a brainstorm scratch file and shipped anyway. The engineers had implemented what design handed them, value for value. The drift I had gone looking for was partly mine, and the mechanism was not carelessness on either side, it was that a prototype looks exactly like a specification if nobody says which one it is.

So the fix went to the cause. The prototype imports tokens now instead of holding its own values, and archived iterations are marked so a superseded one stops reading as current.

What shipped, and how

Version 3.0.1 as of August 2026, with the token distribution work finished and handed to the engineers as a diff rather than a request.

The clearest evidence that the specs travel is the legacy planner. Someone else designed those screens; I rebuilt six of its ten routes against these tokens and components without redesigning them. A system that only fits the screens its own author drew has not been shown to work. It went to a planner developer as a working app to re-implement from rather than a picture to interpret, which is the repo's whole argument tested on the app that needed it most.

Honest edges

The component library is vast and we do not use half of it. That is not a discovery, it is a decision I would make differently: early on I designed for a system's worth of completeness rather than for what the products in front of me actually needed, and the cost is a set of specs that have to be maintained, audited and version-bumped whether or not anything renders them.

I do not have an adoption number. The honest version is that designing against it is easier than it was, the engineers prefer the repo to the Figma handoff because it is closer to what they work in, and the drift count in one app went from 36 to zero. That is the evidence there is.