From 012be568d7213d02e0d0403029b534998c2b8748 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Mon, 4 May 2026 18:16:40 +0200
Subject: [PATCH 1/2] document new `@variant` behavior where you can stack &
 compounds variants

---
 src/docs/adding-custom-styles.mdx | 54 +++++++++++++++++++++++++------
 1 file changed, 44 insertions(+), 10 deletions(-)

diff --git a/src/docs/adding-custom-styles.mdx b/src/docs/adding-custom-styles.mdx
index 56069ae8a..158daf0ae 100644
--- a/src/docs/adding-custom-styles.mdx
+++ b/src/docs/adding-custom-styles.mdx
@@ -328,7 +328,7 @@ Use the `@variant` directive to apply a Tailwind variant within custom CSS:
 
 </CodeExampleStack>
 
-If you need to apply multiple variants at the same time, use nesting:
+If you need to apply multiple variants at the same time, stack them using the same syntax you would in HTML:
 
 <CodeExampleStack>
 
@@ -337,11 +337,9 @@ If you need to apply multiple variants at the same time, use nesting:
 .my-element {
   background: white;
 
-  /* [!code highlight:6] */
-  @variant dark {
-    @variant hover {
-      background: black;
-    }
+  /* [!code highlight:4] */
+  @variant hover:focus {
+    background: black;
   }
 }
 ```
@@ -351,10 +349,10 @@ If you need to apply multiple variants at the same time, use nesting:
 .my-element {
   background: white;
 
-  /* [!code highlight:7] */
-  @media (prefers-color-scheme: dark) {
-    &:hover {
-      @media (hover: hover) {
+  /* [!code highlight:8] */
+  &:hover {
+    @media (hover: hover) {
+      &:focus {
         background: black;
       }
     }
@@ -364,6 +362,42 @@ If you need to apply multiple variants at the same time, use nesting:
 
 </CodeExampleStack>
 
+To apply the same styles for multiple variants, separate each variant with a comma:
+
+<CodeExampleStack>
+
+```css
+/* [!code filename:app.css] */
+.my-element {
+  background: white;
+
+  /* [!code highlight:4] */
+  @variant hover, focus {
+    background: black;
+  }
+}
+```
+
+```css
+/* [!code filename:Compiled CSS] */
+.my-element {
+  background: white;
+
+  /* [!code highlight:10] */
+  &:hover {
+    @media (hover: hover) {
+      background: black;
+    }
+  }
+
+  &:focus {
+    background: black;
+  }
+}
+```
+
+</CodeExampleStack>
+
 ## Adding custom utilities
 
 ### Simple utilities

From 9395d8e4b3f84cd932d1bf46e0873abe4d4e3966 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 8 May 2026 16:06:15 +0200
Subject: [PATCH 2/2] split highlights

---
 src/docs/adding-custom-styles.mdx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/docs/adding-custom-styles.mdx b/src/docs/adding-custom-styles.mdx
index 158daf0ae..bf3792fc3 100644
--- a/src/docs/adding-custom-styles.mdx
+++ b/src/docs/adding-custom-styles.mdx
@@ -383,13 +383,14 @@ To apply the same styles for multiple variants, separate each variant with a com
 .my-element {
   background: white;
 
-  /* [!code highlight:10] */
+  /* [!code highlight:6] */
   &:hover {
     @media (hover: hover) {
       background: black;
     }
   }
 
+  /* [!code highlight:4] */
   &:focus {
     background: black;
   }