Extend the Theme with @theme
MUST: Use theme.extend to add custom values; never overwrite top-level theme keys
Declare design tokens in a CSS @theme block, which extends the defaults instead of replacing them
Bad
Good
Why it matters
This is the single largest v4 breaking change and the one most stale advice still gets wrong. There is no `tailwind.config.js` by default, and `theme.extend` does not exist — the JS config object is gone. Tokens are plain CSS custom properties declared inside `@theme { --color-brand: oklch(0.62 0.19 259); }`, and that block extends by default: your brand color lands next to slate, red, and every other built-in.
Which means the entire v3 failure mode this principle used to be about — "you wrote `theme.colors` instead of `theme.extend.colors` and nuked the palette" — is structurally impossible now. Clobbering is opt-in, not accidental: to drop the defaults you must explicitly reset the namespace with `--color-*: initial;` before declaring your own, which is the escape hatch for teams that want a closed palette where `bg-red-500` should not silently work.
Every token you declare doubles as a real CSS variable, so `var(--color-brand)` resolves anywhere, including inside a third-party stylesheet.