Ship a css-custom-data.json so editors stop reporting @theme as an unknown at-rule #20430

What I'd like to see

Ship a css-custom-data.json in the tailwindcss package, so any project can do this:

// .vscode/settings.json
{
  "css.customData": ["./node_modules/tailwindcss/css-custom-data.json"]
}

…and have VS Code's built-in CSS language service understand @theme, @utility, @variant, @custom-variant, @source, @reference, @apply, @plugin and @config — automatically staying in sync with whatever version of Tailwind is installed.

Following CONTRIBUTING.md, which asks for an idea here before a PR for anything that isn't a bug fix.

The problem

vscode-css-languageservice — which backs VS Code's built-in CSS support, and also Zed and most Neovim LSP setups — doesn't know Tailwind's at-rules. A valid v4 stylesheet reports seven problems:

Unknown at rule @plugin          css(unknownAtRules)
Unknown at rule @source          css(unknownAtRules)
Unknown at rule @theme           css(unknownAtRules)
Unknown at rule @custom-variant  css(unknownAtRules)
Unknown at rule @utility         css(unknownAtRules)
Unknown at rule @apply           css(unknownAtRules)
Unknown at rule @variant         css(unknownAtRules)

That's measured, not hypothetical — it's tailwindcss@4.3.3 compiling that exact file without complaint.

The two workarounds people land on each cost something real:

"css.lint.unknownAtRules": "ignore" turns off the whole lint. You also stop being told about @medai (min-width: 40rem).

"files.associations": { "*.css": "tailwindcss" } moves your CSS files to a different language ID. css.customData no longer applies to them, and other tooling keyed on css quietly stops working. This is what the docs currently steer people toward, and it's why threads like #18556 keep appearing.

Why custom data is the right shape of fix

CSS Custom Data is VS Code's supported extension point for exactly this. It's declarative JSON, has zero runtime cost, and — unlike ignore — it's additive: the language service learns the at-rules and keeps validating everything else.

I checked what that actually does. Same stylesheet, same language service, with a custom data file loaded:

before:  7 problems   (all false)
after:   0 problems

…while colr: red and @medai are both still reported. You also get hover documentation and completion on the directives, which ignore obviously can't give you.

Why in the tailwindcss package specifically

The file itself is easy to write by hand — plenty of people already have. The part that doesn't work is keeping it correct. Which at-rules exist is a property of the installed version (@theme doesn't exist in v3; @tailwind doesn't in v4), so a hand-maintained copy is wrong the moment someone upgrades, and it fails in the most confusing possible way: a warning on a directive that's real.

Shipping it in the package makes the path a version-pinned dependency. Upgrade Tailwind, the file updates with it. Nothing to regenerate, nothing to drift.

It also makes it discoverable. Right now this is folklore spread across blog posts.

On the earlier PR

tailwindlabs/tailwindcss-intellisense#237 proposed this in the extension in 2021 and was declined, for two stated reasons. Both were about the extension, and I think the situation reads differently now:

1. "it does not suppress @apply class list errors" — I couldn't reproduce this on v4 syntax. Once @apply is declared, @apply rounded-lg bg-brand px-4 py-2 font-semibold; produces no diagnostics at all. I think the v3-era @apply forms that caused parse errors are gone.
2. "suggestions are less flexible than the extension's" — true, and this proposal doesn't compete with them. It's for the built-in CSS service, which IntelliSense sidesteps via its own language mode rather than teaching. The two compose: IntelliSense keeps giving class-name completion and theme-aware hovers, and plain .css files stop being marked up.

Putting the file in the framework package rather than the extension also covers editors that aren't VS Code, and projects that don't have the extension installed.

Happy to send a PR

It's an additive JSON file plus a files entry — no runtime impact, and I'd include tests asserting the emitted directives match what the version actually supports. Only if you'd want it, per CONTRIBUTING.

In the meantime I put the same idea in a standalone tool (tailwind-custom-data) that generates the file from the installed version, with a --check mode for CI. Its src/directives.ts is basically the catalogue this proposal would move upstream, if that's a useful starting point.