QmlDesigner: Document the Design Tokens view

This patch documents the Design Tokens view.

Fixes: QDS-11862
Change-Id: Ibfba444a707363433f5d279df53c7b11da2fb22d

Reviewed-by: Vikas Pachdha <vikas.pachdha@qt.io>

doc/config/macros.qdocconf

@@ -6,6 +6,7 @@ macro.author            = "\\b{Author:}"
 macro.br.HTML           = "<br />"
 macro.BR.HTML           = "<br />"
 macro.copyright.HTML    = "&copy;"
+macro.DT                = "\\uicontrol {Design Tokens}"
 macro.eacute.HTML       = "&eacute;"
 macro.gui               = "\\b"
 macro.hr.HTML           = "<hr />"

doc/qtdesignstudio/config/style/qt5-sidebar.html

@@ -433,6 +433,7 @@
                 <li><a href="qtquick-connection-view.html">Connections</a></li>
                 <li><a href="studio-content-library.html">Content Library</a></li>
                 <li><a href="qtquick-curve-editor.html">Curves</a></li>
+                <li><a href="studio-design-tokens-view.html">Design Tokens</a></li>
                 <li><a href="qtquick-effect-composer-view.html">Effect Composer</a></li>
                 <li><a href="creator-file-system-view.html">File System</a></li>
                 <li><a href="studio-material-editor.html">Material Browser</a></li>

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}

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},

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
+
+
+
+*/

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