Add `@import "…" reference`

[philipp-spiess]

This PR adds a new feature, @import "…" reference that can be used to load Tailwind CSS configuration files without adding any style rules to the CSS.

The idea is that you can use this in combination with your Tailwind CSS root file when you need to have access to your full CSS config outside of the main stylesheet. A common example is for Vue, Svelte, or CSS modules:

@import "./tailwind.css" reference;

.link {
  @apply underline;
}

Importing a file as a reference will convert all @theme block to be reference, so no CSS variables will be emitted. Furthermore it will strip out all custom styles from the stylesheet. Furthermore plugins registered via @plugin or @config inside reference-mode files will not add any content to the CSS file via addBase().

Test Plan

Added unit test for when we handle the import resolution and when postcss-import does it outside of Tailwind CSS. I also changed the Svelte and Vue integration tests to use this new syntax to ensure it works end to end.

[TiBianMod]

NICE this is what i was looking.

you can do something similar now with

@import "tailwindcss/theme" theme(reference);

https://tailwindcss.com/docs/v4-beta#using-apply-in-vue-svelte

[philipp-spiess]

@TiBianMod Yep but we figured it's unintuitive to have to split your config up like this and there are further customizations (e.g. custom @utility or @variant rules) that you can't import via theme(reference). We hope this new API will make it easier!

[amir20]

I was testing this and finally upgraded to v4. However, I noticed my output is actually bigger compared to v3. I have created a discussion at https://github.com/tailwindlabs/tailwindcss/discussions/15544