- Context
- Nivoda, a global B2B jewellery marketplace
- Duration
- ~3 months, foundations to ~63 components
- Role
- Team lead with one senior designer. Strategy, token architecture, component API design, build tooling, governance and docs
- Stack
- W3C DTCG tokens (OKLCH) · shadcn/ui + Radix · Tailwind v4 · Nx monorepo · Fumadocs · Storybook
- Shipped
- Token pipeline · component library · live validation app · agent-readable docs · governance model · 4 ADRs
What the audit found
A system that suggested, but did not enforce
Nivoda had a working design system. Material UI, a hand-rolled token pipeline, more than sixty components. Fine on paper. The audit counted what was actually in the repository, and the shape of the problem was in the counts:
sx={} escapes, each a place a token could be ignoredEach of those is a seam where design intent leaked. The team was paying, continuously, to make Material not look like Material, and responsiveness was bolted on per component rather than written into the contract.
The counting was not a formality before the interesting work. It decided the work. Two things came out of it that shaped everything after.
It said what to delete
The fastest way to waste a rebuild is to recreate the old system in nicer syntax. The audit produced a token-by-token comparison against what was actually shipping in production, not against what the design file claimed, and that comparison is what made the scope defensible.
It made the migration invisible
15 token-alignment decisions matched the new values to what production already rendered. That meant zero visual drift on adoption. No flag day, no re-skin for leadership to argue about, and no reason for anyone to block it.
The mechanism
Correctly implemented was never the same thing as design-correct
That loop is not a process failure, and no amount of process improvement removes it. It exists because the thing being checked was never encoded anywhere a build could enforce. So a person has to verify the output by eye, and that verification is the loop.
The rebuild encoded it instead. Tokens, spacing, type, accessibility, responsiveness and the legal range of variants live inside the component API. The guard-rails are in the prop signatures, not in a Figma file or a reviewer's eye.
The consequence is the whole point. Nothing can build "correctly" and "design-incorrect" at the same time, so design has nothing left to catch.
The drift checking did not get faster. It stopped being necessary.
The second problem
A component library says what. It cannot say why
A library tells you what the button looks like. It cannot tell you why it is that way, when to break the rule, or what good looks like for a flow nobody designed by hand. That judgment used to live in designers' heads, which is a single point of failure with a notice period.
Getting it out of their heads only matters if the system can be read, and the readers changed. Engineers, designers and product managers all build through agents now, and an agent never opens the design file. It reads the repository. So the documentation is not a website about the system, it is the interface to it:
- A library map, a for and not-for index of every component, encoding when to reach for each one. The first thing an agent reads.
- 63 colocated docs, props, usage, do and don't, sitting next to the code so they cannot drift from it.
- TypeScript contracts as the spec, Storybook as executable examples, the Nx graph as machine-readable structure.
There is no sync step and no stale mirror, so an agent always reads current truth, and inherits the same judgment a senior designer would have applied by hand.
Outcomes
A week became half a day
A new screen, about a week→about half a day
UI that came out design-correct, roughly 75%→roughly 97%
Two things follow from those, and they matter more than the figures.
Product managers shipped UI. Not a mockup handed to an engineer. Finished interface, built against the system, with no designer in the loop and nothing for one to correct afterwards.
The senior designer stopped reviewing implementations and moved onto components, documentation and governance. The capacity did not get freed up in the abstract, it went somewhere.
The bridge
The counting comes first, every time
Nivoda's numbers were 81, 723 and 32. Another codebase will have different ones, and the point is not the specific figures. It is that they were countable at all, and that counting them first is what made a three-month rebuild a decision rather than a bet.
That first step is the audit, and it is the same instrument every time: what is actually in the repository, what an agent can and cannot read in it, and what would have to change before it could build against it reliably. Some systems come out of it needing a rebuild. Plenty do not, and finding that out in a fortnight is the question worth asking before anyone commits to a rebuild.
The build
Three months, foundations to library
Tokens as the contract
W3C DTCG JSON in Git, vendor-neutral and spec-backed. Two tiers, primitives (color.azure.500) and semantic roles (action.primary). OKLCH colour for perceptually even ramps and predictable dark mode. One source compiles to web CSS, the shadcn theme, JS and TS, email and backend JSON, with semantic tokens emitting var(--…) chains so a primitive can be retargeted without recompiling anything downstream.
color-feedback-error, never blue-5) are the highest-leverage move on the board, for human clarity and for agent output alike.Components on headless primitives
Radix, Tailwind and code ownership through shadcn, the foundation OpenAI, Vercel, Linear and Supabase run on. No vendor design language to override back out. ~63 components across four tiers: 38 atoms, 16 molecules, organisms (FilterToolbar, Megamenu, Sidebar) and templates. One reference component, Button, was hardened first to define what finished meant for everything after it. All of it validated against a live app on real data, because done means it survives a real product surface rather than rendering in isolation.
Four decisions recorded as ADRs
A design system is mostly "do we adopt this tool?" calls, and the reasoning is the artifact:
- Bespoke token build over Style Dictionary. Use the vendor until it costs more than it saves, then own a small tested script. Reversible, because the DTCG source never changed.
- Removed visual-regression testing. Right tool, wrong time. One component, no CI, pure overhead, and a secret-exposure risk. Revisit at ten components.
- Rejected Figma to code token sync. It solves a problem this team did not have. Designers explore in Figma, they do not author tokens there.
- Markdown docs over a hosted hub. When the source is already agent-readable, read it directly rather than maintaining a polished copy of it.
Designed for the handover
Two token tiers, a readable ~230-line build, ADRs and in-repo docs. A system the team owns after I step out, not a black box with my name on it.