Detecting broken utility classes in Tailwind v4

[mark-buhagiar]

Our system is made up of a common library that makes use of Tailwind v4, and a number of consuming projects.

We have just made quite a large change to our library where we renamed some of our semantic tokens.
The previous tokens were being exported and published on npm for the consuming applications to import and make use of.

We are now in the process up migrating the consuming projects. I was expecting building (using vite) the project, or using the tailwind cli to flag the broken utility classes, however this has not happened, and we're now having to go through the projects file by file.

For example, we use to have the semantic token --color-primary. This has now been rename to --color-cta-primary.

Is there any way for us to quickly identify these broken utility classes?

[wongjn]

You could consider using some kind of regex pattern, like (?<!-cta)-primary.

[mark-buhagiar]

Thanks for replying.

Unfortuntely, that was a rather simple example.

In reality, we have migrated from tailwind v3 to v4, and redone our entire semantic token library. So using regexes won't really scale i'm afraid.

To be honest, I was more surprised that this didn't just happen out of the box. I swear that in the past i've had red lines when a color (or other utility) has been unable to resolve. Was that my imagination?

[wongjn]

If you're referring to Tailwind intellisense, I don't remember seeing any lines with utilities that don't resolve, in VSCode at least.

[MaxPrehoda]

For finding every place that still uses an old token, you want a rule that checks classes against your current theme. eslint-plugin-better-tailwindcss has no-unknown-classes for exactly this.

Once the apps are migrated, the next thing that bites is drift: people (and AI agents) reaching for bg-blue-600 or p-[13px] instead of the new tokens. Motif's lint catches those in any template language without any ESLint setup, and you can try it on one of the consuming apps without installing anything (I'm the author, repo: https://github.com/MaxPrehoda/motif):

curl -sL https://raw.githubusercontent.com/MaxPrehoda/motif/main/design-lint.mjs | node --input-type=module -

[Icaro0310]

Tailwind can’t flag these at build time because an unknown class is just a normal HTML class; the scanner only emits CSS for candidates that resolve.

I’d add eslint-plugin-better-tailwindcss and point it at each consumer’s real CSS entrypoint — the file importing your library/theme:

npm i -D eslint-plugin-better-tailwindcss

settings: {
  "better-tailwindcss": { entryPoint: "src/styles.css" },
},
rules: {
  "better-tailwindcss/no-unknown-classes": "error",
},

That should report bg-primary/text-primary after --color-primary is removed, including variants like hover:bg-primary. For a one-off sweep, rg --pcre2 '(?<!cta-)primary' also finds most leftovers.

—
Check out my Repositories: github.com/Icaro0310 · Website: icaro0310.github.io