Canonicalize calc(var(--spacing)*…) expressions into --spacing(…) (tailwindlabs#19769)

This PR canonicalizes usages of `calc(var(--spacing)*…)` to
`--spacing(…)` when used in arbitrary values.

Some examples:

| Before | After |
| --- | --- |
| `pt-[min(20%,calc(var(--spacing)*8))]` | `pt-[min(20%,--spacing(8))]`
|
| `pt-[min(20%,calc(var(--spacing)*var(--other)))]` |
`pt-[min(20%,--spacing(var(--other)))]` |
| `pt-[calc(var(--spacing)*8)]` | `pt-8` |
| `pt-[calc(var(--spacing)*var(--other))]` |
`pt-[--spacing(var(--other))]` |
| `[padding-top:min(20%,calc(var(--spacing)*8))]` |
`pt-[min(20%,--spacing(8))]` |
| `[padding-top:min(20%,calc(var(--spacing)*var(--other)))]` |
`pt-[min(20%,--spacing(var(--other)))]` |
| `[padding-top:calc(var(--spacing)*8)]` | `pt-8` |
| `[padding-top:calc(var(--spacing)*var(--other))]` |
`pt-[--spacing(var(--other))]` |


## Test plan

1. Existing tests pass
2. Added new tests

Author: RobinMalfait

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Guard object lookups against inherited prototype properties ([#19725](https://github.com/tailwindlabs/tailwindcss/pull/19725))
+- Canonicalize `calc(var(--spacing)*…)` expressions into `--spacing(…)` ([#19769](https://github.com/tailwindlabs/tailwindcss/pull/19769))
 
 ## [4.2.1] - 2026-02-23
 

packages/tailwindcss/src/canonicalize-candidates.test.ts

@@ -254,6 +254,20 @@ describe.each([['default'], ['with-variant'], ['important'], ['prefix']])('%s',
     // Additionally we remove unnecessary whitespace.
     ['grid-cols-[min(50%_,_theme(spacing.80))_auto]', 'grid-cols-[min(50%,--spacing(80))_auto]'],
 
+    // `calc(var(--spacing)*…)` to `--spacing(…)`
+    ['pt-[min(20%,calc(var(--spacing)*8))]', 'pt-[min(20%,--spacing(8))]'],
+    ['pt-[min(20%,calc(var(--spacing)*var(--other)))]', 'pt-[min(20%,--spacing(var(--other)))]'],
+    ['pt-[calc(var(--spacing)*8)]', 'pt-8'],
+    ['pt-[calc(var(--spacing)*var(--other))]', 'pt-[--spacing(var(--other))]'],
+
+    ['[padding-top:min(20%,calc(var(--spacing)*8))]', 'pt-[min(20%,--spacing(8))]'],
+    [
+      '[padding-top:min(20%,calc(var(--spacing)*var(--other)))]',
+      'pt-[min(20%,--spacing(var(--other)))]',
+    ],
+    ['[padding-top:calc(var(--spacing)*8)]', 'pt-8'],
+    ['[padding-top:calc(var(--spacing)*var(--other))]', 'pt-[--spacing(var(--other))]'],
+
     // `theme(…)` calls valid in v3, but not in v4 should still be converted.
     ['[--foo:theme(transitionDuration.500)]', '[--foo:theme(transitionDuration.500)]'],
 

packages/tailwindcss/src/canonicalize-candidates.ts

@@ -527,6 +527,7 @@ type UtilityCanonicalizationFunction = (
 const UTILITY_CANONICALIZATIONS: UtilityCanonicalizationFunction[] = [
   bgGradientToLinear,
   themeToVarUtility,
+  calcToSpacingFunction,
   arbitraryUtilities,
   bareValueUtilities,
   deprecatedUtilities,
@@ -640,6 +641,69 @@ function themeToVarVariant(
   return variant
 }
 
+function calcToSpacingFunction(
+  candidate: Candidate,
+  options: InternalCanonicalizeOptions,
+): Candidate {
+  if (candidate.kind === 'arbitrary') {
+    candidate.value = spacingCalcToSpacingFunction(candidate.value, options.designSystem)
+  } else if (candidate.kind === 'functional' && candidate.value?.kind === 'arbitrary') {
+    candidate.value.value = spacingCalcToSpacingFunction(
+      candidate.value.value,
+      options.designSystem,
+    )
+  }
+
+  return candidate
+}
+
+function spacingCalcToSpacingFunction(input: string, designSystem: DesignSystem) {
+  let spacingVariable = designSystem.theme.prefix
+    ? `--${designSystem.theme.prefix}-spacing`
+    : '--spacing'
+
+  let ast = ValueParser.parse(input)
+
+  walk(ast, (node) => {
+    // calc(…)
+    if (node.kind !== 'function' || node.value !== 'calc') return
+
+    // calc(var(--spacing) * 2)
+    //      --------------       1. function        (var)
+    //                    -      2. separator       ( )
+    //                     -     3. word            (*)
+    //                      -    4. separator       ( )
+    //                       -   5. any value, word (2)
+    if (node.nodes.length !== 5) return
+
+    // *
+    if (node.nodes[2].kind !== 'word' || node.nodes[2].value !== '*') {
+      return
+    }
+
+    // var(--spacing)
+    if (
+      node.nodes[0].kind !== 'function' ||
+      node.nodes[0].value !== 'var' ||
+      node.nodes[0].nodes.length !== 1 ||
+      node.nodes[0].nodes[0].kind !== 'word' ||
+      node.nodes[0].nodes[0].value !== spacingVariable
+    ) {
+      return
+    }
+
+    return WalkAction.Replace(
+      ValueParser.parse(
+        `--spacing(${
+          ValueParser.toCss([node.nodes[4]]) // Value node
+        })`,
+      ),
+    )
+  })
+
+  return ValueParser.toCss(ast)
+}
+
 const CONVERTER_KEY = Symbol()
 function createConverterCache(
   designSystem: DesignSystem,