📚 Add migration guide page (#11454)

Point First Steps at the enterprise migration PDF with a short
summary, without duplicating the Community post.

.opencode/skills/update-changelog/SKILL.md

@@ -212,6 +212,37 @@ superseded it:
 
 Replace the reference in the changelog entry with the correct merged PR number.
 
+### 5b. Security advisory (GHSA) entries
+
+Security advisories fixed in a release are documented in the changelog even
+though they are **neither milestone issues nor PRs**. The GHSA ID and its
+description are supplied by the user or the release notes — they never come
+from the milestone fetch in step 2.
+
+**Format** (matches the existing precedent in `CHANGES.md`, e.g. the
+`create-font-variant` arbitrary file read advisory):
+
+```markdown
+- Fix <user-facing description> (https://github.com/penpot/penpot/security/advisories/GHSA-XXXX-XXXX-XXXX)
+```
+
+Rules:
+- Place the entry under `### :bug: Bugs fixed`, with **no issue or PR link** —
+  only the advisory URL.
+- The advisory may be **draft/unpublished** at changelog time (the URL 404s
+  publicly). Do **not** web-fetch or verify the URL, and do **not** drop the
+  entry because of that. Rely on the GHSA ID provided by the user.
+- Derive the description from the supplied advisory title, imperative mood and
+  user-facing (e.g. `Fix command injection in SVG exporter via legacy fill-color`).
+- These entries are **invisible to the automation**: they are not returned by
+  `gh.py issues`, not matched by `--compare` (step 3), not part of the PR
+  cross-reference (step 10), and not scanned by the anomaly-report regexes
+  (step 11, which only match `issues/` and `pull/` links). Add them manually.
+- During pre-flight checks (step 6a) apply only the **backport/duplicate**
+  check: if the same GHSA already appears in an earlier version section, remove
+  it from the current section. Their absence from milestone cross-references
+  is expected, not an anomaly.
+
 ### 6. Read the current CHANGES.md
 
 Read the top of `CHANGES.md` to understand the existing format and find the
@@ -400,6 +431,8 @@ if closed:
 - ✅ Every merged milestone PR is either in the changelog or excluded by label
 - ✅ PR and issue counts are internally consistent
 - ✅ No false-positive PR-to-issue associations
+- ✅ Advisory (GHSA) entries are not milestone PRs — their absence from the
+  cross-reference is intentional (see step 5b)
 
 ## Version section template
 
@@ -410,8 +443,12 @@ if closed:
 
 - <fix description> [#<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>) (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))
 - <fix description> (by @contributor) [#<ISSUE>](https://github.com/penpot/penpot/issues/<ISSUE>) (PR: [#<PR>](https://github.com/penpot/penpot/pull/<PR>))
+- <fix description> (https://github.com/penpot/penpot/security/advisories/GHSA-XXXX-XXXX-XXXX)
 ```
 
+Advisory (GHSA) entries have no issue or PR link — just the advisory URL. See
+step 5b.
+
 ### 11. Generate anomaly report and save to CHANGES-ISSUES.md
 
 After all edits and cross-referencing are complete, generate a structured
@@ -732,6 +769,14 @@ self-contained and clickable in any Markdown viewer.
   Taiga description text or by searching GitHub PRs that reference the Taiga
   URL. Replace the Taiga reference with the GitHub issue link and add the PR
   reference if applicable.
+- **Security advisory (GHSA) entries.** Advisories fixed in the release are
+  listed under `### :bug: Bugs fixed` with the advisory URL and **no issue or
+  PR link**, even though they are not in the milestone. The GHSA ID and
+  description come from the user — do **not** fetch or verify the URL, and do
+  not drop a draft (unpublished) advisory. Precedent:
+  `- Fix arbitrary file read security issue on create-font-variant rpc method
+  (https://github.com/penpot/penpot/security/advisories/GHSA-xp3f-g8rq-9px2)`.
+  See step 5b.
 - **Re-fetch before editing.** Milestones can change — always re-fetch issues
   before making edits, don't rely on cached data.
 - **Use `scripts/gh.py`.** Prefer the helper script over raw `gh api` calls for

CHANGES.md

@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## 2.17.2
+
+### :bug: Bugs fixed
+
+- Fix linear gradients in SVG text exports being emitted as radial gradients [#5972](https://github.com/penpot/penpot/issues/5972) (PR: [#11272](https://github.com/penpot/penpot/pull/11272))
+- Fix typography token becoming detached when editing text content [#11362](https://github.com/penpot/penpot/issues/11362) (PR: [#11366](https://github.com/penpot/penpot/pull/11366))
+- Fix command injection in SVG exporter via legacy fill-color (https://github.com/penpot/penpot/security/advisories/GHSA-4f36-m4hj-cv86)
+
 ## 2.17.1
 
 ### :bug: Bugs fixed

common/src/app/common/types/text.cljc

@@ -9,6 +9,7 @@
     [app.common.data :as d]
     [app.common.data.macros :as dm]
     [app.common.flags :as flags]
+    [app.common.math :as mth]
     [app.common.types.color :as clr]
     [app.common.types.fills :as types.fills]
     [clojure.set :as set]
@@ -217,7 +218,10 @@
       attributes or other things that may be attached).
     - Consider nil values, empty strings or empty lists all equal.
     - Normalize numeric values (legacy) into strings.
-    - No value is equal than the default value."
+    - No value is equal than the default value.
+    - Numeric attrs (e.g. line-height) compare with float tolerance so
+      editor/WASM round-trips like \"1.3333333333333333\" vs \"1.33333\"
+      do not count as a real style change (avoids detaching tokens)."
   [key value1 value2]
   (when (text-node-attr? key)
     (let [default-value (get default-text-attrs key)
@@ -229,7 +233,16 @@
                                 $)))
           value1' (normalize-value value1)
           value2' (normalize-value value2)]
-      (not= value1' value2'))))
+      (cond
+        (= value1' value2')
+        false
+
+        :else
+        (let [n1 (when (string? value1') (d/parse-double value1'))
+              n2 (when (string? value2') (d/parse-double value2'))]
+          (if (and (some? n1) (some? n2))
+            (not (mth/close? n1 n2))
+            true))))))
 
 (defn- compare-text-content
   "Given two content text structures, conformed by maps and vectors,

common/test/common_tests/types/text_test.cljc

@@ -78,6 +78,14 @@
 (def content-changed-line-height
   (assoc-in content-base [:children 0 :children 0 :line-height] "1.5"))
 
+;; Token/WASM may store full float precision; editor round-trips often
+;; truncate (e.g. CSS / f32). These must compare as equal.
+(def content-line-height-full-precision
+  (assoc-in content-base [:children 0 :children 0 :line-height] "1.3333333333333333"))
+
+(def content-line-height-truncated
+  (assoc-in content-base [:children 0 :children 0 :line-height] "1.33333"))
+
 (def content-redundant-span-line-height
   (assoc-in content-base [:children 0 :children 0 :children 0 :line-height] "1.5"))
 
@@ -208,6 +216,8 @@
         ;; Other text-node-attr categories
         attrs-font-family          (cttx/get-diff-attrs content-base content-changed-font-family)
         attrs-line-height          (cttx/get-diff-attrs content-base content-changed-line-height)
+        attrs-line-height-precision (cttx/get-diff-attrs content-line-height-full-precision
+                                                         content-line-height-truncated)
         attrs-span-line-height     (cttx/get-diff-attrs content-base content-redundant-span-line-height)
         attrs-roundtrip-line-height (cttx/get-diff-attrs content-token-like-line-height
                                                          content-after-editor-roundtrip)
@@ -242,6 +252,7 @@
     ;; Each text-node-attr category reports correct attr key
     (t/is (= #{:font-family} attrs-font-family))
     (t/is (= #{:line-height} attrs-line-height))
+    (t/is (= #{} attrs-line-height-precision))
     (t/is (= #{} attrs-span-line-height))
     (t/is (= #{} attrs-roundtrip-line-height))
     (t/is (= #{} attrs-nil-typography-refs))

docker/images/docker-compose.yaml

@@ -78,7 +78,7 @@ services:
   #     - "443:443"
 
   penpot-frontend:
-    image: "penpotapp/frontend:${PENPOT_VERSION:-2.16}"
+    image: "penpotapp/frontend:${PENPOT_VERSION:-2.17}"
     restart: always
     ports:
       - 9001:8080
@@ -111,7 +111,7 @@ services:
       # PENPOT_DISABLE_IPV6_LISTEN: "true"
 
   penpot-backend:
-    image: "penpotapp/backend:${PENPOT_VERSION:-2.16}"
+    image: "penpotapp/backend:${PENPOT_VERSION:-2.17}"
     restart: always
 
     volumes:
@@ -180,13 +180,13 @@ services:
       PENPOT_SMTP_SSL: "false"
 
   penpot-mcp:
-    image: "penpotapp/mcp:${PENPOT_VERSION:-2.16}"
+    image: "penpotapp/mcp:${PENPOT_VERSION:-2.17}"
     restart: always
     networks:
       - penpot
 
   penpot-exporter:
-    image: "penpotapp/exporter:${PENPOT_VERSION:-2.16}"
+    image: "penpotapp/exporter:${PENPOT_VERSION:-2.17}"
     restart: always
 
     depends_on:

docs/mcp/index.md

@@ -26,7 +26,7 @@ Penpot MCP enables **multi-directional workflows** between design and code. Beca
   title="Quick demo: Penpot MCP server in action"
   width="100%"
   height="480"
-  src="https://www.youtube.com/embed/CfvcgMQEmLk?rel=0"
+  src="https://www.youtube.com/embed/7V01SKVG6PQ?rel=0"
   loading="lazy"
   allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
   referrerpolicy="strict-origin-when-cross-origin"

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>

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>

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.
 ---