Improve compatibility with Safari 15 (#17435)

This PR improves the compatibility with Tailwind CSS v4 with unsupported
browsers with the goal to greatly improve compatibility with Safari 15.

To make this work, this PR makes the following changes to all code

- Change `oklab(…)` default theme values to use a percentage in the
first place (so instead of `--color-red-500: oklch(0.637 0.237 25.331);`
we now define it as `--color-red-500: oklch(63.7% 0.237 25.331);` since
this syntax has much broader support on Safari).
- Polyfill `@property` with a `@supports` query targeting older versions
of Safari and Firefox *
- Create fallbacks for the `color-mix(…)` function that use _inlined
color values from your theme_ so that they can be computed a compile
time by `lightningcss`. These fallbacks will convert to srgb to increase
compatibility.
- Create fallbacks for the _relative color_ feature used in the new
shadow utilities and using `color-mix(…)` in case _relative color_ is
applied on `currentcolor` (due to limited browser support)
- Create fallbacks for gradient interpolation methods (e.g. to support
`bg-linear-to-r/oklab`)
- Polyfill `@media` queries range syntax.

## A simplified example

Given this example CSS input:

```css
@import 'tailwindcss';
@source inline('from-cyan-500/50 bg-linear-45');
```

Here's the updated output CSS including the newly added polyfills and
updated `oklab` values:

```css
.bg-linear-45 {
  --tw-gradient-position: 45deg;
  background-image: linear-gradient(var(--tw-gradient-stops));
}

@supports (background-image: linear-gradient(in lab, red, red)) {
  .bg-linear-45 {
    --tw-gradient-position: 45deg in oklab;
  }
}

.from-cyan-500\\/50 {
  --tw-gradient-from: oklab(71.5% -.11682 -.08247 / .5);
  --tw-gradient-stops: var(--tw-gradient-via-stops, var(--tw-gradient-position), var(--tw-gradient-from) var(--tw-gradient-from-position), var(--tw-gradient-to) var(--tw-gradient-to-position));
}

@supports (color: color-mix(in lab, red, red)) {
  .from-cyan-500\\/50 {
    --tw-gradient-from: color-mix(in oklab, var(--color-cyan-500) 50%, transparent);
  }
}

:root, :host {
  --color-cyan-500: oklch(71.5% .143 215.221);
}

@supports (((-webkit-hyphens: none)) and (not (margin-trim: 1lh))) or ((-moz-orient: inline) and (not (color: rgb(from red r g b)))) {
  @layer base {
    *, :before, :after, ::backdrop {
      --tw-gradient-position: initial;
      --tw-gradient-from: #0000;
      --tw-gradient-via: #0000;
      --tw-gradient-to: #0000;
      --tw-gradient-stops: initial;
      --tw-gradient-via-stops: initial;
      --tw-gradient-from-position: 0%;
      --tw-gradient-via-position: 50%;
      --tw-gradient-to-position: 100%;
    }
  }
}

@Property --tw-gradient-position {
  syntax: "*";
  inherits: false
}

@Property --tw-gradient-from {
  syntax: "<color>";
  inherits: false;
  initial-value: #0000;
}

@Property --tw-gradient-via {
  syntax: "<color>";
  inherits: false;
  initial-value: #0000;
}

@Property --tw-gradient-to {
  syntax: "<color>";
  inherits: false;
  initial-value: #0000;
}

@Property --tw-gradient-stops {
  syntax: "*";
  inherits: false
}

@Property --tw-gradient-via-stops {
  syntax: "*";
  inherits: false
}

@Property --tw-gradient-from-position {
  syntax: "<length-percentage>";
  inherits: false;
  initial-value: 0%;
}

@Property --tw-gradient-via-position {
  syntax: "<length-percentage>";
  inherits: false;
  initial-value: 50%;
}

@Property --tw-gradient-to-position {
  syntax: "<length-percentage>";
  inherits: false;
  initial-value: 100%;
}
```

## \* A note on `@property` polyfills and CSS modules

On Next.js, CSS module files are required to be _pure_, meaning that all
selectors must either be scoped to a class or an ID. Fortunatnyl for us,
this does not apply to `@property` rules which we've been using before
to initialize CSS variables.

However, since we're now bringing back the `@property` polyfills, that
would cause unexpected rules to be exported from the CSS file as this:

```css
@reference "tailwindcss";

.skew {
  @apply skew-7;
}
```

Would turn to the following file:

```css
.skew {
  /* … */
}
@supports (/*…*/) {
  @layer base {
    *, :before, :after, ::backdrop {
      --tw-gradient-position: initial;
    }
  }
}
@Property /* … */ 
```

Notice that this adds a `*` selector which is not considered pure.

Unfortunately there is no way for us to silence this warning or work
around it, as the dependency causing this errors
([`postcss-modules-local-by-default`](https://github.com/css-modules/postcss-modules-local-by-default))
is bundled into Next.js. To work around crashes, these polyfills will
not apply to CSS modules processed by the PostCSS extension for now.

## Testing on tailwindcss.com

To see the changes in effect, take a look at this screencast that
compares tailwindcss.com on iOS 15.5 with a version that has the patches
of this PR applied:

https://github.com/user-attachments/assets/1279d6f5-3c63-4f30-839c-198a789f4292

## Test plan

- Tested on tailwindcss.com via a preview build:
https://tailwindcss-com-git-legacy-browsers-tailwindlabs.vercel.app/
- Updated tests
- Ensure we also test on Chrome 111, Safari 16.4, Firefox 128 to
make sure we have no regressions. Also tested on Safari 16.4, 15.5, 18.0

Author: philipp-spiess

integrations/cli/index.test.ts

@@ -713,6 +713,13 @@ test(
     expect(await fs.dumpFiles('./dist/*.css')).toMatchInlineSnapshot(`
       "
       --- ./dist/out.css ---
+      @supports ((-webkit-hyphens: none) and (not (margin-trim: inline))) or ((-moz-orient: inline) and (not (color:rgb(from red r g b)))) {
+        @layer base {
+          *, ::before, ::after, ::backdrop {
+            --tw-content: "";
+          }
+        }
+      }
       .content-\\[\\"components\\/my-component\\.tsx\\"\\] {
         --tw-content: "components/my-component.tsx";
         content: var(--tw-content);
@@ -944,6 +951,13 @@ test(
     expect(await fs.dumpFiles('./project-a/dist/*.css')).toMatchInlineSnapshot(`
       "
       --- ./project-a/dist/out.css ---
+      @supports ((-webkit-hyphens: none) and (not (margin-trim: inline))) or ((-moz-orient: inline) and (not (color:rgb(from red r g b)))) {
+        @layer base {
+          *, ::before, ::after, ::backdrop {
+            --tw-content: "";
+          }
+        }
+      }
       .content-\\[\\'project-a\\/node_modules\\/my-lib-1\\/src\\/index\\.html\\'\\] {
         --tw-content: 'project-a/node modules/my-lib-1/src/index.html';
         content: var(--tw-content);
@@ -1181,6 +1195,13 @@ test(
     expect(await fs.dumpFiles('./dist/*.css')).toMatchInlineSnapshot(`
       "
       --- ./dist/out.css ---
+      @supports ((-webkit-hyphens: none) and (not (margin-trim: inline))) or ((-moz-orient: inline) and (not (color:rgb(from red r g b)))) {
+        @layer base {
+          *, ::before, ::after, ::backdrop {
+            --tw-content: "";
+          }
+        }
+      }
       .content-\\[\\"pages\\/foo\\.html\\"\\] {
         --tw-content: "pages/foo.html";
         content: var(--tw-content);
@@ -1508,7 +1529,7 @@ test(
       "
       --- ./dist/out.css ---
       :root, :host {
-        --color-blue-500: oklch(0.623 0.214 259.815);
+        --color-blue-500: oklch(62.3% 0.214 259.815);
       }
       .flex {
         display: flex;
@@ -1531,8 +1552,8 @@ test(
       "
       --- ./dist/out.css ---
       :root, :host {
-        --color-red-500: oklch(0.637 0.237 25.331);
-        --color-blue-500: oklch(0.623 0.214 259.815);
+        --color-red-500: oklch(63.7% 0.237 25.331);
+        --color-blue-500: oklch(62.3% 0.214 259.815);
       }
       .flex {
         display: flex;

integrations/postcss/next.test.ts

@@ -48,7 +48,7 @@ test(
       'app/page.module.css': css`
         @reference './globals.css';
         .heading {
-          @apply text-red-500 animate-ping;
+          @apply text-red-500 animate-ping skew-7;
         }
       `,
       'app/globals.css': css`
@@ -77,9 +77,10 @@ test(
     ])
 
     await fs.expectFileToContain(moduleCss!, [
-      'color:var(--color-red-500,oklch(.637 .237 25.331)',
+      'color:var(--color-red-500,oklch(63.7% .237 25.331)',
       'animation:var(--animate-ping,ping 1s cubic-bezier(0,0,.2,1) infinite)',
       /@keyframes page_ping.*{75%,to{transform:scale\(2\);opacity:0}/,
+      '--tw-skew-x:skewX(7deg);',
     ])
   },
 )
@@ -130,7 +131,7 @@ describe.each(['turbo', 'webpack'])('%s', (bundler) => {
         'app/page.module.css': css`
           @reference './globals.css';
           .heading {
-            @apply text-red-500 animate-ping content-['module'];
+            @apply text-red-500 animate-ping skew-7 content-['module'];
           }
         `,
         'app/globals.css': css`
@@ -173,6 +174,7 @@ describe.each(['turbo', 'webpack'])('%s', (bundler) => {
         let css = await fetchStyles(url)
         expect(css).toContain(candidate`underline`)
         expect(css).toContain(candidate`bg-red-500`)
+        expect(css).toContain('--tw-skew-x: skewX(7deg);')
         expect(css).toContain('content: var(--tw-content)')
         expect(css).toContain('@keyframes')
       })

integrations/postcss/source.test.ts

@@ -94,6 +94,13 @@ test(
     expect(await fs.dumpFiles('./dist/*.css')).toMatchInlineSnapshot(`
       "
       --- ./dist/out.css ---
+      @supports ((-webkit-hyphens: none) and (not (margin-trim: inline))) or ((-moz-orient: inline) and (not (color:rgb(from red r g b)))) {
+        @layer base {
+          *, ::before, ::after, ::backdrop {
+            --tw-content: "";
+          }
+        }
+      }
       .content-\\[\\"components\\/my-component\\.tsx\\"\\] {
         --tw-content: "components/my-component.tsx";
         content: var(--tw-content);
@@ -324,6 +331,13 @@ test(
     expect(await fs.dumpFiles('./project-a/dist/*.css')).toMatchInlineSnapshot(`
       "
       --- ./project-a/dist/out.css ---
+      @supports ((-webkit-hyphens: none) and (not (margin-trim: inline))) or ((-moz-orient: inline) and (not (color:rgb(from red r g b)))) {
+        @layer base {
+          *, ::before, ::after, ::backdrop {
+            --tw-content: "";
+          }
+        }
+      }
       .content-\\[\\'project-a\\/node_modules\\/my-lib-1\\/src\\/index\\.html\\'\\] {
         --tw-content: 'project-a/node modules/my-lib-1/src/index.html';
         content: var(--tw-content);
@@ -579,6 +593,13 @@ test(
     expect(await fs.dumpFiles('./dist/*.css')).toMatchInlineSnapshot(`
       "
       --- ./dist/out.css ---
+      @supports ((-webkit-hyphens: none) and (not (margin-trim: inline))) or ((-moz-orient: inline) and (not (color:rgb(from red r g b)))) {
+        @layer base {
+          *, ::before, ::after, ::backdrop {
+            --tw-content: "";
+          }
+        }
+      }
       .content-\\[\\"pages\\/foo\\.html\\"\\] {
         --tw-content: "pages/foo.html";
         content: var(--tw-content);
@@ -683,6 +704,13 @@ test(
     expect(await fs.dumpFiles('./project-a/dist/*.css')).toMatchInlineSnapshot(`
       "
       --- ./project-a/dist/out.css ---
+      @supports ((-webkit-hyphens: none) and (not (margin-trim: inline))) or ((-moz-orient: inline) and (not (color:rgb(from red r g b)))) {
+        @layer base {
+          *, ::before, ::after, ::backdrop {
+            --tw-content: "";
+          }
+        }
+      }
       .content-\\[\\'keep-me\\.html\\'\\] {
         --tw-content: 'keep-me.html';
         content: var(--tw-content);

integrations/upgrade/js-config.test.ts

@@ -472,17 +472,17 @@ test(
       @import 'tailwindcss';
 
       @theme {
-        --color-gray-50: oklch(0.985 0 0);
-        --color-gray-100: oklch(0.97 0 0);
-        --color-gray-200: oklch(0.922 0 0);
-        --color-gray-300: oklch(0.87 0 0);
-        --color-gray-400: oklch(0.708 0 0);
-        --color-gray-500: oklch(0.556 0 0);
-        --color-gray-600: oklch(0.439 0 0);
-        --color-gray-700: oklch(0.371 0 0);
-        --color-gray-800: oklch(0.269 0 0);
-        --color-gray-900: oklch(0.205 0 0);
-        --color-gray-950: oklch(0.145 0 0);
+        --color-gray-50: oklch(98.5% 0 0);
+        --color-gray-100: oklch(97% 0 0);
+        --color-gray-200: oklch(92.2% 0 0);
+        --color-gray-300: oklch(87% 0 0);
+        --color-gray-400: oklch(70.8% 0 0);
+        --color-gray-500: oklch(55.6% 0 0);
+        --color-gray-600: oklch(43.9% 0 0);
+        --color-gray-700: oklch(37.1% 0 0);
+        --color-gray-800: oklch(26.9% 0 0);
+        --color-gray-900: oklch(20.5% 0 0);
+        --color-gray-950: oklch(14.5% 0 0);
       }
 
       /*
@@ -1061,7 +1061,7 @@ describe('border compatibility', () => {
           ::before,
           ::backdrop,
           ::file-selector-button {
-            border-color: oklch(0.623 0.214 259.815);
+            border-color: oklch(62.3% 0.214 259.815);
           }
         }
         "

integrations/vite/svelte.test.ts

@@ -100,8 +100,8 @@ test(
 
     await fs.expectFileToContain(files[0][0], [
       candidate`underline`,
-      '.global{color:var(--color-green-500,oklch(.723 .219 149.579));animation:2s ease-in-out infinite globalKeyframes}',
-      /\.local.svelte-.*\{color:var\(--color-red-500\,oklch\(\.637 \.237 25\.331\)\);animation:2s ease-in-out infinite svelte-.*-localKeyframes\}/,
+      '.global{color:var(--color-green-500,oklch(72.3% .219 149.579));animation:2s ease-in-out infinite globalKeyframes}',
+      /\.local.svelte-.*\{color:var\(--color-red-500\,oklch\(63\.7% \.237 25\.331\)\);animation:2s ease-in-out infinite svelte-.*-localKeyframes\}/,
       /@keyframes globalKeyframes\{/,
       /@keyframes svelte-.*-localKeyframes\{/,
     ])
@@ -213,10 +213,10 @@ test(
       let [, css] = files[0]
       expect(css).toContain(candidate`underline`)
       expect(css).toContain(
-        '.global{color:var(--color-green-500,oklch(.723 .219 149.579));animation:2s ease-in-out infinite globalKeyframes}',
+        '.global{color:var(--color-green-500,oklch(72.3% .219 149.579));animation:2s ease-in-out infinite globalKeyframes}',
       )
       expect(css).toMatch(
-        /\.local.svelte-.*\{color:var\(--color-red-500,oklch\(\.637 \.237 25\.331\)\);animation:2s ease-in-out infinite svelte-.*-localKeyframes\}/,
+        /\.local.svelte-.*\{color:var\(--color-red-500,oklch\(63\.7% \.237 25\.331\)\);animation:2s ease-in-out infinite svelte-.*-localKeyframes\}/,
       )
       expect(css).toMatch(/@keyframes globalKeyframes\{/)
       expect(css).toMatch(/@keyframes svelte-.*-localKeyframes\{/)
@@ -238,15 +238,15 @@ test(
       let [, css] = files[0]
       expect(css).toContain(candidate`font-bold`)
       expect(css).toContain(
-        '.global{color:var(--color-green-500,oklch(.723 .219 149.579));animation:2s ease-in-out infinite globalKeyframes}',
+        '.global{color:var(--color-green-500,oklch(72.3% .219 149.579));animation:2s ease-in-out infinite globalKeyframes}',
       )
       expect(css).toMatch(
-        /\.local.svelte-.*\{color:var\(--color-red-500,oklch\(\.637 \.237 25\.331\)\);animation:2s ease-in-out infinite svelte-.*-localKeyframes\}/,
+        /\.local.svelte-.*\{color:var\(--color-red-500,oklch\(63\.7% \.237 25\.331\)\);animation:2s ease-in-out infinite svelte-.*-localKeyframes\}/,
       )
       expect(css).toMatch(/@keyframes globalKeyframes\{/)
       expect(css).toMatch(/@keyframes svelte-.*-localKeyframes\{/)
       expect(css).toMatch(
-        /\.bar.svelte-.*\{color:var\(--color-pink-500,oklch\(\.656 \.241 354\.308\)\)\}/,
+        /\.bar.svelte-.*\{color:var\(--color-pink-500,oklch\(65\.6% \.241 354\.308\)\)\}/,
       )
     })
   },

integrations/webpack/index.test.ts

@@ -75,7 +75,7 @@ test(
       "
       --- ./dist/main.css ---
       :root, :host {
-        --color-blue-500: oklch(0.623 0.214 259.815);
+        --color-blue-500: oklch(62.3% 0.214 259.815);
       }
       .flex {
         display: flex;
@@ -98,8 +98,8 @@ test(
       "
       --- ./dist/main.css ---
       :root, :host {
-        --color-red-500: oklch(0.637 0.237 25.331);
-        --color-blue-500: oklch(0.623 0.214 259.815);
+        --color-red-500: oklch(63.7% 0.237 25.331);
+        --color-blue-500: oklch(62.3% 0.214 259.815);
       }
       .flex {
         display: flex;

packages/@tailwindcss-cli/package.json

@@ -33,7 +33,6 @@
     "@tailwindcss/node": "workspace:*",
     "@tailwindcss/oxide": "workspace:*",
     "enhanced-resolve": "^5.18.1",
-    "lightningcss": "catalog:",
     "mri": "^1.2.0",
     "picocolors": "^1.1.1",
     "tailwindcss": "workspace:*"

packages/@tailwindcss-cli/src/commands/build/index.ts

@@ -2,10 +2,10 @@ import watcher from '@parcel/watcher'
 import { compile, env, Instrumentation } from '@tailwindcss/node'
 import { clearRequireCache } from '@tailwindcss/node/require-cache'
 import { Scanner, type ChangedContent } from '@tailwindcss/oxide'
-import { Features, transform } from 'lightningcss'
 import { existsSync, type Stats } from 'node:fs'
 import fs from 'node:fs/promises'
 import path from 'node:path'
+import { optimize } from '../../../../@tailwindcss-node/src'
 import type { Arg, Result } from '../../utils/args'
 import { Disposables } from '../../utils/disposables'
 import {
@@ -128,7 +128,7 @@ export async function handle(args: Result<ReturnType<typeof options>>) {
     if (args['--minify'] || args['--optimize']) {
       if (css !== previous.css) {
         DEBUG && I.start('Optimize CSS')
-        let optimizedCss = optimizeCss(css, {
+        let optimizedCss = optimize(css, {
           file: args['--input'] ?? 'input.css',
           minify: args['--minify'] ?? false,
         })
@@ -430,39 +430,6 @@ async function createWatchers(dirs: string[], cb: (files: string[]) => void) {
   }
 }
 
-function optimizeCss(
-  input: string,
-  { file = 'input.css', minify = false }: { file?: string; minify?: boolean } = {},
-) {
-  function optimize(code: Buffer | Uint8Array) {
-    return transform({
-      filename: file,
-      code,
-      minify,
-      sourceMap: false,
-      drafts: {
-        customMedia: true,
-      },
-      nonStandard: {
-        deepSelectorCombinator: true,
-      },
-      include: Features.Nesting,
-      exclude: Features.LogicalProperties | Features.DirSelector | Features.LightDark,
-      targets: {
-        safari: (16 << 16) | (4 << 8),
-        ios_saf: (16 << 16) | (4 << 8),
-        firefox: 128 << 16,
-        chrome: 111 << 16,
-      },
-      errorRecovery: true,
-    }).code
-  }
-
-  // Running Lightning CSS twice to ensure that adjacent rules are merged after
-  // nesting is applied. This creates a more optimized output.
-  return optimize(optimize(Buffer.from(input))).toString()
-}
-
 function watchDirectories(scanner: Scanner) {
   return [...new Set(scanner.normalizedSources.flatMap((globEntry) => globEntry.base))]
 }

packages/@tailwindcss-node/package.json

@@ -39,6 +39,7 @@
   "dependencies": {
     "enhanced-resolve": "^5.18.1",
     "jiti": "^2.4.2",
-    "tailwindcss": "workspace:*"
+    "tailwindcss": "workspace:*",
+    "lightningcss": "catalog:"
   }
 }

packages/@tailwindcss-node/src/compile.ts

@@ -9,26 +9,29 @@ import {
   compile as _compile,
   compileAst as _compileAst,
   Features,
+  Polyfills,
 } from 'tailwindcss'
 import type { AstNode } from '../../tailwindcss/src/ast'
 import { getModuleDependencies } from './get-module-dependencies'
 import { rewriteUrls } from './urls'
 
-export { Features }
+export { Features, Polyfills }
 
 export type Resolver = (id: string, base: string) => Promise<string | false | undefined>
 
 export interface CompileOptions {
   base: string
   onDependency: (path: string) => void
   shouldRewriteUrls?: boolean
+  polyfills?: Polyfills
 
   customCssResolver?: Resolver
   customJsResolver?: Resolver
 }
 
 function createCompileOptions({
   base,
+  polyfills,
   onDependency,
   shouldRewriteUrls,
 
@@ -37,6 +40,7 @@ function createCompileOptions({
 }: CompileOptions) {
   return {
     base,
+    polyfills,
     async loadModule(id: string, base: string) {
       return loadModule(id, base, onDependency, customJsResolver)
     },

packages/@tailwindcss-node/src/index.cts

@@ -4,6 +4,7 @@ import * as env from './env'
 export * from './compile'
 export * from './instrumentation'
 export * from './normalize-path'
+export * from './optimize'
 export { env }
 
 // In Bun, ESM modules will also populate `require.cache`, so the module hook is

packages/@tailwindcss-node/src/index.ts

@@ -1,9 +1,10 @@
 import * as Module from 'node:module'
 import { pathToFileURL } from 'node:url'
 import * as env from './env'
-export { __unstable__loadDesignSystem, compile, compileAst, Features } from './compile'
+export * from './compile'
 export * from './instrumentation'
 export * from './normalize-path'
+export * from './optimize'
 export { env }
 
 // In Bun, ESM modules will also populate `require.cache`, so the module hook is