Upgrade: Migrate spacing scale (#14905)

This PR adds migrations for the recent changes to the `--spacing` scale
done in #12263.

There are a few steps that we do to ensure we have the best upgrade
experience:

- If you are overwriting the `spacing` theme with custom values, we now
check if the new values are multiplies of the default spacing scale.
When they are, we can safely remove the overwrite.
- If you are extending the `spacing` theme, we will unset the default
`--spacing` scale and only use the values you provided.
- Any `theme()` function calls are replaced with `calc(var(--spacing) *
multiplier)` unless the values are extending the default scale.

One caveat here is for `theme()` key which can not be replaced with
`var()` (e.g. in `@media` attribute positions). These will not be able
to be replaced with `calc()` either so the following needs to stay
unmigrated:

```css
@media (max-width: theme(spacing.96)) {
  .foo {
    color: red;
  }
}
```

## Test plan

We are mainly testing two scenarios: The JS config _extends_ the
`spacing` namespace and the JS config _overwrites_ the `spacing`
namespace. For both cases we have added an integration test each to
ensure this works as expected. The test contains a mixture of keys (some
of it matching the default multiples, some don't, some have different
scales, and some use non-numeric identifiers). In addition to asserting
on the created CSS `@theme`, we also ensure that `theme()` calls are
properly replaced.

---------

Co-authored-by: Adam Wathan <[email protected]>
Co-authored-by: Adam Wathan <[email protected]>

Author: philipp-spiess

CHANGELOG.md

@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - _Upgrade (experimental)_: Rename `drop-shadow` to `drop-shadow-sm` and `drop-shadow-sm` to `drop-shadow-xs` ([#14875](https://github.com/tailwindlabs/tailwindcss/pull/14875))
 - _Upgrade (experimental)_: Rename `rounded` to `rounded-sm` and `rounded-sm` to `rounded-xs` ([#14875](https://github.com/tailwindlabs/tailwindcss/pull/14875))
 - _Upgrade (experimental)_: Rename `blur` to `blur-sm` and `blur-sm` to `blur-xs` ([#14875](https://github.com/tailwindlabs/tailwindcss/pull/14875))
+- _Upgrade (experimental)_: Migrate `theme()` usage and JS config files to use the new `--spacing` multiplier where possible ([#14905](https://github.com/tailwindlabs/tailwindcss/pull/14905))
 
 ### Fixed
 

integrations/upgrade/js-config.test.ts

@@ -1415,4 +1415,260 @@ describe('border compatibility', () => {
       `)
     },
   )
+
+  test(
+    'migrates extended spacing keys',
+    {
+      fs: {
+        'package.json': json`
+          {
+            "dependencies": {
+              "@tailwindcss/upgrade": "workspace:^"
+            }
+          }
+        `,
+        'tailwind.config.ts': ts`
+          import { type Config } from 'tailwindcss'
+
+          export default {
+            content: ['./src/**/*.html'],
+            theme: {
+              extend: {
+                spacing: {
+                  2: '0.5rem',
+                  4.5: '1.125rem',
+                  5.5: '1.375em', // Units are different from --spacing scale
+                  13: '3.25rem',
+                  100: '100px',
+                  miami: '1337px',
+                },
+              },
+            },
+          } satisfies Config
+        `,
+        'src/input.css': css`
+          @tailwind base;
+          @tailwind components;
+          @tailwind utilities;
+
+          .container {
+            width: theme(spacing.2);
+            width: theme(spacing[4.5]);
+            width: theme(spacing[5.5]);
+            width: theme(spacing[13]);
+            width: theme(spacing[100]);
+            width: theme(spacing.miami);
+          }
+        `,
+        'src/index.html': html`
+          <div
+            class="[width:theme(spacing.2)]
+              [width:theme(spacing[4.5])]
+              [width:theme(spacing[5.5])]
+              [width:theme(spacing[13])]
+              [width:theme(spacing[100])]
+              [width:theme(spacing.miami)]"
+          ></div>
+        `,
+      },
+    },
+    async ({ exec, fs }) => {
+      await exec('npx @tailwindcss/upgrade')
+
+      expect(await fs.dumpFiles('src/**/*.{css,html}')).toMatchInlineSnapshot(`
+        "
+        --- src/index.html ---
+        <div
+          class="[width:calc(var(--spacing)*2)]
+            [width:calc(var(--spacing)*4.5)]
+            [width:var(--spacing-5_5)]
+            [width:calc(var(--spacing)*13)]
+            [width:var(--spacing-100)]
+            [width:var(--spacing-miami)]"
+        ></div>
+
+        --- src/input.css ---
+        @import 'tailwindcss';
+
+        @theme {
+          --spacing-100: 100px;
+          --spacing-5_5: 1.375em;
+          --spacing-miami: 1337px;
+        }
+
+        /*
+          The default border color has changed to \`currentColor\` in Tailwind CSS v4,
+          so we've added these compatibility styles to make sure everything still
+          looks the same as it did with Tailwind CSS v3.
+
+          If we ever want to remove these styles, we need to add an explicit border
+          color utility to any element that depends on these defaults.
+        */
+        @layer base {
+          *,
+          ::after,
+          ::before,
+          ::backdrop,
+          ::file-selector-button {
+            border-color: var(--color-gray-200, currentColor);
+          }
+        }
+
+        /*
+          Form elements have a 1px border by default in Tailwind CSS v4, so we've
+          added these compatibility styles to make sure everything still looks the
+          same as it did with Tailwind CSS v3.
+
+          If we ever want to remove these styles, we need to add \`border-0\` to
+          any form elements that shouldn't have a border.
+        */
+        @layer base {
+          input:where(:not([type='button'], [type='reset'], [type='submit'])),
+          select,
+          textarea {
+            border-width: 0;
+          }
+        }
+
+        .container {
+          width: calc(var(--spacing) * 2);
+          width: calc(var(--spacing) * 4.5);
+          width: var(--spacing-5_5);
+          width: calc(var(--spacing) * 13);
+          width: var(--spacing-100);
+          width: var(--spacing-miami);
+        }
+        "
+      `)
+    },
+  )
+
+  test(
+    'retains overwriting spacing scale',
+    {
+      fs: {
+        'package.json': json`
+          {
+            "dependencies": {
+              "@tailwindcss/upgrade": "workspace:^"
+            }
+          }
+        `,
+        'tailwind.config.ts': ts`
+          import { type Config } from 'tailwindcss'
+
+          export default {
+            content: ['./src/**/*.html'],
+            theme: {
+              spacing: {
+                2: '0.5rem',
+                4.5: '1.125rem',
+                5.5: '1.375em',
+                13: '3.25rem',
+                100: '100px',
+                miami: '1337px',
+              },
+            },
+          } satisfies Config
+        `,
+        'src/input.css': css`
+          @tailwind base;
+          @tailwind components;
+          @tailwind utilities;
+
+          .container {
+            width: theme(spacing.2);
+            width: theme(spacing[4.5]);
+            width: theme(spacing[5.5]);
+            width: theme(spacing[13]);
+            width: theme(spacing[100]);
+            width: theme(spacing.miami);
+          }
+        `,
+        'src/index.html': html`
+          <div
+            class="[width:theme(spacing.2)]
+              [width:theme(spacing[4.5])]
+              [width:theme(spacing[5.5])]
+              [width:theme(spacing[13])]
+              [width:theme(spacing[100])]
+              [width:theme(spacing.miami)]"
+          ></div>
+        `,
+      },
+    },
+    async ({ exec, fs }) => {
+      await exec('npx @tailwindcss/upgrade')
+
+      expect(await fs.dumpFiles('src/**/*.{css,html}')).toMatchInlineSnapshot(`
+        "
+        --- src/index.html ---
+        <div
+          class="[width:var(--spacing-2)]
+            [width:var(--spacing-4_5)]
+            [width:var(--spacing-5_5)]
+            [width:var(--spacing-13)]
+            [width:var(--spacing-100)]
+            [width:var(--spacing-miami)]"
+        ></div>
+
+        --- src/input.css ---
+        @import 'tailwindcss';
+
+        @theme {
+          --spacing-*: initial;
+          --spacing-2: 0.5rem;
+          --spacing-13: 3.25rem;
+          --spacing-100: 100px;
+          --spacing-4_5: 1.125rem;
+          --spacing-5_5: 1.375em;
+          --spacing-miami: 1337px;
+        }
+
+        /*
+          The default border color has changed to \`currentColor\` in Tailwind CSS v4,
+          so we've added these compatibility styles to make sure everything still
+          looks the same as it did with Tailwind CSS v3.
+
+          If we ever want to remove these styles, we need to add an explicit border
+          color utility to any element that depends on these defaults.
+        */
+        @layer base {
+          *,
+          ::after,
+          ::before,
+          ::backdrop,
+          ::file-selector-button {
+            border-color: var(--color-gray-200, currentColor);
+          }
+        }
+
+        /*
+          Form elements have a 1px border by default in Tailwind CSS v4, so we've
+          added these compatibility styles to make sure everything still looks the
+          same as it did with Tailwind CSS v3.
+
+          If we ever want to remove these styles, we need to add \`border-0\` to
+          any form elements that shouldn't have a border.
+        */
+        @layer base {
+          input:where(:not([type='button'], [type='reset'], [type='submit'])),
+          select,
+          textarea {
+            border-width: 0;
+          }
+        }
+
+        .container {
+          width: var(--spacing-2);
+          width: var(--spacing-4_5);
+          width: var(--spacing-5_5);
+          width: var(--spacing-13);
+          width: var(--spacing-100);
+          width: var(--spacing-miami);
+        }
+        "
+      `)
+    },
+  )
 })

packages/@tailwindcss-upgrade/src/migrate-js-config.ts

@@ -12,10 +12,11 @@ import {
 } from '../../tailwindcss/src/compat/apply-config-to-theme'
 import { keyframesToRules } from '../../tailwindcss/src/compat/apply-keyframes-to-theme'
 import { resolveConfig, type ConfigFile } from '../../tailwindcss/src/compat/config/resolve-config'
-import type { ThemeConfig } from '../../tailwindcss/src/compat/config/types'
+import type { ResolvedConfig, ThemeConfig } from '../../tailwindcss/src/compat/config/types'
 import { darkModePlugin } from '../../tailwindcss/src/compat/dark-mode'
 import type { DesignSystem } from '../../tailwindcss/src/design-system'
 import { escape } from '../../tailwindcss/src/utils/escape'
+import { isValidSpacingMultiplier } from '../../tailwindcss/src/utils/infer-data-type'
 import { findStaticPlugins, type StaticPluginOptions } from './utils/extract-static-plugins'
 import { info } from './utils/renderer'
 
@@ -101,6 +102,8 @@ async function migrateTheme(
     Array.from(replacedThemeKeys.entries()).map(([key]) => [key, false]),
   )
 
+  removeUnnecessarySpacingKeys(designSystem, resolvedConfig, replacedThemeKeys)
+
   let prevSectionKey = ''
   let css = '\n@tw-bucket theme {\n'
   css += `\n@theme {\n`
@@ -317,3 +320,42 @@ function patternSourceFiles(source: { base: string; pattern: string }): string[]
   scanner.scan()
   return scanner.files
 }
+
+function removeUnnecessarySpacingKeys(
+  designSystem: DesignSystem,
+  resolvedConfig: ResolvedConfig,
+  replacedThemeKeys: Set<string>,
+) {
+  // We want to keep the spacing scale as-is if the user is overwriting
+  if (replacedThemeKeys.has('spacing')) return
+
+  // Ensure we have a spacing multiplier
+  let spacingScale = designSystem.theme.get(['--spacing'])
+  if (!spacingScale) return
+
+  let [spacingMultiplier, spacingUnit] = splitNumberAndUnit(spacingScale)
+  if (!spacingMultiplier || !spacingUnit) return
+
+  if (spacingScale && !replacedThemeKeys.has('spacing')) {
+    for (let [key, value] of Object.entries(resolvedConfig.theme.spacing ?? {})) {
+      let [multiplier, unit] = splitNumberAndUnit(value as string)
+      if (multiplier === null) continue
+
+      if (!isValidSpacingMultiplier(key)) continue
+      if (unit !== spacingUnit) continue
+
+      if (parseFloat(multiplier) === Number(key) * parseFloat(spacingMultiplier)) {
+        delete resolvedConfig.theme.spacing[key]
+        designSystem.theme.clearNamespace(escape(`--spacing-${key.replaceAll('.', '_')}`), 0)
+      }
+    }
+  }
+}
+
+function splitNumberAndUnit(value: string): [string, string] | [null, null] {
+  let match = value.match(/^([0-9.]+)(.*)$/)
+  if (!match) {
+    return [null, null]
+  }
+  return [match[1], match[2]]
+}