Tokens customization

Principles

Under the hood, Mozaic SCSS uses the compiled tokens that we provide in the @mozaic-ds/tokens npm package. This dependency is imported via @mozaic-ds/styles by default.

Mozaic tokens are based upon the LEROY MERLIN brand guidelines but you can adapt these tokens to fit your brand identity.

It is possible for you to override any value and to add new ones in order to create new patterns or pattern variations.

About tokens

As a reminder, we call tokens a series of JSON files containing mostly color values (among others things).

Those files are transpiled into SCSS, js, ios, and android formats, to be used within multiple platforms and technologies.

For more informations

Read the following documentations:

1 - Configure Mozaic

Create a mozaic.config.js file at your project root (if it is not already done). Then define those keys:

mozaic.config.js


module.exports = {
  tokens: {
    localTokensSrcPath: './src/tokens/', // path to your own json tokens files
    localTokensExportPath: './dest/build/', // path to compiled tokens files
  },
}

By doing that, you tell Mozaic where to look for the source tokens and where to save the compiled ones.

Good to know

The localTokensExportPath property is also used in the Mozaic's PostCSS configuration, to tell it where to look for the SCSS tokens.

By doing that, the SCSS will load the customized ones instead of the ones living in the npm package.

2 - Override tokens

To override tokens, you need to use the same directory structure and file names as the ones provided in the @mozaic-ds/tokens package.

Let's take an example by overriding the primary brand color.

The default primary color swatch is situated in @mozaic-ds/tokens/properties/color/base.json.

Assuming you have the mozaic.config.js set up as described in the previous chapter, we need to create a ./src/tokens/properties/color/base.json file.

Good to know

You can override any value, Mozaic will take care of deep merging the source tokens with the new values you provided.

For example:

src/tokens/properties/color/base.json


{
  "color": {
    "primary-01": {
      "100": {
        "value": "#000"
      }
    }
  }
}

In this example, Mozaic will replace the color.primary-01.100 and set it to #000 (black), but all the other existing values for color.primary-01.xxx will be kept as defined in the npm package source.

Meaning color.primary-01.100 will be customized to #000 (black), and color.primary-01.200 will still be green.

3 - Compiling tokens

In order to compile tokens, you have two options:

3.1 - The mozaic-tokens-build command

Run the mozaic-tokens-build command directly:


  npx mozaic-tokens-build

Or through a package.json script for example:

package.json


"scripts": {
  "tokens:build": "mozaic-tokens-build"
}

3.2 - Using the js function

If you want to trigger the tokens build inside a node script, you can use the function provided by Mozaic:


const tokensBuild = require('@mozaic-ds/tokens/tokensBuild')
tokensBuild()

When triggering either the command or the function, if you override values, you should see something like this logging into the console:


Property Value Collisions:
Collision detected at: color.primary-01.100! Original value: #EAF3E2, New value: #000

4 - Create new values

The same way, by declaring new values, you can create new tokens for your use:


{
  "color": {
    "custom": {
      "100": {
        "value": "#A0C"
      },
      "200": {
        "value": "#BBE"
      },
      "300": {
        "value": "#C1A"
      },
      "400": {
        "value": "#01E"
      }
    }
  }
}

Will generate:


$color-custom-100: #a0c;
$color-custom-200: #bbe;
$color-custom-300: #c1a;
$color-custom-400: #01e;
$color: (
  custom: (
    100: $color-custom-100; 200: $color-custom-200; 300: $color-custom-300; 400:
      $color-custom-400;,
  ),
);

One more thing...

You can see that we build variables but also a sass map. The map is useful when we need to loop through values to create multiple variations of a pattern. More informations about that below.

5 - Overriding components tokens

When we create components related tokens, we try as much as possible to loop through the tokens sass map to generate classes instead of manually creating each variation of the component.

For example, we use mixins to create buttons themes and then we use the key names as modifier classes names:


.mc-button {
  @each $name, $props in $buttons-themes {
    @if ($name != 'solid') {
      &--#{$name} {
        @include set-button-theme($props);
      }
    }
  }
}

This means that if you create a properties/color/button.json file and define something like:

properties/color/button.json


{
  "color": {
    "button": {
      "my-theme": {
        "background": {
          "value": "{color.custom.500.value}"
        },
        "font": {
          "value": "{color.custom.000.value}"
        },
        "focus": {
          "border": {
            "value": "{color.custom.700.value}"
          }
        },
        "disabled": {
          "background": {
            "value": "{color.custom.100.value}"
          },
          "font": {
            "value": "{color.custom.500.value}"
          }
        },
        "active": {
          "background": {
            "value": "{color.custom.700.value}"
          }
        },
        "hover": {
          "background": {
            "value": "{color.custom.600.value}"
          },
          "font": {
            "value": "{color.custom.000.value}"
          }
        }
      }
    }
  }
}

You will end up with a new button theme without the need to write any CSS or SASS.


<button class="mc-button mc-button--my-theme">
  My button with a custom theme
</button>

Useful tip

You can look in the specs tab of the component documentation to help you define which tokens need to be overridden.