docs: create how to work with design tokens #26

dcoa · 2024-09-05T09:02:04Z

This PR adds a how-to about design tokens support for the brand package.

There are still details to evaluate such as whether should we install Paragon as a dev dependency and the possible creation of a Paragon CLI command specific to this package.

Any early feedback should be great @brian-smith-tcril and @PKulkoRaccoonGang.

openedx-webhooks · 2024-09-05T09:02:09Z

Thanks for the pull request, @dcoa!

What's next?

Please work through the following steps to get your changes ready for engineering review:

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

🔘 Update the status of your PR

Your PR is currently marked as a draft. After completing the steps above, update its status by clicking "Ready for Review", or removing "WIP" from the title, as appropriate.

🔘 Let us know that your PR is ready for review:

Who will review my changes?

This repository is currently maintained by @openedx/committers-brand-openedx. Tag them in a comment and let them know that your changes are ready for review.

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

brian-smith-tcril

Thank you so much for putting this together! This is looking wonderful! I left a few comments with questions, more about possible ways to streamline the process than the documentation itself.

brian-smith-tcril · 2024-09-20T19:46:28Z

docs/how-to/design-tokens-support.rst

+
+
+From version 23 `Paragon <https://www.notion.so/Write-the-brand-docs-7a60ece8489e40e1a6ca6ac4b79aac82?pvs=21>`_ supports CSS variables and 
+`design tokens <https://tr.designtokens.org/format/#abstract>`.


Suggested change

`design tokens <https://tr.designtokens.org/format/#abstract>`.

`design tokens <https://tr.designtokens.org/format/#abstract>`_.

brian-smith-tcril · 2024-09-20T19:51:22Z

docs/how-to/design-tokens-support.rst

+How to structure the brand design tokens
+========================================
+
+The file structure in the brand package should be the same as the version of Paragon used as a reference to allow the merge/override during the build time.
+
+.. code-block::
+
+    .
+    └── tokens/
+        └── src/
+            ├── core/
+            │   └── <name_of_the_folder>/
+            │       └── <name_of_the_file>.json
+            └── themes/
+                ├── light/
+                │   └── <name_of_the_folder>/
+                │       └── <name_of_the_file>.json
+                ├── dark/
+                │   └── <name_of_the_folder>/
+                │       └── <name_of_the_file>.json
+                └── my-theme/
+                    └── <name_of_the_folder>/
+                        └── <name_of_the_file>.json


Open question here: the current structure of this repo has paragon as a directory at the top level. Is the plan to have tokens as a directory at the top level, or is the plan to have paragon/tokens?

Good idea. Perhaps consumers can have their own system design and their own set of token designs. It would be nice to have such a named structure for tokens provided by Paragon

Understanding that the brand package contains more than only paragon related code and the guide is related to how to use it with the paragon design system makes sense to have the tokens into the paragon folder.

brian-smith-tcril · 2024-09-20T19:58:01Z

docs/how-to/design-tokens-support.rst

+How to structure the brand design tokens
+========================================
+
+The file structure in the brand package should be the same as the version of Paragon used as a reference to allow the merge/override during the build time.


It might be nice to link to and/or provide a URL format for the paragon tokens directory from here

https://github.com/openedx/paragon/tree/v23.0.0-alpha.3/tokens currently works to show the directory for the v23.0.0-alpha.3 tag, so maybe having something like

To see the tokens directory structure for the version of Paragon you are targeting you can navigate to https://github.com/openedx/paragon/tree/TARGET_PARAGON_VERSION/tokens. For example, if you were targeting Paragon v23.0.0 you would navigate to https://github.com/openedx/paragon/tree/v23.0.0/tokens.

could work

brian-smith-tcril · 2024-09-20T20:00:00Z

docs/how-to/design-tokens-support.rst

+In terms of tokens, Paragon follows the specifications of the `Design Tokens Community Group <https://tr.designtokens.org/format/#abstract>`_. 
+
+The structure that follows to define most of the tokens is ``category > item > subitem > property > state``, for example:
+
+.. code-block:: json
+
+    {
+      "spacing": {    // Category
+        "$type": "dimension",                         
+        "annotation": {    // Item 
+          "padding": {     // Property
+              "$value": ".5rem",
+              "$source": "$annotation-padding"
+          },
+          "arrow-side": {   // Subitem
+            "margin": {     // Property
+              "$value": "{spacing.annotation.padding},
+              "$source": "$annotation-arrow-side-margin"
+            }
+          }
+        }
+      },
+      "typography": {
+        "annotation": {
+          "font-size": { 
+          "source": "$annotation-font-size", 
+          "$value": "{typography.font.size.sm}", 
+          "$type": "dimension" 
+          },
+        }
+      },
+    }
+
+Each token has specific attributes:
+
+- **Value**: It is the value that will be assigned to the variable, which could be a value or a reference, such as l arrow-side in the above example.
+- **Type**: Indicates the property to be processed (color, dimension, etc..). This value could be defined for the token itself or a group of tokens (e.g. spacing)
+- **Source**: This value is additional and indicates the equivalent in saas notation.
+- **Modify**: Optional value that helps to apply a specific token modification.
+
+Use the ``source`` attribute to map the tokens in Paragon and create the theme files. Also, it will help you to replace the values in scss files if you have custom variables (see below).
+
+You can check `Paragon tokens <https://github.com/openedx/paragon/tree/alpha/tokens>` to know the folder and token structure, and how to work with modifiers.


This part feels like it could go under a separate heading. That way we'd have a section for where to put files and how to name them, and a section for what to put in those files.

brian-smith-tcril · 2024-09-20T20:05:01Z

docs/how-to/design-tokens-support.rst

+#. Install Paragon
+
+.. code-block:: bash
+
+    npm install paragon


I wonder if it makes sense to add Paragon as a dev dependency for this repo instead of instructing people to install it. Then we could just have people run npm ci and people wouldn't end up with changes to their package.json and package-lock.json files.

This should be updated in paragon as well https://github.com/openedx/paragon/tree/alpha?tab=readme-ov-file#theming-with-design-tokens

brian-smith-tcril · 2024-09-20T20:07:01Z

docs/how-to/design-tokens-support.rst

+      }
+    }
+
+Replace the destination with the desired path and run the command, it is recommended to use ``./dist/``. 


Is there a specific reason to have this as a template instead of just hardcoding ./dist/?

highlight and in any case be use in the package.json file as the destination for the script template

brian-smith-tcril · 2024-09-20T20:11:50Z

docs/how-to/design-tokens-support.rst

+
+It is recommended to create the `theme-urls.json` if you are working with runtime theming and want to use ``ParagonWebpackPlugin`` to preload the token URLs during the application build time.
+
+The file must be in the ``dist`` folder and should have:


I'm not the biggest fan of having people directly create/edit files in the dist directory. It'd be great to be able to .gitignore dist and have this file copied in as part of the build process.

I think could live in the paragon/tokens folder, referencing all the desired variants. May be in this way, we will need to be clear about the relative path (understanding that the design tokens destination path is not necessary the dist folder, it is the ideal but is not limited to it)

mphilbrick211 · 2024-10-24T20:44:22Z

Hi @dcoa! Just checking in on this!

dcoa · 2024-10-25T03:48:33Z

Hi, @mphilbrick211 this is a work in progress I will allocate some time in the following weeks to finish it. Sorry for that.

PKulkoRaccoonGang · 2024-10-27T14:40:13Z

docs/how-to/design-tokens-support.rst

+===================================
+
+
+From version 23 `Paragon <https://www.notion.so/Write-the-brand-docs-7a60ece8489e40e1a6ca6ac4b79aac82?pvs=21>`_ supports CSS variables and 


[question]: Will there be a link here to the future npm Paragon 23 page?

Paragon Documentation, yes

PKulkoRaccoonGang · 2024-10-27T14:45:13Z

docs/how-to/design-tokens-support.rst

+    .
+    └── tokens/
+        └── src/
+            ├── core/


[question]: Is it worth specifying here more precisely which directories may be needed? For example, now in the alpha version of Paragon we have semantic tokens that we divide into core, alias and global tokens? More information on semantic design tokens

I think due to the the how-to is explaining how to work with the paragon design tokens version I think a mention and a link to that explanation about semantic tokens is a valuable addition. I don't want to duplicate the information if it is already in Paragon. As well, I think the user should decide the folders that they want to include I mean if I want to change a token in the component folder worth it add the global and aliases as well?

PKulkoRaccoonGang · 2024-10-27T14:47:50Z

docs/how-to/design-tokens-support.rst

+How to structure the brand design tokens
+========================================
+
+The file structure in the brand package should be the same as the version of Paragon used as a reference to allow the merge/override during the build time.
+
+.. code-block::
+
+    .
+    └── tokens/
+        └── src/
+            ├── core/
+            │   └── <name_of_the_folder>/
+            │       └── <name_of_the_file>.json
+            └── themes/
+                ├── light/
+                │   └── <name_of_the_folder>/
+                │       └── <name_of_the_file>.json
+                ├── dark/
+                │   └── <name_of_the_folder>/
+                │       └── <name_of_the_file>.json
+                └── my-theme/
+                    └── <name_of_the_folder>/
+                        └── <name_of_the_file>.json


Good idea. Perhaps consumers can have their own system design and their own set of token designs. It would be nice to have such a named structure for tokens provided by Paragon

PKulkoRaccoonGang · 2024-10-27T14:50:11Z

docs/how-to/design-tokens-support.rst

+
+In terms of tokens, Paragon follows the specifications of the `Design Tokens Community Group <https://tr.designtokens.org/format/#abstract>`_. 
+
+The structure that follows to define most of the tokens is ``category > item > subitem > property > state``, for example:


It might be a good idea to add an image from the documentation site here
How do you like my proposal?

docs: create how to work with design tokens

cb2f2d7

openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Sep 5, 2024

dcoa requested review from PKulkoRaccoonGang and brian-smith-tcril September 5, 2024 09:02

brian-smith-tcril reviewed Sep 20, 2024

View reviewed changes

vunguyen-dmt pushed a commit to vunguyen-dmt/brand-openedx that referenced this pull request Oct 15, 2024

fix: add styling for header theme toggle switch button (openedx#26)

b3a1ae6

PKulkoRaccoonGang suggested changes Oct 27, 2024

View reviewed changes

dcoa force-pushed the dcoa/design-tokens-support branch 6 times, most recently from 041a6c2 to 47b7209 Compare November 18, 2024 11:48

refactor: add paragon as dev dependency and update how to

719dec8

dcoa force-pushed the dcoa/design-tokens-support branch from 47b7209 to 719dec8 Compare November 18, 2024 11:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: create how to work with design tokens #26

docs: create how to work with design tokens #26

dcoa commented Sep 5, 2024 •

edited

Loading

openedx-webhooks commented Sep 5, 2024 •

edited

Loading

brian-smith-tcril left a comment

brian-smith-tcril Sep 20, 2024

brian-smith-tcril Sep 20, 2024

PKulkoRaccoonGang Oct 27, 2024

dcoa Nov 18, 2024

brian-smith-tcril Sep 20, 2024

brian-smith-tcril Sep 20, 2024

brian-smith-tcril Sep 20, 2024

dcoa Nov 18, 2024

brian-smith-tcril Sep 20, 2024

dcoa Nov 18, 2024 •

edited

Loading

brian-smith-tcril Sep 20, 2024

dcoa Nov 18, 2024

mphilbrick211 commented Oct 24, 2024

dcoa commented Oct 25, 2024

PKulkoRaccoonGang Oct 27, 2024

dcoa Nov 18, 2024

PKulkoRaccoonGang Oct 27, 2024

dcoa Nov 18, 2024 •

edited

Loading

PKulkoRaccoonGang Oct 27, 2024

PKulkoRaccoonGang Oct 27, 2024



		From version 23 `Paragon <https://www.notion.so/Write-the-brand-docs-7a60ece8489e40e1a6ca6ac4b79aac82?pvs=21>`_ supports CSS variables and
		`design tokens <https://tr.designtokens.org/format/#abstract>`.


		It is recommended to create the `theme-urls.json` if you are working with runtime theming and want to use ``ParagonWebpackPlugin`` to preload the token URLs during the application build time.

		The file must be in the ``dist`` folder and should have:

		===================================


		From version 23 `Paragon <https://www.notion.so/Write-the-brand-docs-7a60ece8489e40e1a6ca6ac4b79aac82?pvs=21>`_ supports CSS variables and


		In terms of tokens, Paragon follows the specifications of the `Design Tokens Community Group <https://tr.designtokens.org/format/#abstract>`_.

		The structure that follows to define most of the tokens is ``category > item > subitem > property > state``, for example:

docs: create how to work with design tokens #26

Are you sure you want to change the base?

docs: create how to work with design tokens #26

Conversation

dcoa commented Sep 5, 2024 • edited Loading

openedx-webhooks commented Sep 5, 2024 • edited Loading

What's next?

🔘 Get product approval

🔘 Provide context

🔘 Get a green build

🔘 Update the status of your PR

🔘 Let us know that your PR is ready for review:

Who will review my changes?

Where can I find more information?

When can I expect my changes to be merged?

brian-smith-tcril left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dcoa Nov 18, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mphilbrick211 commented Oct 24, 2024

dcoa commented Oct 25, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dcoa Nov 18, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dcoa commented Sep 5, 2024 •

edited

Loading

openedx-webhooks commented Sep 5, 2024 •

edited

Loading

dcoa Nov 18, 2024 •

edited

Loading

dcoa Nov 18, 2024 •

edited

Loading