From 9d42ed29cee2e40d408982ee9c9f326259ea6473 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?andr=C3=A9s=20gonz=C3=A1lez?= <andres.gonzalez79@gmail.com>
Date: Thu, 12 Nov 2026 13:04:13 +0100
Subject: [PATCH] :books: Document how to order variant properties and values
 (#12996)

Users ask how to choose the order of values in the variant property
dropdown. The values follow the order of the variants in the Layers
panel, and this was not documented. Also document that properties can
be reordered by dragging them in the Design tab.

AI-assisted-by: claude-opus-5-5
---
 docs/user-guide/design-systems/variants.njk | 7 +++++++
 1 file changed, 7 insertions(+)

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>