Speed your workflow with the reusable power of components.
A component is an object or group of objects that can be reused multiple times across files. This can help you maintain consistency across a group of designs.
-A component has two parts:
+A component consists of two elements:
All component copies used in a file are linked in a way that updates made to the Main component can reflect in their component copies. You can override properties for component copies, so that you can manage singularities while maintaining properties in common.
-You can duplicate a component the same way you can duplicate any other layer. When duplicating a component, you are creating a component copy that will be linked to its main component.
-You can duplicate a component as a new main component from the assets sidebar. Just select the component at the library, open the menu with right click and select the option "Duplicate main".
You can delete main components and its copies anytime the same way you can delete any other layer.
Deleting a main component at the viewport means deleting it at the assets library and viceversa, so be careful!
If a main component has been deleted and you have access to a copy of it, you can use the copy to restore its main. There are two ways to do it:
Where's my component? There are ways to find main components at the assets panel and at the design viewport.
+ +Select a main component at the viewport and then press "Show in assets panel" at the options of the right sidebar.
+Select a component copy and then press "Show main component" at the viewport menu or the right sidebar menu.
+If you find a page at a file called "Main components" this will probably mean that the file had assets with the previous components system and has been migrated to the current components system. The previous system didn't have the components as layers at the design file, only at the assets library, so when migrating a file to the new version Penpot automatically creates a page where to place all the components, grouping them using the library groups structure.
+
+At the Components section from the Assets library, there are two ways to create groups in a components library.
You can ungroup the components the same ways you can group them, via the menu option ("Ungroup" in this case) or renaming them.
-One very direct way to move components between groups at the assets library is by dragging them.
Where's my component? There are ways to find some components at the assets panel and at the design viewport.
+Detach a component copy to unlink it from its Main component and transform it into a group layer. Press Ctrl + Shift + K or right click and select the option “Detach instance” at the component menu.
+You can also detach components in bulk by selecting several components and performing the same action.
-Select a main component at the viewport and then press "Show in assets panel" at the options of the right sidebar.
+You can add text annotations to main components. The annotations are shown in every component copy. It is extremely useful to attach specifications that can be read at each component copy.
Select a component copy and then press "Show main component" at the viewport menu or the right sidebar menu.
+The annotations are also shown at the Inspect tab, as another option to improve communication between designers and developers.
Main components represent the more generic information of an element in a design system. You will usually need to change specific things (like a text, a color or an icon) in a component while maintaining the inheritance of the rest of it properties. Component overrides allows you to do that in Penpot.
+Overrides are modifications made in a specific copy that are not in its main component. With overrides you can keep changes at the component copies while maintaining synchronization with the Main component.
+
+Right click and select the option “Reset overrides” at the component menu to get it to the state of the Main component.
+You can push changes made at a component copy to a main component:
-Main components represent the more generic information of an element in a design system. You will usually need to change specific things (like a text, a color or an icon) in a component while maintaining the inheritance of the rest of it properties. Component overrides allows you to do that in Penpot.
-Overrides are modifications made in a specific copy that are not in its main component. With overrides you can keep changes at the component copies while maintaining synchronization with the Main component.
-
-Right click and select the option “Reset overrides” at the component menu to get it to the state of the Main component.
-Detach a component copy to unlink it from its Main component and transform it into a group layer. Press Ctrl + Shift + K or right click and select the option “Detach instance” at the component menu.
-You can also detach components in bulk by selecting several components and performing the same action.
- - -Penpot allows you to easily substitute component copies with other component copies.
You can add text annotations to main components. The annotations are shown in every component copy. It is extremely useful to attach specifications that can be read at each component copy.
+ +Variants allow you to group similar components, such as buttons, icons, or toggles, into a single, customizable component. Rather than navigating through separate components for every possible state, size, or style, you can manage them all from one unified component using clearly defined properties.
+Imagine a single button component that can switch between primary and secondary styles, active and disabled states, and small to large sizes. Useful, right? That’s the power of Variants.
+ +The annotations are also shown at the Inspect tab, as another option to improve communication between designers and developers.
+A component’s variants are organized by properties and their values.
+Each variant is simply one unique combination of values across all properties (for example, Color=Primary + Size=Small + State=Hover).
Variants must have at least one property, and property values should be kept consistent to make switching predictable and to preserve overrides across connected layers.
+ +You can create variants from an existing component or from another variant:
+
+ 
+When a variant is created:
+
If you find a page at a file called "Main components" this will probably mean that the file had assets with the previous components system and has been migrated to the current components system. The previous system didn't have the components as layers at the design file, only at the assets library, so when migrating a file to the new version Penpot automatically creates a page where to place all the components, grouping them using the library groups structure.
+Properties are key to defining and differentiating your variants. They appear in the Design tab when a variant or component with variants is selected.
+ 
[property_name]=[value].[property_name]=[value].
+Variants must have at least one property. You can’t delete the last one.
+When multiple variants are selected, the Design tab will show all their properties and values. If a property has different values across the selected variants, it will display “Mixed,” allowing you to override them collectively.
+ +If you delete the last variant, the entire component is removed.
+ +If you have a copy of a variant whose original was deleted, you can restore it:
+Once you have created your variants, you can place a copy of a component with variants into your design and then switch between its different versions.
+ +Drag and drop a component with variants from the Assets tab onto the design viewport, just like you would with any other component. Once placed, you can then use its properties in the Design tab to switch to the desired variant.
+ +When a variant is selected:
+
+A key benefit of variants is the ability to preserve overrides when you switch between them. An override is a specific change you make to a component instance that diverges from its original definition (e.g., changing text content or a specific color).
+Layers between variants are considered connected if they:
+
+Example: If Variant 1 has a text layer named label with red color, and you change its content to Click here in an instance, then switch to Variant 2 (which also has a label text layer), the Click here content will be preserved, and Variant 2’s color will be applied.
Changing any of these (e.g., renaming or grouping a layer) breaks the connection, but reverting the change will restore it.
+ +If you already have multiple related components, you can combine them into a single component with variants:
+
+Conditions:
+When combined:
+To turn a variant into an independent component:
+The new component’s name includes the original component name and the variant’s property values.
\ No newline at end of file diff --git a/docs/user-guide/design-tokens/index.njk b/docs/user-guide/design-tokens/index.njk index 186de28280..9e23a935bb 100644 --- a/docs/user-guide/design-tokens/index.njk +++ b/docs/user-guide/design-tokens/index.njk @@ -118,7 +118,7 @@ title: 10· Design Tokens
-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.
To apply a dimension token, select the element and choose the token from the list:
@@ -205,10 +205,6 @@ title: 10· Design TokensThe Y property specifies the position of the element on the Y axis of the canvas.
-Font size tokens allow you to define and standardize font-size values across your design system. These tokens can be applied to the font-size property in text layers, ensuring consistent typography throughout your designs.
-Font size token values are always computed as px (pixels).
-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.
@@ -265,10 +261,168 @@ title: 10· Design TokensThe 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.
+Number tokens define the numeric value of properties that don’t require a unit of measurement.
+The difference between a number token and a dimension token is that the first one has to be unitless.
+The Number Token does not have a default property to apply to, so it can only be applied by right-clicking and selecting the specific property.
+Number token is especially useful as a reference in other tokens, for math equations (operands), to create scales, for example font-size scales, or grid scales.
+It can also be applied to Line Height –since this property works as a multiplier of the font size– or rotation property.
+
+Typography tokens can only be applied to a text layer, but not to individual elements inside a text layer. +Applying a Typography Token will detach any Typography Style previously applied, and vice versa.
+
+
+As in other tokens, Font Family accepts references to other font family tokens.
+Additionally, you can specify a prioritized list of Font Family names or generic names separated by commas (,), as in CSS. Penpot will use only the first font in the list, but this helps define your font fallbacks so developers can implement them accordingly.
+
+
+ font-family: Lucida Console, Courier, monospace
+
+
+
+When writing the string values of a Font Family Token, pay close attention to:
+Note: You can quote font family names — especially those that contain spaces or special characters — + to follow CSS best practices or to align with the conventions used by your development team: +
+
+
+ font-family: "DM Sans", sans-serif;
+
+
+
+If the Font Family does not exist in Penpot, when you apply the token you will see a “Missing font” message in the design panel input:
+
+Font size tokens define the vertical size of glyphs/characters as an individual property. In typography, the letter spacing and line height properties are related to the font size.
+Font sizes are typically defined using a proportional scale. You can use math operations with references in order to create dynamic typography scales that follow a particular multiplier, like Golden Ratio.
+Tip: Use Number Tokens (unitless token) to create stunning typographic scales though design tokens:
+
+Font size is a dimension-type token and should be defined in px (unitless values are computed as px) for now. To follow the DTGC format, in upcoming releases, units will be mandatory and rem units will be allowed.
+You can use any dimension token as a reference in a font size token. Math operations are also allowed.
+Tip: You can use a rounding function to round your resolved values and reduce decimals in math operations, since decimals are not ideal when using px:
+roundTo({values}, decimals)
+Font Weight defines the thickness of each character/glyph in the Font Family. Font Weight design decisions are typically used to communicate visual hierarchy or emphasize text elements.
+Penpot combines Font Weight and Style as a single property written as a string value and it requires a match to the Font Family it is paired with, since not all font families have the same weight / styles.
+The Token can be defined with a numeric value (100, 400, 900, etc) or a string name (Bold, Black, Thin, etc), and the font style (Italic), if needed.
+Note: Font Family and Font Weight Tokens work as a pair in Penpot. This means you must consider the current Font Family in order to decide the Font Weight you want to use in your designs.
+This token can be applied to text layers but the result depends on the Font Family in use.
+Font Weight Token can be defined in numeric values or string values. Both values are accepted. When applied, a conversion will occur, transforming any string value to its corresponding numeric value:
+| Numeric Value | +String Value | +
|---|---|
| 100 | +Thin, Hairline | +
| 200 | +Extra Light, ExtraLight, extra-light, Ultra Light, UltraLight, ultra-light, extraleicht | +
| 300 | +Light, leicht | +
| 400 | +Regular, Normal, Book, buch | +
| 500 | +Medium, kraeftig, kräftig | +
| 600 | +Semibold, SemiBold, Semi Bold, semi-bold, DemiBold, Demi Bold, demi-bold, halbfett | +
| 700 | +Bold, dreiviertelfett | +
| 800 | +ExtraBold, Extra Bold, extra-bold, ultra-bold, UltraBold, Ultra Bold, fett | +
| 900 | +Black, Heavy, extrafett | +
| 950 | +Extra Black, extra-black, Ultra Black, ultra-black | +
Note: values are case insensitive so for example Regular and regular will both work.
Any of these values can also include the Font Style Italic, if needed. Some examples of accepted values:
+ +regular
+Normal Italic
+700
+400 italic
+Bold italic
+ExtraBold Italic
+Letter Spacing, also known as kerning, defines the horizontal distance between individual characters.
+The default value is 0. In Penpot letter spacing is defined in px. In the token, you can use values in px or any reference to a Dimension / Spacing / Sizing / Letter Spacing Token.
+This token can be applied directly to a text element or be used as a reference in a Typography Composite Token.
+ +Text Case defines that the system should transform the capitalization of letters in a text element regardless of how they are typed.
+This property corresponds to text-transform in CSS.
Accepted values are none, uppercase, lowercase and capitalize. It also accepts references to another Text Case token.
This token can be applied directly to a text element or be used as a reference in a Typography Composite Token.
+ +Text Decoration defines an optional line as part of font styling properties, typically used to communicate the visual emphasis of a text.
+Accepted values are none, underline and strike-through. It also accepts references to another Text Decoration token.
This token can be applied directly to a text element or be used as a reference in a Typography Composite Token.
+ +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 a token set is selected, the tokens within the selected set are displayed on the panel below.
-Right-click a token set to perform these quick actions: