Fix polyfill in combination with unused CSS variable removal (#17555)

philipp-spiess · RobinMalfait · web-flow · commit 811e97d61afa · 2025-04-07T09:18:47.000Z
This PR fixes an issue we noticed while investigating #17553, where the unused CSS variable removal didn't work properly when the theme variable it tried to remove was modified by a polyfill rule. The way the bookkeeping for the unused CSS variable worked was that it tired to find the declaration inside it's parent after the traversal. However, the `color-mix(…)` polyfill has since then made changes to the declaration so it can't find it's position correctly anymore and will thus instead delete the last declaration of the node (this caused unrelated CSS variables to be eliminated while the ones with `color-mix(…)` were unexpectedly kept). To fix this, we decided to apply the polyfills after any eventual deletions. This also ensures that no `@supports` query for the variables are created and simplifies the code a bit since all polyfills are now colocated. ## Test plan - Added a unit test for the example we discovered in #17553 - Luckily the conditions of this seemed rare enough so that it doesn't cause any other of our tests to update. --------- Co-authored-by: Robin Malfait <malfait.robin@gmail.com>
diff --git a/CHANGELOG.md b/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 `color-mix(…)` polyfills do not cause used CSS variables to be removed ([#17555](https://github.com/tailwindlabs/tailwindcss/pull/17555))
 
 ## [4.1.3] - 2025-04-04
 
diff --git a/packages/tailwindcss/src/ast.ts b/packages/tailwindcss/src/ast.ts
@@ -266,10 +266,8 @@ export function optimizeAst(
 ) {
   let atRoots: AstNode[] = []
   let seenAtProperties = new Set<string>()
-  let cssThemeVariables = new DefaultMap<
-    Extract<AstNode, { nodes: AstNode[] }>['nodes'],
-    Set<Declaration>
-  >(() => new Set())
+  let cssThemeVariables = new DefaultMap<AstNode[], Set<Declaration>>(() => new Set())
+  let colorMixDeclarations = new DefaultMap<AstNode[], Set<Declaration>>(() => new Set())
   let keyframes = new Set<AtRule>()
   let usedKeyframeNames = new Set()
 
@@ -280,7 +278,7 @@ export function optimizeAst(
 
   function transform(
     node: AstNode,
-    parent: Extract<AstNode, { nodes: AstNode[] }>['nodes'],
+    parent: AstNode[],
     context: Record<string, string | boolean> = {},
     depth = 0,
   ) {
@@ -326,71 +324,7 @@ export function optimizeAst(
       // Create fallback values for usages of the `color-mix(…)` function that reference variables
       // found in the theme config.
       if (polyfills & Polyfills.ColorMix && node.value.includes('color-mix(')) {
-        let ast = ValueParser.parse(node.value)
-
-        let requiresPolyfill = false
-        ValueParser.walk(ast, (node, { replaceWith }) => {
-          if (node.kind !== 'function' || node.value !== 'color-mix') return
-
-          let containsUnresolvableVars = false
-          let containsCurrentcolor = false
-          ValueParser.walk(node.nodes, (node, { replaceWith }) => {
-            if (node.kind == 'word' && node.value.toLowerCase() === 'currentcolor') {
-              containsCurrentcolor = true
-              requiresPolyfill = true
-              return
-            }
-            if (node.kind !== 'function' || node.value !== 'var') return
-            let firstChild = node.nodes[0]
-            if (!firstChild || firstChild.kind !== 'word') return
-
-            requiresPolyfill = true
-
-            let inlinedColor = designSystem.theme.resolveValue(null, [firstChild.value as any])
-            if (!inlinedColor) {
-              containsUnresolvableVars = true
-              return
-            }
-
-            replaceWith({ kind: 'word', value: inlinedColor })
-          })
-
-          if (containsUnresolvableVars || containsCurrentcolor) {
-            let separatorIndex = node.nodes.findIndex(
-              (node) => node.kind === 'separator' && node.value.trim().includes(','),
-            )
-            if (separatorIndex === -1) return
-            let firstColorValue =
-              node.nodes.length > separatorIndex ? node.nodes[separatorIndex + 1] : null
-            if (!firstColorValue) return
-            replaceWith(firstColorValue)
-          } else if (requiresPolyfill) {
-            // Change the colorspace to `srgb` since the fallback values should not be represented as
-            // `oklab(…)` functions again as their support in Safari <16 is very limited.
-            let colorspace = node.nodes[2]
-            if (
-              colorspace.kind === 'word' &&
-              (colorspace.value === 'oklab' ||
-                colorspace.value === 'oklch' ||
-                colorspace.value === 'lab' ||
-                colorspace.value === 'lch')
-            ) {
-              colorspace.value = 'srgb'
-            }
-          }
-        })
-
-        if (requiresPolyfill) {
-          let fallback = {
-            ...node,
-            value: ValueParser.toCss(ast),
-          }
-          let colorMixQuery = rule('@supports (color: color-mix(in lab, red, red))', [node])
-
-          parent.push(fallback, colorMixQuery)
-
-          return
-        }
+        colorMixDeclarations.get(parent).add(node)
       }
 
       parent.push(node)
@@ -595,6 +529,74 @@ export function optimizeAst(
   newAst = newAst.concat(atRoots)
 
   // Fallbacks
+  // Create fallback values for usages of the `color-mix(…)` function that reference variables
+  // found in the theme config.
+  if (polyfills & Polyfills.ColorMix) {
+    for (let [parent, declarations] of colorMixDeclarations) {
+      for (let declaration of declarations) {
+        let idx = parent.indexOf(declaration)
+        // If the declaration is no longer present, we don't need to create a polyfill anymore
+        if (idx === -1 || declaration.value == null) continue
+
+        let ast = ValueParser.parse(declaration.value)
+        let requiresPolyfill = false
+        ValueParser.walk(ast, (node, { replaceWith }) => {
+          if (node.kind !== 'function' || node.value !== 'color-mix') return
+          let containsUnresolvableVars = false
+          let containsCurrentcolor = false
+          ValueParser.walk(node.nodes, (node, { replaceWith }) => {
+            if (node.kind == 'word' && node.value.toLowerCase() === 'currentcolor') {
+              containsCurrentcolor = true
+              requiresPolyfill = true
+              return
+            }
+            if (node.kind !== 'function' || node.value !== 'var') return
+            let firstChild = node.nodes[0]
+            if (!firstChild || firstChild.kind !== 'word') return
+            requiresPolyfill = true
+            let inlinedColor = designSystem.theme.resolveValue(null, [firstChild.value as any])
+            if (!inlinedColor) {
+              containsUnresolvableVars = true
+              return
+            }
+            replaceWith({ kind: 'word', value: inlinedColor })
+          })
+          if (containsUnresolvableVars || containsCurrentcolor) {
+            let separatorIndex = node.nodes.findIndex(
+              (node) => node.kind === 'separator' && node.value.trim().includes(','),
+            )
+            if (separatorIndex === -1) return
+            let firstColorValue =
+              node.nodes.length > separatorIndex ? node.nodes[separatorIndex + 1] : null
+            if (!firstColorValue) return
+            replaceWith(firstColorValue)
+          } else if (requiresPolyfill) {
+            // Change the colorspace to `srgb` since the fallback values should not be represented as
+            // `oklab(…)` functions again as their support in Safari <16 is very limited.
+            let colorspace = node.nodes[2]
+            if (
+              colorspace.kind === 'word' &&
+              (colorspace.value === 'oklab' ||
+                colorspace.value === 'oklch' ||
+                colorspace.value === 'lab' ||
+                colorspace.value === 'lch')
+            ) {
+              colorspace.value = 'srgb'
+            }
+          }
+        })
+        if (!requiresPolyfill) continue
+
+        let fallback = {
+          ...declaration,
+          value: ValueParser.toCss(ast),
+        }
+        let colorMixQuery = rule('@supports (color: color-mix(in lab, red, red))', [declaration])
+        parent.splice(idx, 1, fallback, colorMixQuery)
+      }
+    }
+  }
+
   if (polyfills & Polyfills.AtProperty) {
     let fallbackAst = []
 
diff --git a/packages/tailwindcss/src/compat/config.test.ts b/packages/tailwindcss/src/compat/config.test.ts
@@ -1164,21 +1164,21 @@ test('utilities must be prefixed', async () => {
   // Prefixed utilities are generated
   expect(compiler.build(['tw:underline', 'tw:hover:line-through', 'tw:custom']))
     .toMatchInlineSnapshot(`
-    ".tw\\:custom {
-      color: red;
-    }
-    .tw\\:underline {
-      text-decoration-line: underline;
-    }
-    .tw\\:hover\\:line-through {
-      &:hover {
-        @media (hover: hover) {
-          text-decoration-line: line-through;
+      ".tw\\:custom {
+        color: red;
+      }
+      .tw\\:underline {
+        text-decoration-line: underline;
+      }
+      .tw\\:hover\\:line-through {
+        &:hover {
+          @media (hover: hover) {
+            text-decoration-line: line-through;
+          }
         }
       }
-    }
-    "
-  `)
+      "
+    `)
 
   // Non-prefixed utilities are ignored
   compiler = await compile(input, {
diff --git a/packages/tailwindcss/src/compat/plugin-api.test.ts b/packages/tailwindcss/src/compat/plugin-api.test.ts
@@ -243,14 +243,14 @@ describe('theme', async () => {
 
     expect(compiler.build(['animate-duration-316', 'animate-duration-slow']))
       .toMatchInlineSnapshot(`
-      ".animate-duration-316 {
-        animation-duration: 316ms;
-      }
-      .animate-duration-slow {
-        animation-duration: 800ms;
-      }
-      "
-    `)
+        ".animate-duration-316 {
+          animation-duration: 316ms;
+        }
+        .animate-duration-slow {
+          animation-duration: 800ms;
+        }
+        "
+      `)
   })
 
   test('plugin theme can have opacity modifiers', async () => {
@@ -3340,16 +3340,16 @@ describe('matchUtilities()', () => {
     }
 
     expect(optimizeCss(await run(['@w-1', 'hover:@w-1'])).trim()).toMatchInlineSnapshot(`
-        ".\\@w-1 {
+      ".\\@w-1 {
+        width: 1px;
+      }
+
+      @media (hover: hover) {
+        .hover\\:\\@w-1:hover {
           width: 1px;
         }
-
-        @media (hover: hover) {
-          .hover\\:\\@w-1:hover {
-            width: 1px;
-          }
-        }"
-      `)
+      }"
+    `)
   })
 
   test('custom functional utilities can return an array of rules', async () => {
@@ -4153,30 +4153,30 @@ describe('addComponents()', () => {
 
     expect(optimizeCss(compiled.build(['btn', 'btn-blue', 'btn-red'])).trim())
       .toMatchInlineSnapshot(`
-      ".btn {
-        border-radius: .25rem;
-        padding: .5rem 1rem;
-        font-weight: 600;
-      }
+        ".btn {
+          border-radius: .25rem;
+          padding: .5rem 1rem;
+          font-weight: 600;
+        }
 
-      .btn-blue {
-        color: #fff;
-        background-color: #3490dc;
-      }
+        .btn-blue {
+          color: #fff;
+          background-color: #3490dc;
+        }
 
-      .btn-blue:hover {
-        background-color: #2779bd;
-      }
+        .btn-blue:hover {
+          background-color: #2779bd;
+        }
 
-      .btn-red {
-        color: #fff;
-        background-color: #e3342f;
-      }
+        .btn-red {
+          color: #fff;
+          background-color: #e3342f;
+        }
 
-      .btn-red:hover {
-        background-color: #cc1f1a;
-      }"
-    `)
+        .btn-red:hover {
+          background-color: #cc1f1a;
+        }"
+      `)
   })
 })
 
@@ -4212,16 +4212,16 @@ describe('matchComponents()', () => {
 
     expect(optimizeCss(compiled.build(['prose', 'sm:prose-sm', 'hover:prose-lg'])).trim())
       .toMatchInlineSnapshot(`
-      ".prose {
-        --container-size: normal;
-      }
-
-      @media (hover: hover) {
-        .hover\\:prose-lg:hover {
-          --container-size: lg;
+        ".prose {
+          --container-size: normal;
         }
-      }"
-    `)
+
+        @media (hover: hover) {
+          .hover\\:prose-lg:hover {
+            --container-size: lg;
+          }
+        }"
+      `)
   })
 })
 
diff --git a/packages/tailwindcss/src/css-functions.test.ts b/packages/tailwindcss/src/css-functions.test.ts
@@ -756,10 +756,10 @@ describe('theme(…)', () => {
               }
             `),
           ).toMatchInlineSnapshot(`
-          ".fam {
-            font-family: ui-sans-serif, system-ui, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol, Noto Color Emoji;
-          }"
-        `)
+            ".fam {
+              font-family: ui-sans-serif, system-ui, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol, Noto Color Emoji;
+            }"
+          `)
         })
 
         test('theme(fontFamily.sans) (config)', async () => {
@@ -776,10 +776,10 @@ describe('theme(…)', () => {
           )
 
           expect(optimizeCss(compiled.build([])).trim()).toMatchInlineSnapshot(`
-          ".fam {
-            font-family: ui-sans-serif, system-ui, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol, Noto Color Emoji;
-          }"
-        `)
+            ".fam {
+              font-family: ui-sans-serif, system-ui, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol, Noto Color Emoji;
+            }"
+          `)
         })
       })
 
diff --git a/packages/tailwindcss/src/index.test.ts b/packages/tailwindcss/src/index.test.ts
diff --git a/packages/tailwindcss/src/utilities.test.ts b/packages/tailwindcss/src/utilities.test.ts
