Convert opacity keys to percentage values (#15067)

This PR improves compatibility for named `opacity` theme values. One of
the changes in v4 is that we use the CSS `color-mix()` function to apply
opacity to colors. This, however, is limited to percentage values only:

```css
color: color-mix(in oklch, var(--color-red-500) 50%, transparent);
/*                                              ^^^             */
/*                          This needs to be a percentage value */
```

In v3, however, it was common to specify custom opacity values as
decimal numbers. That's also what we did in our default config:


https://github.com/tailwindlabs/tailwindcss/blob/6069a811871c58a9b202fbb3a6f13774c57278c0/stubs/config.full.js#L703-L725

This PR improves interop with these values by:

1. Converting decimal numbers in the range of `[0, 1]` to their
percentage value equivalent when using the interop layer.
2. Adjusts the codemod that migrates `opacity` theme keys to Tailwind v4
theme variables to include the same conversion.
3. Furthermore, due to the added support of named opacity modifers, we
can also drop theme keys that would now be the default. For example the
following config would not be necessary in v4 as the opacity modifier
would accept the value `50` by default:
    ```js
    module.exports = {
      theme: {
        opacity: {
          50: 0.5
        }
      }
    }
    ```

## Test Plan

Added a new integration test for the codemod and a unit test for the
interop layer. I also re-ran the codemod on the Commit template and it's
now working as expected (left is v3, right is v4):

<img width="2560" alt="Screenshot 2024-11-21 at 17 25 32"
src="https://github.com/user-attachments/assets/f0c87243-ca80-4c39-ae5e-c1ab48fbe614">

Author: philipp-spiess

CHANGELOG.md

@@ -7,8 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- _Upgrade (experimental)_: Drop unnecessary `opacity` theme values when migrating to CSS ([#15067](https://github.com/tailwindlabs/tailwindcss/pull/15067))
+
 ### Fixed
 
+- Ensure `opacity` theme values configured as decimal numbers via JS config files work with color utilities ([#15067](https://github.com/tailwindlabs/tailwindcss/pull/15067))
 - _Upgrade (experimental)_: Include `color` in the form reset snippet ([#15064](https://github.com/tailwindlabs/tailwindcss/pull/15064))
 
 ## [4.0.0-alpha.36] - 2024-11-21

integrations/upgrade/index.test.ts

@@ -2939,3 +2939,137 @@ test(
     )
   },
 )
+
+test(
+  `upgrades opacity namespace values to percentages`,
+  {
+    fs: {
+      'package.json': json`
+        {
+          "dependencies": {
+            "tailwindcss": "^3",
+            "@tailwindcss/upgrade": "workspace:^"
+          },
+          "devDependencies": {
+            "@tailwindcss/cli": "workspace:^"
+          }
+        }
+      `,
+      'tailwind.config.js': js`
+        /** @type {import('tailwindcss').Config} */
+        module.exports = {
+          theme: {
+            opacity: {
+              0: '0',
+              2.5: '.025',
+              5: '.05',
+              7.5: 0.075,
+              10: 0.1,
+
+              semitransparent: '0.5',
+              transparent: 1,
+
+              50: '50%',
+              50.5: '50.5%',
+              '50.50': '50.5%',
+              '75%': '75%',
+              '100%': '100%',
+            },
+          },
+          content: ['./src/**/*.{html,js}'],
+        }
+      `,
+      'src/index.html': html`
+        <div
+          class="text-red-500/0
+            text-red-500/2.5
+            text-red-500/5
+            text-red-500/7.5
+            text-red-500/10
+            text-red-500/semitransparent
+            text-red-500/transparent
+            text-red-500/50
+            text-red-500/50.5
+            text-red-500/50.50
+            text-red-500/50%
+            text-red-500/100%"
+        ></div>
+      `,
+      'src/input.css': css`
+        @tailwind base;
+        @tailwind components;
+        @tailwind utilities;
+      `,
+    },
+  },
+  async ({ exec, fs }) => {
+    await exec('npx @tailwindcss/upgrade')
+
+    expect(await fs.dumpFiles('./src/**/*.{css,html}')).toMatchInlineSnapshot(`
+      "
+      --- ./src/index.html ---
+      <div
+        class="text-red-500/0
+          text-red-500/2.5
+          text-red-500/5
+          text-red-500/7.5
+          text-red-500/10
+          text-red-500/semitransparent
+          text-red-500/transparent
+          text-red-500/50
+          text-red-500/50.5
+          text-red-500/50.50
+          text-red-500/50%
+          text-red-500/100%"
+      ></div>
+
+      --- ./src/input.css ---
+      @import 'tailwindcss';
+
+      @theme {
+        --opacity-*: initial;
+        --opacity-semitransparent: 50%;
+        --opacity-transparent: 100%;
+        --opacity-50_50: 50.5%;
+        --opacity-75\\%: 75%;
+        --opacity-100\\%: 100%;
+      }
+
+      /*
+        In Tailwind CSS v4, basic styles are applied to form elements by default. To
+        maintain compatibility with v3, the following resets have been added:
+      */
+      @layer base {
+        input,
+        textarea,
+        select,
+        button {
+          border: 0px solid;
+          border-radius: 0;
+          padding: 0;
+          color: inherit;
+          background-color: transparent;
+        }
+      }
+
+      /*
+        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);
+        }
+      }
+      "
+    `)
+  },
+)

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

@@ -17,7 +17,10 @@ import { darkModePlugin } from '../../tailwindcss/src/compat/dark-mode'
 import type { Config } from '../../tailwindcss/src/compat/plugin-api'
 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 {
+  isValidOpacityValue,
+  isValidSpacingMultiplier,
+} from '../../tailwindcss/src/utils/infer-data-type'
 import { findStaticPlugins, type StaticPluginOptions } from './utils/extract-static-plugins'
 import { highlight, info, relative } from './utils/renderer'
 
@@ -125,6 +128,25 @@ async function migrateTheme(
       value = value.replace(/\s*\/\s*<alpha-value>/, '').replace(/<alpha-value>/, '1')
     }
 
+    // Convert `opacity` namespace from decimal to percentage values.
+    // Additionally we can drop values that resolve to the same value as the
+    // named modifier with the same name.
+    if (key[0] === 'opacity' && (typeof value === 'number' || typeof value === 'string')) {
+      let numValue = typeof value === 'string' ? parseFloat(value) : value
+
+      if (numValue >= 0 && numValue <= 1) {
+        value = numValue * 100 + '%'
+      }
+
+      if (
+        typeof value === 'string' &&
+        key[1] === value.replace(/%$/, '') &&
+        isValidOpacityValue(key[1])
+      ) {
+        continue
+      }
+    }
+
     if (key[0] === 'keyframes') {
       continue
     }

packages/tailwindcss/src/compat/apply-config-to-theme.test.ts

@@ -186,3 +186,34 @@ describe('keyPathToCssProperty', () => {
     expect(`--${keyPathToCssProperty(keyPath)}`).toEqual(expected)
   })
 })
+
+test('converts opacity modifiers from decimal to percentage values', () => {
+  let theme = new Theme()
+  let design = buildDesignSystem(theme)
+
+  let { resolvedConfig, replacedThemeKeys } = resolveConfig(design, [
+    {
+      config: {
+        theme: {
+          opacity: {
+            0: '0',
+            5: '0.05',
+            10: '0.1',
+            15: '0.15',
+            20: 0.2,
+            25: 0.25,
+          },
+        },
+      },
+      base: '/root',
+    },
+  ])
+  applyConfigToTheme(design, resolvedConfig, replacedThemeKeys)
+
+  expect(theme.resolve('0', ['--opacity'])).toEqual('0%')
+  expect(theme.resolve('5', ['--opacity'])).toEqual('5%')
+  expect(theme.resolve('10', ['--opacity'])).toEqual('10%')
+  expect(theme.resolve('15', ['--opacity'])).toEqual('15%')
+  expect(theme.resolve('20', ['--opacity'])).toEqual('20%')
+  expect(theme.resolve('25', ['--opacity'])).toEqual('25%')
+})

packages/tailwindcss/src/compat/apply-config-to-theme.ts

@@ -37,10 +37,20 @@ export function applyConfigToTheme(
       continue
     }
 
+    // Replace `<alpha-value>` with `1`
     if (typeof value === 'string') {
       value = value.replace(/<alpha-value>/g, '1')
     }
 
+    // Convert `opacity` namespace from decimal to percentage values
+    if (path[0] === 'opacity' && (typeof value === 'number' || typeof value === 'string')) {
+      let numValue = typeof value === 'string' ? parseFloat(value) : value
+
+      if (numValue >= 0 && numValue <= 1) {
+        value = numValue * 100 + '%'
+      }
+    }
+
     let name = keyPathToCssProperty(path)
     if (!name) continue