🎨 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.

📦 Install

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

npm install @mozaic-ds/styles

If you prefer Yarn, use the following command instead:

yarn add @mozaic-ds/styles

📝 Usage

The files in the package are SCSS files. Therefore, the installation of 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).

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:

// 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:

@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:

// 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 standard, which we use to organise and expose our code base. To find out more, see the related Sass documentation 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.

Theming

The Design system is multi-brand. 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):

// 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. 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:

// 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:

$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 :

: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:

// 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:

.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:

// 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. Access to the Changelog to find out about the detailed changes to each release.

📣 Stay in touch

• Join the #mozaic-support channel on Slack
• Follow our KEYS page

🐞 Bugs and feature requests

Have a bug or a feature request? Please open an issue 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. Read the Contributing Guide for more information.

🧑‍💻 Contributors

Owners

ADEO Design System Team

Maintainers

• David Martin
• Mohamed Mokhtari
• Trésor Iloyi

📄 Licensing

This project is licensed under the Apache V2 License. See LICENSE for more information.