Adjust shadow, radius, and blur scales to ensure all utilities have a…

… value suffix (#14849)

This PR reworks the default `--shadow-*` and `--inset-shadow-*` scales
to remove the bare `shadow` and `inset-shadow` utilities, and ensure
every shadow has an explicit size as part of the utility name.

Here's a complete list of changes:

| v3                | v4 Alpha          | Proposed           |
| ----------------- | ----------------- | ------------------ |
| _N/A_             | `shadow-xs`       | `shadow-2xs`       |
| `shadow-sm`       | `shadow-sm`       | `shadow-xs`        |
| `shadow`          | `shadow`          | `shadow-sm`        |
| `shadow-md`       | `shadow-md`       | `shadow-md`        |
| `shadow-lg`       | `shadow-lg`       | `shadow-lg`        |
| `shadow-xl`       | `shadow-xl`       | `shadow-xl`        |
| _N/A_ | `inset-shadow-xs` | `inset-shadow-2xs` |
| _N/A_ | `inset-shadow-sm` | `inset-shadow-xs`  |
| `shadow-inner`    | `inset-shadow`    | `inset-shadow-sm`     |

The motivation for this change is just to make the scale more
predictable — it's never been intuitive to me that `shadow` sits in
between `shadow-sm` and `shadow-md`.

This PR doesn't remove the ability to create classes like `shadow` and
`inset-shadow` by adding bare `--shadow` and `--inset-shadow` theme
variables, but does remove them from the default theme.

## Impact

We'll include a codemod for this in our upgrade tool to automate this
change for people upgrading from v3 to v4, but this is still sort of an
annoying breaking change admittedly and will make lots of educational
resources, example components, and LLM tools out of date for v4 😕 At the
same time I don't want to feel like we can never correct regrettable
legacy decisions just to preserve backward compatibility.

We made a similar change like this when we went from the v0.x color
palette to the v1.x color palette changing names like `bg-red` to
`bg-red-500` and that proved to definitely be the right decision long
term, so want to rip the band-aid off here too if we can.

Planning to make the same change for `rounded`, `drop-shadow`, and
`blur` as well — maybe in separate PRs but maybe just all in this one as
well since I don't think we want to do one and not all.

_Update_: I've also made the same changes to the `--radius-*`,
`--drop-shadow-*`, and `--blur-*` scales now, effectively removed the
`rounded`, `drop-shadow`, and `blur` classes by default, and changing
the meaning `rounded-sm`, `drop-shadow-sm`, and `blur-sm`.

We'll put together a codemod to handle this stuff in a separate PR.

---------

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

CHANGELOG.md

@@ -24,6 +24,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Remove `--drop-shadow-none` from the default theme in favor of a static `drop-shadow-none` utility ([#14847](https://github.com/tailwindlabs/tailwindcss/pull/14847))
+- Rename `shadow` to `shadow-sm`, `shadow-sm` to `shadow-xs`, and `shadow-xs` to `shadow-2xs` ([#14849](https://github.com/tailwindlabs/tailwindcss/pull/14849))
+- Rename `inset-shadow` to `inset-shadow-sm`, `inset-shadow-sm` to `inset-shadow-xs`, and `inset-shadow-xs` to `inset-shadow-2xs` ([#14849](https://github.com/tailwindlabs/tailwindcss/pull/14849))
+- 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))
 
 ## [4.0.0-alpha.31] - 2024-10-29
 

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

@@ -264,34 +264,34 @@ exports[`\`@import 'tailwindcss'\` is replaced with the generated CSS 1`] = `
     --animate-ping: ping 1s cubic-bezier(0, 0, .2, 1) infinite;
     --animate-pulse: pulse 2s cubic-bezier(.4, 0, .6, 1) infinite;
     --animate-bounce: bounce 1s infinite;
-    --blur: 8px;
-    --blur-sm: 4px;
+    --blur-xs: 4px;
+    --blur-sm: 8px;
     --blur-md: 12px;
     --blur-lg: 16px;
     --blur-xl: 24px;
     --blur-2xl: 40px;
     --blur-3xl: 64px;
-    --radius: .25rem;
-    --radius-sm: .125rem;
+    --radius-xs: .125rem;
+    --radius-sm: .25rem;
     --radius-md: .375rem;
     --radius-lg: .5rem;
     --radius-xl: .75rem;
     --radius-2xl: 1rem;
     --radius-3xl: 1.5rem;
     --radius-4xl: 2rem;
-    --shadow: 0 1px 3px 0 #0000001a, 0 1px 2px -1px #0000001a;
-    --shadow-xs: 0 1px #0000000d;
-    --shadow-sm: 0 1px 2px 0 #0000000d;
+    --shadow-2xs: 0 1px #0000000d;
+    --shadow-xs: 0 1px 2px 0 #0000000d;
+    --shadow-sm: 0 1px 3px 0 #0000001a, 0 1px 2px -1px #0000001a;
     --shadow-md: 0 4px 6px -1px #0000001a, 0 2px 4px -2px #0000001a;
     --shadow-lg: 0 10px 15px -3px #0000001a, 0 4px 6px -4px #0000001a;
     --shadow-xl: 0 20px 25px -5px #0000001a, 0 8px 10px -6px #0000001a;
     --shadow-2xl: 0 25px 50px -12px #00000040;
     --shadow-inner: inset 0 2px 4px 0 #0000000d;
-    --inset-shadow-xs: inset 0 1px #0000000d;
-    --inset-shadow-sm: inset 0 1px 1px #0000000d;
-    --inset-shadow: inset 0 2px 4px #0000000d;
-    --drop-shadow: 0 1px 2px #0000001a, 0 1px 1px #0000000f;
-    --drop-shadow-sm: 0 1px 1px #0000000d;
+    --inset-shadow-2xs: inset 0 1px #0000000d;
+    --inset-shadow-xs: inset 0 1px 1px #0000000d;
+    --inset-shadow-sm: inset 0 2px 4px #0000000d;
+    --drop-shadow-xs: 0 1px 1px #0000000d;
+    --drop-shadow-sm: 0 1px 2px #0000001a, 0 1px 1px #0000000f;
     --drop-shadow-md: 0 4px 3px #00000012, 0 2px 2px #0000000f;
     --drop-shadow-lg: 0 10px 8px #0000000a, 0 4px 3px #0000001a;
     --drop-shadow-xl: 0 20px 13px #00000008, 0 8px 5px #00000014;

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

@@ -263,34 +263,34 @@ exports[`compiling CSS > \`@tailwind utilities\` is replaced by utilities using
   --animate-ping: ping 1s cubic-bezier(0, 0, .2, 1) infinite;
   --animate-pulse: pulse 2s cubic-bezier(.4, 0, .6, 1) infinite;
   --animate-bounce: bounce 1s infinite;
-  --blur: 8px;
-  --blur-sm: 4px;
+  --blur-xs: 4px;
+  --blur-sm: 8px;
   --blur-md: 12px;
   --blur-lg: 16px;
   --blur-xl: 24px;
   --blur-2xl: 40px;
   --blur-3xl: 64px;
-  --radius: .25rem;
-  --radius-sm: .125rem;
+  --radius-xs: .125rem;
+  --radius-sm: .25rem;
   --radius-md: .375rem;
   --radius-lg: .5rem;
   --radius-xl: .75rem;
   --radius-2xl: 1rem;
   --radius-3xl: 1.5rem;
   --radius-4xl: 2rem;
-  --shadow: 0 1px 3px 0 #0000001a, 0 1px 2px -1px #0000001a;
-  --shadow-xs: 0 1px #0000000d;
-  --shadow-sm: 0 1px 2px 0 #0000000d;
+  --shadow-2xs: 0 1px #0000000d;
+  --shadow-xs: 0 1px 2px 0 #0000000d;
+  --shadow-sm: 0 1px 3px 0 #0000001a, 0 1px 2px -1px #0000001a;
   --shadow-md: 0 4px 6px -1px #0000001a, 0 2px 4px -2px #0000001a;
   --shadow-lg: 0 10px 15px -3px #0000001a, 0 4px 6px -4px #0000001a;
   --shadow-xl: 0 20px 25px -5px #0000001a, 0 8px 10px -6px #0000001a;
   --shadow-2xl: 0 25px 50px -12px #00000040;
   --shadow-inner: inset 0 2px 4px 0 #0000000d;
-  --inset-shadow-xs: inset 0 1px #0000000d;
-  --inset-shadow-sm: inset 0 1px 1px #0000000d;
-  --inset-shadow: inset 0 2px 4px #0000000d;
-  --drop-shadow: 0 1px 2px #0000001a, 0 1px 1px #0000000f;
-  --drop-shadow-sm: 0 1px 1px #0000000d;
+  --inset-shadow-2xs: inset 0 1px #0000000d;
+  --inset-shadow-xs: inset 0 1px 1px #0000000d;
+  --inset-shadow-sm: inset 0 2px 4px #0000000d;
+  --drop-shadow-xs: 0 1px 1px #0000000d;
+  --drop-shadow-sm: 0 1px 2px #0000001a, 0 1px 1px #0000000f;
   --drop-shadow-md: 0 4px 3px #00000012, 0 2px 2px #0000000f;
   --drop-shadow-lg: 0 10px 8px #0000000a, 0 4px 3px #0000001a;
   --drop-shadow-xl: 0 20px 13px #00000008, 0 8px 5px #00000014;
@@ -412,7 +412,7 @@ exports[`compiling CSS > \`@tailwind utilities\` is replaced by utilities using
   background-color: var(--color-red-500, oklch(.637 .237 25.331));
 }
 
-.shadow {
+.shadow-sm {
   --tw-shadow: 0 1px 3px 0 var(--tw-shadow-color, #0000001a), 0 1px 2px -1px var(--tw-shadow-color, #0000001a);
   box-shadow: var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
 }

packages/tailwindcss/src/index.test.ts

@@ -111,7 +111,7 @@ describe('compiling CSS', () => {
           ${defaultTheme}
           @tailwind utilities;
         `,
-        ['bg-red-500', 'w-4', 'sm:flex', 'shadow'],
+        ['bg-red-500', 'w-4', 'sm:flex', 'shadow-sm'],
       ),
     ).toMatchSnapshot()
   })

packages/tailwindcss/src/utilities.test.ts

@@ -14559,14 +14559,14 @@ test('shadow', async () => {
       css`
         @theme {
           --color-red-500: #ef4444;
-          --shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
+          --shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
           --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1);
         }
         @tailwind utilities;
       `,
       [
         // Shadows
-        'shadow',
+        'shadow-sm',
         'shadow-xl',
         'shadow-none',
         'shadow-[12px_12px_#0088cc]',
@@ -14598,15 +14598,10 @@ test('shadow', async () => {
   ).toMatchInlineSnapshot(`
     ":root {
       --color-red-500: #ef4444;
-      --shadow: 0 1px 3px 0 #0000001a, 0 1px 2px -1px #0000001a;
+      --shadow-sm: 0 1px 3px 0 #0000001a, 0 1px 2px -1px #0000001a;
       --shadow-xl: 0 20px 25px -5px #0000001a, 0 8px 10px -6px #0000001a;
     }
 
-    .shadow {
-      --tw-shadow: 0 1px 3px 0 var(--tw-shadow-color, #0000001a), 0 1px 2px -1px var(--tw-shadow-color, #0000001a);
-      box-shadow: var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
-    }
-
     .shadow-\\[10px_10px\\] {
       --tw-shadow: 10px 10px var(--tw-shadow-color, currentcolor);
       box-shadow: var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
@@ -14627,6 +14622,11 @@ test('shadow', async () => {
       box-shadow: var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
     }
 
+    .shadow-sm {
+      --tw-shadow: 0 1px 3px 0 var(--tw-shadow-color, #0000001a), 0 1px 2px -1px var(--tw-shadow-color, #0000001a);
+      box-shadow: var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
+    }
+
     .shadow-xl {
       --tw-shadow: 0 20px 25px -5px var(--tw-shadow-color, #0000001a), 0 8px 10px -6px var(--tw-shadow-color, #0000001a);
       box-shadow: var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);

packages/tailwindcss/tests/ui.spec.ts

@@ -214,7 +214,7 @@ test('composing shadow, inset shadow, ring, and inset ring', async ({ page }) =>
     page,
     html`<div
       id="x"
-      class="shadow shadow-[#f00] inset-shadow inset-shadow-[#0f0] ring ring-[#fff] inset-ring inset-ring-[#00f]"
+      class="shadow-sm shadow-[#f00] inset-shadow-sm inset-shadow-[#0f0] ring ring-[#fff] inset-ring inset-ring-[#00f]"
     ></div>`,
   )
 
@@ -233,11 +233,13 @@ test('shadow colors', async ({ page }) => {
   let { getPropertyValue } = await render(
     page,
     html`
-      <div id="a" class="shadow shadow-red"></div>
+      <div id="a" class="shadow-sm shadow-red"></div>
       <div id="b" class="shadow-xl shadow-red"></div>
       <div id="c" class="shadow-[0px_2px_4px] shadow-red"></div>
-      <div id="d" class="shadow shadow-red hover:shadow-xl">Hello world</div>
-      <div id="e" class="shadow shadow-red hover:shadow-xl hover:shadow-initial">Hello world</div>
+      <div id="d" class="shadow-sm shadow-red hover:shadow-xl">Hello world</div>
+      <div id="e" class="shadow-sm shadow-red hover:shadow-xl hover:shadow-initial">
+        Hello world
+      </div>
     `,
   )
 
@@ -318,13 +320,13 @@ test('inset shadow colors', async ({ page }) => {
   let { getPropertyValue } = await render(
     page,
     html`
-      <div id="a" class="inset-shadow-sm inset-shadow-red"></div>
-      <div id="b" class="inset-shadow inset-shadow-red"></div>
+      <div id="a" class="inset-shadow-xs inset-shadow-red"></div>
+      <div id="b" class="inset-shadow-sm inset-shadow-red"></div>
       <div id="c" class="inset-shadow-[0px_3px_6px] inset-shadow-red"></div>
-      <div id="d" class="inset-shadow-sm inset-shadow-red hover:inset-shadow">Hello world</div>
+      <div id="d" class="inset-shadow-xs inset-shadow-red hover:inset-shadow-sm">Hello world</div>
       <div
         id="e"
-        class="inset-shadow-sm inset-shadow-red hover:inset-shadow hover:inset-shadow-initial"
+        class="inset-shadow-xs inset-shadow-red hover:inset-shadow-sm hover:inset-shadow-initial"
       >
         Hello world
       </div>

packages/tailwindcss/theme.css

@@ -291,17 +291,17 @@
   --animate-bounce: bounce 1s infinite;
 
   /* Blurs */
-  --blur: 8px;
-  --blur-sm: 4px;
+  --blur-xs: 4px;
+  --blur-sm: 8px;
   --blur-md: 12px;
   --blur-lg: 16px;
   --blur-xl: 24px;
   --blur-2xl: 40px;
   --blur-3xl: 64px;
 
   /* Radii */
-  --radius: 0.25rem;
-  --radius-sm: 0.125rem;
+  --radius-xs: 0.125rem;
+  --radius-sm: 0.25rem;
   --radius-md: 0.375rem;
   --radius-lg: 0.5rem;
   --radius-xl: 0.75rem;
@@ -310,23 +310,23 @@
   --radius-4xl: 2rem;
 
   /* Shadows */
-  --shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
-  --shadow-xs: 0 1px rgb(0 0 0 / 0.05);
-  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  --shadow-2xs: 0 1px rgb(0 0 0 / 0.05);
+  --shadow-xs: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  --shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
   --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
   --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
   --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1);
   --shadow-2xl: 0 25px 50px -12px rgb(0 0 0 / 0.25);
   --shadow-inner: inset 0 2px 4px 0 rgb(0 0 0 / 0.05);
 
   /* Inset shadows */
-  --inset-shadow-xs: inset 0 1px rgb(0 0 0 / 0.05);
-  --inset-shadow-sm: inset 0 1px 1px rgb(0 0 0 / 0.05);
-  --inset-shadow: inset 0 2px 4px rgb(0 0 0 / 0.05);
+  --inset-shadow-2xs: inset 0 1px rgb(0 0 0 / 0.05);
+  --inset-shadow-xs: inset 0 1px 1px rgb(0 0 0 / 0.05);
+  --inset-shadow-sm: inset 0 2px 4px rgb(0 0 0 / 0.05);
 
   /* Drop shadows */
-  --drop-shadow: 0 1px 2px rgb(0 0 0 / 0.1), 0 1px 1px rgb(0 0 0 / 0.06);
-  --drop-shadow-sm: 0 1px 1px rgb(0 0 0 / 0.05);
+  --drop-shadow-xs: 0 1px 1px rgb(0 0 0 / 0.05);
+  --drop-shadow-sm: 0 1px 2px rgb(0 0 0 / 0.1), 0 1px 1px rgb(0 0 0 / 0.06);
   --drop-shadow-md: 0 4px 3px rgb(0 0 0 / 0.07), 0 2px 2px rgb(0 0 0 / 0.06);
   --drop-shadow-lg: 0 10px 8px rgb(0 0 0 / 0.04), 0 4px 3px rgb(0 0 0 / 0.1);
   --drop-shadow-xl: 0 20px 13px rgb(0 0 0 / 0.03), 0 8px 5px rgb(0 0 0 / 0.08);