What is a design harness?
AI writes most of the UI now. Here is the small, boring artifact that keeps it from quietly wrecking your design system — and why the parts that look dull are the parts that matter.
The design system breaks quietly
You have probably seen it. An agent hardcodes #3b82f6 instead of reaching for your color.primary token. You catch it in review, fix it, move on. Next week the same value is back, in a different file. Nobody is being careless — each agent simply builds what looks right, in isolation, with no memory of the last decision. That slow divergence has a name: design token drift.
Then it compounds. Three sessions each invent a button, and now three versions of the same button exist. A spacing value drifts two pixels. The diff survives in git; the reasoning behind it does not. Six weeks later someone asks why a padding is 14px, and the honest answer is: no one knows.
None of this is an AI failure. It is a missing-context failure. The model was never told what consistent means for your project, in a form it could actually read while it worked. A design harness is our name for that missing artifact — and the rest of this piece is what it is and why the boring parts matter.
What is a design harness?
A design harness is your tokens, your component specs, and your quality gates, kept in a single source that both AI agents and humans can read.
It exists because AI agents now write UI at a speed and scale that outpaces human review, and design intent that lives only in people's memory or in prose docs cannot survive that. Where a traditional design system is documentation meant for people, a harness is the same intent expressed so that both a human and an agent build within it — and any drift away from it can be caught automatically.
The word is borrowed from tack. A harness does not slow the horse; it lets a rider direct enormous power without fighting it. Reins are not a cage. In AI-driven development the power is real and the speed is real — what has been missing is the light, deliberate connection between that power and your intent. The harness is that connection: not a rulebook that nags, but a shared contract the agent consults before it writes a line of UI. Written once, read by everyone — the agent that generates a component, the teammate reviewing the PR, and the checker that flags a drift. One source, many readers.
The three parts, and why the boring details matter
A harness has three moving parts.
- Tokens — the vocabulary. Colors, spacing, radii, type, expressed as named values rather than literals:
color.accent, not#0a0a0a. When those references break, you get token drift. - Component specs — the grammar. What a Button is, its variants and states, which tokens it may use, and the rules it must not break. Written down, that is a component contract.
- Quality gates — the proofreader. Machine-checkable rules — no raw hex, no off-scale spacing — generated from the same definition as the human-readable docs, so the rule you read and the rule that runs can never disagree.
Two decisions that carry the weight
Two design choices do most of the quiet work. The first is stable IDs: every token, component, and gate carries an identifier that never changes, even when its name does. Rename color.brand to color.accent and every reference, every logged decision, every past drift stays attached. Systems that link by name break the moment a name moves; systems that link by ID remember.
The second is two-layer recording. We keep the fact — what changed, in which files — separate from the context — why it changed, and what was considered instead. The fact layer is deterministic and never depends on a model remembering to explain itself; the context layer adds the reasoning when it exists. Keep them apart and a missing explanation never costs you the record of the change. Fold them together and one lazy commit erases both.
Why not just use Figma?
Figma is where many teams keep design, and a harness is not a competitor to it. But a Figma file is drawn for humans to look at, not structured for an agent to read at 2 a.m. while it edits button.tsx. The information an agent needs — the exact token, the rule it must not break, the reason a past decision went the way it did — is not what a canvas is built to carry.
So a harness starts from zero, in text, in your repo. npx harnd scan reads the app your agents already built and extracts your tokens and components — no design tool assumed, no account required — and produces something an agent can pull before it touches a component: a few hundred tokens of just the relevant spec. If you use Figma, good: the harness lives alongside it as the machine-readable contract. If you do not, you have lost nothing. The harness never needed it.
We build Harnd under its own harness
Everything here is dogfooded. Harnd is built under its own harness: the colors in this article are tokens in our own source, the components are specced, and the same gates we ship run against our own pull requests. If the ideas above sound abstract, they are not — they are the rules this very page was written under.
If any of the problems at the top of this page felt a little too familiar, that is the point. Start with the two parts that break first — design token drift and the component contract — or get early access and point Harnd at the app your agents already built.