One theme.json: a single source of truth for design, code, and AI

Every team I’ve worked with keeps its design language in more than one place, and those places quietly disagree. Figma has its variables. The codebase has its CSS. Someone wrote the brand colors into a slide deck, and now an AI tool is generating screens with its own idea of what “your blue” is. Four copies of the truth, four owners, and no mechanism that keeps them equal. The gap between them is where “why doesn’t this match the design?” comes from — not from carelessness, but from architecture.

The fix isn’t more discipline. It’s removing the copies. There should be one definition of the design language, in a format a machine can read, and everything else should be generated from it.

That file is a theme.json.

One file, many readers

A design token is just a named value with intent — accents.brand instead of #1072EA, spacing.4 instead of 16px. Collect all of them into a single structured file (the W3C’s Design Tokens format gives it a standard shape), and you have a description of the whole visual system that isn’t tied to any one tool. It’s not Figma’s and it’s not the code’s. It’s the source; they’re both outputs.

Once the definition lives in one file, the tools stop being peers that have to be kept in sync and become renderings of the same thing. Change accents.brand in the theme, regenerate, and Figma’s variable, the CSS custom property, and the tokens an AI reads all move together — because they were never separate values, just separate views of one value.

This is the whole idea behind Veritheme, the open-source system I build: you edit one theme, and it generates Figma variables and components, CSS utilities, and an exportable theme.json that any other tool can consume. Design and code stop being two projects that shadow each other and become two ends of one pipeline.

What one file actually generates

Here’s part of what Veritheme builds from a single theme — real, production components (66 of them in the set), every one wired to the same tokens instead of to hardcoded values:

Nothing there owns a color or a corner radius. Each component reads them, which is exactly what lets the whole set re-skin from one edit. The pipeline underneath is boring on purpose — one value flows straight through to the rendered component:

"brand":  "213 87% 49%",
"radius": 10,
"font":   "Inter"

--accents-brand: 213 87% 49%;
--radius-lg:     10px;

<button class="vt-btn vt-btn-primary">
  Get started
</button>

The part that’s new: the machine is now a reader too

For years “single source of truth” meant keeping Figma and code aligned. That mattered, but it was a two-reader problem. There’s a third reader now, and it changes the stakes.

AI generates interfaces. You describe a screen and a model produces the markup, the styles, the layout. Left alone, it invents a design language on the spot — a plausible blue, a reasonable spacing rhythm, none of it yours. But a model is very good at reading a structured file and following it. Hand it your theme.json and “generate on brand” stops being a hope and becomes an instruction with values attached.

That reframes what design tokens are for. They were a sync mechanism between humans and tools. They’re becoming the interface between human intent and machine generation — the contract that lets you delegate production to a model without delegating your identity to it. A design system that isn’t machine-readable is about to feel the way an API-less product feels: usable by hand, invisible to everything that could have automated it.

Rules, not just tokens: the MCP server

Handing a model a token file gets you the right colors. It does not stop the model from reaching for the most average layout it has ever seen — the generic, could-be-any-startup screen. Tokens fix the palette; they don’t fix the taste.

That’s the gap Veritheme’s MCP server is built to close. It exposes two things to the AI, not one: the real components, and the rules for using them — component-first (reach for the actual Button, don’t rebuild one out of utility classes), semantic tokens over raw values, a fixed spacing grid, minimum type sizes. The model stops inventing primitives and starts composing from yours, inside constraints that encode how the system is meant to be used. The result reads less like a template and more like your product — because it’s assembled from your parts, by your rules, not guessed from the average of the internet.

Re-skin the whole thing to your brand

The flip side of one source is the fun one: change the source, and everything downstream changes with it. In Veritheme’s live theme generator you pick a brand color — plus type and radius if you want — and every one of those components re-skins instantly. Same layout, same structure, your identity. Then you export that theme.json, and it is the very same file Figma imports, the browser ships, and the AI reads.

No designer, no developer, no hand-tuning a hundred screens. One value in, a coherent on-brand system out — including for people who could never have built one by hand.

Where it breaks

A single file is a strong idea, which means it fails in specific, worth-knowing ways.

Tokens are not the whole system. A theme.json captures values and their names. It does not capture judgment — when to use accents.brand versus mains-primary, what a card is allowed to look like, which patterns are blessed. Ship the tokens and call it a design system and you’ve shipped a paint set, not a way of painting. The file is the foundation; the system is still the decisions on top of it.

One source is also one point of failure. Centralize the truth and you centralize the blast radius: a careless edit propagates everywhere, instantly, to every surface. That’s the cost of the coupling that makes it powerful. It demands the governance a shared dependency demands — review, versioning, a way to roll back — not the informality of a file someone edits on a Friday.

Not everything wants to be a token. Over-tokenize and you get a system that’s technically centralized and practically unreadable — a wall of aliases nobody can hold in their head. The single source only helps if what’s in it earns its place; the discipline of what to leave out matters as much as the format. (I wrote a whole piece on where that line sits.)

The machine still needs guardrails. Feeding a model your tokens keeps its colors and spacing honest. It does not make its layout good, its hierarchy correct, or its copy usable. On-brand and well-designed are different claims; the theme.json guarantees the first, never the second.

The contract

Strip it down and the argument is simple. Design, code, and AI are three surfaces that all have to speak the same visual language, and the only reliable way to make them agree is to stop asking them to agree — and give them one file to read instead.

Author it once. Let Figma render it, let the browser render it, let the model render it. The theme.json becomes the contract between the designer, the developer, and the machine — and a contract, unlike a convention, is the kind of agreement that actually holds.