Documentation Improvement Request: `@reference` Directive Clarity

[richardtallent-erm]

Affected Pages

• https://tailwindcss.com/docs/functions-and-directives#reference-directive
• https://tailwindcss.com/docs/theme#referencing-other-variables

Problem

The @reference directive documentation states:

"If you're just using the default theme with no customizations, you can import tailwindcss directly"

However, it's unclear that:

1. Adding any @theme variables (including @theme inline) counts as "customizations"
2. @reference "tailwindcss" will not include your custom theme variables
3. You must switch to referencing your actual CSS file path when using custom themes

Using @reference "tailwindcss" when you have custom @theme variables results in "Cannot apply unknown utility class" errors when trying to use those custom utilities in @apply directives. The error message suggests adding @reference but doesn't clarify that @reference "tailwindcss" is insufficient in this case.

Suggested Improvements

1. In the @reference section, make it more explicit that you can only use use @reference "tailwindcss" if you have no @theme blocks, otherwise you need to use @reference "path/to/your-css-file.css".

2. Add a callout in the @theme documentation's "Referencing other variables" section:

Note: When using custom theme variables with @apply in component styles, you must use @reference "path/to/your-css-file.css" (not @reference "tailwindcss") to access those variables. See the @reference directive documentation for details.

Why This Matters

Developers expect @reference "tailwindcss" to mean "give me access to all available Tailwind utilities for this project," but it actually means "give me only the default built-in theme, ignoring customizations." This mental model mismatch causes confusion and difficult-to-debug build errors, especially for projects using dynamic theming patterns.

[thecrypticace]

Using @theme at all would mean you're no longer using just the default theme — but maybe can add a bit to clarify this point further. We should probably mention that @reference is just an @import that doesn't output CSS. The semantics are otherwise identical.

[richardtallent-erm]

Yup, it's totally "operator error" on my part in missing it the first 15 times I read it in the docs trying to get my theme to work. I also have a custom variant defined, I assume it wouldn't have worked either, but I didn't test it independently.

As an aside, it would be great if the @reference docs also mentioned the workaround here for relative path references (forgot to include that in my request above):

tailwindlabs/tailwindcss#18433