Prefer @custom-variant over @variant

src/docs/adding-custom-styles.mdx

@@ -526,9 +526,14 @@ If you need to apply multiple variants at the same time, use nesting:
 
 ```css
 /* [!code filename:CSS] */
-@variant dark {
-  @variant hover {
-    background: black;
+.my-element {
+  background: white;
+
+  /* [!code highlight:6] */
+  @variant dark {
+    @variant hover {
+      background: black;
+    }
   }
 }
 ```

src/docs/dark-mode.mdx

@@ -116,7 +116,7 @@ If you want your dark theme to be driven by a CSS selector instead of the `prefe
 @import "tailwindcss";
 
 /* [!code highlight:2] */
-@variant dark (&:where(.dark, .dark *));
+@custom-variant dark (&:where(.dark, .dark *));
 ```
 
 Now instead of `dark:*` utilities being applied based on `prefers-color-scheme`, they will be applied whenever the `dark` class is present earlier in the HTML tree:
@@ -145,7 +145,7 @@ To use a data attribute instead of a class to activate dark mode, just override
 @import "tailwindcss";
 
 /* [!code highlight:2] */
-@variant dark (&:where([data-theme=dark], [data-theme=dark] *));
+@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));
 ```
 
 Now dark mode utilities will be applied whenever the `data-theme` attribute is set to `dark` somewhere up the tree:

src/docs/functions-and-directives.mdx

@@ -85,9 +85,14 @@ If you need to apply multiple variants at the same time, use nesting:
 
 ```css
 /* [!code filename:CSS] */
-@variant dark {
-  @variant hover {
-    background: black;
+.my-element {
+  background: white;
+
+  /* [!code highlight:6] */
+  @variant dark {
+    @variant hover {
+      background: black;
+    }
   }
 }
 ```
@@ -106,7 +111,7 @@ Use the `@custom-variant` directive to add a custom variant in your project:
 
 This lets you write utilities like `pointer-coarse:size-48` and `theme-midnight:bg-slate-900`.
 
-Learn more about adding custom variants in the [adding custom variants documentation](/docs/adding-custom-styles#adding-custom-variants).
+Learn more about adding custom variants in the [registering a custom variant documentation](/docs/hover-focus-and-other-states#registering-a-custom-variant).
 
 <h3 id="apply-directive">@apply</h3>
 

src/docs/hover-focus-and-other-states.mdx

@@ -1925,7 +1925,7 @@ Use the `not-supports-[...]` variant to style things based on whether a certain
 You can configure shortcuts for common `@supports` rules you're using in your project by creating a new variant in the `supports-*` namespace:
 
 ```css
-@variant supports-grid {
+@custom-variant supports-grid {
   @supports (display: grid) {
     @slot;
   }
@@ -2142,8 +2142,8 @@ By default we've included variants for the most common boolean ARIA attributes:
 You can customize which `aria-*` variants are available by creating a new variant:
 
 ```css
-@variant aria-asc (&[aria-sort="ascending"]);
-@variant aria-desc (&[aria-sort="descending"]);
+@custom-variant aria-asc (&[aria-sort="ascending"]);
+@custom-variant aria-desc (&[aria-sort="descending"]);
 ```
 
 If you need to use a one-off `aria` variant that doesn’t make sense to include in your project, or for more complex ARIA attributes that take specific values, use square brackets to generate a property on the fly using any arbitrary value:
@@ -2342,7 +2342,7 @@ Alternatively, you can configure shortcuts for common data attributes you're usi
 <!-- [!code filename:app.css] -->
 @import "tailwindcss";
 
-@variant data-checked (&[data-ui~="checked"]);
+@custom-variant data-checked (&[data-ui~="checked"]);
 ```
 
 You can then use these custom `data-*` variants in your project:
@@ -2885,7 +2885,7 @@ With at-rule custom variants the `&` placeholder isn't necessary, just like when
 If you find yourself using the same arbitrary variant multiple times in your project, it might be worth creating a custom variant:
 
 ```css
-@variant pointer-coarse {
+@custom-variant pointer-coarse {
   @media (pointer: coarse) {
     @slot;
   }
@@ -2902,13 +2902,13 @@ Now you can use the `pointer-coarse:<utility>` variant in your HTML:
 You can create variants using the shorthand syntax when nesting isn't required:
 
 ```css
-@variant pointer-coarse (@media (pointer: coarse));
+@custom-variant pointer-coarse (@media (pointer: coarse));
 ```
 
 When a custom variant has multiple rules, they can be nested within each other:
 
 ```css
-@variant any-hover {
+@custom-variant any-hover {
   @media (any-hover: hover) {
     &:hover {
       @slot;