This document provides an overview of the tokens flow in the project. It explains the players involved, the flow of token updates, and the main functions responsible for generating SCSS files based on the tokens.

Repository ​

You can find dsy-lighthouse on our DevOps portal.

Repository on Azure DevOps

Players ​

The tokens flow involves two main players:

Token Studio: A website where designers can push new tokens in the form of a tokens.json file on this repository branches.

Tokens Plugin: A workspace in this repository that developers use to obtain the new tokens and generate SCSS files based on them.

Flow ​

By following the next steps you should be able to use tokens from Token Studio directly in your Frontend projects. This flow starts when a UI Designer push a new tokens.json on a branch on dsy-lighthouse repository

  1. Get sections from tokens.json
  2. Implement a new getTokens function
  3. Check variables output
  4. Expose css vars
  5. Build dsy
  6. Serve docs
  7. Done!

Before you start ​

If you need to extend the current variables set provided by the tokens-plugin, you may want to:

  • Add new theme
  • Add new color mode for existing theme
  • Add new scss section
  • Edit variables output

Inside the tokens-plugin src folder, you'll find all the interfaces for the tokens-plugin itself.

It looks something like this:

Add new theme ​

Note: This is not enabled right now and must be fully implemented and tested yet. If you really need to do it, you need to create a separate build task like a separate vite.config.ts foreach theme.

Add new color mode for existing theme ​

Simply add the name of the related workspace on Token Studio, it must follow the naming convention and start with theme/yourthemename-mode (eg. theme/lighthouse-dark"). Then it should lookup for this key in your tokens.json and convert its contents to SASS variables.

Add new scss section ​

If you need to add a new section (eg. create new component), start by adding the name of the related workspace on Token Studio, it must follow the naming convention and start with context/section (eg. components/modal").

Then you need to implement a function to get and convert tokens from tokens.json to SASS variables (covered later in this document at 1. Get sections from tokens.json)

Edit variables output ​

Check if the section from tokens.json is already declared or add your new workspace (eg. you're developing a new component xyz and need to add "components/xyz").

Understand main function ​

The main function is createThemeAndColorMode and creates .scss files foreach Theme and related Color Modes.

  • createVariablesFile This function reads a JSON file, converts its content to SCSS variables, and writes the result to a new file.

  • createColorModeFiles This function is responsible for generating SCSS files for different color modes.

  • addImportColorModeFiles This function adds import statements for different color mode files into a main style file.

1. Get sections from tokens.json ​

Now you can define which keys you want to filter or just get all of them with Object.keys.

2. Implement a new getTokens function ​

getMySectionTokens: This function takes four parameters: tokens, section, keys, and themeColorMode.

  • getVariables: This function generates SCSS variables from the provided tokens. It loops over the keys of the tokens object (or over the provided filterKeys if they exist), and for each key it generates a SCSS variable. The variable's name is generated by the fixVariableKey function, and its value is generated by the fixVariableValue function.

Ultimately it returns the lines of SCSS code related to our section.

Note: you can write custom code in your getTokens methods, but you must always return a lines of SCSS code as string[] to be fully compliant.

3. Check variables output ​

If the tokens plugin process ends successfully, you'll find some changed scss files. Check for errors, build the project using npm run build --workspace=dsy or npm run build --workspace=docs

4. Expose css vars ​

Now you have the scss variables and need to expose this stuff into the css vars layer. We usually deal with native Bootstrap variables and custom QubicaAMF variables (the ones with q- prefix).

Native Bootstrap variables ​

Use Sass mixins from Bootstrap and override css variables foreach color mode (eg. NavBar override):

Custom q- variables ​

Add new variables to the $custom-variables Sass map inside createColorModeFiles function:

5. Build dsy ​

Check for errors, build the project using npm run build --workspace=dsy or npm run build --workspace=docs.

For debug purposes you can enable this useful flags when using the plugin:

  • verbose a boolean value that enabled verbose mode during tokens conversion;
  • compareWithBootstrap a boolean value that compares parsed variables with Bootstrap 5 core variables.scss.

6. Serve docs ​

If it builds, try launching docs by pressing F5 or npm run serve --workspace=docs and check it live on your browser.

7. Done! ​

Great! Looks like it works as expected.

Merge your PR into main branch and complete related work items.