@mozaic-ds/vue
Version:
Mozaic-Vue is the Vue.js implementation of ADEO Design system
302 lines (213 loc) • 8.19 kB
text/mdx
import { Meta, Source } from '@storybook/addon-docs/blocks';
<Meta title="Getting Started" />
# Getting Started
**Mozaic-Vue** is the [Vue.js](https://vuejs.org/) implementation of ADEO Design system.
### 📦 Installation
In order to use **Mozaic-Vue** in your **Vue.js** project, you must first install the [npm package](https://www.npmjs.com/package/@mozaic-ds/vue):
<Source language="bash" dark code="npm i @mozaic-ds/vue" />
Or with **Yarn**:
<Source language="bash" dark code="yarn add @mozaic-ds/vue" />
### 📝 Usage
Import the styles
<Source
language='typescript'
dark
code={`
// main.ts
import '-ds/vue/style.css';
`} />
To import and use a component, you can proceed as follows:
<Source
language='html'
dark
code={`
<script setup>
import { MButton } from '-ds/vue';
</script>
<template>
<MButton>Button Label</MButton>
</template>
`} />
### 🎨 Brand Presets
**Mozaic** is a **multi-brand** design system.<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 of customising **Mozaic** for you, we have created themes _(which we also call **"presets"**)_ ready to use according to your context of use.
Currently **Mozaic** can be customized with the following presets:
- Preset **Leroy Merlin**: this is the default preset/theme configured when **Mozaic** was first installed
- Preset **Adeo**: dedicated to the **Adeo Group's** internal interfaces and products
- Preset **Bricoman**: dedicated to the interfaces and products of the **Bricoman** brand
The rest of this documentation shows you how to use/install the Adeo preset in your project.
> Note that the procedure remains the same for all other presets.<br/> You just need to replace all references to "Adeo" with the brand name of your choice.
#### Using the Adeo's preset
Before anything else, make sure you have followed the **Mozaic-Vue** installation procedure as described in the [Getting Started](?path=/docs/getting-started--docs) page.
Once **Mozaic-Vue** is installed as shown, we can make the following changes:
#### Loading preset
All it has to do is insert the following code into its main Sass file (entrypoint stylesheet):
<Source
language="css"
dark
code={`
// Entrypoint stylesheet
"@mozaic-ds/tokens/<presetName>/theme" as *;
`}
/>
> [!NOTE]
> The `<presetName>` string should be replaced by the name of the preset you want, one of the following values: `adeo | mbrand`.
> As the `leroymerlin` preset is the default preset, you don't need to use this syntax to use it.
For example, for ADEO
<Source
language="css"
dark
code={`
// Entrypoint stylesheet
"@mozaic-ds/tokens/adeo/theme" as *;
`}
/>
#### Font by brand
Each brand is distinguished not only by different styles but also by a different font.
The table below summarises which font to use depending on the brand.
<table>
<tr>
<td>Brand</td>
<td>Font</td>
</tr>
<tr>
<td>Leroy Merlin</td>
<td>
[LeroyMerlinSans](https://mozaic.adeo.cloud/foundations/typography/font-families/)
</td>
</tr>
<tr>
<td>Adeo</td>
<td>[Roboto](https://fonts.google.com/specimen/Roboto)</td>
</tr>
<tr>
<td>Bricoman</td>
<td>[Inter](https://fonts.google.com/specimen/Inter)</td>
</tr>
</table>
For example, here is how to include the Roboto font in your HTML for the Adeo brand:
<Source
language="html"
dark
code={`
<head>
<meta charset="UTF-8" />
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100..900;1,100..900&display=swap"
rel="stylesheet"
/>
</head>
`}
/>
From there, we can update the main style sheet of your project, in order to import the right font.
<Source
language='css'
dark
code={`
'-ds/tokens/adeo/theme' as *;
body {
font-family: var(--font-family, 'Roboto', sans-serif);
}
`} />
Specific for LM fonts
> This section describes the use of fonts for the **Leroy Merlin** preset, but if you are using another preset, please see [the associated documentation](?path=/docs/using-presets--docs).
The theme defined by default when **Mozaic-Vue** is first installed/used is the theme corresponding to the **Leroy Merlin** charter.
For any use of the **Leroy Merlin** theme, it is recommended to use the font [LeroyMerlinSans](/typography/font-families/) which has been specially designed for **Leroy Merlin** products.
To use the `LeroyMerlinSans` font in your project, you must copy it into your project so that it is present in your `assets`.
You can do this as follows:
1. Create a folder in your project where you can save the fonts, for example: `static/assets/fonts`
2. Copy fonts from Mozaic dependencies:
<Source
language="bash"
dark
code="cp node_modules/@mozaic-ds/web-fonts/*.{woff,woff2} static/assets/fonts"
/>
#### Usage
At this stage, the integration of the **Mozaic-Vue** components should normally be customised with the preset values.
All that remains is to use the components as usual:
<Source
language="html"
dark
code='<MButton label="This is a Mozaic Button" />'
/>
### 🌑 Dark Mode
A concise guide explaining **how dark mode works** with your CSS variables and **how to use it** in Storybook.
---
## What dark mode is (high‑level)
Dark mode is implemented with **two sets of CSS variables** (tokens):
- **Light** values live under `:root`.
- **Dark** values override under `:root[data-theme="dark"]`.
Components only reference tokens with `var(--token-name)` — switching theme is just toggling the `data-theme` attribute (no component code changes).
---
#### Token structure (SCSS → CSS)
Your presets export SCSS like this:
<Source
language="scss"
dark
code={`
$root-selector: ':root' !default;
$dark-selector: '[data-theme="dark"]' !default;
#{$root-selector} {
/_ Light tokens _/
--color-background-primary: #ffffff;
--color-text-primary: #000000;
/_ … all your light variables … _/
}
#{$root-selector}#{$dark-selector} {
/_ Dark tokens _/
--color-background-primary: #191919;
--color-text-primary: #d9d9d9;
/_ … all your dark variables … _/
}
`}
/>
After compilation, this becomes standard CSS:
<Source
language="css"
dark
code={`
:root {
/* light tokens */
}
:root[data-theme='dark'] {
/* dark tokens */
}
`}
/>
> If you can’t (or don’t want to) target `:root`, you can pass a different `$root-selector` when building your theme and apply `data-theme="dark"` on that container instead.
---
#### Using tokens inside components
To enable the dark mode you have to ensure to:
- Add the `data-theme` attribute in your root element with the value `dark`,
- Use variables — never hard‑code colors or sizes
```html
<div class="root" data-theme="dark">…</div>
```
<Source
language="sass"
dark
code={`
"@mozaic-ds/tokens" as *;
.mc-component: {
background-color: $--color-background-primary;
}
`}
/>
When the theme changes, these values update automatically via CSS.
---
#### Accessibility & good practices
- Aim for **WCAG AA** contrast at minimum; verify text vs. background pairs.
- Prefer **semantic tokens** (`--button-color-…`, `--color-text-…`) over raw color hexes.
- Keep all component styles expressed in tokens so the **theme switch has zero component logic**.
---
#### Troubleshooting
- **Dark toggle does nothing** → Ensure the tokens were imported **before** component styles and that `data-theme="dark"` is set on the same selector the tokens target (usually `:root`).
- **Weird colors** → Search for hard‑coded values and replace them with tokens.
- **Variables undefined** → Check your build order and that the SCSS was compiled to CSS and loaded by Storybook.
---
#### Summary
- Light tokens on `:root`, dark overrides on `:root[data-theme="dark"]`.
- Components read tokens with `var(--$token-name)` — no runtime branching required.