From 88d715938f889cc7a661f9edd2119d052bd65173 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?andr=C3=A9s=20gonz=C3=A1lez?= <andres.gonzalez79@gmail.com>
Date: Wed, 2 Sep 2026 14:06:06 +0200
Subject: [PATCH] :books: Add migration guide page (#11454)

Point First Steps at the enterprise migration PDF with a short
summary, without duplicating the Community post.
---
 docs/user-guide/first-steps/index.njk         |  6 ++++
 .../first-steps/migration-guide.njk           | 31 +++++++++++++++++++
 .../first-steps/troubleshooting-webgl.njk     |  2 +-
 3 files changed, 38 insertions(+), 1 deletion(-)
 create mode 100644 docs/user-guide/first-steps/migration-guide.njk

diff --git a/docs/user-guide/first-steps/index.njk b/docs/user-guide/first-steps/index.njk
index c26777b24f..e707f6d46e 100644
--- a/docs/user-guide/first-steps/index.njk
+++ b/docs/user-guide/first-steps/index.njk
@@ -31,4 +31,10 @@ desc: Begin with the Penpot user guide! Get quickstarts, shortcuts, and tutorial
       <p>Useful resources to better understand Penpot</p>
     </a>
   </li>
+  <li>
+    <a href="/user-guide/first-steps/migration-guide">
+      <h2>Migration Guide →</h2>
+      <p>Move a design system from Figma to Penpot</p>
+    </a>
+  </li>
 </ul>
diff --git a/docs/user-guide/first-steps/migration-guide.njk b/docs/user-guide/first-steps/migration-guide.njk
new file mode 100644
index 0000000000..cd8600ff68
--- /dev/null
+++ b/docs/user-guide/first-steps/migration-guide.njk
@@ -0,0 +1,31 @@
+---
+title: Migration Guide
+order: 6
+desc: Move a design system from Figma to Penpot. Read a short summary of the enterprise migration guide and open the full PDF.
+---
+
+<h1 id="migration-guide">Migration Guide</h1>
+
+<p class="main-paragraph">If you are moving a design system to Penpot, especially from Figma, start with the enterprise migration guide. It covers file and library migration, tokens, validation, dual-tool workflows, and how different roles can run a pilot.</p>
+
+<div class="advice">
+  <p><strong>Open the full guide (PDF)</strong></p>
+  <p><a href="https://nextcloud.kaleidos.net/index.php/s/mKordyz62QF3PQ4?dir=/&amp;editing=false&amp;openfile=true" target="_blank" rel="noopener"><strong>The Enterprise Guide to Migrating Design Systems from Figma to Penpot</strong></a></p>
+</div>
+
+<h2 id="what-the-guide-covers">What the guide covers</h2>
+<p>The document is written for teams that need to move more than a few mockups: libraries, tokens, variants, and the workflows around them. It focuses on Figma, but the same audit, pilot, and validation steps apply if you are coming from another tool.</p>
+
+<ul>
+  <li><strong>Before you export:</strong> audit critical files, component chains, token usage, and plugins that will not come along. Split oversized files and clean unused libraries while you are still in Figma.</li>
+  <li><strong>Static assets:</strong> export SVG, PNG, or JPG from Figma and place them in Penpot.</li>
+  <li><strong>Complex files and libraries:</strong> use the Penpot Exporter plugin for Figma (design files, slides, components, variants, auto layout, styles, variables, and libraries). Expect some layout cleanup, Figma Auto Layout becomes Flex and Grid in Penpot.</li>
+  <li><strong>Tokens:</strong> if you already use Tokens Studio, export JSON and import it in Penpot. Native Figma Variables can go through Tokens Studio, or through the Exporter plugin.</li>
+  <li><strong>Validate before you scale:</strong> migrate one representative file (or a sandbox library), write down recurring cleanup, then roll the same checklist out to the rest of the workspace.</li>
+  <li><strong>People and pilots:</strong> the second half of the guide has paths for designers, frontend developers, DesignOps, design-system leads, and product/engineering pilots, including how Penpot MCP can help with post-import cleanup.</li>
+</ul>
+
+<p>The guide also covers running Figma and Penpot in parallel for a while. The exporter is for one-off migration, not continuous sync.</p>
+
+<h2 id="discuss-the-guide">Questions and discussion</h2>
+<p>If you want to ask about a migration, or share how yours is going, use the Community post <a href="https://community.penpot.app/t/the-enterprise-guide-to-migrating-design-systems-to-penpot/10768" target="_blank" rel="noopener">The Enterprise Guide to Migrating Design Systems to Penpot</a>.</p>
diff --git a/docs/user-guide/first-steps/troubleshooting-webgl.njk b/docs/user-guide/first-steps/troubleshooting-webgl.njk
index 7188090ac8..c3893f90e8 100644
--- a/docs/user-guide/first-steps/troubleshooting-webgl.njk
+++ b/docs/user-guide/first-steps/troubleshooting-webgl.njk
@@ -1,6 +1,6 @@
 ---
 title: Troubleshooting WebGL
-order: 5
+order: 7
 desc: Diagnose and fix common WebGL issues in Penpot, enable WebGL rendering (Beta), and troubleshoot browser, GPU, and system checks.
 ---