`@reference` misses some fallback values

[aaronadamsCA]

What version of Tailwind CSS are you using?

v4.1.4

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

N/A

What version of Node.js are you using?

v23.11.0

What browser are you using?

N/A

What operating system are you using?

N/A

Reproduction URL

https://play.tailwindcss.com/lAycX1oWGq?file=css

Describe your issue

We apply Tailwind preflight CSS to the entire page, then use @reference to generate utility CSS per module. Unfortunately there are currently a few gaps in the generated CSS. It looks like #16774 misses some fallback values.

I can reproduce the issue on Tailwind Play using this simple config:

@import "tailwindcss/preflight.css";
@reference "tailwindcss/theme.css";
@tailwind utilities;

Right away you'll notice the default HTML has some broken styles because --color-gray-950 doesn't have a fallback value:

https://play.tailwindcss.com/lAycX1oWGq?file=css

Here's another example where --breakpoint-sm doesn't have a fallback value:

https://play.tailwindcss.com/bbX2smHCx6?layout=horizontal

[wongjn]

It could b the fallbacks don't get added here because the arbitrary values are seen as literally arbitrary and not related to Tailwind theme tokens. Thus Tailwind does not interpret them as such and does not "know" there are fallback values for them.

As a work-around, you could consider referencing the theme variable values using --theme():

• --color-gray-950 example
• --breakpoint-sm example

[aaronadamsCA]

Interesting, but I think Tailwind must be seeing those values as theme tokens, right? Since in the regular case it does know to emit their CSS variables.

I'm hoping it's just the reference fallback logic that's missing in a couple of spots.

[wongjn]

Yep, that's because you can think of it doing --theme() calls internally for the regular case . When you do [--foo:var(--color-gray-950)] or max-w-(--breakpoint-sm), it seems it's just passing the stated value through as-is. Though intellisense still picks up the theme value and modifier pattern works for colors, so perhaps it does know they're theme values.

Edit

Seems like fallback emissions rely on resolving to the Tailwind theme:

tailwindcss/packages/tailwindcss/src/theme.ts

Lines 180 to 195 in a7f4a4d

	#var(themeKey: string) {
	let value = this.values.get(themeKey)
	if (!value) {
	return null
	}
	// Since @theme blocks in reference mode do not emit the CSS variables, we can not assume that
	// the values will eventually be set up in the browser (e.g. when using `@apply` inside roots
	// that use `@reference`). Ensure we set up a fallback in these cases.
	let fallback = null
	if (value.options & ThemeOptions.REFERENCE) {
	fallback = value.value
	}
	return `var(${escape(this.prefixKey(themeKey))}${fallback ? `, ${fallback}` : ''})`
	}

This is done in regular class utilities by calling theme.resolve():

tailwindcss/packages/tailwindcss/src/utilities.ts

Lines 391 to 394 in a7f4a4d

	value =
	desc.defaultValue !== undefined
	? desc.defaultValue
	: theme.resolve(null, desc.themeKeys ?? [])

tailwindcss/packages/tailwindcss/src/utilities.ts

Lines 400 to 403 in a7f4a4d

	value = theme.resolve(
	candidate.value.fraction ?? candidate.value.value,
	desc.themeKeys ?? [],
	)

However, for arbitrary properties:

tailwindcss/packages/tailwindcss/src/compile.ts

Lines 256 to 268 in a7f4a4d

	if (candidate.kind === 'arbitrary') {
	let value: string | null = candidate.value
	// Assumption: If an arbitrary property has a modifier, then we assume it
	// is an opacity modifier.
	if (candidate.modifier) {
	value = asColor(value, candidate.modifier, designSystem.theme)
	}
	if (value === null) return []
	return [[decl(candidate.property, value)]]
	}

or arbitrary values:

tailwindcss/packages/tailwindcss/src/utilities.ts

Lines 395 to 399 in a7f4a4d

	} else if (candidate.value.kind === 'arbitrary') {
	if (candidate.modifier) return
	value = candidate.value.value
	dataType = candidate.value.dataType
	} else {

This theme.resolve() call doesn't happen.

[philipp-spiess]

Hey! I don't think what you're doing in this Play is supposed to work. One one hand you rely on CSS variables (var(--color-gray-950)) but on the other hand you're using @reference which ensures that no CSS variables are emitted. So all the variables you rely on are not going to be defined because there is simply no place for them to be written to.

The main use case for @reference was for users who have CSS modules or other per-module stylesheets that don't want to have their CSS variables emitted multiple times. I'd still suggest that you use a regular @import "tailwindcss" in your global CSS styles so that these variables are initialized.

The other idea if you want fallbacks is to use the --theme(…) function instead of var(…): https://play.tailwindcss.com/mtZVq5JEET

[aaronadamsCA]

Thanks @philipp-spiess, it took me a bit but I think I get it now, and I appreciate the workaround.

IMO this is a footgun, because it's very surprising that @import can resolve a CSS variable to a theme variable, but @reference cannot.

Here's a much tighter reproduction I hope convinces you this is worth another look:

• https://play.tailwindcss.com/IcEr24OFx0?layout=horizontal&file=css
• https://play.tailwindcss.com/j9chOWe7pL?layout=horizontal&file=css