diff --git a/CHANGES.md b/CHANGES.md
index 001577184c..cddaeec72c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -37,6 +37,7 @@
- [DESIGN TOKENS] Integration with components.
- [DESIGN TOKENS] Import and export tokens from a JSON file.
- [DESIGN TOKENS] Apply Themes and Sets at document level.
+- Add more descriptive tooltip to boards for first time users [Taiga #9426](https://tree.taiga.io/project/penpot/us/9426)
### :bug: Bugs fixed
@@ -51,6 +52,8 @@
- Fix problem with default shadows value in plugins [Plugins #191](https://github.com/penpot/penpot-plugins/issues/191)
- Fix problem with constraints when creating group [Taiga #10455](https://tree.taiga.io/project/penpot/issue/10455)
- Fix opening pen with shortcut multiple times breaks toolbar [Taiga #10566](https://tree.taiga.io/project/penpot/issue/10566)
+- Fix actions when workspace is visited first time [Taiga #10548](https://tree.taiga.io/project/penpot/issue/10548)
+- Chat icon overlaps "Show" button in carrousel section [Taiga #10542](https://tree.taiga.io/project/penpot/issue/10542)
## 2.5.4
diff --git a/common/src/app/common/data.cljc b/common/src/app/common/data.cljc
index 5006d0c47d..80268f617e 100644
--- a/common/src/app/common/data.cljc
+++ b/common/src/app/common/data.cljc
@@ -82,15 +82,22 @@
"Assoc a k v pair, in the order position just before the other key."
[o ks k v before-k]
(let [f (fn [o']
- (cond-> (reduce
- (fn [acc [k' v']]
- (cond
- (and before-k (= k' before-k)) (assoc acc k v k' v')
- (= k k') acc
- :else (assoc acc k' v')))
- (ordered-map)
- o')
- (not before-k) (assoc k v)))]
+ (let [found (volatile! false)
+ result (reduce
+ (fn [acc [k' v']]
+ (cond
+ (and before-k (= k' before-k))
+ (do
+ (vreset! found true)
+ (assoc acc k v k' v'))
+
+ (= k k') acc
+ :else (assoc acc k' v')))
+ (ordered-map)
+ o')]
+ (if (or (not before-k) (not @found))
+ (assoc result k v)
+ result)))]
(if (seq ks)
(oupdate-in o ks f)
(f o))))
diff --git a/common/src/app/common/logic/tokens.cljc b/common/src/app/common/logic/tokens.cljc
index 3e7ca4a08d..39f2374bf3 100644
--- a/common/src/app/common/logic/tokens.cljc
+++ b/common/src/app/common/logic/tokens.cljc
@@ -65,13 +65,7 @@
to (nth tree to-index)
before (case position
:top to
- :bot (let [v (nth tree (inc to-index) nil)]
- ;; if the next index is a group, we need to set it as
- ;; nil because if we set a path on different subpath,
- ;; the move algorightm will simply remove the set
- (if (:group? v)
- nil
- v))
+ :bot (nth tree (inc to-index) nil)
:center nil)
prev-before (if (:group? from)
@@ -87,6 +81,7 @@
(= :bot position)
(:group? to)
(not (get collapsed-paths (:path to)))))
+
from-path (:path from)
to-parent-path (if drop-as-direct-group-child?
(:path to)
diff --git a/common/src/app/common/types/token.cljc b/common/src/app/common/types/token.cljc
index bba70ba5ac..12f5c5d3e8 100644
--- a/common/src/app/common/types/token.cljc
+++ b/common/src/app/common/types/token.cljc
@@ -60,7 +60,7 @@
(token-types t))
(def token-name-ref
- [:and :string [:re #"^(?!\$)([a-zA-Z0-9-$]+\.?)*(?Podman instead of Docker.
* Try the under development Penpot Desktop app.
* Try a simple Kubernetes Deployment option penpot-kubernetes.
+* Penpot is available in the catalog of apps installable on YunoHost instances.
* Or try a fully manual installation if you have a really specific use case.. For help, you can look at the [Architecture][1] section and the Docker configuration files.
[1]: /technical-guide/developer/architecture
diff --git a/docs/user-guide/components/index.njk b/docs/user-guide/components/index.njk
index bac8b0ed97..44893da64d 100644
--- a/docs/user-guide/components/index.njk
+++ b/docs/user-guide/components/index.njk
@@ -1,5 +1,5 @@
---
-title: 10· Components
+title: 11· Components
---
Design tokens are the building blocks of all UI elements, the same tokens are used in designs, tools, and code. They include colors, typography, spacing, shadows, and any visual element that affects an object: all these properties collectively make up a design system or a visual inheritance.
+
+
+
+
+
+
Why Design Tokens?
+
Design tokens act as a single source of truth, a common language that can be translated and used in any other tool or framework capable of reading the token format. With Design Tokens, you can create, manage, and synchronize these visual elements within Penpot and across other design tools, keeping your designs consistent and making your workflows faster and easier to maintain.
+
You can also integrate Design Tokens with other core Penpot features, such as components and grid & flex layout, plus plugins will be able to access the tokens API (coming soon) making it even more powerful.
+
+
W3C DTCG Format
+
Penpot Design Tokens adhere to the Design Tokens Format Module and its definitions, a draft by the W3C DTCG. Penpot ensures compatibility across various disciplines, tools, and technologies by following the most standardized approach available for design tokens.
+
Tokens can be exported from Penpot or integrated into other tools directly, without conversion. Additionally, the knowledge gained from using Design Tokens in Penpot remains valuable, regardless of whether you continue using Penpot or a different tool or technology.
+
+
Using Tokens
+
Creating a token
+
You can create reusable and semantic tokens to be referenced in your designs at the Tokens panel. In this panel, you’ll find all the available types of tokens in Penpot arranged alphabetically, with existing tokens being shown at the top of the list.
+
+
+
+
To create a token, click on the + next to the type of token you want to create. You’ll then be prompted to define the token’s:
+
+
Name: The name should be specific to that token, as it is not possible to create multiple tokens with the same name; for example, dimension.small.
+
Value: The value you wish to attribute to the token; depending on the token type, values may be numerical or color spaces (Hex, RGB, RGBA, ARGB, HSL or HSLA).
+
Description: You can also choose to add a description to your token.
+
+
Once you have named the token and assigned it a value, click Save to store the token and start referencing it.
+
+
Referencing tokens into values (aliases)
+
When assigning a value to a token, you can reference existing tokens - these are called aliases at the DTCG Glossary.
+
+
+
+
For example, if you have created a dimension.small token, with a value of 64, you could create a spacing.small token with a value of {dimension.small}. The spacing.small token would thereby have a value of 64.
+
When referencing an existing token in the value of a new token, you must reference it within {}.
+
If the value of the referenced token changes, this will also change the value of the tokens where it is referenced.
+
References to existing tokens are case sensitive.
+
+
Using equations
+
Token types with numerical values also accept mathematical equations. If, for example, you create a spacing.small token with the value of 2, and you then want to create a spacing.medium token that is twice as large, you could do so by writing {spacing.small} * 2 in its value. As a result, spacing.medium would have a value of 4.
+
Say you have a spacing.scale token with a value of 2. You could also use this token in the equation to calculate the value of spacing.medium by writing {spacing.small} * {spacing.scale} in its value.
+
+
+
+
Mathematical equations can be performed using:
+
+
+ for addition.
+
- for subtraction.
+
* for multiplication.
+
/ for division.
+
+
+
Editing a token
+
Tokens can be edited by right-clicking the token and selecting Edit token. This will allow you to change the tokens name, value and description. Once the changes are made, click Save.
+
+
+
+
Renaming tokens will break any references to their old names. If a token is already applied somewhere, you'll need to reapply it after renaming. This can lead to extra work, so rename with caution. We're actively working on a solution to handle this automatically, ensuring renamed tokens stay linked to their properties without additional effort.
+
+
Duplicating a token
+
Tokens can be duplicated by right-clicking the token you wish to duplicate and selecting Duplicate token. This will create a copy of the selected token within the same set, with -copy added to its name.
+
+
Deleting a token
+
Tokens can be deleted by right-clicking the token you wish to delete and selecting Delete token.
+
+
Available tokens
+
You can apply tokens to the properties of any object. There are two ways to apply tokens to a selection:
+
+
Right-click on tokens to specify a particular property that you want to apply.
+
Left-click on tokens to apply the assumtion. Assumptions can vary across different token types. For example, for the color type the assumtion is that you want to apply the token as a fill.
+
+
Tokens can be applied to multiple selected elements, but not to groups.
+
+
Border radius
+
Border radius tokens allow you to define specific values for border-radius properties, offering flexibility in how you style the corners of elements.
+
+
+
+
Applying Border Radius Tokens
+
To apply the border radius token to an element, select the element and choose the token from the list:
+
+
Clicking on a border radius token will apply it to all corners of the element simultaneously.
+
Right-clicking on a border radius token, allows you to select which corners the token should be applied to.
+
+
+
Color
+
Color tokens support color properties that can be applied to many different design elements, including boards, groups, shapes, and text.
+
+
+
+
You can define a color token’s value using:
+
+
The color picker, select the color switch to the left of the token Value input to open the color picker; here you’ll also be able to define the colors opacity.
+
+ The color Spaces, define your color token in the following color spaces:
+
+
Hex: #ff0000
+
RGB: rgb(255, 0, 0)
+
RGBA: rgba(255, 0, 0, 1)
+
ARGB: #80FFFF00 (also known as Hex8)
+
HSL: hsl(120, 50%, 50%)
+
HSLA: hsla(120, 50%, 50%, 1)
+
+
+
+
Applying Color Tokens
+
Color tokens can define a design element's fill or stroke color. To apply the color token to an element, select the element and choose the token from the list:
+
+
Clicking on a color token will apply it to the element as a fill by default.
+
Right-clicking on a color token, allows you to select whether it should be applied as a fill or stroke color.
+
+
+
+
+
+
Dimensions
+
Dimension tokens allow you to define an amount of distance that can be used to set the size, space, radius or position of specific elements within a design.
+
Applying Dimension Tokens
+
To apply a dimension token, select the element and choose the token from the list:
+
+
Clicking on a dimension token will apply it to the element’s width and height by default.
+
+ Right-clicking on a dimension token, allows you to select where you want the token to be used in the element. You can use it for:
+
+
Sizing
+
Spacing
+
Border radius
+
Stroke width
+
X position
+
Y position
+
+
+
+
Sizing (dimension)
+
The sizing property of the dimension token defines the height or width of design elements like boards, shapes, and groups.
+
+
+
+
When using dimension tokens for sizing, you can apply the token to an element's size by selecting:
+
+
All to apply the same size value to both the width and height of an element;
+
Width to apply the token value to the horizontal size of an element;
+
Height to apply the token value to the vertical size of an element;
+
+
If you are working with flex-layout boards, you can also apply the token to an element’s size by selecting:
+
+
All to apply the same size value to both the Min width and Min height of an element;
+
Min width to define the smallest allowed horizontal size of an element but allow a larger size;
+
Min height to define the smallest allowed vertical size of an element but allow a large size;
+
All to apply the same size value to both the Max width and Max height of an element;
+
Max width to define the largest allowed horizontal size of an element but allow a smaller size;
+
Max height to define the largest allowed vertical size of an element but allow a smaller size.
+
+
If you apply the min/max height/width properties to a board before flex-layout is applied to it, you may have to remove and re-apply the token for it to take effect.
+
+
Spacing (dimension)
+
The spacing property of the dimension token defines the distance between elements and it must be applied to flex-layout boards.
+
+
+
+
If you apply the token to a board before flex-layout is applied to it, you may have to remove and re-apply the token for it to take effect.
+
When using dimension tokens for spacing, you can apply the token to an element's padding and gap. Specifically, you can select:
+
+
+ Gaps
+
+
All to apply the gap to all sides of the element;
+
Column Gap to add a gap between child elements within a parent element;
+
Row Gap to add vertical space between rows on flex-layout board elements set to wrap.
+
+
+
+ Paddings & Margins:
+
+
Horizontal applies to the left and right of the container;
+
Vertical and to the top and bottom sides of the container;
+
Top, right, bottom or left apply space to individual sides of the element.
+
+
+
+
+
Border radius (dimension)
+
The border radius property of the dimension token defines the roundness of the corner of elements like boards, shapes, and groups.
+
You can apply the border radius property by right-clicking on the dimension token and selecting:
+
+
All to apply the radius to all sides of the selected element;
+
Top Left to apply the radius to the top-left corner of the selected element;
+
Top Right to apply the radius to the top-right corner of the selected element;
+
Bottom Right to apply the radius to the bottom-right corner of the selected element;
+
Bottom Left to apply the radius to the bottom-left corner of the selected element.
+
+
+
Stroke width (dimension)
+
The stroke width property specifies the thickness of a border for elements that already have a stroke property applied.
+
If you apply the border property to an element before it has a stroke applied to it, you may have to remove and re-apply the token for it to take effect.
+
+
X Position (dimension)
+
The X property specifies the position of the element on the X axis of the canvas.
+
+
Y Position (dimension)
+
The Y property specifies the position of the element on the Y axis of the canvas.
+
+
Opacity
+
Opacity tokens allow you to define the opacity of a layer, ranging from fully opaque to fully transparent.
+
Opacity tokens can be applied to any design element that supports transparency. You can use any decimal value between 0 and 1 to set varying levels of opacity or you can use any value between 0 and 100 with `%` sign at the end of the value. For example, you can use 45% which would resolve to .45.
+
Applying Opacity Tokens
+
To apply the opacity token to an element, select the element and click on the desired token.
+
+
Rotation
+
Rotation tokens are used to define and standardize rotational values within a design system. These tokens represent rotation angles, typically measured in degrees, and can be applied to elements such as icons or images, to ensure consistent rotation throughout a design.
+
Applying Rotation Tokens
+
To apply a rotation token, select the element and choose the token from the list.
+
+
Sizing
+
Sizing tokens can define various size-related design properties, namely the height and width of design elements.The sizing token supports numeric values, which include negative values.
+
+
+
+
Applying Sizing Tokens
+
To apply the sizing token to an element, select the element and choose the token from the list:
+
+
Clicking on a sizing token will apply it to all sides of the element by default;
+
+ Right-clicking on a sizing token, allows you to specify which side of the element the token should apply to:
+
+
All applies the same size value to both the width and height of an element;
+
Width applies the token to the horizontal size of an element;
+
Height applies the token to the vertical size of an element;
+
+
+
+
If you are working with flex-layout boards, you can also apply the token to an element’s size by selecting:
+
+
Min width defines the smallest allowed horizontal size of an element, allowing larger sizes;
+
Min height defines the smallest allowed vertical size of an element, allowing larger sizes;
+
Max width defines the largest allowed horizontal size of an element, allowing smaller sizes;
+
Max height defines the largest allowed vertical size of an element, allowing smaller sizes.
+
+
+
Spacing
+
The spacing token defines the distance between design elements and supports numeric values, which include negative values. Spacing tokens must be applied to Flex Layout boards.
+
If you apply the token to a board before flex-layout is applied to it, you may have to remove and re-apply the token for it to take effect.
+
Applying Spacing Tokens
+
To apply the spacing token to an element, select the element and choose the token from the list:
+
+
Clicking on a spacing token will apply it to all gaps (row and column).
+
Right-clicking on a spacing token, allows you to specify which property of the element the token should apply to. In this menu, properties are divided by blocks. In each property you can choose to apply to ‘All’ sides in a specific property, or choose to apply them to individual sides:
+
Gaps: Applies spaces between child elements within a parent container (both column and row gaps). This only works on flex and grid layouts.
+
+ Paddings & Margins:
+
+
Horizontal applies to the left and right of the container;
+
Vertical and to the top and bottom sides of the container;
+
Top, right, bottom or left apply space to individual sides of the element.
+
+
+
+
+
Stroke Width
+
The stroke width token, also known as the border width token, defines the thickness of a stroke around a design element. It can be applied to boards, groups, rectangles and text elements.
+
+
+
Token Sets
+
Token Sets allow you to split your tokens up into multiple files in order to create organized groups or collections of tokens. It enables efficient management and customization within design files. For example you can group all your color sets, sizing sets or platform-specific sets. The purpose of tokens sets is to organize them in a way that matches your needs.
+
+
+
+
When you create your first token, a default set is created. You can rename, group or move it later. As you create new token sets, they’ll be added sequentially after existing ones. You can reorder token sets by dragging and dropping them.
+
The order of the token sets is essential! If you have tokens with the same name (and different values) across multiple sets, the tokens that are in the set that appears last in the list will override the previous ones - similar to how Cascading Style Sheets work.
+
When creating a token set, it’s recommended that you assign it a unique name to ensure clarity. Token set names are not included in individual token names by default so it is possible to have tokens with the same name belonging to different token sets.
+
Token sets can be enabled or disabled. If a set is disabled, its tokens will be excluded from the token resolution process.
+
+
Creating Token Sets
+
There are two ways to create a token set at the Tokens tab:
+
+
Click on the + next to Sets;
+
Click on the Create one button.
+
+
You’ll then need to name your token set. Set names should be specific, as it is not possible to create multiple token sets with the same name.
+
When a token set is selected, the tokens within the selected set are displayed on the panel below.
+
+
+
Deleting and Renaming a Token Set
+
Token sets can be renamed or deleted by right-clicking on the token set and:
+
+
Selecting Rename, entering a new name, and hitting Enter.
+
Selecting Delete.
+
+
+
+
+
+
+
Once you have created a token set, you can start creating tokens within that token set. To do so, simply select the token set and create a new token.
+
If a token with the same name already exists in another set, a new token can still be created in the current set.
+
+
Creating Token Groups
+
You can create a token set group by simply naming your token sets to have a folder path. For example, you can create a Light group with a Global set and a Colors set using: Light/Global, Light/Colors.
+
+
+
+
+
Token Themes
+
Themes are a way to configure your sets to be applied in a specific context, such as a brand, a mode or a touchpoint. Themes enable switching between different styles dynamically by applying different token values depending on the selected theme.
+
Themes are multidimensional, this means that you can have more than one theme active at the same time, combining the values of the active themes.
+
+
Theme groups
+
Using Theme Groups you can categorise your themes into groups. This will allow you to generate a number of combinations involving color themes, brands, platforms, density, and more. Using groups will reduce the need to create an excessive number of individual themes with every combination.
+
+
+
+
For example:
+
Group - theme options
+
+
Mode - Light, Dark
+
Brand - RedPlanet, YellowCab
+
Contrast - High, Low, Dim
+
Platform - Web, App
+
+
When you have various themes inside a group, only one of the themes in this group can be active.
+
Having your sets clubbed under groups makes it more accessible to switch from a matrix of themes.
+
+
Creating Token Themes
+
To create a new theme, click the Create one button in the Themes section. You can create a group (this is optional) or add an existing one, and then you then need to assign a name to your theme and click on Save Theme.
+
Your new theme will now appear on the Theme lists. You’ll need to enable the tokens sets that you want to include in the theme, clicking on the button “no active sets”. Here you can also activate and deactivate it, as well as delete the theme.
+
+
+
+
+
Editing Themes
+
In the Themes section, you can find a dropdown to activate and deactivate themes. If there are no active themes, the dropdown shows a message of: “no theme active”.
+
+
+
+
To edit existing themes, you can click on the Edit button next to the dropdown in the Themes section or open the dropdown and select Edit themes:
+
+
+
+
This action will open a modal window where you can activate or deactivate themes, as well as select which Token sets should be part of the theme.
+
+
You can enable and disable the themes.
+
Configure the token sets you want to be included in the theme.
+
Deletes the theme.
+
Creates a new theme.
+
+
+
Grouping Themes
+
You can categorize your themes into groups. This allows you to generate a matrix of potential combinations involving color themes, brands, modes, and more.
+
+
+
+
+
+
Select a particular group.
+
Select the theme from the group.
+
You can define what token sets should be used as part of this theme option.
+
Click save theme to see the changes.
+
Cancel to clear the edits.
+
Delete.
+
+
+
Importing and Exporting Tokens
+
You can export Tokens from Penpot and import them from your computer to a Penpot file. Tokens can be imported from the Tools option at the bottom of the Tokens tab.
+
The Import functionality allows you to upload and replace the global token set using a single file, while the Export functionality lets you download the current global token set using a single file to your system.
+
These features support JSON files formatted according to specific guidelines and preserve the ability to undo changes if needed.
+
+
+
+
+
Import: At the Tools option, select Import, then select your tokens.json file.
+
Export: At the Tools option, select Export. This will export all the tokens, including token sets and themes.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+