Ensure that the CSS file rebuilds if a new CSS variable is used from templates (#17301)

Fixes #17288

This PR fixes an issue where changes in template files that _only mark a
new CSS variable as used_ was not causing the CSS file to rebuilds.

This also fixes a flaky integration test that was caused by a missing
`await` line on the final assertion (causing it to sometimes run the
assertion in time while the test runner was still running).

## Test plan

Turns out we already had an integration test for this but it wasn't
correctly running due to the missing await.

Author: philipp-spiess

CHANGELOG.md

@@ -37,6 +37,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fix class extraction followed by `(` in Slim ([#17278](https://github.com/tailwindlabs/tailwindcss/pull/17278))
 - Export `PluginUtils` from `tailwindcss/plugin` for compatibility with v3 ([#17299](https://github.com/tailwindlabs/tailwindcss/pull/17299))
 - Increase Standalone hardware compatibility on macOS x64 builds ([#17267](https://github.com/tailwindlabs/tailwindcss/pull/17267))
+- Ensure that the CSS file rebuilds if a new CSS variable is used from templates ([#17301](https://github.com/tailwindlabs/tailwindcss/pull/17301))
 
 ## [4.0.14] - 2025-03-13
 

integrations/cli/index.test.ts

@@ -1303,11 +1303,11 @@ test(
       `,
     )
 
-    fs.expectFileToContain(
+    // prettier-ignore
+    await fs.expectFileToContain(
       './dist/out.css',
       css`
-        :root,
-        :host {
+        :root, :host {
           --color-blue-500: blue;
         }
       `,

packages/tailwindcss/src/index.ts

@@ -696,18 +696,21 @@ export async function compileAst(
       }
 
       let didChange = defaultDidChange
+      let didAddExternalVariable = false
       defaultDidChange = false
 
       // Add all new candidates unless we know that they are invalid.
       let prevSize = allValidCandidates.size
       for (let candidate of newRawCandidates) {
         if (!designSystem.invalidCandidates.has(candidate)) {
           if (candidate[0] === '-' && candidate[1] === '-') {
-            designSystem.theme.markUsedVariable(candidate)
+            let didMarkVariableAsUsed = designSystem.theme.markUsedVariable(candidate)
+            didChange ||= didMarkVariableAsUsed
+            didAddExternalVariable ||= didMarkVariableAsUsed
           } else {
             allValidCandidates.add(candidate)
+            didChange ||= allValidCandidates.size !== prevSize
           }
-          didChange ||= allValidCandidates.size !== prevSize
         }
       }
 
@@ -725,7 +728,7 @@ export async function compileAst(
       // If no new ast nodes were generated, then we can return the original
       // CSS. This currently assumes that we only add new ast nodes and never
       // remove any.
-      if (previousAstNodeCount === newNodes.length) {
+      if (!didAddExternalVariable && previousAstNodeCount === newNodes.length) {
         compiled ??= optimizeAst(ast, designSystem)
         return compiled
       }

packages/tailwindcss/src/theme.ts

@@ -193,11 +193,13 @@ export class Theme {
     return `var(${escape(this.prefixKey(themeKey))}${fallback ? `, ${fallback}` : ''})`
   }
 
-  markUsedVariable(themeKey: string) {
+  markUsedVariable(themeKey: string): boolean {
     let key = unescape(this.#unprefixKey(themeKey))
     let value = this.values.get(key)
-    if (!value) return
+    if (!value) return false
+    let isUsed = value.options & ThemeOptions.USED
     value.options |= ThemeOptions.USED
+    return !isUsed
   }
 
   resolve(