Fix non-deterministic variant sorting

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Detect classes in new files when using `@tailwindcss/postcss` ([#14829](https://github.com/tailwindlabs/tailwindcss/pull/14829))
 - Fix crash when using `@source` containing `..` ([#14831](https://github.com/tailwindlabs/tailwindcss/pull/14831))
+- Ensure utilities with variants are sorted deterministically ([#14835](https://github.com/tailwindlabs/tailwindcss/pull/14835))
 - _Upgrade (experimental)_: Install `@tailwindcss/postcss` next to `tailwindcss` ([#14830](https://github.com/tailwindlabs/tailwindcss/pull/14830))
 - _Upgrade (experimental)_: Remove whitespace around `,` separator when print arbitrary values ([#14838](https://github.com/tailwindlabs/tailwindcss/pull/14838))
 

packages/tailwindcss/src/compat/config.test.ts

@@ -1109,16 +1109,16 @@ test('creates variants for `data`, `supports`, and `aria` theme options at the s
       'print:flex',
     ]),
   ).toMatchInlineSnapshot(`
-    ".aria-polite\\:underline {
-      &[aria-live="polite"] {
-        text-decoration-line: underline;
-      }
-    }
-    .aria-hidden\\:flex {
+    ".aria-hidden\\:flex {
       &[aria-hidden="true"] {
         display: flex;
       }
     }
+    .aria-polite\\:underline {
+      &[aria-live="polite"] {
+        text-decoration-line: underline;
+      }
+    }
     .data-checked\\:underline {
       &[data-ui~="checked"] {
         text-decoration-line: underline;

packages/tailwindcss/src/compat/plugin-api.ts

@@ -156,12 +156,12 @@ export function buildPluginApi(
           if (a.kind !== 'functional' || z.kind !== 'functional') {
             return 0
           }
-          if (!a.value || !z.value) {
-            return 0
-          }
 
-          let aValue = options?.values?.[a.value.value] ?? a.value.value
-          let zValue = options?.values?.[z.value.value] ?? z.value.value
+          let aValueKey = a.value ? a.value.value : 'DEFAULT'
+          let zValueKey = z.value ? z.value.value : 'DEFAULT'
+
+          let aValue = options?.values?.[aValueKey] ?? aValueKey
+          let zValue = options?.values?.[zValueKey] ?? zValueKey
 
           if (options && typeof options.sort === 'function') {
             return options.sort(
@@ -170,11 +170,15 @@ export function buildPluginApi(
             )
           }
 
-          let aOrder = defaultOptionKeys.indexOf(a.value.value)
-          let zOrder = defaultOptionKeys.indexOf(z.value.value)
+          let aOrder = defaultOptionKeys.indexOf(aValueKey)
+          let zOrder = defaultOptionKeys.indexOf(zValueKey)
+
+          if (aOrder !== zOrder) return aOrder - zOrder
 
-          if (aOrder - zOrder === 0) return aValue < zValue ? -1 : 1
-          return aOrder - zOrder
+          // SAFETY: The values don't need to be checked for equality as they
+          // are guaranteed to be unique since we sort a list of de-duped
+          // variants and different (valid) variants cannot produce the same AST.
+          return aValue < zValue ? -1 : 1
         },
       )
     },