add comment that there could be a behavior change

Co-Authored-By: Jordan Pittman <[email protected]>

Author: RobinMalfait

integrations/upgrade/js-config.test.ts

@@ -1018,6 +1018,13 @@ test(
       --- src/input.css ---
       @import 'tailwindcss';
 
+      /*
+        These variants have been migrated from your Tailwind CSS configuration file.
+        Since they are custom variants, they will be sorted after all built-in variants.
+
+        This may result in elements appearing different if you were relying on the order of
+        the variants in the CSS.
+      */
       @custom-variant aria-bar (&[aria-baz="true"]);
       @custom-variant aria-asc (&[aria-sort="ascending"]);
       @custom-variant aria-desc (&[aria-sort="descending"]);

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

@@ -1,4 +1,5 @@
 import { Scanner } from '@tailwindcss/oxide'
+import dedent from 'dedent'
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -223,6 +224,17 @@ async function migrateTheme(
 
   if (variants.size > 0) {
     css += '\n@tw-bucket custom-variant {\n'
+
+    css += dedent`
+      /*
+        These variants have been migrated from your Tailwind CSS configuration file.
+        Since they are custom variants, they will be sorted after all built-in variants.
+
+        This may result in elements appearing different if you were relying on the order of
+        the variants in the CSS.
+      */
+    `
+
     for (let [name, selector] of variants) {
       css += `@custom-variant ${name} (${selector});\n`
     }