[v4.0.9+] Variables are ignored when referenced within CSS Modules

[boylett]

What version of Tailwind CSS are you using?

For example: v4.0.9

What build tool (or framework if it abstracts the build tool) are you using?

Vite 6.2.0

What version of Node.js are you using?

22.0.0

What browser are you using?

Chrome, Safari and Firefox

What operating system are you using?

macOS and Windows

Reproduction URL

https://github.com/boylett/tailwind-4-0-9-cssmodule-var-bug

Describe your issue

When referencing the main theme file within CSS Modules, variables are no longer recognised and exported in the main CSS.

This works fine in 4.0.8 (see 'working' branch) so am inclined to believe it has something to do with the new @reference keyword.

Within reproduction, the background colour of the main "Welcome" component wrapper should be --color-hot-pink rather than transparent.

On the 'main' branch, tw 4.0.9, the variable is simply ignored and not included in the final CSS.

[philipp-spiess]

Hey! Thanks for the bug report. The issue is that right now we do not scan .css files for possible CSS variables we use. We'll keep this open while we're thinking about how to resolve this issue.

[mcmxcdev]

We have the same issue, all CSS variables which are not referenced inside e.g. .tsx files are getting purged with a setup like below (simplified example).

On top of that, we have e.g. --text--primary: var(--color-gray-3); which doesn't work anymore since --color-gray-3 could get purged if its not directly used anywhere.

References like --color-background-canvas: var(--background--canvas) -> --background--canvas: var(--color-white) -> --color-white: #ffffff should also still work.

tailwind.css:

@layer reset, theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
/* @import "tailwindcss/preflight.css" layer(base); */
@import "tailwindcss/utilities.css" layer(utilities);

@custom-variant dark (&:where(.darkMode, .darkMode *));

@theme inline {
  --color-*: initial;
  --color-white: #ffffff;
  --color-gray-1: #f3f5f7;
  --color-gray-2: #e9ebee;
  --color-gray-3: #dadde0;

  --color-background-canvas: var(--background--canvas)
  --color-background-base: var(--color-gray-2);
  --color-background-dark-base: var(--color-gray-3);
}

theme.css:

@reference "./tailwind.css";

@layer theme {
  .lightMode {
	--background--canvas: var(--color-white);
    --text--primary: var(--color-gray-1);
    --text--secondary: var(--color-gray-2);
    --text--disable: var(--color-gray-3);
  }

  .darkMode {
    --background--canvas: var(--color-gray-3);
    --text--primary: var(--color-gray-3);
    --text--secondary: var(--color-gray-2);
    --text--disable: var(--color-gray-1);
  }
}

[boylett]

Just popping by to say that this is still happening as of 4.0.14.

I'm assuming the main reason Tailwind removes "unused" variables is for speed/minification - which is fair - but I am a little concerned at the assumption that all unused variables can and should be trimmed, regardless of whether the developer has intentionally placed them into the theme or not.

Surely Tailwind should only omit default variables that the developer has not created? My expectation is that if I add a CSS variable to my theme, it will be included in the CSS payload no matter what. That way I can even reference it dynamically with JavaScript later on if I need to.

I know that Tailwind, historically, has never compiled dynamically constructed class names, but removing custom CSS variables just because they're not immediately referenced by CSS feels a little too intrusive.

Say for example I have a button that generates its own CSS during user interactions (a horrible example I know, but bare with me)

const [ varName, setVarName ] = useState("default");
const [ themeName, setThemeName ] = useState("default");

return (
  <Button
    onMouseEnter={ e => setVarName(`--color-button-${ theme }-hover`) }
    onMouseLeave={ e => setVarName(`--color-button-${ theme }-idle`) }
    onClick={ e => setThemeName("clicked") }
    style={{
      background: varName,
    }}
);

The argument against this is probably something like "just put your variables somewhere else", but that would mean I am unable to reuse values for my Tailwind theme, which sort of defeats the purpose of having variables to begin with.

[RobinMalfait]

@boylett every CSS variable created in @theme will be removed if it was not statically used.
The reason we even do that for user defined @theme blocks compared to the defaults is so that you can import shared themes from your company's design system without shipping unnecessary CSS. Or just have a complete set of values ready for when you need them later.

If you are dynamically using CSS variables you can use the @theme static option (https://tailwindcss.com/docs/theme#generating-all-css-variables) which keeps all the variables for that @theme block. Or if you want to keep all the defaults, you could use @import "tailwindcss" theme(static); which does the same thing but applies it to the @theme we ship behind the scenes.

[boylett]

@RobinMalfait awesome, this is exactly what I was looking for! Thanks so much for getting back to me

[KianYang-Lee]

I used tailwind/upgrade tool to upgrade from v3 to v4, but the upgrade generated the CSS without static. I feel that it should generate it as static so that the behaviour is maintained, as previously if we extended custom color in tailwind.config.js it will not be purged, even when unused