From 9cb38993d2e68cd98b458ebd8c863e87bf7ce5ae Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 23 May 2025 17:21:21 +0200
Subject: [PATCH] Upgrade deprecated `order-none` to `order-0` (#18126)

This PR adds an initial version for deprecated utilities. Right now it's
hardcoded to just the `order-none` utility.

This means that `order-0` and `order-[0]` will not be migrated to
`order-none` anymore. We did that automatically because we prefer named
utilities over bare values and arbitrary values.

With this PR, `order-none` is ignored.

Similarly, `order-none` will be migrated to `order-0` instead (defined
in a separate migration for deprecated values). Made it a new migration
instead of using the legacy migration because there all utilities still
exist, but are defined differently (e.g.: `shadow`, `shadow-sm`,
`shadow-xs`).

This PR is also an initial version, it doesn't add any form of
`deprecated` flag or feature on a per-utility implementation basis. This
therefor has the side effect that if you have a custom `order-none`
defined, that it will also be ignored during migrations.


## Test plan

1. Added tests to ensure the `order-0` is not migrated to `order-none`
2. Added tests to ensure `order-none` is migrated to `order-0` (if it's
safe to do so, the signature is still computed to ensure the output is
the same).
3. Ran this on the Tailwind Plus codebase and ensured that `order-0` is
not migrated to `order-none` and that `order-none` is migrated to
`order-0`.

---------

Co-authored-by: Jordan Pittman <jordan@cryptica.me>
---
 CHANGELOG.md                                  |  1 +
 .../src/codemods/template/candidates.ts       |  8 +++
 .../template/migrate-deprecated-utilities.ts  | 52 +++++++++++++++++++
 .../src/codemods/template/migrate.test.ts     | 42 +++++++++++++++
 .../src/codemods/template/migrate.ts          |  2 +
 .../__snapshots__/intellisense.test.ts.snap   |  1 -
 .../src/compat/legacy-utilities.ts            |  2 +
 packages/tailwindcss/src/utilities.ts         |  1 -
 8 files changed, 107 insertions(+), 2 deletions(-)
 create mode 100644 packages/@tailwindcss-upgrade/src/codemods/template/migrate-deprecated-utilities.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5b5c30e89..c002d985e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Upgrade: Do not migrate declarations that look like candidates in `<style>` blocks ([#18057](https://github.com/tailwindlabs/tailwindcss/pull/18057), [18068](https://github.com/tailwindlabs/tailwindcss/pull/18068))
 - Upgrade: Improve `pnpm` workspaces support ([#18065](https://github.com/tailwindlabs/tailwindcss/pull/18065))
+- Upgrade: Migrate deprecated `order-none` to `order-0` ([#18126](https://github.com/tailwindlabs/tailwindcss/pull/18126))
 - Support Leptos `class:` attributes when extracting classes ([#18093](https://github.com/tailwindlabs/tailwindcss/pull/18093))
 
 ## [4.1.7] - 2025-05-15
diff --git a/packages/@tailwindcss-upgrade/src/codemods/template/candidates.ts b/packages/@tailwindcss-upgrade/src/codemods/template/candidates.ts
index e33c67e18..f873c1e10 100644
--- a/packages/@tailwindcss-upgrade/src/codemods/template/candidates.ts
+++ b/packages/@tailwindcss-upgrade/src/codemods/template/candidates.ts
@@ -33,3 +33,11 @@ export function parseCandidate(designSystem: DesignSystem, input: string) {
       : input,
   )
 }
+
+export function printUnprefixedCandidate(designSystem: DesignSystem, candidate: Candidate) {
+  let candidateString = designSystem.printCandidate(candidate)
+
+  return designSystem.theme.prefix && candidateString.startsWith(`${designSystem.theme.prefix}:`)
+    ? candidateString.slice(designSystem.theme.prefix.length + 1)
+    : candidateString
+}
diff --git a/packages/@tailwindcss-upgrade/src/codemods/template/migrate-deprecated-utilities.ts b/packages/@tailwindcss-upgrade/src/codemods/template/migrate-deprecated-utilities.ts
new file mode 100644
index 000000000..41fc3697b
--- /dev/null
+++ b/packages/@tailwindcss-upgrade/src/codemods/template/migrate-deprecated-utilities.ts
@@ -0,0 +1,52 @@
+import type { Config } from '../../../../tailwindcss/src/compat/plugin-api'
+import type { DesignSystem } from '../../../../tailwindcss/src/design-system'
+import type { Writable } from '../../utils/types'
+import { baseCandidate, parseCandidate, printUnprefixedCandidate } from './candidates'
+import { computeUtilitySignature } from './signatures'
+
+const DEPRECATION_MAP = new Map([['order-none', 'order-0']])
+
+export async function migrateDeprecatedUtilities(
+  designSystem: DesignSystem,
+  _userConfig: Config | null,
+  rawCandidate: string,
+): Promise<string> {
+  let signatures = computeUtilitySignature.get(designSystem)
+
+  for (let readonlyCandidate of designSystem.parseCandidate(rawCandidate)) {
+    // The below logic makes use of mutation. Since candidates in the
+    // DesignSystem are cached, we can't mutate them directly.
+    let candidate = structuredClone(readonlyCandidate) as Writable<typeof readonlyCandidate>
+
+    // Create a basic stripped candidate without variants or important flag. We
+    // will re-add those later but they are irrelevant for what we are trying to
+    // do here (and will increase cache hits because we only have to deal with
+    // the base utility, nothing more).
+    let targetCandidate = baseCandidate(candidate)
+    let targetCandidateString = printUnprefixedCandidate(designSystem, targetCandidate)
+
+    let replacementString = DEPRECATION_MAP.get(targetCandidateString) ?? null
+    if (replacementString === null) return rawCandidate
+
+    let legacySignature = signatures.get(targetCandidateString)
+    if (typeof legacySignature !== 'string') return rawCandidate
+
+    let replacementSignature = signatures.get(replacementString)
+    if (typeof replacementSignature !== 'string') return rawCandidate
+
+    // Not the same signature, not safe to migrate
+    if (legacySignature !== replacementSignature) return rawCandidate
+
+    let [replacement] = parseCandidate(designSystem, replacementString)
+
+    // Re-add the variants and important flag from the original candidate
+    return designSystem.printCandidate(
+      Object.assign(structuredClone(replacement), {
+        variants: candidate.variants,
+        important: candidate.important,
+      }),
+    )
+  }
+
+  return rawCandidate
+}
diff --git a/packages/@tailwindcss-upgrade/src/codemods/template/migrate.test.ts b/packages/@tailwindcss-upgrade/src/codemods/template/migrate.test.ts
index 45a5a15a9..5c91f3d07 100644
--- a/packages/@tailwindcss-upgrade/src/codemods/template/migrate.test.ts
+++ b/packages/@tailwindcss-upgrade/src/codemods/template/migrate.test.ts
@@ -45,6 +45,14 @@ describe.each([['default'], ['with-variant'], ['important'], ['prefix']])('%s',
 
     // Promote inferred data type to more specific utility if it exists
     ['bg-[123px]', 'bg-position-[123px]'],
+
+    // Do not migrate bare values or arbitrary values to named values that are
+    // deprecated
+    ['order-[0]', 'order-0'],
+    ['order-0', 'order-0'],
+
+    // Migrate deprecated named values to bare values
+    ['order-none', 'order-0'],
   ])(testName, async (candidate, result) => {
     if (strategy === 'with-variant') {
       candidate = `focus:${candidate}`
@@ -63,4 +71,38 @@ describe.each([['default'], ['with-variant'], ['important'], ['prefix']])('%s',
     let migrated = await migrate(designSystem, {}, candidate)
     expect(migrated).toEqual(result)
   })
+
+  test.each([
+    ['order-[0]', 'order-0'],
+    ['order-0', 'order-0'],
+
+    // Do not migrate `order-none` if defined as a custom utility as it is then
+    // not safe to migrate to `order-0`
+    ['order-none', 'order-none'],
+  ])(`${testName} with custom implementations`, async (candidate, result) => {
+    if (strategy === 'with-variant') {
+      candidate = `focus:${candidate}`
+      result = `focus:${result}`
+    } else if (strategy === 'important') {
+      candidate = `${candidate}!`
+      result = `${result}!`
+    } else if (strategy === 'prefix') {
+      // Not only do we need to prefix the candidate, we also have to make
+      // sure that we prefix all CSS variables.
+      candidate = `tw:${candidate.replaceAll('var(--', 'var(--tw-')}`
+      result = `tw:${result.replaceAll('var(--', 'var(--tw-')}`
+    }
+
+    let localInput = css`
+      ${input}
+
+      @utility order-none {
+        order: none; /* imagine this exists */
+      }
+    `
+
+    let designSystem = await designSystems.get(__dirname).get(localInput)
+    let migrated = await migrate(designSystem, {}, candidate)
+    expect(migrated).toEqual(result)
+  })
 })
diff --git a/packages/@tailwindcss-upgrade/src/codemods/template/migrate.ts b/packages/@tailwindcss-upgrade/src/codemods/template/migrate.ts
index 4c0a26a83..4763577c7 100644
--- a/packages/@tailwindcss-upgrade/src/codemods/template/migrate.ts
+++ b/packages/@tailwindcss-upgrade/src/codemods/template/migrate.ts
@@ -14,6 +14,7 @@ import { migrateBareValueUtilities } from './migrate-bare-utilities'
 import { migrateBgGradient } from './migrate-bg-gradient'
 import { migrateCamelcaseInNamedValue } from './migrate-camelcase-in-named-value'
 import { migrateCanonicalizeCandidate } from './migrate-canonicalize-candidate'
+import { migrateDeprecatedUtilities } from './migrate-deprecated-utilities'
 import { migrateDropUnnecessaryDataTypes } from './migrate-drop-unnecessary-data-types'
 import { migrateEmptyArbitraryValues } from './migrate-handle-empty-arbitrary-values'
 import { migrateLegacyArbitraryValues } from './migrate-legacy-arbitrary-values'
@@ -48,6 +49,7 @@ export const DEFAULT_MIGRATIONS: Migration[] = [
   migrateLegacyArbitraryValues,
   migrateArbitraryUtilities,
   migrateBareValueUtilities,
+  migrateDeprecatedUtilities,
   migrateModernizeArbitraryValues,
   migrateArbitraryVariants,
   migrateDropUnnecessaryDataTypes,
diff --git a/packages/tailwindcss/src/__snapshots__/intellisense.test.ts.snap b/packages/tailwindcss/src/__snapshots__/intellisense.test.ts.snap
index 8c3b136a7..d49ecf433 100644
--- a/packages/tailwindcss/src/__snapshots__/intellisense.test.ts.snap
+++ b/packages/tailwindcss/src/__snapshots__/intellisense.test.ts.snap
@@ -8079,7 +8079,6 @@ exports[`getClassList 1`] = `
   "order-12",
   "order-first",
   "order-last",
-  "order-none",
   "ordinal",
   "origin-bottom",
   "origin-bottom-left",
diff --git a/packages/tailwindcss/src/compat/legacy-utilities.ts b/packages/tailwindcss/src/compat/legacy-utilities.ts
index e3f9436d1..8667816a1 100644
--- a/packages/tailwindcss/src/compat/legacy-utilities.ts
+++ b/packages/tailwindcss/src/compat/legacy-utilities.ts
@@ -90,4 +90,6 @@ export function registerLegacyUtilities(designSystem: DesignSystem) {
       return [decl('flex-grow', candidate.value.value)]
     }
   })
+
+  designSystem.utilities.static('order-none', () => [decl('order', '0')])
 }
diff --git a/packages/tailwindcss/src/utilities.ts b/packages/tailwindcss/src/utilities.ts
index 9a671a41d..0fdb5c9f2 100644
--- a/packages/tailwindcss/src/utilities.ts
+++ b/packages/tailwindcss/src/utilities.ts
@@ -649,7 +649,6 @@ export function createUtilities(theme: Theme) {
    */
   staticUtility('order-first', [['order', '-9999']])
   staticUtility('order-last', [['order', '9999']])
-  staticUtility('order-none', [['order', '0']])
   functionalUtility('order', {
     supportsNegative: true,
     handleBareValue: ({ value }) => {