📚 Update user guide for 2.17 release (#10518)

docs/user-guide/design-systems/design-tokens.njk

@@ -31,6 +31,7 @@ desc: Learn how to create, manage and apply Penpot Design Tokens using W3C DTCG
     <li><strong>Description:</strong> You can also choose to add a description to your token.</li>
 </ul>
 <p>Once you have named the token and assigned it a value, click <strong>Save</strong> to store the token and start referencing it.</p>
+<p>Token value fields suggest existing tokens as you type. Pick a suggestion to insert a reference, or keep typing a custom value.</p>
 
 <h2 id="design-tokens-aliases">Referencing tokens into values (aliases)</h2>
 <p>When assigning a value to a token, you can reference existing tokens - these are called aliases at the <a href="https://www.designtokens.org/glossary/" target="_blank">DTCG Glossary</a>.</p>
@@ -111,7 +112,7 @@ desc: Learn how to create, manage and apply Penpot Design Tokens using W3C DTCG
 <p>This ensures the spacing is at least 8, even if the base token is smaller.</p>
 
 <h2 id="design-tokens-edit">Editing a token</h2>
-<p>Tokens can be edited by right-clicking the token and selecting <strong>Edit token</strong>. This will allow you to change the tokens name, value and description. Once the changes are made, click <strong>Save</strong>.</p>
+<p>Tokens can be edited by right-clicking the token and selecting <strong>Edit token</strong>. This will allow you to change the tokens name, value and description. Value fields offer the same token suggestions as when creating a token. Once the changes are made, click <strong>Save</strong>.</p>
 <figure>
   <img src="/img/design-tokens/05-tokens-edit.webp" alt="Tokens edit" />
 </figure>
@@ -141,12 +142,15 @@ desc: Learn how to create, manage and apply Penpot Design Tokens using W3C DTCG
   <li><strong>Size and position:</strong> width, height, x, y</li>
   <li><strong>Rotation and border radius</strong></li>
   <li><strong>Layout spacing:</strong> gaps, paddings, margins, min and max widths and heights</li>
-  <li><strong>Typography:</strong> letter spacing and line height</li>
+  <li><strong>Typography:</strong> letter spacing, line height, and composite typography tokens on text layers</li>
   <li><strong>Stroke width</strong></li>
   <li><strong>Shadows:</strong> x, y, blur, spread</li>
   <li><strong>Blur</strong> amount</li>
 </ul>
 <p>Click the token control on a field to open a list of applicable tokens from your active sets and themes. Select a token to apply it; a token pill shows the bound token. Use the pill menu to detach the token when you need a custom value again.</p>
+<p>On text layers, the Typography section shows a composite typography token row when one is applied. Open the token list from the section header to pick or switch tokens without going to the Tokens panel. Hover a token name to see its resolved values (font family, size, weight, and the rest).</p>
+<p>When you multi-select text layers that share typography tokens, the Typography section shows the applied token. If the selection mixes different tokens, detach them from there or apply a new one to the whole selection.</p>
+<p>Typography options in the dropdown list show resolved values on hover, so you can tell styles apart before applying them.</p>
 <p class="advice">When a numeric field has a token applied, drag-to-change is disabled for that field. Edit the token or detach it first.</p>
 <figure>
   <img src="/img/design-tokens/41-design-tab-token-dropdown.webp" alt="Token list on a numeric field in the Design sidebar">
@@ -528,6 +532,7 @@ ExtraBold Italic
 
 <h4 id="apply-typography-token">Apply a Typography token</h4>
 <p>A <strong>Typography composite token</strong> can be applied to a full text layer to set all typography properties at once. This lets you manage complete text styles using a single token instead of combining multiple individual ones.</p>
+<p>Apply it from the Tokens panel, or from the Typography section in the Design sidebar when a text layer is selected.</p>
 <p>When applying a Typography composite token to a layer, any previously applied <em>Typography composite token</em> or <em>style</em> will be detached. The same happens in reverse. Only one of them can be active at a time.</p>
 
 <h3 id="design-tokens-shadow">Shadow</h3>

docs/user-guide/designing/color-stroke.njk

@@ -57,7 +57,7 @@ desc: Style your designs with Penpot's options! Learn about color fills, gradien
   <li><strong>Color type</strong> - Solid, gradient, or image.</li>
   <li><strong>Sliders</strong> - Easily manage settings like brightness, saturation or opacity.</li>
   <li><strong>Values</strong> - Set precise color values. Available formats depend on the selected color model.</li>
-  <li><strong>Libraries</strong> - Switch between recent colors and libraries.</li>
+  <li><strong>Libraries</strong> - Switch between recent colors and libraries. Color tokens in a library can be shown as a grid or a list. Use the list view when you need to scan names or work with long token lists.</li>
   <li><strong>Color palette</strong> - A quick launcher of the palette with the selected library.</li>
 </ol>
 
@@ -116,6 +116,7 @@ desc: Style your designs with Penpot's options! Learn about color fills, gradien
   <li><strong>Style</strong> - solid, dotted, dashed, mixed</li>
   <li><strong>Visibility</strong> - show or hide the stroke without removing it</li>
 </ul>
+<p>When the style is set to <strong>dashed</strong>, two extra fields appear to control the <strong>dash</strong> and <strong>gap</strong> length in pixels.</p>
 <p>You can add as many strokes as you want to the same layer.</p>
 <figure>
   <img alt="Multiple strokes" src="/img/styling/stroke-multiple.webp"/>

docs/user-guide/designing/layers.njk

@@ -461,8 +461,18 @@ You can choose to edit individual nodes or create new ones. Press <kbd>Esc</kbd>
 </ul>
 
 <h3 id="blur">Blur</h3>
-<p>You can set a blur for each and every layer at Penpot.</p>
-<p><strong></strong>Applying a lot and/or big values for blurs can affect Penpot’s performance as it requires a lot from the browser.</p>
+<p>You can add blur effects to layers from the Design sidebar. Penpot supports two types:</p>
+<ul>
+  <li><strong>Layer blur</strong> blurs the layer content itself.</li>
+  <li><strong>Background blur</strong> blurs whatever sits behind the layer. Use it for frosted-glass or depth effects. Background blur requires the <a href="/user-guide/first-steps/troubleshooting-webgl/">WebGL renderer</a> to be enabled.</li>
+</ul>
+<p class="advice">Background blur is not included in exported files yet (PNG, SVG, PDF, and others). The exporter still uses the legacy SVG renderer, so the effect only shows in the workspace and View mode. Export support is a current priority and will land in an upcoming release.</p>
+<figure>
+  <img src="/img/styling/background-blur.webp" alt="Colorful shapes behind a frosted panel with background blur applied" />
+  <figcaption>Background blur affects the layers behind the shape, not the shape itself.</figcaption>
+</figure>
+<p>Click <strong>+</strong> in the Blur section to add an effect. You can apply both types on the same layer. Use the type selector to switch between them, the eye icon to show or hide an effect without removing it, and the value field to set the blur amount.</p>
+<p class="advice">Applying many or large blur values can affect Penpot’s performance, as it requires a lot from the browser.</p>
 <figure>
   <video title="Apply blur to a layer" muted="" playsinline="" controls="" width="100%" poster="/img/styling/blur.webp" height="auto">
     <source src="/img/styling/blur.mp4" type="video/mp4">

docs/user-guide/prototyping-testing/prototyping.njk

@@ -42,6 +42,10 @@ desc: This Penpot user guide explains how to prototype interactions, connect boa
   <strong>10)</strong> Flow indicator and launcher
 </p>
 
+<h2 id="interaction-settings">Interaction settings</h2>
+<p>When a layer with interactions is selected, the Prototype sidebar lists every connection attached to it. From there you can change the trigger, action, destination, animation, and other options.</p>
+<p>Destination dropdowns include a search field. Type to filter boards on the current page when your file has many screens.</p>
+
 <h2 id="interaction-triggers">Interaction triggers</h2>
 <figure>
   <img src="/img/prototype/prototype-trigger.webp" alt="Prototype trigger options">