Tailwind v4 killed the JS config. Your AI builder still guesses
By The WAALEE Team · · 4 min read
Tailwind v4 replaced `tailwind.config.js` with a CSS-first `@theme` block, and it switched every default color to OKLCH. Both changes are good news for AI coding tools, and neither one stops your Claude, Lovable, v0, Cursor, or Bolt build from shipping with Tailwind's own palette instead of yours. Here's why, and what actually closes the gap.
The JS config is gone, and that's the right call for AI
In v3, your design tokens lived inside a JavaScript object nested in `tailwind.config.js`, a file an AI agent had to parse as code before it could even see your palette. Tailwind's own docs now put tokens in a plain `@theme` block, written as CSS custom properties, sitting in your global stylesheet. That's a meaningfully better fit for a model: it reads CSS natively and reliably, where it sometimes trips on which config file wins, which import path is live, or whether a project is even on v3 or v4. MatchKit's guide to the change makes the same point plainly: agents find tokens by reading your CSS file directly, or by being told the token names in a rules file, and a `@theme` block is the more legible of the two.
OKLCH is the default now, and that changes what a token even looks like
The other headline change is quieter but touches every color in the framework: Tailwind v4's entire default palette is defined in oklch() instead of hex or rgb. OKLCH is perceptually uniform, meaning equal numeric steps look like equal visual steps, which is why the built-in shade ramps look more consistent in dark mode and on wide-gamut screens. Tailwind's docs recommend writing your own custom colors in OKLCH too, to match. Practically, this means a token file you hand-typed in hex a year ago no longer matches the format your framework's own defaults are written in, and a straight find-and-replace on colors isn't as safe as it used to be.
None of that stops the default palette from shipping
Here's the part that doesn't get fixed by any of the above: `@theme` is just a place to put your tokens. If you never fill it in, Tailwind falls back to its own 22-hue, 11-shade default palette, and so does every agent generating classes against it. Ask Claude Code or Cursor for a signup form and, absent an opinion, you'll get `bg-indigo-600` and `text-gray-500`, Tailwind's defaults, not a decision anyone made about your brand. The CSS-first format made the token file easier for a model to read. It didn't make the model any more likely to fill it with something that isn't the stock palette.
- A blank or default `@theme` block reads as "no brand," the same way a blank system prompt does.
- OKLCH values are harder to eyeball than hex, which makes hand-authoring them error-prone under time pressure.
- Two-layer setups (raw tokens in one file, Tailwind utilities generated from them in another) are the recommended pattern now, per Clearly Design's walkthrough, but someone still has to populate the raw layer.
Filling the block: three ways to get real values in
The `@theme` block needs real values before an agent can apply them. Here's how each approach gets you there:
- Hand-write it: Tailwind's own docs on the @theme syntax. Free, and correct once you've decided your brand's OKLCH values by hand, shade by shade.
- MatchKit's token guide: A thorough walkthrough of how to structure tokens for v4 and wire them so agents pick them up. Teaches the pattern; you still supply the colors.
- WAALEE: Paste a live URL and get the real OKLCH-ready colors, type scale, and spacing straight off the rendered page, exported as W3C tokens plus a prompt for Claude, Lovable, v0, Cursor, and Bolt. Drop the values into @theme instead of guessing them.
Tailwind v4 fixed the plumbing. The `@theme` block is a better place for tokens to live than a JS config ever was, and OKLCH is a better color space than hex for building consistent shade ramps. But a better pipe still needs something real flowing through it. Whether you fill it in by hand, follow a guide, or pull the values off a page you already like, the point is the same one it's always been: an agent applies a decision, it doesn't invent one.