diff --git a/doc/config/macros.qdocconf b/doc/config/macros.qdocconf index 916c9623a18..f7fc1f1e7a8 100644 --- a/doc/config/macros.qdocconf +++ b/doc/config/macros.qdocconf @@ -6,6 +6,7 @@ macro.author = "\\b{Author:}" macro.br.HTML = "
" macro.BR.HTML = "
" macro.copyright.HTML = "©" +macro.DT = "\\uicontrol {Design Tokens}" macro.eacute.HTML = "é" macro.gui = "\\b" macro.hr.HTML = "
" diff --git a/doc/qtdesignstudio/config/style/qt5-sidebar.html b/doc/qtdesignstudio/config/style/qt5-sidebar.html index 91c948d3622..c10ba62da30 100644 --- a/doc/qtdesignstudio/config/style/qt5-sidebar.html +++ b/doc/qtdesignstudio/config/style/qt5-sidebar.html @@ -433,6 +433,7 @@
  • Connections
  • Content Library
  • Curves
    • +
  • Design Tokens
  • Effect Composer
  • File System
  • Material Browser
    • diff --git a/doc/qtdesignstudio/images/figma-qtbridge-setting-for-variables.webp b/doc/qtdesignstudio/images/figma-qtbridge-setting-for-variables.webp new file mode 100644 index 00000000000..46d6aad9535 Binary files /dev/null and b/doc/qtdesignstudio/images/figma-qtbridge-setting-for-variables.webp differ diff --git a/doc/qtdesignstudio/images/studio-designtokens-add-import.webp b/doc/qtdesignstudio/images/studio-designtokens-add-import.webp new file mode 100644 index 00000000000..5529b44a8de Binary files /dev/null and b/doc/qtdesignstudio/images/studio-designtokens-add-import.webp differ diff --git a/doc/qtdesignstudio/images/studio-designtokens-binding-between-collections.webp b/doc/qtdesignstudio/images/studio-designtokens-binding-between-collections.webp new file mode 100644 index 00000000000..d46c198a78a Binary files /dev/null and b/doc/qtdesignstudio/images/studio-designtokens-binding-between-collections.webp differ diff --git a/doc/qtdesignstudio/images/studio-designtokens-binding-color-property.webp b/doc/qtdesignstudio/images/studio-designtokens-binding-color-property.webp new file mode 100644 index 00000000000..6f5a2bd0fe3 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-designtokens-binding-color-property.webp differ diff --git a/doc/qtdesignstudio/images/studio-designtokens-binding-component-properties.webp b/doc/qtdesignstudio/images/studio-designtokens-binding-component-properties.webp new file mode 100644 index 00000000000..46fe16c595d Binary files /dev/null and b/doc/qtdesignstudio/images/studio-designtokens-binding-component-properties.webp differ diff --git a/doc/qtdesignstudio/images/studio-designtokens-connecting-functions.webp b/doc/qtdesignstudio/images/studio-designtokens-connecting-functions.webp new file mode 100644 index 00000000000..2a3fdc9aa0f Binary files /dev/null and b/doc/qtdesignstudio/images/studio-designtokens-connecting-functions.webp differ diff --git a/doc/qtdesignstudio/images/studio-designtokens-create-collection.webp b/doc/qtdesignstudio/images/studio-designtokens-create-collection.webp new file mode 100644 index 00000000000..8c6978831c8 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-designtokens-create-collection.webp differ diff --git a/doc/qtdesignstudio/images/studio-designtokens-create-variable.webp b/doc/qtdesignstudio/images/studio-designtokens-create-variable.webp new file mode 100644 index 00000000000..4048aa485d6 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-designtokens-create-variable.webp differ diff --git a/doc/qtdesignstudio/images/studio-designtokens-delete-mode.webp b/doc/qtdesignstudio/images/studio-designtokens-delete-mode.webp new file mode 100644 index 00000000000..858862d019c Binary files /dev/null and b/doc/qtdesignstudio/images/studio-designtokens-delete-mode.webp differ diff --git a/doc/qtdesignstudio/images/studio-designtokens-delete-variable.webp b/doc/qtdesignstudio/images/studio-designtokens-delete-variable.webp new file mode 100644 index 00000000000..3f798f657f7 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-designtokens-delete-variable.webp differ diff --git a/doc/qtdesignstudio/images/studio-designtokens-edit-variable.webp b/doc/qtdesignstudio/images/studio-designtokens-edit-variable.webp new file mode 100644 index 00000000000..b7fd3c6deee Binary files /dev/null and b/doc/qtdesignstudio/images/studio-designtokens-edit-variable.webp differ diff --git a/doc/qtdesignstudio/images/studio-designtokens-view.webp b/doc/qtdesignstudio/images/studio-designtokens-view.webp new file mode 100644 index 00000000000..0e0245850e6 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-designtokens-view.webp differ diff --git a/doc/qtdesignstudio/images/studio-experimental-features.webp b/doc/qtdesignstudio/images/studio-experimental-features.webp new file mode 100644 index 00000000000..850fdb8aa77 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-experimental-features.webp differ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc index e269253bba3..8b4018fffd8 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc @@ -26,6 +26,7 @@ \li \l{Connections} \li \l{Content Library} \li \l{Curves} + \li \l{Design Tokens} \li \l{Effect Composer} \li \l{File System} \li \l{Material Browser} diff --git a/doc/qtdesignstudio/src/views/qtquick-effect-maker-view.qdoc b/doc/qtdesignstudio/src/views/qtquick-effect-maker-view.qdoc index 175e3f013bb..09767ade85d 100644 --- a/doc/qtdesignstudio/src/views/qtquick-effect-maker-view.qdoc +++ b/doc/qtdesignstudio/src/views/qtquick-effect-maker-view.qdoc @@ -3,7 +3,7 @@ /*! \page qtquick-effect-composer-view.html - \previouspage studio-qt-insight.html + \previouspage studio-design-tokens-view.html \nextpage studio-model-editor.html \sa {Effect Composer example}, {Using a shader from Shadertoy in Effect Composer}, diff --git a/doc/qtdesignstudio/src/views/studio-design-tokens.qdoc b/doc/qtdesignstudio/src/views/studio-design-tokens.qdoc new file mode 100644 index 00000000000..9c29fa49787 --- /dev/null +++ b/doc/qtdesignstudio/src/views/studio-design-tokens.qdoc @@ -0,0 +1,291 @@ +// Copyright (C) 2025 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page studio-design-tokens-view.html + \previouspage studio-qt-insight.html + \nextpage studio-model-editor.html + + \ingroup studio-views + + \title Design Tokens + + \brief Create design themes. + + Use \DT to create theming for \QDS projects. Define + colors, booleans, numbers, and strings using the variables + and collections in \DT. + + \section1 Enabling Design Tokens in \QDS + + \DT is an experimental feature in \QDS. + + To enable the experimental features in \QDS: + \list 1 + \li Go to \uicontrol Edit > \uicontrol Preferences... + \li Select \uicontrol Environment > \uicontrol {\QDS Configuration}. + \li Select \uicontrol {Enable Experimental Features}, and then \uicontrol Ok. + \image {studio-experimental-features.webp} {Enable \QDS Experimental Features} + \endlist + + Next, select \uicontrol View > \uicontrol Views > \DT. + After the view is available, you can dock it anywhere in \QDS. + + \image {studio-designtokens-view.webp} {\DT view in \QDS} + + \section1 Creating a collection in Design Tokens + + \DT are organized into collections, which serve as structured containers + for grouping related design variables. These variables are categorized into + the following groups: + \list + \li \c Colors + \li \c Numbers + \li \c Strings + \li \c Flags + \endlist + + You can create multiple modes for each \DT collection. However, only one mode + can be set active at a time. + + To create a \DT collection: + + \list 1 + \li In the \DT view, select \imagemorebutton, and then select + \uicontrol {Create collection}. + \image {studio-designtokens-create-collection.webp} {Create a \DT collection} + \li Use a unique name for the collection and select \uicontrol Create. + \endlist + + The created collection is automatically selected in the collection dropdown menu in the + \DT view. You can use this dropdown menu to switch between collections. + + \note You can locate this collection's \c qml in the \uicontrol Projects view. However, + an empty collection does not appear. After adding variables to the collection, + you can find it in the folder \uicontrol Generated > \uicontrol DesignSystem. + + \DT variables can be used in a binding. Check the example below: + \code + Rectangle { + color: CollectionDark.colors.background + } + \endcode + + You can use \c colors to connect a \c Color, \c numbers to connect a \c Number, + \c strings to connect a \c String, and \c flags to connect a \c Boolean \DT variable + in a \QDS component's property binding. + + \image {studio-designtokens-connecting-functions.webp} {Connecting \DT collections with variables with functions} + + \section1 Removing an existing collection from Design Tokens + + To remove an existing collection from the \DT view: + \list 1 + \li Select the collection from the dropdown in the \DT view. + \li Select \imagemorebutton and then select \uicontrol Delete. + \li Select \uicontrol Remove. + \endlist + + \section1 Creating variables in Design Tokens + + In the \DT view, variables can store different values for each mode + within a collection. Variables can be bound to component properties to + define values such as colors, text, numbers, or boolean flags. + + After you define variables in one mode, you can create another mode and + have different values for the same set of variables. You can bind these variables + to different components to control their properties. Later, when you change + the mode from the dropdown menu in the \DT view, these changed values are + immediately applied to the components. + + To create a variable in \DT: + + \list 1 + \li Select a collection from the dropdown menu in which you want to add the variable. + \li Select \uicontrol {+ Create variable}, then select the type of variable you + want to create. + \image {studio-designtokens-create-variable.webp} {Creating a \DT variable} + + \li After the variable is added to the collection in the \DT view, you can + rename and update it according to your preferences. + + \note Always use unique names for the variables. + \endlist + + \section1 Removing an existing variable from a Design Tokens collection + + All the variables in a \DT collection are removed when you remove the collection. + However, to delete a single variable from a particular collection: + + \list 1 + \li Select the collection from the dropdown in the \DT view. + \li Right-click on the variable name and select \uicontrol {Delete variable}. + \image {studio-designtokens-delete-variable.webp} {Deleting a variable from a \DT collecction} + \endlist + + \section1 Create a new mode in Design Tokens + + Using modes in \DT, you can store different values for the same set of variables. + Just by switching the mode, you can change all the properties connected to + those variables. With multiple modes defined, you can do quick design prototyping. + + To create a different mode of the variables within a \DT collection: + + \list 1 + \li Select a collection from the dropdown menu where the variable exists. + \li Select \uicontrol {+ Create mode}. + + \note A new mode copies all the variables of the first mode in + the \DT collection. + \endlist + + \section1 Removing an existing mode from a Design Tokens collection + + All the modes in a \DT collection is removed when you remove the collecton. + However, to delete a single mode from a particular collection: + + \list 1 + \li Select the collection from the dropdown in the \DT view. + \li Right-click on the mode name and select \uicontrol {Delete mode}. + \image {studio-designtokens-delete-mode.webp} {Deleting a \DT mode} + \endlist + + \section1 Editing an existing variable or mode + + To edit an existing variable or mode in a collection: + + \list 1 + \li Select a collection from the dropdown menu where the variable or mode exists. + \li Double-click on the value you want to edit, then update the value. + \li After updating the value, press \key Enter to confirm it. Alternatively, + you can press \key ESC to cancel the update. + + \image {studio-designtokens-edit-variable.webp} {Edit a \DT variable or mode} + \endlist + + \section1 Including the Design Tokens library + + Before including the \DT library in your \QDS design file, you need to create: + \list 1 + \li A \DT collection. + \li A \DT variable for the \DT collection. + \endlist + + Then, include the import library of the \DT to your design file to make the \DT functional. + If you are creating the design in \c {Screen01.ui.qml}, double-click that file in + the \uicontrol Projects view. Then go to the \uicontrol Code view, and at the top + of the file include the code given below: + + \code + import Generated.DesignSystem + \endcode + + \image {studio-designtokens-add-import.webp} {Including \DT library to your \QDS design file} + + Afterwards, the variables you create in the \DT are available + to bind with your components. + + \section1 Binding components to Design Tokens variables + + \image {studio-designtokens-binding-component-properties.webp} {Binding \DT with component properties} + + To bind components to \DT variables, you need: + \list + \li The \QDS component you want to bind. + \li A \DT collection with variables. + \endlist + + When you have all the required elements: + + \list 1 + \li Select the \QDS component you want to bind in the \uicontrol 2D view. + \li Go to the \uicontrol Properties view and to the property that you + want to bind. + \li Select \imageactionicon in the property and select + \uicontrol {Set Binding}. + \li Remove the existing data and write your binding logic there. Suppose your + \QDS component \uicontrol ID is \c firstRectangle, you have made a \DT + collection named \c CollectionDark,and have a color variable named \c color_dark. + Now, to bind this color variable with the \uicontrol {Fill color} property of + the component, you write this in the binding: + \code + CollectionDark.colors.color_dark + \endcode + \image {studio-designtokens-binding-color-property.webp} {Writing the binding logic in the \uicontrol Properties view} + + \li Select \uicontrol Ok to apply the binding logic. After the binding is + applied, you can change between the modes in the \DT view. The changes + are directly applied to your component. + \endlist + + \section1 Binding variables between Design Tokens collections + + You can bind variables between different \DT collections. + + To bind variables between two \DT collections: + + \list 1 + \li Select the collection from the collection dropdown in the \DT view + where the variable you want to bind is available. + \li Select the mode of the variable you want to bind to the \QDS component from + the mode dropdown in the \DT view. + \li Select \imageactionicon next to the variable value and then + select \uicontrol {Set Binding}. + \li Now write your binding logic and press \key Enter. Suppose your first + \DT collection is \c CollectionDark and you have a color variable in it named + \c color_dark. Your second \DT collection is \c CollectionLight and you + have a color variable named \c color_light. Now, to bind the \c color_light + variable with the \c color_dark variable, you need to write this as the + binding logic for the \c color_light variable: + \code + CollectionDark.colors.color_dark + \endcode + \image {studio-designtokens-binding-between-collections.webp} {Binding variables between different \DT collections} + + \note Cyclic binding is not allowed between variables in the same or different + collections. + + \endlist + + \section1 Getting Design Tokens through \QBF + + While you can always create \DT in \QDS from scratch, you can + also bring designs made with Figma with \QBF and have the collections + and variables used in Figma designs as local \c QML \DT in \QDS. + + To do that: + + \list 1 + \li First, use Figma collections, variables, and modes to create a vaild + design. To learn more about using collections, variables and modes in a + Figma design, see \l {https://help.figma.com/hc/en-us/articles/15145852043927-Create-and-manage-variables-and-collections} {here}. + \li Now, use \QBF to export this design for \QDS. To learn more, + see \l {Using Qt Bridge for Figma}. + + \note Before exporting your Figma design for \QDS, in the \QBF plugin, + go to \uicontrol Settings > \uicontrol {Additional settings}, + and select \uicontrol {Export variables \[BETA\]}. \br + \inlineimage {figma-qtbridge-setting-for-variables.webp} {\QBF veriables export settings} + \endlist + + When you have the \c .qtbridge file exported through \QBF, you are ready to follow + the next steps: + + \list 1 + \li Create or open a \QDS project. + \li Create a \DT collection and variable. This adds the necessary \DT files to + your project. + \li Drag the \c .qtbridge file with your variable and design from Figma to the + \uicontrol 2D view. + \li Go to the file that has your imported design, and in the \uicontrol Code view, include + this: + \code + import Generated.DesignSystem + \endcode + \li Go to the \DT view, and select your imported collection from the \uicontrol Collections + dropdown. You can now bind these variables to locally created \QDS components as well. + \endlist + + + +*/ diff --git a/doc/qtdesignstudio/src/views/studio-qtinsight.qdoc b/doc/qtdesignstudio/src/views/studio-qtinsight.qdoc index 65dbbf3f8d2..b66c443c05c 100644 --- a/doc/qtdesignstudio/src/views/studio-qtinsight.qdoc +++ b/doc/qtdesignstudio/src/views/studio-qtinsight.qdoc @@ -4,7 +4,7 @@ /*! \page studio-qt-insight.html \previouspage studio-texture-editor.html - \nextpage qtquick-effect-composer-view.html + \nextpage studio-design-tokens-view.html \ingroup studio-views