npm package: @mozaic-ds/tokens
Description: Design Tokens for Mozaic, the Adeo's Design System
Author: Adeo Design System team
Latest version: 2.14.0

<p align="center">
  <img alt="ADEO Design system - Core library" src="./../../.storybook/assets/adeo-design-system-tokens-banner.svg" />
</p>

<h1 align="center">
  ADEO Design system - Tokens
</h1>

<p align="center">
  A set of <a href="https://styledictionary.com/">Design Tokens</a> following ADEO Design system guidelines.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@mozaic-ds/tokens">
    <img src="https://img.shields.io/npm/v/@mozaic-ds/tokens?label=NPM&logo=npm&color=yellow" alt="npm alpha version">
  </a>
  <a href="https://github.com/adeo/mozaic-styles/blob/master/CONTRIBUTING.md">
    <img src="https://img.shields.io/badge/PRs-welcome-blue.svg?logo=github" alt="PRs welcome" />
  </a>
  <a href="https://app.slack.com/client/T4R6RCZFA/CKQJZL7C4">
    <img src="https://img.shields.io/badge/Slack-mozaic_support-611f69.svg?logo=slack" alt="Slack mozaic-support" />
  </a>
  <a href="https://keys.adeo.com/keys/ls/space/2583429798460717/adeo-adeo-design-system">
    <img src="https://img.shields.io/badge/KEYS-Adeo_Design_System-4526ce.svg" alt="KEYS ADEO Design system" />
  </a>
</p>

## 🎨 Getting started

**Adeo Design System** is a global and collaborative design system that facilitates the designer and developer experience, enabling them to create universal interfaces perfectly aligned with the business strategy of [Adeo](https://www.adeo.com/).

## 📦 Install

To install this library in your project, you need to run the following command using `npm`:

```bash
npm install --save @mozaic-ds/tokens
```

If you prefer [Yarn](https://yarnpkg.com/), use the following command instead:

```bash
yarn add @mozaic-ds/tokens
```

> [!CAUTION]
> If the package `@mozaic-ds/styles` is already installed in your project, then you don't need to install the `@mozaic-ds/tokens` package.<br />
> The `@mozaic-ds/tokens` package is a dependency of the `@mozaic-ds/styles` package, so it is installed automatically when the latter is installed.

## 📝 Usage

This package gives you access to all the tokens made available by our design system.<br/>
This allows you to create code that is robust, easy to maintain and perfectly aligned with our design system guidelines.

This package provides design tokens for the following three formats: `CSS`, `SCSS`, `JavaScript` and `Flutter`.

This documentation shows you how to use tokens for each of these formats.

### Using tokens in your SCSS projects

**SCSS** is the main format on which we supply our tokens.<br/>
The [design system's styles](https://www.npmjs.com/package/@mozaic-ds/styles) are built using [Sass](https://www.npmjs.com/package/sass), so tokens in this format are proposed first.

The package exposes the following SCSS entry points that can be used in your projects:

| Preset           | File path                       | Notes                                                             |
| ---------------- | ------------------------------- | ----------------------------------------------------------------- |
| **Leroy Merlin** | `@mozaic-ds/tokens`             | Exposes all tokens in SCSS format for the **Leroy Merlin** preset |
| **Adeo**         | `@mozaic-ds/tokens/adeo`        | Exposes all tokens in SCSS format for the **Adeo** preset         |
| **Brico Center** | `@mozaic-ds/tokens/bricocenter` | Exposes all tokens in SCSS format for the **Brico Center** preset |
| **Mbrand**       | `@mozaic-ds/tokens/mbrand`      | Exposes all tokens in SCSS format for the **Mbrand** preset       |

### Using tokens in your CSS projects

If the **SCSS** format isn't for you, the package also exposes all the design system tokens in the form of [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties), also known as "**CSS variables**".

CSS variable files are exposed via the following entry points:

| Preset           | File path                             | Notes                                                                                                                            |
| ---------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Leroy Merlin** | `@mozaic-ds/tokens/theme`             | Generates a `root.css` file with a `:root {}` selector containing tokens in variable CSS format for the **Leroy Merlin** preset. |
| **Adeo**         | `@mozaic-ds/tokens/adeo/theme`        | Generates a `root.css` file with a `:root {}` selector containing tokens in variable CSS format for the **Adeo** preset.         |
| **Brico Center** | `@mozaic-ds/tokens/bricocenter/theme` | Generates a `root.css` file with a `:root {}` selector containing tokens in variable CSS format for the **Brico Center** preset. |
| **Mbrand**       | `@mozaic-ds/tokens/mbrand/theme`      | Generates a `root.css` file with a `:root {}` selector containing tokens in variable CSS format for the **Mbrand** preset.       |

> [!IMPORTANT]
> The root.css files generated do not contain the entire set of tokens, in order to preserve the integrity of the design system.<br/>
> So, unlike SCSS files/entry points, files containing CSS variables contain only the colour, spacing and font tokens, but none of the primitive tokens or components.<br/>
> You can find out more by reading this part of the documentation, which explains [the difference between presets and themes](#).

### Using tokens in your JavaScript projects

Finally, in addition to the `SCSS` and `CSS` formats, the package also gives you access to all tokens in **JavaScript** format.

To do this, the package exposes JavaScript files in [CJS](https://nodejs.org/api/modules.html) & [ESM](https://nodejs.org/api/esm.html) module format to cover as many use cases as possible.

Variable files in JavaScript format are available in this package via the following paths:

| Preset           | File path                       |
| ---------------- | ------------------------------- |
| **Leroy Merlin** | `@mozaic-ds/tokens`             |
| **Adeo**         | `@mozaic-ds/tokens/adeo`        |
| **Brico Center** | `@mozaic-ds/tokens/bricocenter` |
| **Mbrand**       | `@mozaic-ds/tokens/mbrand`      |

You can use the paths above to import the JavaScript module of your choice, depending on the context in which you are using it.

For example:

```js
import adeoTokens from '@mozaic-ds/tokens/adeo'
```

## 📰 Changelog

Releases are managed with **GitHub Releases**, including the changelog for each one.<br/>
Access to the [Changelog](/CHANGELOG.md) to find out about the detailed changes to each release.

## 📣 Stay in touch

- Join the [#mozaic-support](https://app.slack.com/client/T4R6RCZFA/CKQJZL7C4/) channel on **Slack**
- Follow our [KEYS page](https://keys.adeo.com/keys/ls/space/2583429798460717/adeo-adeo-design-system)

## 🐞 Bugs and feature requests

Have a bug or a feature request?<br/>
Please [open an issue](https://github.com/adeo/mozaic-styles/issues/new/choose) and use the template associated with your request.

However, if you are able to contribute and fix bugs, build new features, or help to improve the project documentation, feel free to do it!

## ✍️ Contributing

Your contribution, no matter how big or small, is much appreciated.<br/>
Read the [Contributing Guide](../../CONTRIBUTING.md) for more information.

## 🧑‍💻 Contributors

**Owners**

**[ADEO Design System Team](https://github.com/orgs/adeo/teams/adeo-design-system)**

**Maintainers**

- **[David Martin](https://github.com/dmartinds)**
- **[Mohamed Mokhtari](https://github.com/mohamedMok)**
- **[Trésor Iloyi](https://github.com/tiloyi)**

## 📄 Licensing

This project is licensed under the **Apache V2** License. See [LICENSE](LICENSE) for more information.