When we port a vibe-coded app to WordPress, most people assume the first thing we build is a template — the homepage, the hero, something you can look at. It isn’t. The first file we write is theme.json. Colors, spacing, typography, layout widths: all of it gets defined before a single template is touched.
That ordering isn’t a quirk. It’s the whole strategy. Because theme.json isn’t a stylesheet. It’s a contract — and the parties to that contract are your original design and every person who will ever edit the site after you’re gone.
What a contract actually does
A contract constrains behavior so that trust isn’t required. You don’t have to hope the other party behaves; the terms make the bad outcomes unavailable.
That’s exactly what theme.json does inside the WordPress block editor. The editor reads it to decide what choices a user is even allowed to make. Define a palette of six brand colors, and the color picker offers six colors — not the full sixteen-million-color wheel where someone eventually picks a slightly-off blue because it was Tuesday and they were in a hurry. Define a spacing scale, and padding snaps to your scale instead of becoming a field where anyone can type 37px.
{
"settings": {
"color": {
"palette": [
{ "slug": "ink", "color": "#101418", "name": "Ink" },
{ "slug": "blueprint", "color": "#2456F0", "name": "Blueprint" }
]
}
}
}
Two colors, two names. But what you’ve actually written is a rule: these are the brand colors, and they are the only colors this site speaks. The design system stops being a PDF nobody opens and becomes a thing the software enforces on its own.
Why we front-load it
The reason we write theme.json first, before any template, comes down to a simple truth about systems: it’s far cheaper to make good choices the default than to police bad ones after the fact.
If you build the templates first and define tokens later, you spend the rest of the project reverse-engineering — finding every hardcoded hex value, every magic-number margin, every one-off font size, and retrofitting them into a system. You’ll miss some. The ones you miss are the cracks where drift gets in.
Front-load the tokens and the logic inverts. Every template you build afterward is composed from the contract. There’s no hardcoded color to hunt down later because there was never a place to hardcode one. The constraint isn’t a cleanup step at the end; it’s the foundation everything else stands on.
This is also why a faithful migration cares so much about the prototype’s actual design decisions. In a vibe-coded app, the real design system is usually hiding in utility classes scattered across the markup — not in a tidy config file. Extracting those decisions and crystallizing them into tokens is the migration’s first hard problem. Get it right and the rest of the build is downhill. Get it wrong and you’re shipping a clone with extra JSON.
The handoff dividend
Here’s where the contract pays out — and it pays out long after you’ve moved on.
Picture the site six months after delivery. You’re not in the loop anymore. A junior marketer who has never met you needs to spin up a landing page for a new promotion. They open the editor, drop in some blocks, and start styling. They pick a color — from your palette. They set spacing — from your scale. They choose a heading — from your type ramp. Not because they read your brand guidelines. Because those were the only options the editor offered.
They ship the page. It looks like the site. It looks like the site because it could not have looked like anything else.
That’s the dividend, and it compounds. Every page anyone adds, forever, inherits the design system for free. The brand holds together not through vigilance or review cycles, but because consistency is the path of least resistance. You made the right thing the easy thing.
A design system that depends on people remembering it will drift. A design system encoded as a contract holds — because following it is easier than breaking it.
The reframe
So the next time you think of theme.json as the file where you list some colors, flip it. It’s the legal text of your design system. It defines what’s permitted, removes what isn’t, and binds every future editor to terms they’ll never have to read because the software reads them instead.
Decoration is what a site looks like on launch day. A contract is what keeps it looking right on every day after. We write the contract first because that’s the part that has to last.
Lowpable rebuilds vibe-coded apps from Lovable, Bolt, and v0 into production WordPress — tokens first, templates second, drift never. Zip in, zip out. See a live demo or get a quote.