Replace default explicit spacing scale with multiplier system (#14857)

This PR replaces the default spacing scale (`--spacing-*`) with a
generative system based on a default spacing _unit_.

Instead of the default theme containing values like `--spacing-4`,
`--spacing-6`, `--spacing-8`, etc., instead we just define a single
`--spacing` value:

```css
@theme {
  --spacing: 0.25rem;
}
```

Utilities like `px-4` are derived from this unit by multiplying it by
the value in the utility (4 in this case):

```css
.px-4 {
  padding-inline: calc(var(--spacing) * 4);
}
```

The biggest consequence of this change is that every value is available
now, rather than just the explicitly configured values.

This means utilities like `px-42` will work now, whereas prior to this
PR only `px-40` and `px-44` were valid utilities. I personally found it
very difficult to know which values actually existed at the higher end
of the scale without IntelliSense, and in practice even when working
with a skilled designer like [Steve](https://x.com/steveschoger) who
helped design Tailwind's default spacing scale, I'd very often need to
break out of it to implement a design, and trying to round to a value
that was in the scale made the design worse, not better.

This PR allows you to use any whole number, as well as decimal numbers
that are multiples of `0.25` to ensure classes like `px-1.5` continue to
work. While this means you can now technically do things like
`pt-97.25`, I think the presence of the fractional value will be enough
of a signal to developers that they are doing something a little
unusual, and they can use their judgment as to whether they are making
the right decision or not.

I'll update this PR with a lot more detail when I have a chance, as
there are a few other things to explain like:

- Unifying all of the values for
width/min-width/max-width/height/min-height/max-height utilities
- Deriving numeric line-height values from the spacing multiplier
instead of a separate line-height scale
- Using `--spacing: initial` to disable the multiplier
- How you can still use an explicit spacing scale and ignore this change
- How we plan to use IntelliSense to surface a more curated set of
spacing values even if smaller increments work when you type them
explicitly

---------

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

Author: adamwathan

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Support derived spacing scales based on a single `--spacing` theme value ([#14857](https://github.com/tailwindlabs/tailwindcss/pull/14857))
+- Add `svh`, `dvh`, `svw`, `dvw`, and `auto` values to all width/height/size utilities ([#14857](https://github.com/tailwindlabs/tailwindcss/pull/14857))
 - _Upgrade (experimental)_: Migrate `grid-cols-[subgrid]` and `grid-rows-[subgrid]` to `grid-cols-subgrid` and `grid-rows-subgrid` ([#14840](https://github.com/tailwindlabs/tailwindcss/pull/14840))
 - _Upgrade (experimental)_: Support migrating projects with multiple config files ([#14863](https://github.com/tailwindlabs/tailwindcss/pull/14863))
 
@@ -29,7 +31,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Rename `drop-shadow` to `drop-shadow-sm` and `drop-shadow-sm` to `drop-shadow-xs` ([#14849](https://github.com/tailwindlabs/tailwindcss/pull/14849))
 - Rename `rounded` to `rounded-sm` and `rounded-sm` to `rounded-xs` ([#14849](https://github.com/tailwindlabs/tailwindcss/pull/14849))
 - Rename `blur` to `blur-sm` and `blur-sm` to `blur-xs` ([#14849](https://github.com/tailwindlabs/tailwindcss/pull/14849))
+- Remove fixed line-height theme values and derive `leading-*` utilites from `--spacing-*` scale ([#14857](https://github.com/tailwindlabs/tailwindcss/pull/14857))
 - Remove `--transition-timing-function-linear` from the default theme in favor of a static `ease-linear` utility ([#14880](https://github.com/tailwindlabs/tailwindcss/pull/14880))
+- Remove default `--spacing-*` scale in favor of `--spacing` multiplier ([#14857](https://github.com/tailwindlabs/tailwindcss/pull/14857))
 
 ## [4.0.0-alpha.31] - 2024-10-29
 

integrations/upgrade/index.test.ts

@@ -69,7 +69,7 @@ test(
       'src/index.html': html`
         <h1>🤠👋</h1>
         <div
-          class="!flex sm:!block bg-gradient-to-t bg-[--my-red] max-w-screen-md ml-[theme(spacing[1.5])]"
+          class="!flex sm:!block bg-gradient-to-t bg-[--my-red] max-w-screen-md ml-[theme(screens.md)]"
         ></div>
       `,
       'src/input.css': css`
@@ -93,7 +93,7 @@ test(
       --- ./src/index.html ---
       <h1>🤠👋</h1>
       <div
-        class="flex! sm:block! bg-linear-to-t bg-[var(--my-red)] max-w-[var(--breakpoint-md)] ml-[var(--spacing-1_5)]"
+        class="flex! sm:block! bg-linear-to-t bg-[var(--my-red)] max-w-[var(--breakpoint-md)] ml-[var(--breakpoint-md)]"
       ></div>
 
       --- ./src/input.css ---
@@ -154,7 +154,7 @@ test(
       candidate`bg-linear-to-t`,
       candidate`bg-[var(--my-red)]`,
       candidate`max-w-[var(--breakpoint-md)]`,
-      candidate`ml-[var(--spacing-1\_5)`,
+      candidate`ml-[var(--breakpoint-md)`,
     ])
   },
 )

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

@@ -296,41 +296,7 @@ exports[`\`@import 'tailwindcss'\` is replaced with the generated CSS 1`] = `
     --drop-shadow-lg: 0 10px 8px #0000000a, 0 4px 3px #0000001a;
     --drop-shadow-xl: 0 20px 13px #00000008, 0 8px 5px #00000014;
     --drop-shadow-2xl: 0 25px 25px #00000026;
-    --spacing-px: 1px;
-    --spacing-0: 0px;
-    --spacing-0_5: .125rem;
-    --spacing-1: .25rem;
-    --spacing-1_5: .375rem;
-    --spacing-2: .5rem;
-    --spacing-2_5: .625rem;
-    --spacing-3: .75rem;
-    --spacing-3_5: .875rem;
-    --spacing-4: 1rem;
-    --spacing-5: 1.25rem;
-    --spacing-6: 1.5rem;
-    --spacing-7: 1.75rem;
-    --spacing-8: 2rem;
-    --spacing-9: 2.25rem;
-    --spacing-10: 2.5rem;
-    --spacing-11: 2.75rem;
-    --spacing-12: 3rem;
-    --spacing-14: 3.5rem;
-    --spacing-16: 4rem;
-    --spacing-20: 5rem;
-    --spacing-24: 6rem;
-    --spacing-28: 7rem;
-    --spacing-32: 8rem;
-    --spacing-36: 9rem;
-    --spacing-40: 10rem;
-    --spacing-44: 11rem;
-    --spacing-48: 12rem;
-    --spacing-52: 13rem;
-    --spacing-56: 14rem;
-    --spacing-60: 15rem;
-    --spacing-64: 16rem;
-    --spacing-72: 18rem;
-    --spacing-80: 20rem;
-    --spacing-96: 24rem;
+    --spacing: .25rem;
     --width-3xs: 16rem;
     --width-2xs: 18rem;
     --width-xs: 20rem;
@@ -386,14 +352,6 @@ exports[`\`@import 'tailwindcss'\` is replaced with the generated CSS 1`] = `
     --line-height-normal: 1.5;
     --line-height-relaxed: 1.625;
     --line-height-loose: 2;
-    --line-height-3: .75rem;
-    --line-height-4: 1rem;
-    --line-height-5: 1.25rem;
-    --line-height-6: 1.5rem;
-    --line-height-7: 1.75rem;
-    --line-height-8: 2rem;
-    --line-height-9: 2.25rem;
-    --line-height-10: 2.5rem;
     --perspective-dramatic: 100px;
     --perspective-near: 300px;
     --perspective-normal: 500px;

packages/@tailwindcss-upgrade/src/codemods/migrate-theme-to-var.test.ts

@@ -24,7 +24,7 @@ async function migrate(input: string) {
 it('should migrate `theme(…)` to `var(…)`', async () => {
   expect(
     await migrate(css`
-      @media theme(spacing.4) {
+      @media theme(screens.sm) {
         .foo {
           background-color: theme(colors.red.900);
           color: theme(colors.red.900 / 75%);
@@ -33,7 +33,7 @@ it('should migrate `theme(…)` to `var(…)`', async () => {
       }
     `),
   ).toMatchInlineSnapshot(`
-    "@media theme(--spacing-4) {
+    "@media theme(--breakpoint-sm) {
       .foo {
         background-color: var(--color-red-900);
         color: theme(--color-red-900 / 75%);

packages/@tailwindcss-upgrade/src/template/codemods/theme-to-var.test.ts

@@ -2,6 +2,8 @@ import { __unstable__loadDesignSystem } from '@tailwindcss/node'
 import { expect, test } from 'vitest'
 import { themeToVar } from './theme-to-var'
 
+let css = String.raw
+
 test.each([
   // Keep candidates that don't contain `theme(…)` or `theme(…, …)`
   ['[color:red]', '[color:red]'],
@@ -107,9 +109,51 @@ test.each([
     '[--foo:theme(colors.red.500/50/50)_var(--color-blue-200)]/50',
   ],
 ])('%s => %s', async (candidate, result) => {
-  let designSystem = await __unstable__loadDesignSystem('@import "tailwindcss";', {
-    base: __dirname,
-  })
+  let designSystem = await __unstable__loadDesignSystem(
+    css`
+      @import 'tailwindcss';
+      @theme {
+        --spacing-px: 1px;
+        --spacing-0: 0px;
+        --spacing-0_5: 0.125rem;
+        --spacing-1: 0.25rem;
+        --spacing-1_5: 0.375rem;
+        --spacing-2: 0.5rem;
+        --spacing-2_5: 0.625rem;
+        --spacing-3: 0.75rem;
+        --spacing-3_5: 0.875rem;
+        --spacing-4: 1rem;
+        --spacing-5: 1.25rem;
+        --spacing-6: 1.5rem;
+        --spacing-7: 1.75rem;
+        --spacing-8: 2rem;
+        --spacing-9: 2.25rem;
+        --spacing-10: 2.5rem;
+        --spacing-11: 2.75rem;
+        --spacing-12: 3rem;
+        --spacing-14: 3.5rem;
+        --spacing-16: 4rem;
+        --spacing-20: 5rem;
+        --spacing-24: 6rem;
+        --spacing-28: 7rem;
+        --spacing-32: 8rem;
+        --spacing-36: 9rem;
+        --spacing-40: 10rem;
+        --spacing-44: 11rem;
+        --spacing-48: 12rem;
+        --spacing-52: 13rem;
+        --spacing-56: 14rem;
+        --spacing-60: 15rem;
+        --spacing-64: 16rem;
+        --spacing-72: 18rem;
+        --spacing-80: 20rem;
+        --spacing-96: 24rem;
+      }
+    `,
+    {
+      base: __dirname,
+    },
+  )
 
   expect(themeToVar(designSystem, {}, candidate)).toEqual(result)
 })

packages/tailwindcss/src/__snapshots__/index.test.ts.snap

@@ -295,41 +295,7 @@ exports[`compiling CSS > \`@tailwind utilities\` is replaced by utilities using
   --drop-shadow-lg: 0 10px 8px #0000000a, 0 4px 3px #0000001a;
   --drop-shadow-xl: 0 20px 13px #00000008, 0 8px 5px #00000014;
   --drop-shadow-2xl: 0 25px 25px #00000026;
-  --spacing-px: 1px;
-  --spacing-0: 0px;
-  --spacing-0_5: .125rem;
-  --spacing-1: .25rem;
-  --spacing-1_5: .375rem;
-  --spacing-2: .5rem;
-  --spacing-2_5: .625rem;
-  --spacing-3: .75rem;
-  --spacing-3_5: .875rem;
-  --spacing-4: 1rem;
-  --spacing-5: 1.25rem;
-  --spacing-6: 1.5rem;
-  --spacing-7: 1.75rem;
-  --spacing-8: 2rem;
-  --spacing-9: 2.25rem;
-  --spacing-10: 2.5rem;
-  --spacing-11: 2.75rem;
-  --spacing-12: 3rem;
-  --spacing-14: 3.5rem;
-  --spacing-16: 4rem;
-  --spacing-20: 5rem;
-  --spacing-24: 6rem;
-  --spacing-28: 7rem;
-  --spacing-32: 8rem;
-  --spacing-36: 9rem;
-  --spacing-40: 10rem;
-  --spacing-44: 11rem;
-  --spacing-48: 12rem;
-  --spacing-52: 13rem;
-  --spacing-56: 14rem;
-  --spacing-60: 15rem;
-  --spacing-64: 16rem;
-  --spacing-72: 18rem;
-  --spacing-80: 20rem;
-  --spacing-96: 24rem;
+  --spacing: .25rem;
   --width-3xs: 16rem;
   --width-2xs: 18rem;
   --width-xs: 20rem;
@@ -385,14 +351,6 @@ exports[`compiling CSS > \`@tailwind utilities\` is replaced by utilities using
   --line-height-normal: 1.5;
   --line-height-relaxed: 1.625;
   --line-height-loose: 2;
-  --line-height-3: .75rem;
-  --line-height-4: 1rem;
-  --line-height-5: 1.25rem;
-  --line-height-6: 1.5rem;
-  --line-height-7: 1.75rem;
-  --line-height-8: 2rem;
-  --line-height-9: 2.25rem;
-  --line-height-10: 2.5rem;
   --perspective-dramatic: 100px;
   --perspective-near: 300px;
   --perspective-normal: 500px;
@@ -404,7 +362,7 @@ exports[`compiling CSS > \`@tailwind utilities\` is replaced by utilities using
 }
 
 .w-4 {
-  width: var(--spacing-4, 1rem);
+  width: calc(var(--spacing, .25rem) * 4);
 }
 
 .bg-red-500 {