Reference imports should not generate utilities (#15307)

We noticed an issue where the new `@import "…" reference` syntax was not
throwing away `@tailwind` declarations, effectively causing you to
create utility classes whenever you used this feature.

This is especially noticed in setups with very strict compilers like
Svelte.

## Test Plan

### Before

<img width="1142" alt="Screenshot 2024-12-05 at 11 56 00"
src="https://github.com/user-attachments/assets/546f0eb3-4401-48c9-9268-76992e899226">

### After

<img width="2560" alt="Screenshot 2024-12-05 at 12 27 30"
src="https://github.com/user-attachments/assets/16732000-e02c-49bc-ac6f-91da0cfcc7e8">

CHANGELOG.md

@@ -7,7 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-- Nothing yet!
+### Fixed
+
+- Ensure `@import "…" reference` never generates utilities ([#15307](https://github.com/tailwindlabs/tailwindcss/pull/15307))
 
 ## [4.0.0-beta.5] - 2024-12-04
 

integrations/vite/svelte.test.ts

@@ -48,7 +48,7 @@ test(
           target: document.body,
         })
       `,
-      'src/index.css': css`@import 'tailwindcss' reference;`,
+      'src/index.css': css`@import 'tailwindcss';`,
       'src/App.svelte': html`
         <script>
           import './index.css'
@@ -58,7 +58,7 @@ test(
         <h1 class="global local underline">Hello {name}!</h1>
 
         <style>
-          @import 'tailwindcss/theme' theme(reference);
+          @import 'tailwindcss' reference;
           @import './other.css';
         </style>
       `,
@@ -165,14 +165,11 @@ test(
         <h1 class="local global underline">Hello {name}!</h1>
 
         <style>
-          @import 'tailwindcss/theme' theme(reference);
+          @import 'tailwindcss' reference;
           @import './other.css';
         </style>
       `,
-      'src/index.css': css`
-        @import 'tailwindcss/theme' theme(reference);
-        @import 'tailwindcss/utilities';
-      `,
+      'src/index.css': css` @import 'tailwindcss'; `,
       'src/other.css': css`
         .local {
           @apply text-red-500;

integrations/vite/vue.test.ts

@@ -45,7 +45,7 @@ test(
       `,
       'src/App.vue': html`
         <style>
-          @import 'tailwindcss' reference;
+          @import 'tailwindcss';
           .foo {
             @apply text-red-500;
           }

packages/tailwindcss/src/index.test.ts

@@ -3138,6 +3138,36 @@ describe('`@import "…" reference`', () => {
     `)
   })
 
+  test('does not generate utilities', async () => {
+    let loadStylesheet = async (id: string, base: string) => {
+      if (id === './foo/baz.css') {
+        return {
+          content: css`
+            @layer utilities {
+              @tailwind utilities;
+            }
+          `,
+          base: '/root/foo',
+        }
+      }
+      return {
+        content: css`
+          @import './foo/baz.css';
+        `,
+        base: '/root/foo',
+      }
+    }
+
+    let { build } = await compile(
+      css`
+        @import './foo/bar.css' reference;
+      `,
+      { loadStylesheet },
+    )
+
+    expect(build(['text-underline', 'border']).trim()).toMatchInlineSnapshot(`"@layer utilities;"`)
+  })
+
   test('removes styles when the import resolver was handled outside of Tailwind CSS', async () => {
     await expect(
       compileCss(

packages/tailwindcss/src/index.ts

@@ -388,11 +388,21 @@ async function parseCss(
                 return WalkAction.Skip
               }
 
-              // Other at-rules, like `@media`, `@supports`, or `@layer` should
-              // be recursively traversed as these might be inserted by the
-              // `@import` resolution.
+              case '@media':
+              case '@supports':
+              case '@layer': {
+                // These rules should be recursively traversed as these might be
+                // inserted by the `@import` resolution.
+                return
+              }
+
+              default: {
+                replaceWith([])
+                return WalkAction.Skip
+              }
             }
           })
+
           node.nodes = [contextNode({ reference: true }, node.nodes)]
         }