diff --git a/docs/user-guide/design-systems/variants.njk b/docs/user-guide/design-systems/variants.njk
index 5b41f0fade..5a6a1ff2e1 100644
--- a/docs/user-guide/design-systems/variants.njk
+++ b/docs/user-guide/design-systems/variants.njk
@@ -86,6 +86,13 @@ desc: Streamline your design workflow with Penpot's Components guide! Learn to c
   <img src="/img/variants/04-variants-properties-edit.webp" alt="Edit variant property" />
 </figure>
 
+<h5>Order properties and values</h5>
+<ul>
+  <li><strong>Properties:</strong> In the Design tab, drag a property by its handle to move it up or down.</li>
+  <li><strong>Values:</strong> The values dropdown follows the order of the variants in the Layers panel, from top to bottom. Each value appears where the first variant that uses it sits. To change the order, reorder the variants in the Layers panel. Empty values always go last.</li>
+</ul>
+<p class="advice">The variant order applies to all properties at once, so you may not be able to set the value order you want for two properties at the same time.</p>
+
 <h5>Delete properties</h5>
 <ul>
   <li><strong>From the Design tab:</strong> Select the main component (not an individual variant) and press the minus button next to the property.</li>