// 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 \c {Generated/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 Drag the \c .qtbridge file with your variable and design from Figma to the
            \uicontrol 2D view. That imports the design and the \DT from Figma to
            your \QDS project.
    \endlist

*/
