You upgraded to Tailwind v4, the build passes, and a class just does nothing. No error, no warning — the element renders as if the class weren't there.
I hit this on this site: every bg-ds-* token stopped working after the move to v4, because the colors were still defined in tailwind.config.ts. To write this up properly I reproduced each cause against the real compiler (@tailwindcss/postcss 4.3.3), with a one-line HTML file containing the class and nothing else. Every result marked "tested" below is what that compiler actually produced.
1. Your colors are still in tailwind.config.ts#
Tailwind v4 does not read the JavaScript config file on its own. A color in theme.extend.colors generates nothing.
// tailwind.config.mjs — silently ignored in v4
export default { theme: { extend: { colors: { brand: '#f00' } } } }Tested: bg-brand → no CSS. bg-blue-500 and p-4 still work, which is what makes this confusing — the framework clearly runs, only your tokens are missing.
Fix (preferred): move the token into CSS.
@import 'tailwindcss';
@theme {
--color-brand: #f00;
}Fix (stopgap): load the old file explicitly. Tested: with this line, bg-brand is generated again.
@import 'tailwindcss';
@config './tailwind.config.mjs';The stopgap is useful mid-migration, but the CSS version is where v4 wants you, and it gives you real CSS custom properties you can use outside class names.
2. The variable is missing its namespace#
@theme only turns variables into utilities when they use a namespace Tailwind knows — --color-* for colors, --font-* for fonts, --spacing-* and so on.
@theme {
--brand: #f00; /* tested: creates no bg-brand */
--color-brand: #f00; /* tested: creates bg-brand, text-brand, border-brand */
}3. The variable is in :root, not @theme#
A custom property in :root is just CSS. Tailwind doesn't turn it into a utility.
:root {
--color-brand: #f00; /* tested: no bg-brand */
}If you need it as a class, it belongs in @theme. Variables in @theme are emitted as custom properties too, so you lose nothing by moving them.
4. The CSS still uses the v3 directives#
This one has the opposite symptom, which is why it is easy to misdiagnose.
/* v3 style */
@tailwind base;
@tailwind components;
@tailwind utilities;Tested, with a --color-brand in @theme alongside: bg-brand works, but bg-blue-500 and p-4 generate nothing. Without @import 'tailwindcss' the default theme is never loaded, so every built-in color and spacing value disappears while your own tokens survive.
Fix: replace all three lines with one.
@import 'tailwindcss';5. The class lives in a file Tailwind doesn't scan#
v4 finds your classes automatically, with no content array. But automatic detection skips anything your .gitignore excludes.
Tested: a class used only inside a gitignored generated/ folder → no CSS. Adding a @source line fixed it.
@import 'tailwindcss';
@source './generated';This bites anything that renders markup from outside the usual source tree: build output you template from, a CMS export, a package in a monorepo.
6. The arbitrary value has spaces in it#
Tested: text-[rgba(1,2,3,0.5)] generates CSS; bg-[rgba(0, 0, 0, 0.5)] generates nothing. A class name ends at the first space, so Tailwind never sees a complete class — and there is no warning either way. I wrote about hitting this in a generated-code tool in Tailwind v4's CSS-first config.
Before you blame the config: is the CSS stale?#
One more cause that isn't Tailwind's fault. On this site, edits to globals.css sometimes didn't reach the browser under next dev with webpack — the old stylesheet kept being served, even after a hard reload and a restart. If a fix you are sure of seems to do nothing, check what the browser actually loaded (document.styleSheets in the console). If it's stale, delete .next and start the dev server again. A production build was never affected.
The order I check things in#
- Is the CSS file using
@import 'tailwindcss', not the three@tailwindlines? (cause 4) - Are custom tokens in
@theme, with a namespace? (causes 1–3) - Is the file containing the class gitignored? (cause 5)
- Does the class contain a space? (cause 6)
- Is the browser running the CSS you think it is?
Most broken upgrades are cause 1 or cause 4, and they look like opposite problems. For how the rest of this site's stack is put together, see Building DevStash.
Quick answers
Why do my custom Tailwind colors not work after upgrading to v4?
Tailwind v4 does not read tailwind.config.ts on its own. Colors defined in theme.extend are ignored unless you either move them into an @theme block in your CSS as --color-<name> variables, or load the old file explicitly with @config "./tailwind.config.ts".
Why does a variable in @theme not create a Tailwind class?
Only variables in a known namespace become utilities. --color-brand creates bg-brand and text-brand; --brand creates nothing. A --color-brand declared in :root instead of @theme also creates nothing.
Why do bg-blue-500 and p-4 stop working while my own colors still work?
The CSS file still uses the v3 directives (@tailwind base, components, utilities) without @import "tailwindcss". The default theme is never loaded, so built-in colors and spacing generate nothing while your own @theme values still do. Replace the three directives with @import "tailwindcss".
Why does Tailwind v4 ignore classes in some of my files?
Automatic content detection skips files your .gitignore excludes, such as generated output. Add the folder explicitly with @source "./path/to/folder" in your CSS.
Need something like this built or fixed?
Custom websites, landing pages and speed fixes. I reply within 24 hours.
Adesh Shukla
Front-end developer who came to the web from accounts, by way of an interest in UX. Building DevStash — a developer ecosystem covering automation, AI workflows, and modern frontend systems.