npm package: @mozaic-ds/styles
Description: SCSS files 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-core-banner.svg" />
</p>

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

<p align="center">
  A library of <a href="https://sass-lang.com/">SCSS</a> components implementing ADEO Design system guidelines.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@mozaic-ds/styles">
    <img src="https://img.shields.io/npm/v/@mozaic-ds/styles?label=NPM&logo=npm&color=yellow" alt="npm beta 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 @mozaic-ds/styles
```

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

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

## 📝 Usage

The files in the package are `SCSS` files. <br/>Therefore, the installation of [Sass](https://www.npmjs.com/package/sass) in your project **is required** to enable you to compile our files.

### Configuring Sass

Once it is installed and made sure that **Sass** is implemented in your project, all that remains is to configure **Sass** to include the `node_modules` folder in the `loadPaths` option. _(See the [related Sass documentation](https://sass-lang.com/documentation/at-rules/use/#load-paths))._

### Use of components styles

The CSS style of design system components is used by importing the SCSS style sheet associated with the component.

This can be done using the following syntax: `@use "@mozaic-ds/styles/components/<COMPONENT-NAME>` where `<COMPONENT-NAME>` is the name of the component.

For example:

```scss
// Use styles for the Button component
@use '@mozaic-ds/styles/components/button';
```

> [!TIP]
> If for any reason you want to import all the style sheets in the design system, you can do so using the following syntax:
>
> ```scss
> @use '@mozaic-ds/styles';
> ```

### Using the design system's design tokens

In addition to the components, you can also access all the design system tokens so that you can use them in your projects.

Tokens can be used through the `@mozaic-ds/tokens` package, which is a dependency of the `@mozaic-ds/styles` package.

You can therefore access all the tokens by inserting the following code at the top of the SCSS file of your choice:

```scss
// Use design system tokens
@use '@mozaic-ds/tokens';

body {
  background: tokens.$color-background-primary;
}
```

> [!NOTE]
> As you may have noticed from the code examples above, the use of our SCSS style sheets begins with the `@use` rule.
> This is the new [Sass modules](https://sass-lang.com/blog/the-module-system-is-launched/) standard, which we use to organise and expose our code base.
> To find out more, see [the related Sass documentation](https://sass-lang.com/documentation/at-rules/use/) on this new feature.

### Do more with design system styles

In addition to the use of components and tokens, the library provides a number of tools and helpers to help you create robust, maintainable CSS code that is perfectly aligned with our design system guidelines.

To find out more about all the possibilities offered by this package, please consult our [SassDoc](https://github.com/adeo/mozaic-styles/blob/main/docs/sass/sassdoc.md).

### Theming

The Design system is **multi-brand**.<br/>
This means that it is fully customisable so that its constituent elements _(foundations, components, etc.)_ can be adapted to the graphic charter of the brand that uses it.

To simplify this aspect for you, we have created themes ready to use according to your context of use.

Currently the components can be customized with the following presets:

- Preset **Leroy Merlin**: this is the default preset/theme
- Preset **Adeo**: dedicated to the **Adeo Group's** internal interfaces and products
- Preset **Brico Center**: dedicated to the interfaces and products of the **Brico Center** brands
- Preset **Mbrand**: dedicated to the interfaces and products of the **Mbrand** brands

Users of our design system can use all the presets in the following two ways:

#### 1. Use a single preset _(without having to switch between several presets on the fly)_.

The first use case _(the most common)_ is that of a user who installs the design system and wishes to use it with a single, well-defined preset.

All it has to do is insert the following code into its **main Sass file** _(entrypoint stylesheet)_:

```scss
// Entrypoint stylesheet
@use '@mozaic-ds/tokens/<PRESET-NAME>';
```

> [!NOTE]
> The `<PRESET-NAME>` string should be replaced by the name of the preset you want, one of the following values: `adeo | bricocenter | mbrand`.<br/>
> As the `leroymerlin` preset is the default preset, you don't need to use this syntax to use it.

#### 2. Use several presets _(need to switch between several presets on the fly)_

The second scenario is that of a user who wants to switch between several presets on the fly.
To do this, it needs to insert the following code into its **main SCSS file**:

```scss
// In your main SCSS file
@use '@mozaic-ds/tokens/<PRESET-NAME>/theme';
```

> [!NOTE]
> The `<PRESET-NAME>` string should be replaced by the name of the preset you want, one of the following values: `adeo | bricocenter | mbrand`.

The above code generates an SCSS theming code for each preset, structured as follows:

```scss
$root-selector: ':root' !default;

#{$root-selector} {
  --color-overlay: rgba(0, 0, 0, 0.5);
  --color-standalone-disabled: #b3b3b3;
  --color-status-background-info: #e1f3f9;
  --color-status-background-success: #ebf5de;
  --color-status-background-warning: #fdf1e8;
  --color-status-background-error: #fdeaea;
  --color-status-background-neutral: #f2f2f2;
  // ...
}
```

Once the code has been compiled and transformed into CSS, it becomes :

```css
:root {
  --color-overlay: rgba(0, 0, 0, 0.5);
  --color-standalone-disabled: #b3b3b3;
  --color-status-background-info: #e1f3f9;
  --color-status-background-success: #ebf5de;
  --color-status-background-warning: #fdf1e8;
  --color-status-background-error: #fdeaea;
  --color-status-background-neutral: #f2f2f2;
  /* ... */
}
```

If for some reason using the `:root` selector is problematic for you, you can customise this selector as follows:

```scss
// In your main SCSS file
@use '@mozaic-ds/tokens/<PRESET-NAME>/theme' with (
  $root-selector: '.my-custom-selector'
);
```

This will generate the following CSS code:

```css
.my-custom-selector {
  --color-overlay: rgba(0, 0, 0, 0.5);
  --color-standalone-disabled: #b3b3b3;
  --color-status-background-info: #e1f3f9;
  --color-status-background-success: #ebf5de;
  --color-status-background-warning: #fdf1e8;
  --color-status-background-error: #fdeaea;
  --color-status-background-neutral: #f2f2f2;
  /* ... */
}
```

If you need to use several themes within the same style sheet, but targeting different selectors, you can do so as follows:

```scss
// Use CSS variables from the Adeo preset with custom root selector
@use '@mozaic-ds/tokens/adeo/theme' as adeo-theme with (
  $root-selector: '.preset-adeo'
);

// Use CSS variables from the Adeo preset with custom root selector
@use '@mozaic-ds/tokens/bricocenter/theme' as adeo-theme with (
  $root-selector: '.preset-bricocenter'
);

// Use CSS variables from the Mbrand preset with custom root selector
@use '@mozaic-ds/tokens/mbrand/theme' as mbrand-theme with (
  $root-selector: '.preset-mbrand'
);
```

> [!NOTE]
> As you can see, the use of several themes within the same style sheet requires the definition of a namespace dedicated to each preset thanks to the SCSS declaration `as <YOUR-NAMESPACE>` just before the `with` keyword.

## 📰 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! _(more information below)_

## ✍️ 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.