Add shadow-initial and inset-shadow-initial utilities (#14468)

This PR complements #14458 by adding new `shadow-initial` and
`inset-shadow-initial` utilities that make it possible to "undo" a
custom shadow color and revert to the default shadow color for the
current shadow size.

For example, in this example the shadow will be red on hover even though
the default color for the `shadow` utility is `rgb(0 0 0 / 5%)`:

```html
<div class="shadow-sm shadow-red-500 hover:shadow">
  <!-- … -->
</div>
```

This is usually what you want, but if you actually want `hover:shadow`
to apply its default color, you need to know what the color is and add
it yourself:

```html
<div class="shadow-sm shadow-red-500 hover:shadow hover:shadow-black/5">
  <!-- … -->
</div>
```

Using `shadow-initial`, you can achieve the same thing without having to
know what the original color was:

```html
<div class="shadow-sm shadow-red-500 hover:shadow hover:shadow-initial">
  <!-- … -->
</div>
```

The `inset-shadow-initial` utility does the same thing for the
`inset-shadow-*` utilities.

---------

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

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add CSS codemods for migrating `@tailwind` directives ([#14411](https://github.com/tailwindlabs/tailwindcss/pull/14411))
 - Support `screens` in JS config files ([#14415](https://github.com/tailwindlabs/tailwindcss/pull/14415))
 - Add `bg-radial-*` and `bg-conic-*` utilities for radial and conic gradients ([#14467](https://github.com/tailwindlabs/tailwindcss/pull/14467))
+- Add new `shadow-initial` and `inset-shadow-initial` utilities for resetting shadow colors ([#14468](https://github.com/tailwindlabs/tailwindcss/pull/14468))
 
 ### Fixed
 

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

@@ -2324,6 +2324,7 @@ exports[`getClassList 1`] = `
   "inset-shadow-inherit/90",
   "inset-shadow-inherit/95",
   "inset-shadow-inherit/100",
+  "inset-shadow-initial",
   "inset-shadow-transparent",
   "inset-shadow-transparent/0",
   "inset-shadow-transparent/5",
@@ -3302,6 +3303,7 @@ exports[`getClassList 1`] = `
   "shadow-inherit/90",
   "shadow-inherit/95",
   "shadow-inherit/100",
+  "shadow-initial",
   "shadow-transparent",
   "shadow-transparent/0",
   "shadow-transparent/5",

packages/tailwindcss/src/utilities.ts

@@ -4270,6 +4270,8 @@ export function createUtilities(theme: Theme) {
       ])
     }
 
+    staticUtility('shadow-initial', [boxShadowProperties, ['--tw-shadow-color', 'initial']])
+
     utilities.functional('shadow', (candidate) => {
       if (candidate.negative) return
 
@@ -4359,6 +4361,11 @@ export function createUtilities(theme: Theme) {
       },
     ])
 
+    staticUtility('inset-shadow-initial', [
+      boxShadowProperties,
+      ['--tw-inset-shadow-color', 'initial'],
+    ])
+
     utilities.functional('inset-shadow', (candidate) => {
       if (candidate.negative) return
 

packages/tailwindcss/tests/ui.spec.ts

@@ -224,6 +224,9 @@ test('shadow colors', async ({ page }) => {
       <div id="b" class="shadow-xl shadow-red-500"></div>
       <div id="c" class="shadow-[0px_2px_4px] shadow-red-500"></div>
       <div id="d" class="shadow shadow-red-500 hover:shadow-xl">Hello world</div>
+      <div id="e" class="shadow shadow-red-500 hover:shadow-xl hover:shadow-initial">
+        Hello world
+      </div>
     `,
   )
 
@@ -276,6 +279,28 @@ test('shadow colors', async ({ page }) => {
       'rgb(239, 68, 68) 0px 20px 25px -5px, rgb(239, 68, 68) 0px 8px 10px -6px',
     ].join(', '),
   )
+
+  expect(await getPropertyValue('#e', 'box-shadow')).toEqual(
+    [
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+      'rgb(239, 68, 68) 0px 1px 3px 0px, rgb(239, 68, 68) 0px 1px 2px -1px',
+    ].join(', '),
+  )
+
+  await page.locator('#e').hover()
+
+  expect(await getPropertyValue('#e', 'box-shadow')).toEqual(
+    [
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+      'rgba(0, 0, 0, 0.1) 0px 20px 25px -5px, rgba(0, 0, 0, 0.1) 0px 8px 10px -6px',
+    ].join(', '),
+  )
 })
 
 test('inset shadow colors', async ({ page }) => {
@@ -286,6 +311,12 @@ test('inset shadow colors', async ({ page }) => {
       <div id="b" class="inset-shadow inset-shadow-red-500"></div>
       <div id="c" class="inset-shadow-[0px_3px_6px] inset-shadow-red-500"></div>
       <div id="d" class="inset-shadow-sm inset-shadow-red-500 hover:inset-shadow">Hello world</div>
+      <div
+        id="e"
+        class="inset-shadow-sm inset-shadow-red-500 hover:inset-shadow hover:inset-shadow-initial"
+      >
+        Hello world
+      </div>
     `,
   )
 
@@ -338,6 +369,28 @@ test('inset shadow colors', async ({ page }) => {
       'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
     ].join(', '),
   )
+
+  expect(await getPropertyValue('#e', 'box-shadow')).toEqual(
+    [
+      'rgb(239, 68, 68) 0px 1px 1px 0px inset',
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+    ].join(', '),
+  )
+
+  await page.locator('#e').hover()
+
+  expect(await getPropertyValue('#e', 'box-shadow')).toEqual(
+    [
+      'rgba(0, 0, 0, 0.05) 0px 2px 4px 0px inset',
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+      'rgba(0, 0, 0, 0) 0px 0px 0px 0px',
+    ].join(', '),
+  )
 })
 
 test('outline style is optional', async ({ page }) => {