Re-enable: Only expose used CSS variables (#16676)

This PR re-enables the changes necessary to remove unused theme
variables and keyframes form your CSS.

This change was initially landed as #16211 and then later reverted in
#16403 because we found some unexpected interactions with using `@apply`
and CSS variables in multi-root setups like CSS modules or Vue inline
`<style>` blocks that were no longer seeing their required variables
defined.

This issue is fixed by now ensuring that theme variables that are
defined within an `@reference "…"` boundary will still be emitted in the
generated CSS when used (as this would otherwise not generate a valid
stylesheet).

So given the following input CSS:

```css
@reference "tailwindcss";
.text-red {
  @apply text-red-500;
}
```

We will now compile this to:

```css
@layer theme {
  :root, :host {
    --text-red-500: oklch(0.637 0.237 25.331);
  }
}
.text-red {
  color: var(--text-red-500);
}
```

This PR also improves the initial implementation to not mark theme
variables as used if they are only used to define other theme variables.
For example:

```css
@theme {
  --font-sans:
    ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol',
    'Noto Color Emoji';
  --font-mono:
    ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New',
    monospace;

  --default-font-family: var(--font-sans);
  --default-mono-font-family: var(--font-mono);
}

.default-font-family {
  font-family: var(--default-font-family);
}
```

This would be reduced to the following now as `--font-mono` is only used
to define another variable and never used outside the theme block:

```css
:root, :host {
  --font-sans:
    ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol',
    'Noto Color Emoji';
  --default-font-family: var(--font-sans);
}

.default-font-family {
  font-family: var(--default-font-family);
}
```

## Test plan

- See updated unit and integration tests
- Validated it works end-to-end by using a SvelteKit example

Author: philipp-spiess

CHANGELOG.md

@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - _Experimental_: Add `user-valid` and `user-invalid` variants ([#12370](https://github.com/tailwindlabs/tailwindcss/pull/12370))
 
+### Changed
+
+- Don't include theme variables that aren't used in compiled CSS ([#16211](https://github.com/tailwindlabs/tailwindcss/pull/16211), [#16676](https://github.com/tailwindlabs/tailwindcss/pull/16676))
+
 ### Fixed
 
 - Remove invalid `!important` on CSS variable declarations ([#16668](https://github.com/tailwindlabs/tailwindcss/pull/16668))
@@ -44,9 +48,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Revert change to no longer include theme variables that aren't used in compiled CSS ([#16403](https://github.com/tailwindlabs/tailwindcss/pull/16403))
-
-### Fixed
-
 - Upgrade: Don't migrate `blur` to `blur-sm` when used with Next.js `<Image placeholder="blur" />` ([#16405](https://github.com/tailwindlabs/tailwindcss/pull/16405))
 
 ## [4.0.5] - 2025-02-08

integrations/cli/index.test.ts

@@ -1289,9 +1289,7 @@ test(
     expect(await fs.dumpFiles('./dist/*.css')).toMatchInlineSnapshot(`
       "
       --- ./dist/out.css ---
-      :root, :host {
-        --color-blue-500: blue;
-      }
+      <EMPTY>
       "
     `)
 

packages/@tailwindcss-postcss/src/__snapshots__/index.test.ts.snap

@@ -330,11 +330,7 @@ test('runs `Once` plugins in the right order', async () => {
   )
 
   expect(result.css.trim()).toMatchInlineSnapshot(`
-    ":root, :host {
-      --color-red-500: red;
-    }
-
-    .custom-css {
+    ".custom-css {
       color: red;
     }"
   `)
@@ -347,11 +343,7 @@ test('runs `Once` plugins in the right order', async () => {
     }"
   `)
   expect(after).toMatchInlineSnapshot(`
-    ":root, :host {
-      --color-red-500: red;
-    }
-
-    .custom-css {
+    ".custom-css {
       color: red;
     }"
   `)