# Welcome to Roma
Discover the design and content system that powers our product ecosystem.
Roma is our design and content system created by our **Design**, **Front-end**, and **Content** teams.
Here, you will find comprehensive and detailed guidelines for each of our components, patterns, and content. Each section offers guidance on usage, accessibility, writing, with examples.
## Get started
Components
A comprehensive list of our UI components, from atoms to organisms level. Learn about their design, variants and accessibility details.
# Design principles
Roma, our design system with its guiding principles, is a lever to help us achieve our goal of building the most robust, high-speed, and reliable ecommerce platform.
> *“Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.”*
>
> *Antoine de Saint-Exupéry.*
## KISS (Keep it Simple, Stupid)
We want to make it easy for our users. Do not add steps when they're not necessary; remove pages and reduce the number of clicks. **Make it light, period.**
## Make it inclusive
No matter who they are, where they are, or what platform they’re using we want to offer our users the best user experience possible. A localized and accessible experience is at the core of what we do.
## Make it conversational
Provide an immersive experience where the information goes between the platform and the users.
## Build trust
Running businesses relying on Mirakl technology. We must provide a seamless and frictionless experience, supported by a robust technology with no downtime, without bugs & fast.
## Focus on efficiency
Mirakl experiences should help people achieve their goals quickly, accurately, and with less effort. We focus on speed and simplicity, but we value productivity even more.
## Build for real people
Our products are designed to fulfill the needs of our users, not our own. \
This involves a deep understanding of our users' desires and requirements, allowing us to deliver optimal solutions.
We commit to create tangible business value for our customers through innovation while addressing their challenges. We assess the performance of our launches and continue refining them until we meet our success criteria.
## Inspired by data
Where relevant, we will build smart, data-driven features to allow business teams to learn quickly and operate efficiently.
## Build a Minimum Loveable Product
Of course, we want to build quickly and fail fast, but we also don't want to put too much burden on the user's side. A Minimum Loveable Product (MLP) is an initial offering that users love from the start.
# Components
## Actions
Action menu
An action menu shows a list of items presenting the user with actions that can have an immediate effect, or a redirection to another section of the Mirakl platform.
A Save Bar is an action bar that sticks to the bottom of the viewport as you scroll. It contains actions related to a page and allow users to scroll without loosing visibility on the different actions
A modal displays content that requires user interaction in a layer that shows up on top of the current context. Modals block access to the rest of the page and force user interaction.
# Actions
this are all the available actionable components
Action menu
An action menu shows a list of items presenting the user with actions that can have an immediate effect, or a redirection to another section of the Mirakl platform.
A Save Bar is an action bar that sticks to the bottom of the viewport as you scroll. It contains actions related to a page and allow users to scroll without loosing visibility on the different actions
# Action menu
The action menu displays a list of actions triggered by a button. These actions have an immediate effect or redirect to another section of the Mirakl platform.
## Overview
After clicking a button ([Split Button](/design/components/actions/buttons#split-button), [Menu Button](/design/components/actions/buttons#menu-button), [Icon Button](/design/components/actions/buttons#icon-button)), an action menu appears as an overlay, allowing users to choose from a collection of actions.
## Guidelines
Action Menu must be used for secondary (or sub-)actions that do not require to be visible right away on the front page.
Clicking on an item automatically triggers the associated action. It must lead to a visual feedback ([Snackbar](/design/components/feedback/snackbar) or [Alert](/design/components/feedback/alerts)) showing the effect and the result of the action to the user or redirect him to the appropriate section of the Mirakl platform.
If all actions are disabled, consider disabling the parent component (button).
### Organizing an Action Menu
The Action Menu component can accommodate both small and extensive lists of secondary actions. However, it's crucial to avoid overly long, non-hierarchical lists as they can overwhelm users.
As a general rule, if a list of actions starts feeling extensive (without defining an exact threshold, as each project may determine its own cognitive load limit), there are several effective options available to structure the component:
1. **Grouping Similar Actions:** Consider categorizing semantically related Action Menu Items with a distinctive title (e.g., "Separator Action Menu Item"). This approach is particularly effective when all Action Menu Items can fit into a category and the list remains reasonably short.
Using separators to group similar actions
2. **Creating Sub-level Actions:** Introduce a sub-level of actions using the "Sub-menu" property. While this may make actions less visible, it efficiently organizes semantically related actions, even if others in the sub-menu cannot be easily categorized.
Creating sub-level actions
### Additional options to Action Menu
1. **Search function** : When dealing with a long list that can't be shortened, adding a search function to the component makes it easier for users to find what they need and improves their experience.
Search function
2. **Adding Media Elements:** Enhance the visual appeal of the list by incorporating media visuals for each list item. This approach is particularly useful when a visual representation adds value beyond a simple icon.
Adding media element
3. **External link :** In situations where an action is linked to an object but operates on a different URL, use the "external" property. This displays the associated icon, informing users that clicking the action will redirect them.
External link in action menu
4. **Badge** : Using badges is a great way to highlight one action from others in the action menu. \
For instance, when a new action is available in the menu or if one action is recommended compared to others.
Use of a Badge in a Action Menu
### Progressive disclosure
For temporarily inactive actions, adhere to the guideline of adding a tooltip upon hover, explaining why the action is inactive. If an action is never active for a specific user (e.g., due to their role), it should be omitted from the Action Menu to prevent unnecessary clutter and streamline the user experience.
{% hint style="info" %}
[Learn more about our Progressive Disclosure pattern](#progressive-disclosure)
{% endhint %}
## Accessibility
* The first item is automatically given focus when the action menu is triggered with the keyboard
* Navigate through the list using the arrow keys
* Give focus to the list's parent element by pressing the `Esc` or `Shift+Tab` key while on the first item of the list.
* Activate the action using the `enter/return` key or the `space` key
## Key takeaways
{% hint style="success" %}
* Group semantically related action for a better readability
{% endhint %}
{% hint style="danger" %}
* Mix items with icons and items without icons
* Use 2 separators in a row
* Use a separator for the last item on the list
{% endhint %}
# Buttons
A central component to guide users through their experience in the platform. They trigger actions and let users know what their options are.
{% hint style="info" %}
This article is quite lengthy. To quickly find the information you're looking for, consider using the search.
{% endhint %}
## Overview
`Button` enable actions that are important to a user. They are not decorative elements. Instead, they direct users to complete important goals within an experience.
* 1 `Button` = 1 action = 1 label
* In most cases, `Buttons` are automatically displayed in a nested component such as `Page Title`, `Panel Header`, `Modal` , etc.
## Design Guidelines
Overview of Roma Button
Buttons are a central component for enabling users to take actions in our products. Roma offers a wide variety of buttons to better suit use-cases and interactions.
### Basic Buttons
{% tabs %}
{% tab title="Button" %}
`Buttons` are highly visual clickable elements that are used to trigger actions.
They allow users to interact with our product in various ways. `Button` is the main and most used one.
**Async capabilities :**
`Loading state` creates a specific interaction. It must be used only when the action involve a back-end operation that may take some time.
{% endtab %}
{% tab title="Counter Button" %}
`Counter Button` is to be used on very specific conditions. Because of its `Counter` props added after `Label`, this button is meant to trigger the action only on selected items. The user's selection automatically updates the counter.
Users **have to** select at least 1 item before triggering action. Until then, `Counter Button` should remain disabled or hidden to emphasize its action perimeter.
{% endtab %}
{% endtabs %}
Deciding which button to use : Button / Async Button / Counter Button
*Click on the image to open it*
These three buttons may look alike, but they display distinct behaviors based on the outcomes of their activation.
`Button` is the default component. The action is direct, and does not need any loading.\
*exemple : A button "Create" opening a form ; a button "Close" to exit a modale*
`Async Button` must be used only when the action involve a back-end operation that may take some time. It conveys the information to users back-end operation are ongoing.\
*exemple : A button "Save" to save an item creation form ; a button "Load more" to load list items*
`Counter Button` must be used only when the action concerns pre selected items.
### Buttons with overlay
{% tabs %}
{% tab title="Menu Button" %}
`Menu Button` allows presenting a large collection of actions to users without overloading the page content. The button triggers[`Action Menu`](/design/components/actions/action-menu) as an overlay. The final action is then triggered by the user's selection in the overlay.
Because of our tool's various features, some pages may propose many actions. Not all of them need to be offered to users at once.
While the most important actions must be highlighted by using [`Primary/Secondary Buttons`](/design/components/actions/buttons) and shown directly in the page content, other less important actions can be nested into a Menu Button.
`Menu Button` has its guidelines and props.
{% hint style="success" %}
* Use Menu Button not to overload the page with too many small actions.
* Follow Action Menu guidelines to display additional actions.
{% endhint %}
{% hint style="warning" %}
* Do not hide important actions behind Menu Button because of low discoverability.
{% endhint %}
{% endtab %}
{% tab title="Filter Button" %}
`Filter Button` should:
* Always be used in a toolbar (e.g. for [Datatable](/design/components/datatable))
* Have the same microcopy as the column you wish to filter
* Triggers a selection list
`Filter Button` can also have a tooltip that appears when hovering the button.
{% endtab %}
{% tab title="Split Button" %}
`Split Button` is a hybrid between a `Basic Button` and a `Menu Button` : it groups related commands into a dropdown but also offers one-click access to a default choice that does not require opening the menu.
It has two components: a `Button` with a label and an `Icon Button` with an arrow. Clicking the `Button` triggers the default action - the most used one. Clicking on the `Icon Button` opens up a list of other minor possible actions related to the default one.
Be careful when using `Split Button`. While it may seem like an obvious design pattern for some, options within the menu can have low discoverability for some users. In our research, we have found users don’t always recognize this pattern, so they may not notice the secondary menu button and, consequently, the options located within the menu. Therefore the default option should be strong enough to serve most use cases.
We mostly use it in the [`Save Bar`](/design/components/actions/save-bar) to offer an additional "Save as Draft" option to forms.
{% endtab %}
{% endtabs %}
Deciding which button to use : Menu Button / Split Button
Those buttons are a great way to reduce visual clutter. However, they introduce more complexity into the design: the additional step results in a decrease in action discoverability.
Use `Split Button` when you have one strongest action to propose compared to another one. For the user, clicking the main part triggers the primary action; clicking the right side reveals additional options.
Use `Menu Button` for equally important but secondary actions, accessible after a click. For the user, clicking the button in itself doesn't trigger an action but it reveals additional options.
### Navigation Buttons
{% tabs %}
{% tab title="Navigation Button" %}
Navigation Button is a button with an icon expliciting users they are going to navigate to another page
Use `Navigation Button` for users to perform actions on another page. This component distinguishes itself from `Hyperlink` or `Link Button` by emphasizing its functionality, allowing users to perform actions rather than solely navigate.\
*exemple : Go to a configuration page related to current page's focus*
{% endtab %}
{% tab title="Link Button" %}
`Link Button` allows creating a visual hierarchy for those minor actions. They look like links but are not. `Link Button` is meant to be used sparingly.
Some actions may not need to be as visually attractive as others. Those are *peripheral actions*. They bring added value to certain users in specific use cases, but yet those actions are still less important than others.
`Link Button` comes in 2 sizes : `Small` or `Default`. It has 3 available states: `Primary`, `Secondary` and `Tertiary`. A customizable icon can be added before or after `Label` but it is not mandatory. It has to bring added value to understand the action. For example, adding a down arrow to the "See more" label help users understand some content is hidden but may be shown just below.
{% hint style="success" %}
Use the right size to comply with the page's homogeneity.
{% endhint %}
{% endtab %}
{% endtabs %}
Deciding which button to use : Navigation Button / Link Button
Each of these components facilitates user navigation but with distinct objectives.
Use `Link Button` for minor navigation options. While this component offer the possibility to users to navigate to another related page, they are not the primary focus of the page. `Link button` are meant to be used as secondary optional navigation.\
*exemple : Go back to previous page*
Use `Navigation Button` to perform actions on another page. This component distinguishes itself from `Hyperlink` or `Link Button` by emphasizing its functionality, allowing users to perform actions rather than solely navigate.\
*exemple : Go to a configuration page related to current page's focus*
Use Hyperlink to point to external resources, providing users with additional information or directing them to relevant documents or online resources, such as help center.\
*exemple : Learn more about a feature*
#### When should I add a trailing icon to Navigation Button and Hyperlink ?
Include an 'External link' icon when URL points to an external link (outside the current product).
Users will be informed clicking on component will take them outside the current product. This transparency prevents confusion about whether they will remain within the current environment or navigate to an external source.\
Also, it enhances accessibility for users, especially those relying on screen readers or other assistive technologies. The 'External link' icon provides additional information about the nature of the link, aiding users with disabilities in understanding its context.
### Specific Use Cases Buttons
{% tabs %}
{% tab title="Icon Button" %}
`Icon Button` are buttons with **no label**. It contains only a visual indication of the action it performs.
Using `Icon Button` is a great way to stack multiple actions into a small space or to repeat the same action several times in the same view.
Because only an icon is not easily understandable by everyone, **it must be used only for common actions,** such as `Download`, `Delete`, `View`, `Copy` , etc.
For common actions, we must always use the same icon throughout our platform to facilitate our users' experience.
`Icon buttons` can use `Primary`, `Secondary` or `Ghost` variant depending on the context.
{% hint style="info" %}
[Learn more about Icon Button on a Datatable](https://design.mirakl.com/components/datatable#55a556-2)
{% endhint %}
{% endtab %}
{% tab title="Switch Button" %}
Also known as "Toggle", `Switch Button` allows users to switch between two mutually-exclusive states, such as:
* On/Off
* Show/Hide
* Activate/Deactivate
{% hint style="info" %}
Usually `Switch Button` is considered as a [selection control component](/design/components/form/selection-controls). However, we have decided to consider it a `Button` because it has an `Auto-Save` behavior, unlike other listed components in forms.
{% endhint %}
We mainly use `Switch Button` to swap between two views (Show/Hide elements). But it can also be used for use cases such as setting enablement (Activate/Deactivate).
Because **its state cannot be indeterminate,**`Switch Button` always has a **default value**. It is up to product teams to determine which one would be the best one depending on features.
#### Label and helptext
This component can be used with or without a `Label`. The `Label` can be placed on the right or the left of the switch. Note that adding a `Label` is relevant to explain to users the concrete consequences of their actions.
{% hint style="danger" %}
Do not change Switch label depending on its state. The label must be understandable in both states.
{% endhint %}
If `Label` seems too short to explain the action's consequences, a`Helptext` prop can be added. Then, formatting is automated for the label to appear on the left and the switch component on the right.
If disabled, a `tooltip` appearing while hovering the component can be added to explain why the action is unavailable.
### Save pattern
`Switch Button` has a generic autosave behavior, which means changes are saved without further actions from users. \
For critical changes, you may add a confirmation modal to make sure users understand what they are changing.
{% hint style="warning" %} **Don't** use `Switch Button` in forms because of save pattern. Use checkboxes instead.
{% endhint %}
{% endtab %}
{% tab title="Upload Button" %}
`Upload Button` is a standard-looking button, but its behavior is restricted to file upload.
It automatically handles file formatting and number acceptance.
{% endtab %}
{% endtabs %}
##
## Variations
### Variant
{% tabs %}
{% tab title="Primary" %}
Use a `Primary Button` to call the user's attention to the main action of a section or container.
This variant is dedicated to strong and important actions.
* `Primary Button` calls for important actions, it should be used mindfully. Our best guideline is to offer either a single `Primary Button` within the page title **or** one per container.
* It must never be doubled up to sit side by side.
* Not all pages require a `Primary Button`. Sometimes all actions are secondary to the content and of equal importance.
{% endtab %}
{% tab title="Secondary" %}
Use a `Secondary Button` for additional and less important actions within a page.
You can use several `Secondary buttons` on the same container, providing they serve the actual purpose of the feature.
{% endtab %}
{% tab title="Destructive" %}
Use `Destructive Button` for actions that will delete or disable something important.
{% hint style="danger" %}
Destructive actions must be validated using a non-skippable confirmation modal.
{% endhint %}
{% endtab %}
{% tab title="Ghost" %}
Use for minor actions on a page. In main cases, `Ghost Button` goes with a `Primary button` for additional actions, such as “Cancel" or “Clear”.
`Ghost Button` is used for minor actions that don't serve the actual purpose of the feature.
{% hint style="info" %}
If a button is placed within a page, it has to be included in a [spacing wrapper](broken://pages/byQut7ZugQiakNQSO64v).
{% endhint %}
{% endtab %}
{% endtabs %}
###
### Size
**In most cases, use Default Size.** The button height is set to 40px, but its width fits its content. Thus, be mindful when writing button microcopy. [Learn more on how to write labels for buttons](/design/components/actions/buttons#content)
The small size is reserved for tight spaces, such as `Datatable Toolbar`, `Panel Header`.
The tiny size is dedicated to the tiniest spaces.
{% hint style="info" %}
What about the Stretch variant?
`Button` has specific props:`Full width : True/False`. When activated, the button will fit the width of its container. It provides a Stretch effect.
This prop is to be used sparingly, mostly for tiny spaces such as mobile or small containers.
{% endhint %}
### State
Depending on users' interactions or action availability, buttons may be in various states
* `Default state` is how buttons appear by default with no user interactions
* `Hover state` is how buttons appear when the user moves their mouse over the component. While hovering, a `tooltip` may appear to provide more information about the action.
* `Loading state` is how buttons interact when users click on the component, but the platform needs time to process the action. This interaction is mandatory when the button describes an action (creation, edition) and should not be used when the button creates a redirection.
* `Disable state` is how buttons appear when the action is not clickable. Users will not be able to perform any action. A tooltip may appear to provide more information about the deactivation reasons.
## **Behaviors & Interactions**
### **Disable State or Hide Button?**
When an action is temporarily unavailable for reasons such as (but not only) :
* Technical update ongoing
* Roles allows a certain type of action, but a specific permission is required for an item
Then, use `Disable state` to display the button without allowing user interaction. Also, provide context through tooltips.
However, if the action is permanently inaccessible due to specific configurations such as (but not only) :
* Roles don't allows actions at all
Then, the button must be hidden. This way, the interface remains uncluttered and users are not presented with unnecessary options for them, reducing cognitive load and making the interface simpler to navigate. Hiding inaccessible buttons avoids confusion and frustration when users encounter non-functional elements.
**Exemple :** \
As a user, I usually use a Button to perform a recurring action to an item. I know perfectly where this button is.
But, it appear for once, i cannot perform this action as usual because the item status has changed.
Thus, Button is in disable state with a tooltip to explain why I cannot perform this action as I usually do.
But, if I didn't have the necessary permissions due to my role, I wouldn't have encountered this button previously.I would have never known about this action because I would have never had to perform it.
## Content
Buttons are clear and predictable. They drive users to the next action.
Capitalize the first word and don’t use punctuation
{% hint style="info" %}
Template: **\** or just **\**
{% endhint %}
{% hint style="success" %}
Send message
{% endhint %}
Avoid unnecessary words and articles (’the’, ‘a’, ‘new’)
{% hint style="success" %}
Preview profile
Import catalog
{% endhint %}
Reuse preexisting labels as much as possible, especially for common actions. It’ll help with adoption and scalability.
{% hint style="success" %}
Back, Continue, Delete
{% endhint %}
## Accessibility
{% hint style="info" %}
All Button size are compliant to [WGAC 2.5.8 Minimum Target Size](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html)
{% endhint %}
* In most cases, prefer using default-size buttons over small buttons. They are easier for users to notice and press.
# Button group
Button group is used to gather multiple actions.
Button Group with primary and secondary actions
## Overview
Use Button group when you have to display multiple buttons located in the same space. Button Group will help to space buttons out evenly.
It can contain the following combinations:
* 1 `Primary Button` + 1 `Secondary button` : when two actions are available, but one is more important than the other
* 2 `Secondary Buttons` : when two actions are available, and none is more important
* 1 `Primary Button` **OR** 1 `Secondary Button` + 1 [`Menu Button`](/design/components/actions/buttons#menu-button)`:` when there are more than two actions available, but one stands out, and others are regrouped in a sub-menu
* 2 `buttons` + 1 [`Menu Button`](/design/components/actions/buttons#menu-button)
## Guidelines
Buttons must be displayed in order of importance :
* `Primary Button` , if there is any, should always be displayed as the group's first action. ⚠️ Only one primary Action Button can be used in a Button Group.
* The `Secondary Button` comes afterward
* `Menu Button` comes last
💡 Please keep in mind that depending on the context, `Button group`can be displayed from left to right or from right to left.
{% hint style="success" %}
Use only one primary action
{% endhint %}
{% hint style="success" %}
Put primary action as the first button of the group
{% endhint %}
{% hint style="danger" %}
Do not use 2 primary actions
{% endhint %}
## Accessibility
While it's not a formal WGAC rule, it's considered good practice to maintain a minimum 8px spacing between buttons to prevent accidental clicks. This spacing is automatically managed by ROMA, so please avoid altering it for larger or smaller gaps
## Content
Button group content must follow [button guidelines](/design/components/actions/buttons#content).
# File download
This component allows users to download a file from Mirakl.
## Overview
{% hint style="info" %}
This component allows users to **download** a file from the platform, not upload one.
To upload any document into the platform, refer to [`Upload Button`](/design/components/actions/buttons#upload-button) a dedicated component to be used in a form.
{% endhint %}
This component has two mandatory fields:
* File name (specifying the file type). \
If the file name is too long to fit into the given space, we automatically include an ellipsis but always display the file format.
* File icon
This component has a optional fields:
* File size\
Specifying the file size is better because it provides users a useful information, aiding transparency from our side, download speed estimation, and data storage needed.
Each component can contain only one file. \
If multiple files are available for download, you must overstack the component
## Key takeaways
{% hint style="success" %}
* Include file size if possible
* Use one component per file
{% endhint %}
{% hint style="danger" %}
* Change the wording of the action (no "Download here")
{% endhint %}
# Save bar
A Save Bar is an action bar that sticks to the bottom of the viewport as you scroll. It contains actions related to a page and allow users to scroll without loosing visibility on the different actions
## Overview
Save Bar is always located at the bottom of the screen and stays fixed as you scroll through the page. It appears after a user performs an action (edit a form, tick a checkbox, etc.) from the bottom and should persist until the task is submitted or canceled.
Sticky Save should be used to save or discard in-progress changes. It contains a `Button Group` with a Save button as a primary action and a cancel button.
Sticky save should be used on all forms and is visible when there are unsaved changes.
To limit the user's mental load, we restrict `Save Bar` actions to two `Buttons` : "**Save**" (as a `Primary Button`) and "**Cancel**" (as a `Secondary Button`)**.**
Sometimes, we may want to offer users a third option: "**Save as draft**". As this option isn't prevalent in all of our forms, we decided to introduce a specific pattern with "**Save**" as a Primary Split Button and "**Save as draft**" as a Split option.
## Guidelines
### **How to use**
`Save Bar` behavior is automated by Roma; it will always stick to the bottom of the page and allow the user to scroll down the page.
The Save Bar has been created to be visible enough for users to notice it without disturbing them to perform their actions.
{% hint style="info" %}
[Learn more on how to use Save Bar in a form, depending on the form mode (creation or edition)](https://design.mirakl.com/~/changes/DpgERwSwrKIthStzL4D6/patterns/forms/creation-and-edition-modes)
{% endhint %}
## Key takeaways
{% hint style="success" %}
* Align Save Bar buttons with page content
* Respect Button content guidelines
{% endhint %}
{% hint style="danger" %}
* Do not show Save Bar if no actions are required from users
* Do not display more than 2 actions in the Save Bar
{% endhint %}
# Tasklist
Task lists are created to present users with a series of tasks they need to accomplish in order to complete a more intricate process, such as creating a store or profile.
## Overview
This component can be used as a to-do list or checklist. It is a simple and effective tool for organizing and managing tasks.
`Task lists` is a valuable tool to organise a workflow and ensuring that important actions are completed in an efficient manner. They are highly adaptable and can be customized to suit specific project requirements.
## Layout
#### Steps
Each step is made of:
* a status icon
* a title
* a paragraph
* an illustration (optional, will not be displayed on small screens)
* 1 or 2 buttons
Status
Description
Example
To do
Icon is blank
Collapsed
Active
Icon is blank
Expanded
Can have 2 buttons (one Primary and one Secondary)
Done
Icon is ticked + green
Can be expanded or collapsed
Disabled
Icon is blank
Collapsed
## Guidelines
### Modes
`Tasklist` has 2 modes :
* **Linear mode.** In Linear mode, tasks must be executed in the listed order. This mode is particularly suited for cases where task dependencies exist, with certain tasks relying on the completion of preceding ones.
* **Flexible mode**. In Flexible mode, tasks can be completed in any order, offering users more freedom in how they choose to complete their tasks, while still ensuring that all of it must be executed.
### Number of item
The component **does not** set a strict limit on the number of tasks, but it is prudent to maintain a reasonable quantity, keeping the user's cognitive load in mind. An excessively long list can be overwhelming, potentially causing users to lose motivation and become disoriented in their actions.
Grouping actions or requests with similar themes into tasks, such as 'Configure your shipping settings' or 'Import your catalog,' aids reduce the number of item and keeping the tasks list digest.
### Marking tasks as completed
Some tasks may not be suitable for automatic completion marking. In these cases, users must manually mark them as 'done' using a `Secondary Button` labeled 'Mark as done.' This feature empowers users to explicitly confirm task completion, enhancing task management and offering clear progress tracking.
### Content
Think of the tasklist as a step-by-step guide for our users to complete their tasks.
#### Step label
Starting with a verb will help drive users to the next action.
* Start with a verb, unless you have to repeat the same verb over and over
* Keep it short and clear
{% hint style="success" %}
Complete the report
{% endhint %}
#### Step description
Consider adding a description to describe the task, to add more details, and to explain its purpose.
* Keep it under one sentence
* Add a hyperlink if necessary
* Remove articles (a/the) if you can
{% hint style="info" %}
**Step title**: <2 to 3 words, action verb or not>
**Step subtitle**: <1 actionable sentence, clear and helpful to specify the task, or describe it >
{% endhint %}
## Key Takeaways
{% hint style="success" %} **Do**
* Choose the right task list mode (flexible or specific)
* Keep the task quantity manageable
* Use concise action titles and consider subtitles for additional information
{% endhint %}
{% hint style="danger" %} **Don't**
* Avoid long, overwhelming task lists.
* Only add non-relevant illustrations to tasks.
{% endhint %}
# Contextual Toolbar
Convert a single page into a dynamic interface by granting users efficient control for visualizing and managing displayed data.
Illustration of a contextual toolbar
The **Contextual Toolbar** is a versatile component designed to let users managing the context of data on a page efficiently.
Integrating [pickers](/design/components/form/pickers) and filters, it provides users a granular control over the displayed information and transform a single page into a dynamic interface.
## When to use
Contextual Toolbar is useful for interface displaying multiple data, such as dashboards or complex DataTables or DataLists.
It differs from simple filters as it enables the display of the same items but with different data attached, depending on the context.
Below is an example of how the same DataTable with and without a Contextual Toolbar. The use of the toolbar enhances readability by eliminating a column (channel) and concatenating multiple rows (items).
## How to use ?
Contextual Toolbar is a versatile component. From a technical point of view, it can be used freely : at a page level, in a panel or in a card.
When used alongside a DataTable or DataList with integrated toolbars, the Contextual Toolbar should avoid replicating identical filters, maintaining separate functionalities.
# Datalist
Datalists display objects of the same type in a lean and clear way.
## Overview
Datalists are designed to list objects of similar types without the hassle of a datatable.
Datalist should be used:
* To display a collection of similar items (order lines, marketplaces, stores...)
Datalist should not be used:
* To display complex data (use [Datatable](/design/components/datatable))
* If users need to search and filter on multiple columns (use [Datatable](/design/components/datatable))
* To highlight part of a data set (use **Data Visualization**)
* If you need users to export data (use [Datatable](/design/components/datatable))
{% hint style="info" %}
Having trouble deciding between Datalist and Datatable? \
Head over to the [Displaying data pattern](/design/patterns/displaying-data)
{% endhint %}
## Design Guidelines
1\. **Title (*****Mandatory) :*** clearly states the content of the datatable.
2\. **Toolbar**: has interactive elements such as a search bar and filters. Also has options like letting users manage visual display and a call to action to add content to the data set.
3\. **Rows**: show different data types with actions to edit and manage them.
{% tabs %}
{% tab title="Toolbar" %}
Provides various tools and options to interact with the data displayed in the table.
The datalist toolbar can have different elements:
* Search (standard or on a specific column)
* Filters
* Number of items or results
* Sorting (via Filter button)
* Action button
{% endtab %}
{% tab title="Rows" %}
A row displays information related to a single item.
There are 4 different row types:
* Expandable: when clicked, the row expands to display extra information
* Removable: when the close button is clicked, the row disappears
* With action menu: when the action is clicked, a drop-down menu appears
* Checkable: when the checkbox is clicked, the row is selected
**Rows have a fully customizable layout, but each row within the datalist must have the same layout**
{% endtab %}
{% endtabs %}
### Variant
Datalist exist in Row version and in Grid Version
exemple of a Datalist in grid version
### Behaviors & Interactions
Datalist has features that let users interact with the content:
* Layout in line; each element can have its own height depending on its content
* Lines have an action menu and can be expandable or removable
* Density and column width are managed automatically, with no horizontal scroll
* Load more CTA and no automatic pagination
* Responsive management is done inside the row, not at the datalist level.
### Loading
When datalists items are loading :
Skeleton loading is fully automated for `Datalist.` [Learn more about Loading patterns](/design/patterns/loading)
### Empty state
Empty state behavior and microcopy are automatically handled.
[Learn more about writing empty states](/design/components/feedback/empty-state)
# Datatable
Datatables are designed to present information consistently, facilitating easy data comparison
{% hint style="info" %}
This article is quite lengthy. To quickly find the information you're looking for, consider using the intelligent search.
{% endhint %}
## **Overview**
**Datatables are a core component of our products**, designed to present information in a structured grid format with rows and columns. This format simplifies data comprehension and helps users in managing their content
Datatable should be used:
* to display complex data in an easy-to-scan way,
* if users need to sort on multiple columns,
* if users need column titles to make sure the context and content are clear,
* if data needs to be displayed in a controlled way (using pre-formatted cells).
Datatable should not be used:
* To display a collection of items with an elaborate layout (use [Datalist](/design/components/datalist)),
* To highlight part of a data set (use **Data Visualization**).
* If data is not structured or with variable content
{% hint style="info" %}
Having trouble deciding between Datalist and Datatable? \
Head over to the [Displaying data pattern](/design/patterns/displaying-data)
{% endhint %}
## Design Guidelines
1\. **Title *****:*** clearly states the content of the datatable.
{% hint style="info" %}
For further details on each listed element, please refer to the dedicated subpage.
{% endhint %}
2\. **Toolbar**
3\. **Columns**
4\. **Rows**
5\. **Scrollbar**
6\. **Footer and pagination**
{% tabs %}
{% tab title="Toolbar" %}
The toolbar includes a search bar, filters, and options for managing displays and adding content.\
Available elements include:
* Search (standard or column-specific with a drop-down selector)
* **Item count (mandatory)**
* Column management
* **Density management (mandatory)**
* Export (only on visible data)
* Action button
* Refresh (disabled while reordering)
* Filters
For 3 or fewer filters, use the Quick Filters layout. For more than 3 filters, use the Filters Drawer, which opens on the right side of the screen.
{% endtab %}
{% tab title="Columns" %}
Column width is defined by the largest content (cell and header) within a limit of 500 px. The width is overridable. Otherwise, the content is cut with an ellipsis.
**Datatables are sorted by default.** Feature teams define which column is used to sort the datatable. It can be sorted by identifier, by date/time, by status...\
The sort must be visible, on the left side, to help users understand how data is sorted.
* **At least one column must provide a sortable property**.
* Sortable properties are exclusive. It means if two or more columns provide a sortable property, they can not be active at the same time.
* Sort property can only be deactivated when search is active. When user type for an item in the search bar, sort is not mandatory.
{% endtab %}
{% tab title="Rows" %}
A row displays information related to a single item.
#### Row States :
* **Default:** row is clear, and actions are available. This is the standard row behavior.
* **Disabled:** row is greyed out, and actions are unavailable. For example, you may use it when a product is rejected, and no action can be taken to change its status.
* **Highlighted:** row has a ribbon to highlight it
* **Dimmed:** row is greyed out, but actions are still available. For example, you may use it when a product has been excluded from a selection, but you can reactivate it later.
#### Rows Types
* **Selection :** rows are selectable and selection is managed with the bulk.
* **Reorder:** rows can be reordered by user action. \
The drag functionality is shown but disabled when the table contains only a single row.
{% hint style="info" %}
In our products, we commonly utilize the 'reorder' datatable type to prioritize custom rules based on their importance. \
It's essential to remind users, in such scenarios, their rules will be processed by their ranking.
{% endhint %}
{% hint style="warning" %}
When using the reorder function, datatable cannot have pagination.
{% endhint %}
#### Rows Size
Rows are available in three sizes: *compact*, *default* (used by default), and *comfortable*. Users can change size with the density button in the filter bar. This option is automatically handled.
{% endtab %}
{% tab title="Cells" %}
They are 9 Cell Types for Datatables :
**1. TextCellContent**
* **Description**: Displays text with optional subtext, media, actions, and a trailing icon for tooltips.
* **Options**:
* **Sizes**: Default / Comfortable / Compact
* **Actions**: No action, expandable, view, edit, or external link.
* **Media**: Available for Default and Comfortable sizes.
TextCellContent
**2. BadgeCellContent**
* **Description**: Displays up to 3 badges, each with an optional tooltip. More than 3 badges are expandable.
* **Options**:
* **Statuses**: Custom badge statuses.
BadgeCellContent
**3. DateCellContent**
* **Description**: Displays dates with optional subtext, statuses, and a trailing icon for additional information (e.g., late, help).
* **Options**:
* Expandable, subtext, trailing icon, and statuses.
DateCellContent
**4. IconListCellContent**
* **Description**: Displays a list of icons, each with a name, status, and automatic tooltip.
* **Options**:
* **Icon Statuses**: Pending (purple), Warning (orange), Error (red), Success (green), Default (grey).
* Icons should never be empty; use disabled status if needed.
IconListCellContent
**5. MonetaryCellContent**
* **Description**: Displays numeric monetary values, aligned to the right.
* **Options**:
* Expandable or edit actions, optional subtext, icons, and various statuses.
* Currency symbol can be placed before or after the number.
MonetaryCellContent
**6. NumericCellContent**
* **Description**: Displays numeric content (non-currency), aligned to the right.
* All numeric content HAVE to be displayed with this cell type ; not as paragraph
* **Options**:
* Same options as MonetaryCellContent but without the currency symbol.
**7. ParagraphCellContent**
* **Description**: Displays a paragraph with automatic truncation to 2 lines.
* **Options**:
* No statuses, subtext, or actions; solely for displaying long text.
ParagraphCellContent
**8. RatingCellContent**
* **Description**: Displays rating content with optional subtext, expandable action, or tooltip.
* **Options**:
* **Variants**: Rating with stars or numeric text-only.
* Same statuses as TextCellContent.
RatingCellContent
**9. StatusCellContent**
* **Description**: Displays a single status with optional tooltip.
* **Options**:
* **Icon Statuses**: Pending (purple), Warning (orange), Error (red), Success (green), Default (grey).
* Can be expandable.
StatusCellContent
{% endtab %}
{% tab title="Footer & pagination" %}
On Datatable's footer, users can manage pagination :
* Manage number of items per page
* Navigate through the pages
Each project has the flexibility to set its own pagination thresholds, which should be determined based on the average number of results.
**We recommend using thresholds of 50, 100, and 200 items per page.**
If your datatable is expected to display a smaller number of items, you can opt for lower thresholds.
**Navigation elements are consistently visible on the datatable.**
* In cases where the current page corresponds to either the first or last page, the pagination controls are displayed, but the navigation buttons are disabled.
* In cases where the current number of item is lower than the first threshold, the pagination controls are displayed, but the navigation buttons are disabled.
When your Datatable contains a significant amount of data, such as more than 1,234 results, we display a universally formatted number, typically around +1,000.
{% endtab %}
{% endtabs %}
## Behaviors & Interactions
The datatable allows users to:
* Sort by column headers
* Filter data subsets
* Perform single or bulk actions
* Export data in various formats
* Add or reorder data
* Navigate via pagination
### Default item
In a datatable, **only one item can be designated as the 'default.**'
'Default' status is designed with a simple "Default" mark inlined with the Label of the cell.
### Expand cells
Cells may contain extensive or highly detailed information that could potentially overwhelm the datatable's presentation. But also, opening a separate detailed page might appear excessive. To strike a balance, we have introduced 'expand' properties for select cells.
Expandable cells are recognized with a chevron. Extra content is displayed in a [popover ](/design/components/overlays/popover)cell. Content can be structured and with a button if needed.
### **Actions on a Datatable**
Datatables support bulk and individual actions, with varied behavior based on user interactions.
To get more details about a row, the first cell ("TextCellContent") must have either the "view" action (open object) or "external link" action (open in a new window). In these cases, the first action in the [action menu](/design/components/actions/action-menu) should always be "View Details."
Below are listed all ways we design action, wether its individual or bulk actions :
#### Individual action
Individual quick actions for a single row are available to users, these actions are consistently presented at the end of the row. Three options are available :
* Actions displayed as icon buttons for common actions such as Download, Delete, View, Copy, etc. (**Must be IconButton in Secondary Variant**)
* Actions displayed as secondary buttons for less common actions that may not be easily understood through icons. (**Must be Button in Secondary Variant**)
* Actions accessible via an action menu for multiple choice of actions.
#### Bulk actions
Datatable enables users to select individual rows or multiple rows for performing actions.
Once selected, a bulk action bar will appear, offering a single action (primary button) or more action options ([button group](/design/components/actions/button-group)). \
Actions listed on the bulk bar actions must always remain the same ; they cannot change based on the selection or filters.
The selection bar allows to quickly select all items in the dataset, all items on the current page, or to deselect all items. However, once all items are selected in a datatable through this option, individual deselection is not possible.
Users can select all elements in a filtered dataset by first applying a filter to the data and then using the 'select all from this page' option.
### Scrolling
#### **Horizontal**
When the content of a row is longer than the width of the panel, a floating trailing action is displayed. It ensures the user can perform an action on a row without scrolling.
#### **Fixed header**
The column header is pinned while scrolling to ensure the readability of the cell content. The horizontal scrollbar is pinned to the bottom of the viewport to ensure it will always be visible and easily reached.
### Loading
When datatable's items are loading :
Skeleton loading is fully automated for `Datatable.` [Learn more about Loading patterns](/design/patterns/loading)
### Empty state
Empty state behavior and microcopy are automatically handled.
Content for any other type of empty state has to be defined for each project.
The toolbar (with the options you chose to add) is displayed in disabled mode, and the primary action is disabled. The same action is moved to the empty state.
The empty state action is the same as the toolbar's, but you may override it. \
[Learn more about writing empty states](/design/components/feedback/empty-state)
# Feedback
Alert
Alerts highlight important information that needs to be communicated quickly to the user.
# Alerts
Alerts highlight important information that needs to be communicated quickly to the user.
## Overview
Alerts are meant to attract users' attention and provide them contextual information. Use them cautiously, as they can become overwhelming.
## Guidelines
An alert is always composed of at least an icon and a title. \
The dismissible feature is optional, displayed with a close icon in the top right corner. \
Short description (children prop) and Action Button are optional.
{% hint style="warning" %}
**Only one CTA can be displayed in an alert.** It can be used to perform a direct action or redirect users to another page.
{% endhint %}
{% hint style="info" %}
If more documentation is available, add a hyperlink `"Learn more about ..."` at the end of a description.
{% endhint %}
Example of an Alert with a title, description, hyperlink, dismissible icon and CTA
### When to use
* **Immediate Attention Required:** Utilize Alerts to convey essential information that demands the user's immediate attention.
* **Contextual Information:** Implement Alerts to offer contextual guidance or feedback in response to user actions, enhancing their understanding and decision-making process.
### When not to use
* **Non-Essential Information:** Avoid using Alerts for non-essential information that could detract from the user experience, such as promotional content or marketing messages.
* **Overuse:** Refrain from excessive use of Alerts, as this can lead to user desensitization to important messages and potentially overwhelm the user.
## Variants
Alerts convey different levels of severity. We have determined 5 stages of severity: from general information to critical issues.
Each of the 5 levels has its design style:
Type
Color
Icon
Info displayed
Loading
Blue
loading
Display information about a loading item
Info
Blue
info
Display general information
Success
Green
check_circle
Inform about the success of a previously performed action
Warning
Yellow
warning
Display important information that the user should notice or take action on
Error
Red
error
Alert about a very critical issue (suspension, errors, etc)
### LoadingAlert
Loading Alert is a variant of `Alert` to be used when users are uploading a file into the platform. \
This component is a piece of visual information informing users their request is being processed and should wait until its completion.
Loading Alert is an `Info Alert` (blue) with a `spinner icon`
## Alert Compact
`Alert Compact` is a streamlined version of the standard `Alert`, optimized for use in constrained spaces where only a succinct message is necessary, with no actions.\
It is ideal for panels, modals or sections of the interface where minimalistic feedback is required.
`Alert Compact` is a component in itself, not a variant of `Alert`.
exemple of Alert Compact use in a panel
{% hint style="warning" %}
You cannot use this alert in Date Time Range Modals
{% endhint %}
## Content
An alert focuses on a specific topic or piece of information and provide only one main call to action.
#### Title
The text should be concise and clear so that users understand right away what's going on on the page. Capitalize only on the first word, with no period at the end.
{% hint style="info" %}
Template: **< 2 to 3 words>**
{% endhint %}
#### Body
* 1 to 2 sentences
* Capitalize the first word, use full stop
* Avoid repeating the heading
* Avoid phrases like ‘You can’. They are not decisive enough for users
#### Informative
Add any information to help the user understand what's happening on the page.
{% hint style="info" %}
Template: **< 1 sentence to help users understand what’s happening now >**
{% endhint %}
#### Success
Explain the impact of the action and what's going to happen next.
{% hint style="info" %}
Template: **< 1 sentence to explain what’s going to happen next >**
{% endhint %}
#### Warning and error
Explain how the user can fix what went wrong. You may add a hyperlink to redirect users to the documentation if needed.
{% hint style="info" %}
Template: **< 1 solution-oriented sentence to help users fix what went wrong >**
{% endhint %}
#### Button
Microcopy should follow [button guidelines](/design/components/actions/buttons#content).
{% hint style="info" %}
Template: < Action verb (+ noun) >
{% endhint %}
## Accessibility
To communicate the level of severity, we combine a color pattern with a specific icon. \
**Do not change the icon under any circumstance**, as colors are not perceived the same way by everyone (disabilities, cultures ...).
## Key takeaways
{% hint style="success" %}
* Keep labels and descriptions clear and concise
* Set clear expectations on user's action in the title
* Display only one action per alert
* Add a link to the documentation if more information is available
{% endhint %}
{% hint style="danger" %}
* Do not change icons
* Do not forget the title (never display only the description and CTA)
* Do not use "Please" or "Thank you" or Latinisms
* Do not add actions to Compact Alert
{% endhint %}
# Activity Loader
A component that indicates to users that we're processing their data or that a page is loading.
## Overview
A good loading strategy is essential to design a seamless experience for users. The activity loader is one of the components to achieve that goal.
With a simple message that appears on the screen, the activity loader informs users that Mirakl is performing an action under the hood.
The component has a title and a progress bar (mandatory), and one or several subtitles (optional).
## Guidelines
{% hint style="info" %}
Do not overuse the activity loader, as it can create uncertainty.
{% endhint %}
### When to use
Loaders should be used:
* when users are waiting for Mirakl to process a task.
### When not to use
Loaders should not be used:
* when the task is known to take some time, importing large amounts of data, for example, as it can bring uncertainty.
* when the task is known to take very little time. Avoid the strobe effect.
{% hint style="info" %}
[Learn more about loading patterns](/design/patterns/loading)
{% endhint %}
# Badge (status)
Badges are used to show the status of an object or the result of an action that has been performed.
## Overview
Badges convey information to users (status, actions) that needs to be quickly processed visually.
It needs to be easily understandable and consistent across the Mirakl ecosystem.
Badges vary in **status** (colors), **size** (`Default` or `Small`) and **importance** (`Primary` or `Secondary`):
|  |
New:
When a new item has been created. This status helps to distinguish new objects from old ones.
When an item has reached its final step and no more action is required/requested.
This status helps to fade out items that don't require attention.
|
Associated label:
Done, Closed, Voided, Deleted, Disabled
|
|
|
Info:
When an item needs to be labeled with a tag but is not part of a specific process (platform model, currency...).
|
|
## Guidelines
`Badges` has to be displayed the closest and right after the element it is related to.
* in a Page Title, after the title itself, up to two Badges max. [See Page Title properties](/design/components/navigation/page-title)
* in a panel, after its title, up to two Badges max.
* in a datatable inside a dedicated cell, one badge per cell.
{% hint style="info" %}
🥊 **Primary VS Secondary? Default VS Small?**
In most cases, favor the use of `Primary Default Badge`.
* `Secondary Badge` can be used to help structure information hierarchy when a tag is not as important as another element on the page.
* `Small Badge` are mostly used for responsive use cases or smaller panels.
{% endhint %}
### **When to use**
* Use `Badges` when an object can be mapped into multiple states, and the user needs a way to differentiate between them.
### **When not to use**
* Do not use `Badges` as a counter (quantifying the number of objects).
### How to use the Tooltip ?
When `Badge` label is not explicit enough, adding a tooltip is a good way to convey additional information without overloading the component or creating confusing labels.
The (?) indicating the presence of a tooltip is placed inside the badge to clearly state additional information is available regarding the status.
{% hint style="danger" %}
Do not add a custom overlay to the badge to provide additional information. The tooltip's role is to inform when a badge has additional information. Without the tooltip indicator, users will not know additional information is available.
{% endhint %}
## Content
* Reuse preset labels as much as possible. A list is available in Figma variables.
* Don’t rely only on colors and provide easily scannable text for everyone.
## Accessibility
Badges convey information using a combination of colors and text. Because colors are not perceived the same way by everyone (disabilities, cultures ...), make sure to use clear, short, and easily scannable text.
This component has been developed to meet accessibility guidelines (use of color, minimum contrast...). Do not interfere with it.
## Key takeaways
{% hint style="success" %}
* Favor the use of Primary Default Badge
* Add a tooltip right next to the badge to provide additional information
* For more consistency, reuse existing and approved microcopy
{% endhint %}
{% hint style="danger" %}
* Do not use more than two badges next to each other
* Do nos customize an overlay directly on the badge to provide additional information
* Do not use overcomplicated labels
{% endhint %}
# Empty state
Empty states should be used when the expected content cannot be displayed. It sets expectations and indicates the reasons for this blank space.
## Overview
The `Empty State` is a customizable component you can use when the real content is not available. It informs users why content is not shown or cannot be displayed.
This component is a great help to create or maintain communication with users in various situations: error management, no results after a search, or no objects in a panel.
The `Empty State` component is fully customizable; therefore, it has a large number of variants:
* `Illustration`is **optional but highly recommended**; its size varies: "small", "medium" or "large". **Illustrations must convey the right message:** be mindful when choosing them.
* `Title` (Heading/H2) is **mandatory.** Heading must be concise as it summarizes the situation.
* `Subtitle` (Paragraph) is **optional.** It always needs to go with a title. Subtitles are meant to clarify the title and bring additional information if needed. Don't repeat the heading in paragraph text, and don't add a subtitle if it doesn't add any value.
* `Action Button` is **optional**. \
Sometimes, user don't have anything to resolve the empty state, thus `Action Button` is not needed. \
But, in case users need to perform a specific action to resolve the Empty State, adding an `Action Button` help them understand what they need to do. \
If more than one action is available to resolve the situation, you can use a `Group Button`.
The component takes over the expected content. As soon as an `Empty State` appears in a panel, there cannot be any other kind of content (text, title, datatable, etc.) in the same panel.
{% hint style="success" %} **Do**
Replace all content of a panel by Empty State Component
{% endhint %}
Correct Empty State
{% hint style="danger" %} **Don’t**\
Mix Empty State component with actual content
{% endhint %}
Incorrect Empty State
## Content
An empty state shows users that the content they are looking for doesn't exist yet, preventing any kind of confusion. It‘s an opportunity to educate users towards their next action. We can also use it to highlight the benefit of a feature.
An empty state should:
* **Be clear:** To help users better understand what to do next.
* **Give direction and educate the customer:** let users know what are the next steps.
* **Be encouraging and inspire confidence:** use approachable copy and never make users feel unsuccessful or guilty because they see an empty state.
If users land on a page they don't have permission to view, explain it clearly.
## **How to use**
### **First time on a feature**
*When the user sees a feature for the first time, aka FTU (First Time Use).*
{% hint style="info" %}
Title: \
{% endhint %}
The description is here to explain what will happen when users start using this feature.
{% hint style="info" %}
Body: < Describe the first use case for this feature. Drive users to the next action to start seeing content here.>
{% endhint %}
The optional button can guide users towards the creation of a first object.
### Onboarding or configuration process
*When the user sees a feature for the first time and is encouraged to take action.*
In this specific context, users must be encouraged to take action\
Title and description should be action-driven and describe what will be expected from the user.
{% hint style="info" %}
Title: \
\ \
or \
{% endhint %}
{% hint style="info" %}
Body: \
{% endhint %}
### Datatable or Datalist
When a `Datatable` or a `Datalist` is empty, only display the toolbar + Pagination (all disable) and the empty state (medium size, not editable). \
Column titles, action buttons, etc., must be removed.
exemple of empty state in datatable
It's up to each project to decide if their empty `Datatable` / `Datalist` needs an action button to help users take action. \
The `Empty State Action Button` can differ from the `Datatable` / `Datalist Action Button` that will be displayed later on.
### No results
*When users have searched for specific data, but no results match.*
{% hint style="info" %}
Automatically handled by ROMA for`Datatable` and `Datalist`.
{% endhint %}
Content guideline : "No results found. Try different search term or update filters."
Title and description should make it obvious that there are no results after searching for an item or filtering data and encourage users to check their search input and update filters.
### Error management
*When the user faces network or generic technical issues preventing us from showing them the data they are looking for.*
{% hint style="info" %}
Automatically handled by ROMA for `Datatable` and `Datalist`.
{% endhint %}
Content guideline : There was a problem \[**verb**]-ing \[**object**]. Refresh the page or try again later.
Title and description should be clear and transparent on what is happening and if the user can do anything about it.
## **When not to use**
Do not use empty states:
* to display marketing information or feature promotion.
* to display important contextual information covered by the [Alert](/design/components/feedback/alerts) component.
## Key takeaways
{% hint style="success" %}
* Choose the right illustration to convey the information
* Add a [button](/design/components/actions/buttons) if it guides users through a process
* Include a heading that summarizes the situation in a short sentence and add a subtitle if more explanation is needed
{% endhint %}
{% hint style="danger" %}
* Forget to select an illustration
* Add more than one button
* Write long and complex headings and/or paragraphs. Use both elements to simplify mental load.
{% endhint %}
# Snackbar
A discreet but efficient way to convey feedback on the outcome of an action.
## Overview
Snackbars inform users when a backend action is done.\
They pop up briefly at the bottom of the screen, explaining the outcome without being too intrusive.
### When to use ?
Use snackbars to quickly share results, whether good or bad. \
*For example: 'Item added' or 'Item deleted'*
Snackbar should not be used to display critical information; use [alerts](/design/components/feedback/alerts) instead.\
*For example: 'You cannot perform this action because your profile has not been verified'*
## Design guidelines
Snackbars can only have one [button](/design/components/actions/buttons).
{% hint style="info" %}
**Prototyping a Snackbar on Figma for designers**
* Trigger : onClick **OR** onDelay - 50ms
* Animation type : Custom Spring
* Duration: 300ms
{% endhint %}
## Content
**Keep it short**
Snackbars are visible for 5 seconds, users won’t have time to read a long sentence. If you need more than one sentence consider using another component.
**Use simple words**
Use everyday language and generic terms as much as possible, it’ll be easier to reuse.
**Capitalize the first word, no period**
{% hint style="info" %}
**Template**: Object + verb+ED
{% endhint %}
# Form
A page that has interactive controls with which a user can submit information to a web server.
### Forms at Mirakl
Forms represent a great deal in Mirakl's products. Our users encounter forms in various situations: to fill in information, to manage settings, or to create objects...
As a recurring pattern in our products, we aim to provide a consistent form experience. To do so, we described in this section each form component guideline.
Learn more about [form behavior](/design/patterns/forms) (save/cancel behavior, error management, ...) in our [Patterns section](broken://pages/vu7c3Prmeh2lyI38WJAo).
***
Fields
Fields allow users to enter an input. They will provide answers we cannot foresee unlike pickers.
# Fields
Fields allow users to enter an input. They will provide answers we cannot foresee unlike pickers.
{% hint style="info" %}
This article is quite lengthy. To quickly find the information you're looking for, consider using the search.
{% endhint %}
## Overview
Different types of fields can be used in forms. Each one of them represents a precise type of information to collect. Make sure to use the right field for the right type of information to guide users when filling out a form.
Decision tree to choose which field to used based on your use case
{% hint style="info" %}
We do not recommend using Placeholder text for most of our form fields, as it is not accessible and disappears when users start typing their information. Use `Helptext` instead to convey extra information to help fill in the field. [Learn more about Placeholder text and Helptext](#content)
{% endhint %}
## Text Fields
In the following tabs, you will find all informations for fields containing textual inputs.
{% tabs %}
{% tab title="Text Fields" %}
`Text Field` is the most basic form element. It provides a single-line, plain-text input control. It should be used when we expect a short answer from users.
We provide multiple optional features to custom the field, such as: `Label`, `Requirement Indicator` (red asterisk), `Tooltip`, `Suffix` or `Prefix`, `Placeholder` and `Helptext.`
{% endtab %}
{% tab title="Text Area Field" %}
`Text Area Field` is different from `Text Field` because it allows users to write more than a single-line answer. This component would be preferred for use cases such as messaging, comments, or descriptions.
It has almost the same options as `Text Field`, including `has counter,`only without `Prefix` and `Suffix` options.
It comes in 3 sizes to adapt to each use case : `Small` (72px height), `Default` (96px height) and `Large` (300px height).
If needed, users can interact with the field at its bottom-right corner to expand it.
{% endtab %}
{% tab title="Email Field" %}
`Email Field` is a specific form element. **It must only be used to provide mail information.** This field cannot be used to collect other information than mail. This component is subject to a technical format validation: users will have to enter a mail format to validate this field. Otherwise, the field will be in an error state.
A mail icon helps users differentiate this specific field from any other field. It is automatically included in the component and cannot be removed.
Like `Text Field`, optional features are available to custom the field only without `Prefix` and `Suffix` options.
{% endtab %}
{% tab title="Password Field" %}
The `Password Field` is dedicated **exclusively to handling passwords** and should not be repurposed for other use cases. This component includes crucial security features and behaviors.
The 'Show/Hide' functionality, triggered by clicking the eye icon, allows users to reveal or hide the password. This feature is integral to the component and cannot be removed.
Additionally, to provide higher security if needed, another props called 'hidePasswordVisibilityButton' allows control of preview button's visibility :
* During creation, the preview button is displayed.
* When editing, the preview button is hidden, a placeholder value in the field indicate the field has a value saved. But if the field goes on focus, the value is cleared and redisplay the preview button.
{% endtab %}
{% endtabs %}
## Number Fields
In the following tabs, you will find all informations for fields containing inputs with numbers.
{% tabs %}
{% tab title="Float Number Field" %}
`Float Number Field` is a specific form element that only accepts numeric inputs. It can be used for use cases such as percentages, measurement, and delays.
**Do not use this component for monetary information**, use dedicated `Monetary Field`
Use Prefix props (`Select` or `String` Prefix) to indicate the expected unit for user input.
* `Select Prefix` : allow users to choose a unit between at least two options.
* `String Prefix` : visual help to understand which unit number is required. Users cannot change it.
Number formatting is automatically defined by the user's locale. It helps for auto-formatting while OnBlur (decimal, thousand, separator).
{% endtab %}
{% tab title="Integer Number Field" %}
`Integer Number Field` is a specific form element that **only accepts whole number inputs**. While it can be positive or negative numbers, **it just cannot allow separators**. It can be used for use cases such as delays and stocks.
While this field has the same optional features as other fields, it also automatically comes with a `Stepper Control` to allow quick small adjustments. In this field, users can use their keyboard to increase/decrease value
The valid input range of an `Integer Number Field` can be set by defining minimum and maximum values. In this case, use `helptext` to provide information about the range.
{% endtab %}
{% tab title="Monetary Field" %}
`Monetary Field` is a specific form element that only accepts numeric inputs. It does allow separators. This field can only be used for monetary use cases such as setting a price or a price reduction.
Like `Float Number Field`, this field also comes with `Prefix` features:
* `Select Prefix` : allow users to choose a unit between at least two options.
* `String Prefix` : visual help to understand which unit number is required; users cannot change it.
Another customization option is available: `currencyDisplay` which allows defining which code of the currency is displayed in the field:
* 'symbol' : $US
* 'code' : USD
* 'name' : U.S Dollar
* 'narrowSymbol' : $
⚠️ Number format and currency are automatically defined by user local.
{% endtab %}
{% endtabs %}
## Upload Field
Upload Field with or without dropzone
`Upload Field` is a specific form element that allows users to upload a file to the platform.
This field is different from others because users cannot actually enter any kind of text into it. This field can only be used to retrieve a file from users' computers. It can be used for use cases such as providing ID documents, company logos, and product pictures...
{% hint style="warning" %}
This component allows users to **upload** a file from the platform, not to download one. To download any kind of document from the platform, refer to [`File Download Component`](/design/components/actions/file-download), a dedicated component to be used in a form.
{% endhint %}
{% tabs %}
{% tab title="File Upload" %}
`FileUpload` is a component attached to `Upload Field`. When a file is selected, we display `FileUpload` component under the button.
If the project allows several files, `FileUpload` components are stacked.
Behavior when several files are accepted : FileUpload components are stacked
If the project does not allow several files, the button becomes disabled after selecting one file. If users remove the file by clicking on its "Close icon", then the component comes back to its initial state.
Behavior when only one file is accepted : Button is disabled
{% endtab %}
{% tab title="Dropzone" %}
Each project can choose to use the `dropzone`.
`Dropzone` comes with error management to give direct feedback to users if files do not comply with defined rules (maximum size, format...)
Exemples of error management
{% endtab %}
{% endtabs %}
## Layout
For a clear form layout, follow these simple design rules:
* Place inputs in a vertical sequence, each stretching across the full panel width for a clean look.
* If you're aligning inputs side-by-side, leave a 16px gap between them to prevent clutter.
* Similarly, when stacking inputs vertically under a single label, keep a 16px space for clear separation.
## Content
### Label
**Use a noun**, no preposition/article (my/a/the), and no action verb.
{% hint style="info" %}
**Template**: \
{% endhint %}
### Help text
Prefer a help text over a tooltip to add extra details, and explain how to fill the field or its purpose.
If you feel you're repeating yourself in the help text, you don't need it.
{% hint style="info" %}
**Template:** \
{% endhint %}
### Placeholder text
As they disappear when you start typing, **refrain from using placeholders** if possible. Rely on a clear label and help text.
### Tooltip
Tooltip appears when hovering the ? icon or a disabled button. They are not used to communicate critical information but to provide additional information.
{% hint style="info" %}
**Template**: \
{% endhint %}
## Key takeaways
{% hint style="success" %}
* Use wisely different features for field customization (placeholder, tooltip, requirement level...)
* Use Float Number Field with a prefix for percentages
* Use predictable and logically ordered values
{% endhint %}
{% hint style="danger" %}
* Never use Password Field with a placeholder and no label
* Never use Monetary field for any other means than money
* Create new/custom behavior patterns with form components
{% endhint %}
# Pickers
Pickers allow users to select content from a set of values, usually presented in a list or dropdown menu.
{% hint style="info" %}
This article is quite lengthy. To quickly find the information you're looking for, consider using the search.
{% endhint %}
## Overview
Different types of pickers can be used in forms. Choosing the right picker depends on the type of answers requested and their number.
Here is an overview to assist you in choosing the appropriate picker based on your use case. For more in-depth information, please refer to the details of each picker.
Decision tree to choose which picker based on your use case
`Select` is the simplest picker.\
Allows users to choose **one** item from a option list.\
To use for 'simple' option lists that do not require back-end calls to retrieve options (eg. list of countries, language...)
{% hint style="danger" %}
For 3 options or less, use [RadioGroup](https://design.mirakl.com/components/form/selection-controls#8185e8) component.
{% endhint %}
* Default Placeholder is manageable. [See Content Guideline](#default-placeholder-state-for-select) below.
* Search bar is automatically shown for item lists with 20+ items
* Group options into bundles with title separators to make it easier to read and understand.
* Custom the field with optional props : `Label`, `Requirement Indicator` (Red Asterix), `Tooltip`, `Placeholder Value` and `Helptext`
{% endtab %}
{% tab title="Async Select" %}
Illustration of an Async Select
`Async Select` is a variation of `Select` component. \
Allows users to choose **one** item from a option list.\
**This variant is specifically made for complex list of options that requires a back-end call (eg. list of brands, available options...)**
`Async Select` loads options only when opened, which can result in a potential loading state before displaying the options. The component also supports partial loading for improved performance.
* Default Placeholder is manageable. [See Content Guideline](#default-placeholder-state-for-select) below.
* Search bar is automatically shown.
* Group options into bundles with title separators to make it easier to read and understand.
* Custom the field with optional props : `Label`, `Requirement Indicator` (Red Asterix), `Tooltip`, `Placeholder Value` and `Helptext`
{% endtab %}
{% tab title="Mutli Select" %}
`Multi Select` is a picker that offers more flexibility to the user.\
Allows users to choose **multiple items** from a list **without limitations**.\
To use for 'simple' option lists that do not require back-end calls to retrieve options (eg. list of countries, language...)
When empty, `Multi Select` shows a '+' icon on the far right corner (unlike Single Select, which uses a dropdown arrow).
The Selection List opens in an overlay, showing checkboxes and a blue background for selected items. Chosen items are represented by chips in the field.
{% hint style="info" %}
`Selection List` stays open until users click on CTA "*Done*". But if users click outside, the selection is still saved.
{% endhint %}
Users can unselect a value by clicking on the "x" ("remove") icon of its [chips](https://mirakl.zeroheight.com/styleguide/s/42502/p/310752-chips) or by unchecking the line in the `Selection List`. They can also clear the whole selection with the Secondary Button in the dropdown "*Clear*".
Once the selection is made and the overlay is closed, the picker will only show **the first 8 values** (overridable setting) with chips. A " `Show More` / `Show Less` " action appears in the input to let users manage the overview.
When disabled with value, the picker shows all the selected values and cannot be collapsed.
{% endtab %}
{% tab title="Async Multi Select" %}
Illustration of Async Multi Select
`Async Multi Select` is a variation of `Multi Select.`\
Allows users to choose **multiple items** from a list **without limitations**.\
**This variant is specifically made for complex list of options that requires a back-end call (eg. list of brands, available options...)**
Async Multi Select loads options only when opened, which can result in a potential loading state before displaying the options. The component also supports partial loading for improved performance.
{% endtab %}
{% endtabs %}
## Date/Time Selection
{% tabs %}
{% tab title="Time Picker" %}
Illustration of Time Picker
`Time Picker` is a component dedicated to time (hours & minutes). \
With this picker, users can select **one item** in the calendar.
When empty, `Time Picker` shows a 'time' icon on the far right corner (unlike Single Select, which uses a dropdown arrow).
`Selection List items` of `Time Picker` are customizable :
* 'interval' (from 1 to 60): allows populating options with precise interval
* Removing time before the current time
{% endtab %}
{% tab title="Date Picker" %}
`Date Picker` is a component dedicated to dates (day). \
With this picker, users can select **one day** in the calendar.
When empty, `Date Picker` shows a 'calendar' icon on the far right corner (unlike Single Select, which uses a dropdown arrow).
When the user clicks the field, a calendar overlay appears with different actions and information (see below). The overlay is dismissed once one chooses a date. The chosen date populates the field. Users can always change the selected date or erase their selection by clicking on the "x" ("delete") icon.
{% hint style="info" %}
Timezone information appears automatically and only if the users' locale is different from the platform timezone.
{% endhint %}
{% hint style="info" %}
A mobile version of the calendar is automatically displayed on small screens.
{% endhint %}
{% endtab %}
{% tab title="Daterange Picker" %}
`Daterange Picker` is a variation `Date Picker` component. \
With this picker, users are invited to select **a period**, not only a single date. \
It has the same behaviors as `Date Picker`.
The `Daterange Picker` differs from the `Date Picker` component in two ways:
* The calendar overlay exhibits two consecutive months, as opposed to just one in the `Date Picker`.
* The placeholder content is "Select a period"
{% hint style="info" %}
You have the option to enforce a specific time range.
*eg. If a 4-day minimum range is enforced, users cannot select an end date earlier than 4 days from the chosen start date.*
{% endhint %}
{% hint style="warning" %}
This component is made for users to select a range with **two different values (a start date and an end date)**. While it's still possible to select the same value for both (ending with users selecting a range of a unique day), this behavior should not be encouraged.
{% endhint %}
{% endtab %}
{% tab title="DateTimerange Picker" %}
`DateTimerange Picker` is the most complete version of pickers dedicated to dates and times. \
It allows users to select a date range and to associate a precise time of the day. \
Time selection is optional.
Modal for the Date Time Range Picker
Unlike other pickers and because of its complexity, `DateTimerange Picker` overlay opens in a modal when the user clicks on the field.
{% endtab %}
{% endtabs %}
## Inline advanced picker
\
The inline advanced picker triggers the advanced picker modal which is a key component to [advanced selection](/design/patterns/advanced-selection). Once the items are selected, it displays a counter with "selected" as microcopy; you may override it.
## Layout
For a clear form layout, follow these simple design rules:
* Place inputs in a vertical sequence, each stretching across the full panel width for a clean look.
* If you're aligning inputs side-by-side, leave a 16px gap between them to prevent clutter.
* Similarly, when stacking inputs vertically under a single label, keep a 16px space for clear separation.
## Content
### Label
Use a noun, no preposition, no action verb.
{% hint style="info" %}
Template: \
{% endhint %}
### Default Placeholder State for Select
{% hint style="info" %}
Template: - - Select - - or \
{% endhint %}
How to choose the right placeholder
When a clear and logical default choice is evident, pre-select it, while also allowing users the option to override it. \
For example, in language selection, 'English' is initially chosen but can be modified by the user. \
In such instances, we recommend informing the user this default choice was made on their behalf by explicitly marking it as the 'default' selection.\
In this scenario, the component will always have a value, eliminating the possibility of it being null, and consequently, the picker will never be in an error state. This approach obviates the need to designate the picker as 'mandatory' to avoid rendering an ineffectual verification step.
When no option presents a clear logical choice, employ a 'blank option,' such as **'- - Select - -'**, to guide users in making their decision. \
It's important to note that the 'blank option' is not a valid response for required fields and will result in an error if users attempt to save the form with this selection.\
In this scenario, the component can be clearly stated as mandatory.
exemple of two placeholder content for picker
### Help text
Prefer a help text over a tooltip to add extra details, and explain how to fill the field or its purpose. If you are just repeating yourself, don’t use a help text.
{% hint style="info" %}
Template: \
{% endhint %}
### Tooltip
Tooltip appears when hovering the ? icon or a disabled button. They are not used to communicate critical information but to provide additional information.
{% hint style="info" %}
Template: \
{% endhint %}
## Key takeaways
{% hint style="success" %} **Do**
* Consider whether to display a default value or prompt users to select one when using a picker component
* Asynchronous components are meant for complex selection lists.
* Use predictable and logically ordered values
* Always report to form patterns
{% endhint %}
{% hint style="danger" %} **Don't**
* Avoid imposing an illogical pre-selection as the default state
* Use DateTimeRange for a single date, even if it's technically possible
* Consider providing less granularity when specifying minutes in a date picker.
* Create new/custom behavior patterns with form components
{% endhint %}
# Selection controls
Selection controls are specific components to let users control different kinds of options, settings, or situations.
## Overview
Selection controls are form components allowing users to select one (`Radiogroup`) or several (`Checkbox`) options within a list.
They differ from Pickers as they don't have fields and, therefore, no overlays. Thus, all options are fully displayed on the screen. To not overflood users with tons of options, we recommend thinking **carefully about the number of options displayed**. Too many options will appear complex for users, long to read, and difficult to distinguish from another. Reduce to a minimum number of options if possible.
The following components are worthwhile in use cases, such as selecting a configuration (user profile, type of company,...) or activating options.
{% hint style="info" %}
Note that usually, [Switch Button](https://zeroheight.com/065715af6/v/latest/p/30b43c-switch-button/b/20a137) is considered a`Selection Controls` component. However, we have decided to consider it a [`Button`](/design/components/actions/buttons) because it has an `Auto-Save` behavior, unlike the listed components here. Selection Controls components must follow Form Save behavior.
{% endhint %}
{% hint style="info" %}
💡**How to manage errors?** [Learn more about Error Management](/design/patterns/errors)
{% endhint %}
## Guidelines
### Checkbox
`Checkbox` is a form element. Each checkbox must be given a label and contain a link. Adding a help text is a good practice if the label is not self-explanatory enough, but it must bring added value.
{% hint style="warning" %}
While it is technically possible to add a tooltip to the label, it is better to use a `Helptext` to add content to each option.
{% endhint %}
{% hint style="info" %}
In a form, a `Checkbox` cannot be in an '`Indetermined`' state; users can only select or unselect an item.
{% endhint %}
### Checkbox Group
`Checkbox Group` is a list of items in which users are free to select one option, no option at all, or several options. **There is interdependence between checkboxes in a group.**
Each checkbox must be given a label. Adding a help text is a good practice if the label is not self-explanatory enough, but it must bring added value. For consistency issues, all labels must have a helptext or none at all.
### Radio Group (Default)
`Radiogroup` requires users to choose one option in a list of minimum 2 options. The selection of a radio button, therefore, prevents the selection of other radio buttons in the same group. There is no limitation to the number of options.
Each radio button must be given a label and can have a helptext. For consistency issues, all items must have a helptext or none at all. Also, if needed, a global label for the `Radiogroup` component is available.
{% hint style="info" %}
Using a radiogroup means selection is mandatory for users. Therefore, the asterix can not be removed.\
If selection is not mandatory, use `Checkbox Group`.
{% endhint %}
Depending on the page layout, 2 directions are available:
* **Column**: each radio element will be stacked one above the other. This direction will be preferred for long labels if you want to add help texts to each element.
* **Row**: each radio element will be stacked next to the other. This direction will be preferred to short labels.
It is also possible to group or split radio buttons per type or theme in order to classify them while keeping the validation rules.
{% hint style="info" %}
When possible, if one of the options seems more logical, set is as default. It means the options will already be selected without any actions from the user. In this case, you must write it down in the `Label` to communicate to users why it has already been selected.
{% endhint %}
### Radiogroup (Card)
`Radiogroup Card` is a variant of the`Radiogroup` component. It has the same guidelines and behavior (see above).
`Radiogroup Card` has a different UI, as each option is contained in the card (outline stroke). It visually helps users to differentiate options when content is too long or uneven between options. The component width has to fill its container.
It is also possible to group or split radio buttons per type or theme in order to classify them while keeping the validation rules.
## Content
### **Label**
Use a noun, no preposition, no action verb.
{% hint style="info" %}
Template: \
{% endhint %}
### **Help text**
Prefer a help text over a tooltip to add extra details, and explain how to fill the field or its purpose. If you are just repeating yourself, don’t use a help text.
{% hint style="info" %}
Template: \
{% endhint %}
# Tree
A tree helps showcase data in a hierarchical way, either for selection or navigation.
Tree in navigation mode
## Overview
The tree component helps users navigate large amounts of data and potentially select some thanks to a clear hierarchy. Like a regular tree, the component has a root and can have branches that can be collapsed or expanded, and leaves.
At Mirakl, we use the tree component to showcase catalog categories, for example.
## Guidelines
The tree root helps gives users a reference point so that they understand that they're at the right place. It is optional and can be selected by users. [Learn more about selection types](#selection-types)
Tree items are sorted alphabetically, with priority given to branches arranged alphabetically, then to leaves arranged alphabetically.
It is possible to add extra information next to the root, branch, or leaf label, like a settings code or a number (e.g. number of products within a category). You may also add an icon.
In terms of loading, each brand has its own loader if it has lots of items. A loading icon will appear when this happens.
### When to use
* When navigating large amounts of data organized in a logical order.
### When not to use
* For primary navigation on a page.
* For simpler information structures. Use[^1] Radio group or checkbox group instead.
### Selection types
Roma offers 4 different selection types.
* **Simple** allows for a single value to be selected at a time.
* **Navigation** allows for a single value to be selected at a time but without showing the radio button.
* **Multiple** allows for multiple selections with heritage. Selecting a branch will automatically select all its leaf children.
* **Multiple without heritage** allows for multiple selections without heritage. Selecting a branch will only select the branch as if it were a leaf. To select a branch and its children, you can use the Select all button available when hovering over a branch.
The 4 selection types
{% hint style="info" %}
It is not possible to split your tree with separators.
{% endhint %}
{% hint style="info" %}
The tree selection icon will change depending on your selection type.
{% endhint %}
## Accessibility
Tree offers keyboard navigation for accessibility purposes.
[^1]:
# Images
Illustrations
Our illustrations have a visual and emotional impact in order to bring optimism, friendliness and engagement to users.
# Illustrations
Our illustrations have a visual and emotional impact in order to bring optimism, friendliness and engagement to users.
## Overview
Mirakl's illustrations simplifies complex ideas for our users, guiding them through their user experience.
These illustrations play a distinctive role in our design system, setting us apart with their unique style and impact. They create a positive, friendly, and engaging impact.
Each illustration conveys a specific message, such as "empty," "sending," or "in progress."
Use them sparingly to maintain their communication power, rather than as mere decoration.
some of our illustrations
# Icons
Icons provide visual help to users and illustrate key concepts.
## Overview
ROMA includes a comprehensive set of around 200 icons.
Each icon is designed to be simple, intuitive, and adaptable to various use cases. Icons should be used to support actions, statuses, and information, enhancing user understanding without overwhelming the interface.
Icons can be used in Icon Button ; Avatar with Icon ; Page Title
# Media
The Media component is designed to display images or videos, enhancing interfaces by providing graphic or video representations.
Illustration of Media Component
## Overview
Use the Media component to add graphics into the interface like image, illustrations, videos, flags, icons or avatars to the interface.
### Size and formats
The component can adapt from very small (siez 5) to extra extra large (size 11) sizes, allowing flexibility in design and layout. In total 7 sizes are available.
The component adjusts its design to adapt for differents formats :
* **Square Images:** Fill the entire space.
* **Landscape Images:** Fit to height.
* **Portrait Images:** Fit to width.
* **Custom Sizing:** Media dimensions can be customized with specific max and min widths and heights, ensuring optimal display across devices.
How various media format are displayed
### Technical specifications
Media comes with an empty state, to be used when no media has been provided. It is also used for loading state.
Hovering over the media reveals a preview icon. Media is clickable, triggering a Lightbox for preview.
Hovering a media
### Lightbox
Media appears as a thumbnail image, providing a clean and uniform look across the platform. When a user clicks on the thumbnail, the media opens in a dedicated overlay (called a Lightbox). This Lightbox focuses the viewer’s attention by dimming the rest of the website and presenting the media in a larger, central frame. This feature is especially useful for videos but also allows users to view images in a larger format.
Lightbox
## Avatar
The Avatar component adapts to show users or entities. It can display initials, icons, or images, with the name shown when you hover. Clicking triggers actions.
To display multiple avatars, uses component `Avatars` it automatically handles different colors and spacing.
Disabled avatars show that the user or entity is no longer active.
## Guidelines
### How to use
* **Enhance content by adding visual representation :** Use Media to add value to the content, aiding in user navigation and comprehension without overwhelming the text content.
* **Media to the second plan :** Media should never dominate the page or replace textual information, it always has to be used as a complementary source of knowlegde.
### How to not use
* **Decorative purpose only:** Do not use Media component if it does not add informational value or if it overly clutters the interface.
## Accessibility
* **Screen Reader Support:** All media must have `alt` text for screen readers, enhancing accessibility for visually impaired users. For videos, use video tracks with captions.\
Avoid repeating information already present on the page visually.
* **Captions and Tracks:** Adding captions to images and providing track support for videos (with captions, subtitles) is crucial for accessibility and compliance with web standards.
## Key takeaways
{% hint style="success" %}
* Context is crucial: media should add value to the related content.
* Use the right component size considering the whole page design
* Provide descriptive Alt-text for screen readers and captions for all other users
{% endhint %}
{% hint style="danger" %}
* Use `Media` with no context to it
* Repeat information in your alt text that is already on the page.
{% endhint %}
# Navigation
Hyperlink
Hyperlinks are anchor tags users can interact with to navigate to other pages.
# Hyperlink
Hyperlinks are anchor tags users can interact with to navigate to other pages.
## Overview
`Hyperlink` is a component used in our products as a guide through multiple web pages. Because we have a lot of content to display (documentation, additional information) and many pages, users may need to navigate through pages to proceed with their needs.
`Hyperlink` are giving them just-in-time information without overloading or distracting them with information that is too tangential or secondary to the tasks at hand.
## Guidelines
### **How to use**
It should remain in a secondary role:
* at the end of a paragraph if the link is related to the whole paragraph (example: documentation)
* as part of the paragraph, if the link is related to specifics words in a paragraph
### **When to use**
When complementary information is available and may help user to accomplish their tasks, or when we want users to perform an action on another page.
### **When not to use**
They are not meant to be used as a [Button](https://zeroheight.com/065715af6/v/latest/p/815f32-action-button/b/405683). Buttons are meant to perform precise actions, not redirect users to another page.
{% hint style="info" %}
**🥊 Hyperlink VS Link Button**
Hyperlinks redirect users to a new page. It means pressing the trigger results in a URL change. While Button action happens on the same page.
For accessibility, the distinction becomes even more important, especially for those who are using Assistive Technology (A.T.) such as screen readers and dictation software.
{% endhint %}
Datatable has its own hyperlink rules and components. Do not import this component into a datatable. [Learn more about Datatable](https://zeroheight.com/065715af6/v/latest/p/51998e-datatable-wip/b/03871e)
In order to distinguish Hyperlink from Paragraph, this component has its Typography style: Bold, Underline, and Blue.
We add an icon to inform users they will open a new page by clicking on the component. **The icon is displayed after the text.**
An external link in a paragraph
💡 `Hyperlink` is an anchor text, which means the actual link is hidden behind a more readable text. In only rare cases, we provide the full link directly in the interface (follow orders on the partner's website, for example) as this practice deteriorates visual design and user experience.
## **Accessibility**
* `Hyperlink` must be differentiated from other text as it will open new pages. While color is useful for the majority of users to convey this information, it is not enough for users with visual impairment. We decided to use color+bold+underline to ensure this component stands out from other text.
* In our products, `Hyperlink` will, most of the time, guide users to a new page in another window. That's why adding `'launch' icon` is important for all users to understand our navigation. It's also an important piece of information for Screen Reader to inform visually impaired users of the consequences of their actions. **The icon is not mandatory, but it does bring useful information for all.**
## Key takeaways
{% hint style="success" %}
* Use Hyperlink to enrich users' knowledge with complementary content we provide
* Use Hyperlink in a context, in or at the end of a paragraph
* Add Icon to inform all users they will open a new page
{% endhint %}
{% hint style="danger" %}
* Paste a full link into the interface. Hyperlink should be easily readable
* Use it as an Action Button
* Use it in a datatable
{% endhint %}
# Page title
Page title provides the core information users need when viewing the page.
## Overview
`Page title` is the very first component to appear on a page. Used as a header, it's **a mandatory component to display on every page**.
`Page title` should be:
* Used as a page header
* Always placed at the **top of the page.** No content can be placed above.
* **Only one** `Page Title` per page.
## Guidelines
There is **only one mandatory feature** to this component: the title itself `H1` It summarizes the page content or gives the current object name/identifier. The title wraps onto multi-lines when scaling down the viewport.
Other features, such as `Backlink`, `Subtext`, `Badge`, `Actions` ,`Image` and `Page Navigation` are **optional**. They should only be displayed if the page content needs it.
1. **Back Link**: optional secondary navigation aid. It reminds the workflow architecture: from which section this page is placed.
2. **Image**: optional visual (e.g. store logo).
3. **Title (H1)**: Title of the page
4. **Badge**: optional extra items to show status ("New", "Ongoing", "Invalid"...) or the result of an action that has been performed ("Submitted", "Pending",...). See [Badge guidelines](/design/components/feedback/badge-status) for more information.
5. **Subtitle:** provides users with additional information about the title or page content.
6. **Page Navigation**: helps organize content around a similar theme (an order, a client). The different tabs allow content to be viewed without navigating away from the main page.
7. **Actions**: modify the page and its content. Use primary, secondary, or ghost buttons. See [Button Group guidelines](/design/components/actions/button-group) for more information.
{% hint style="info" %}
**Additional Info on Page Title Actions:**
The action buttons in the Page Title are static and should not change as the user navigates the page.\
Avoid replacing the Primary Button with a Destructive Button. Any potentially harmful action should be placed under the Menu Button.
{% endhint %}
### Small screens specifics
The layout changes below 768px (mobile breakpoint) for better usability and to help the user to process the information. Back Link changes into an [`Icon Button`](/design/components/actions/buttons#icon-button). Button Group changes into Small Screen variant.
Page title for small screens
### Backlink
The link must always have the following structure:
* Back to \[landing page title]
The \[landing page title] is the exact title of the page users will land on when clicking the link.
{% hint style="success" %} **Do**
* Add a Backlink to guide users in page hierarchy
* Respect content structure
{% endhint %}
{% hint style="danger" %} **Don't**
* Modify content structure by adding any other words such as "***Go*** back to...","***Let's go*** back to..." or "***Take me*** back to..."
* Let users take a guess on where backlink may take them to, always specify clearly where the link is pointed to.
{% endhint %}
#### Frequently Asked Questions
> Should we display a `prompt-before-leave` when using the backlink?
A `prompt-before-leave` is an exit modale shown to users before they leave or close a page. It ask them to confirm their intent to leave the page.
Exemple of a Prompt Before You Leave
It can appears in several situation : when using the backlink in the Page Title but also when closing the window or clicking into any other menu item. Thus, displaying it does not depends on where users clicks into but whether if he made any changes in the current page.
* On **form pristine:** No *`Prompt-before-leave`* + Back to the previous page
* On **form dirty :** Custom *`Prompt-before-leave`* when using *`Page-Title-Backlink`*
* On **form dirty :** Browser Native *`Prompt-before-leave`* when using any other means to leave the page
### Page Navigation
Page Navigation is an option of `Page Title` and its presence influences the rest of the page content.
Page navigation shouldn’t be used:
* for a completion path (use Stepper instead)
* to display forms to complete
{% hint style="success" %} **Do**
* Limit to 5 items maximum; otherwise, other items will be hidden under a **More** tab
* Rank tabs in order of importance
* You may use panel tabs within a Page Navigation item
* Microcopy should be short, clear, without any variables
* You may add a counter if needed (e.g. Messages (10))
{% endhint %}
{% hint style="danger" %} **Don't**
* Create a tab for a “select option" or a mini-feature.
{% endhint %}
{% hint style="info" %}
💡 With our new sidebar, you can remove the Page navigation component and add subpages in a sidebar submenu.
{% endhint %}
## Accessibility
Well-organized content helps users to orient themselves and to navigate effectively. Such content includes:
* **Pages must have clear titles**. Use subtitles to describe page content if needed (for complex pages). Keep in mind Titles (\
) is also displayed in the navigator tab and will be the first element read by a screenreader. If the page title is not clear enough it may confuse users, not only those with screen readers but also those with multiple open pages.
{% hint style="warning" %} **DON'T** Add a tooltip to a title. Title must be clear enough to understand page content. Use subtext if additional information is *really* needed.
{% endhint %}
* Users are informed about their current location within a set of related pages. Use a backlink label to inform the higher-level page.
## Key takeaways
{% hint style="success" %}
* Always provide at least a title (H1) to a page
* Respect content guidelines when naming a page
* Use the optional feature carefully
* Use only one primary action
* Use Badge to display the object status
{% endhint %}
{% hint style="danger" %}
* Do not overstack Page Title with unnecessary information
* Do not use multiple Primary actions
* Do not use very long titles
* Do not use 1+ Badge within the Extra section
* Do not use the backlink on section pages
* Do not add a tooltip in Title
{% endhint %}
# Sidebar
Sidebar menu is the primary navigation. It provides access to the main sections of the platform.
Navigation sidebar appears to the left side of all our products. It showcases all Mirakl key features and enables users to easily switch between activities.
{% hint style="info" %}
Automatically handled by ROMA
{% endhint %}
## Overview
* `Sidebar` is collapsible to make sure users can focus on their tasks. When `Sidebar` is collapsed, users can hover the icon and an action menu appears.
* `Sidebar` items *may* display a counter, like **Messages**.
* `Sidebar` header may have a Store switcher feature that triggers an action menu.
Sidebar and topbar
{% hint style="info" %}
`Sidebar` always goes with [`Topbar`](/design/components/navigation/top-bar). While Sidebar allows users to navigate through various activities, `Topbar` is dedicated its profile and personal activities.
{% endhint %}
Sidebar menu supports two levels of navigation :
* Section (level 1) is the main level, used as a heading of nested pages.
* Sub-level (level 2) is the secondary level with direct redirection to targeted pages.
Sections are displayed in white (theme.color.white) with an icon. \
With a chevron, it means sub-level are attached to the section. Thus, on click to Section title, it opens Sub-level menu. \
Without a chevron, it means no sub-level are attached to the section. Thus, on click, users are redirected to the section page.
Sub-level are displayed in blue (theme.color.primary\[900]) with no icons. \
Sub-level must always be attached to a Section. **At least two Sub-levels are needed to created a nested section.**
Illustration of Sections and Sub-level
## Content
Naming Section and Sub-section is strategic in user experience. Users must be able to scan an dunderstand very quickly menu. Keep the navigation link text short. They can be shorter versions of pages titles. Try to use a specific task/mission without necessarily using an action verb.
## Accessibility
Navigational mechanisms must be repeated within a set of Web pages. (WCAG 3.2.3, level AA) Order, naming and behavior must be repeated through all sections. Thus, it is important to respect naming convention. Naming a section or a sub-section must be a joint effort of Product, Design, Content and Marketing teams.
# Top bar
Top bar allows operators and sellers to switch between our different tools and access their profile.
Our top bar gathers all notifications and profile functions:
* User profile
* App switcher between Mirakl applications
* Notifications
* Messages
For very specific purposes, we may add a button.
# Overlays
Modal
A modal displays content that requires user interaction in a layer that shows up on top of the current context. Modals block access to the rest of the page and force user interaction.
# Modal
A modal displays content that requires user interaction in a layer that shows up on top of the current context. Modals block access to the rest of the page and force user interaction.
### Guidelines
Use modal for the following purposes:
* **Users need to confirm an action** before they can continue with the main workflow. Only use modals for important steps in a workflow. While standard actions can be marked as skipped by users, confirmation of destructive actions is mandatory and can never be skipped.
* **Add an item to a list** by creating it or selecting it from a list (see Advanced Picker
* **Create a simple object with limited information** using a maximum of 5 input fields. For complex forms, you should consider creating a dedicated page for that task.
* **Complete a task** without losing the current context of the page. Users won't be able to interact with the page until the modal is closed.
Modals come in 3 sizes: SMALL, MEDIUM, and LARGE. **SMALL should only be used for confirmation Modals.**
Modals should:
* Require that users take an action or cancel.
* Close when users press the `✕` button, the `Cancel` button, the `Esc` key, or when users click or tap the overlay outside the modal.
* Must have a primary action (the main purpose of the modal) and a secondary action (usually `Cancel`).
* Scroll if the content is larger than the max height of the container. The footer is sticky during scrolling so that the actions are always accessible by the user. Scrolling should be indicated by adding an additional drop shadow on the footer.
\
Accessibility
-------------
* When a modal opens, focus moves automatically to the modal container so it can be accessed by keyboard users
* While the modal is open, a focus trap keyboard focus shouldn’t leave the modal
* Users can close the modal with the keyboard by activating the `✕` button, the `Cancel` button if one is provided, or by pressing the `Esc` key
* After a modal is closed, the focus returns to the button that opened it
\
Content
-------
Modals are composed of:
* A title
* A description
* One or several buttons
Remember modals are disruptive and can be perceived as aggressive, so use them only when necessary.
Avoid using questions in modals, they could add confusion.
### Title
The title should be concise and clear and provide enough information for users to make an informed choice.
Capitalize the first word, no article, no punctuation
{% hint style="success" %}
* Generate new key
* Report as critical
{% endhint %}
### Description
The description adds any information that users need to know in order to make an informed choice between the two action states in the buttons below.
{% hint style="success" %}
You're about to delete the entire product mapping configuration of the store. This cannot be undone.
{% endhint %}
### Buttons
Buttons on modals should [follow generic button guidelines](https://mirakl.zeroheight.com/styleguide/s/42502/p/36c855-buttons/b/04e88d). Users are likely to only read the title and the main CTA.
#### **Primary action**
Try to use the same words in the button as the action mentioned in the modal title.
{% hint style="success" %}
Title: Delete product mapping configuration
Button: Delete
{% endhint %}
#### **Secondary action**
The secondary action will most likely close the modal. Use common verbs like Cancel or Close.
### Specific patterns
#### **Cancelation confirmation**
Cancellation confirmation modals can be tricky as "cancel" is the ultimate secondary action in modals. Here, it has to be the primary action.
You can use "Cancel" as a primary action and clarify the secondary action as much as possible, "Keep \[verb-ing]" for example. The main objective is that the difference between the two actions is absolutely clear.
{% hint style="success" %}
Cancel + Keep editing
Cancel order + Keep order
Cancel order + Back to order
{% endhint %}
# Popover
An overlay for larger amounts of data.
## Overview
A popover is an overlay that appears above page content and can contain formatted text. Popover appears when rolling over, clicking, or tapping an element.
## Guidelines
Its content can be structured with a title and paragraphs, and placement can be customized.
{% hint style="warning" %}
Limit the use of popovers, as they can become overwhelming.
{% endhint %}
### When to use
* When you need to display additional content to give more context to users.
* When this additional content is longer than one sentence or needs to be formatted.
### When not to use
* For smaller overlays. Use [tooltip](/design/components/overlays/tooltip) instead.
## Content
Popover content should follow our [content guidelines](/content/writing-for-mirakl).
# Tooltip
An overlay for small amounts of data.
## Overview
Tooltips add additional context to a button or other UI element.
## Guidelines
Tooltips can only contain a short volume of text.
{% hint style="danger" %}
Do not communicate critical information in a tooltip; think of it as a "Did you know?" prop.
{% endhint %}
### When to use
* When you need to display additional content to give more context to users.
### When not to use
* For long-text overlays. Use [popover](/design/components/overlays/popover) instead.
* As a bandaid on a broken experience.
## Content
Tooltip content should follow our [content guidelines](/content/writing-for-mirakl). Keep them clear and useful.
# Side Drawer
A drawer is a panel that slides in from the right side of the viewport.
Exemple of a Side Drawer
## Overview
`Side Drawer` is an overlaid panel : it appears on top of a page and slides in from the right side of the viewport.
This component is useful when we want to organize a page content into different levels. Defer secondary content helps to limit visual clutter and minimize cognitive load. That said, this content must remain easily available and appear when users intends to expose it.
Typical use case is to deep dive into a specific element without having to leave the current page. That way, tasks can be achieved more efficiently within the same context.
Exemples :
* Take a closer look into a datatable element
* Opening a large list of datatable filters
* Opening details of a datalist element
* Take quick actions
## Guidelines
### Layout
#### Sizes
The `Side Drawer` comes in three sizes to accommodate its content. It's up to designers to decide which size is more appropriate for visualizing the content.
* Small : 356px
* Medium : 450px
* Large : 600px
#### Compatible components to use with Side Drawer
The only mandatory component to display in the `Side Drawer` is the `title`. It helps users to understand to which element `Side Drawer` is related to.
The content of the `Side Drawer` is *almost* design-free. However, keep in mind to make it easy to read. Therefore, we have prohibited the use of the [Expandable Panel](/design/components/structure/panel/expandable-panel) inside the `Side Drawer`, as it may introduce excessive complexity, affecting readability.
### Behaviors
#### General behaviors
When the drawer is open, all actions on the main page are disabled. Users must close the drawer to perform any actions on the main page.
A datatable row can open a side drawer, not just the hyperlink (href) cell.
#### Exit behaviors
There is several ways to exit `Side Drawer` :
* A `Close Button,`always available to the top-right corner.
* A Click outside of the `Side Drawer` area
* An action through a `Primary Button` of the `Save Bar`. Though it is optional, to add a Save Bar
## Accessibility
When using a keyboard to navigate the interface, user can use the 'Esc' key, also known as the Escape key, to exit or close the drawer.
# Structure
Global layout
Global layout is the way we arrange elements on a page to create a consistent experience for the user.
# Global layout
Global layout is the way we arrange elements on a page to create a consistent experience for the user.
## Overview
To keep consistency across products, we have determined basic layout rules to display informations on pages with **3 PageLayout sizes** and **3 layout item sizes.**
## PageLayout
{% hint style="info" %}
`PageLayout` is always centered on the page
{% endhint %}
Adapt PageLayout to the complexity and number of informations to display on a page. Few exemples :
* Prefer a `Small PageLayout` to display a single form with few imputs or a simple datatable with two/three columns.
* Use a `Medium PageLayout` to display a more complexe datatable or to create a page with several [cards](/design/components/structure/card) in it.
Name
Size
Size
Small
640px
640px
Medium
1024px
1024px
Large
2000px max
2000px max
illustration of PageLayout
If you need to display more than one element in a page, use `LayoutItem` to create columns in your page.
## Layout item
`LayoutItem` are used to create more complex PageLayout with columns. It helps to display more informations in the same page by keeping while maintaining legibility.
Be mindful when choosing `LayoutItem` to display informations. Few exemples :
* Use `S LayoutItem` to display text
* Prefer M LayoutItem for richer panel such as forms
{% hint style="info" %}
`S/M LayoutItem` can not be used alone in a container, they must be combined with a Flex LayoutItem.
{% endhint %}
{% hint style="info" %}
All LayoutItem are always separated by 24px.
{% endhint %}
## Illustrations
## Responsive Web Design
Responsive Web Design is the capacity of an interface to be adapted to any monitor resolution (from computer screen to mobile). With RWD, users are able to navigate through our products and perform their tasks, whatever their IT tool are.
Designs must be provided with responsive versions depending on breakpoints. Possible `Breakpoint` values are :
* lg (1440px)
* md (1080px)
* sm (768px)
* xs (540px)
Exemple of a responsive version with a complex layout and a datatable
### Breakpoint Feature Block
Not all designs and features should be responsive. Indeed, we have seen with some of our complex functionalities that sometimes, on smaller screens, usability is degraded.
Thus, for features that would not work on smaller screens, designs must be provided with a Breakpoint feature block :
Breakpoint Feature Block on mobile
`Breakpoint Feature Block` is a specific [empty state](/design/components/feedback/empty-state) letting users understand why they cannot access the feature.
It's up to each project to define at which beakpoint this message is shown. The illustration, title and subtitle have default value but can be overided. By default, there is no `Primary Button`, but it can be added to redirect to another page is an alternative solution is available.
## Key Takaway
{% hint style="success" %} **Do**
* Provide informations about page structure
* Respect predefined Page and Item Layout
* Ensure to provide responsive version of complex pages
{% endhint %}
{% hint style="danger" %} **Don't**
* Custom layouts
* Allow complex functionnalities run under smaller screens
{% endhint %}
# Panel
The key component to structure content on Mirakl.
## Overview
To make sure all designers on all projects build views consistently, it is important that we use Roma layout components. By doing so, we ensure the consistency, sustainability, and scalability of our designs, and we facilitate the onboarding of new designers into the team.
Panels can be composed of the following components that can only be children of the main panel.
* [Panel Header](#panel-header)
* [Panel Content](#panel-content)
* [SubContentWrapper](#subcontentwrapper)
* [Panel Link](#panel-link)
* [Panel Separator](#panel-separator)
* [Panel Tabs](#panel-tabs)
* [Panel Footer](#panel-footer)
You cannot nest these elements inside each other; if you want a panel separator, you have to place it within the main panel, not the panel content component.
## Guidelines
### Panel header
As its name states, Panel Header is the first element that appears within the panel structure. It is not mandatory but highly recommended. As an example, if the [Page Title](/design/components/navigation/page-title) is clear enough, you may remove it.
{% hint style="info" %}
For accessibility reasons, if there is no `Panel Header` in the `Panel`, you should specify an ``(to be added in the code). It will not be visible in the interface but it will help screen readers to read the page while reassuring users who are navigating it.
{% endhint %}
Panel Header has several options, such as [Button group](/design/components/actions/button-group), [Background Icon](broken://pages/9R017djUPa5PP51eeYWG), and [Badges](/design/components/feedback/badge-status) (2 maximum).
### Panel content
Panel Content is used to contain anything that has to go inside a panel (text, image, datatable, datalist, etc.).
Panel has 3 options:
* Classic
* Expandable : its content is hidden until user triggers it to reveal content.
* Scrollable : user can navigate content by scrolling it
{% tabs %}
{% tab title="Expandable" %}
This layout helps declutter a page and hide information that might not be useful at first to users. You can choose to expand or collapse it by default.
{% endtab %}
{% tab title="Scrollable" %}
This layout allows putting long-form content within a panel in which the user can scroll. You can define a max height.
{% endtab %}
{% endtabs %}
All elements contained within a panel are separated by a 16px margin in all directions, as follows:
#### SubContentWrapper
***SubContentWrapper*** is a structural container used exclusively within Panel Content to express visual hierarchy and dependency between content blocks. It adds a semi-transparent vertical indentation bar and consistent spacing to communicate "this section belongs to the preceding element."
{% hint style="success" %}
**When to use**
* To visually group content that is structurally dependent on a parent element (checkbox, radio, select, or toggle)
* When the nested content represents a sub-element or sub-configuration of its trigger, not merely a conditional choice
* To maintain clear visual hierarchy within complex panel layouts
{% endhint %}
{% hint style="danger" %}
**When not to use**
* For generic spacing or indentation without a true dependency relationship
* To reveal content that only depends on a form choice but is not a sub-element of that choice (use standard [progressive disclosure](/design/patterns/progressive-disclosure) instead)
* Key distinction: SubContentWrapper is for parent-child relationships (e.g., "Configure shipping method" → "Express shipping options"), not simple conditional visibility (e.g., "Enable notifications" → "Email address field"). If the revealed content is a peer requirement rather than a nested configuration, do not use SubContentWrapper.
{% endhint %}
**Options**
Collapsible: Can expand/collapse when controlled by an external trigger (button, checkbox, toggle). The wrapper itself is non-interactive; state is managed by the controlling element using aria-expanded and aria-controls.\
Spacing: Bottom spacing can be removed when multiple wrappers are stacked consecutively.\
Nesting: Supports up to 2 levels maximum. Keep nesting shallow to avoid overwhelming users.
**Accessibility**
* The wrapper is purely presentational (no role, no form behavior)
* When collapsible, the controlling element must be focusable and reflect state with aria-expanded
* Use aria-controls to connect the trigger to the wrapper region by ID
* Ensure keyboard users can reach all interactive elements within the wrapper when expanded
**Relationship to Progressive Disclosure**
SubContentWrapper pairs naturally with the [Progressive Disclosure pattern](/design/patterns/progressive-disclosure). When content is conditionally revealed based on a prior choice, wrap it in a SubContentWrapper only if it represents a sub-element or nested configuration of the trigger. Place the wrapper immediately after its controlling element to keep the cause → effect relationship obvious. For simple conditional visibility without hierarchical dependency, use standard progressive disclosure techniques without SubContentWrapper.
### Panel link
Panel link creates a vertical visual narrative between different panel elements. You may also add text within the link.
### Panel separator
Panel Separator can help you structure your panel visually and make a difference between 2 panel content components. It is never mandatory.
Two options are available: classic and full-width. You may also add text within the separator.
### Panel footer
Panel footer is really useful when you wish to display a fixed element after a Panel Content, especially a scrollable one.
# Activable Panel
A Panel variant with dynamic display control to bring flexibility in the interface.
## Overview
Activable Panels are dynamic component used to display or hide elements based on user interactions.
Each panel includes a title and a mandatory switch button (with an attached label), allowing users to easily control what they see.
## Guidelines
1. **Toggling On Displays Content:** When the switch is activated, additional content or features become visible.
2. **Toggling On Hides Content:** When the switch is activated, certain content or features are hidden to simplify the view.
## Content
* **Clarity is Key:** Ensure that the label on the Switch Button is exceptionally clear. Users should understand exactly what will happen when they toggle the switch—whether it will reveal or hide information.
{% hint style="info" %}
Learn more about how to use Activable Panel in [Configure Options ](/design/patterns/configure-options)Pattern.
{% endhint %}
# Clickable Panel
Clickable panels are used to display information in a clickable zone.
## Overview
Clickable panels are used to display information in a clickable zone. Clickable panels are composed of a background icon and a title and can have a subtext and/or a tooltip (optional), and an arrow icon (optional and overridable). Icon background, title, and subtext have their own loading strategy.
## Guidelines
A clickable panel can either trigger a redirection (navigating to another page, opening a URL) or an action (opening a modal, requesting an API).
{% hint style="info" %}
A clickable panel cannot be used within another panel and cannot contain any child component.
{% endhint %}
## Content
Clickable panel content should follow our [content guidelines](/content/writing-for-mirakl).
Both title and subtext must be as concise as possible and indicate clearly where the user will land or what they will be asked to do when clicking the panel.
# Expandable Panel
## Overview
Expandable panels are used to lighten the user's cognitive load by hiding extra information yet showcasing the type of information that is displayed.
Expandable panels are composed of a title and a toggle icon (mandatory).
## Guidelines
Do not display critical information within an expandable panel.
Do not use within a form, as the user will not see any mandatory fields that might be hidden in the panel.
## Content
Expandable panel content should follow our [content guidelines](/content/writing-for-mirakl).
Focus on making the title as clear as possible.
# Panel tabs
Panel tabs display related but specific content within the same panel, filtered views, for example.
## Overview
Panel tabs allow switching between different but related content. They're very useful when you need to declutter your interface and make it scannable.
{% hint style="info" %}
**Panel tabs vs Page navigation**
Content update:
* Page navigation influences the whole page content
* Panel tabs influence the panel content
Theme consistency:
* Page navigation items don't share any common theme
* Panel tab items share a common theme
{% endhint %}
## Guidelines
Panel tabs should be used:
* As a quick filter in a [`Datatable`](/design/components/datatable) or [`Datalist`](/design/components/datalist) context (All orders + Orders in progress)
* As a way to declutter a panel
Panel tabs should not be used:
* For a completion path (use [Stepper](/design/patterns/forms/stepper-form) instead)
* For any kind of navigation
Each panel tab can have a specific URL. This is helpful when you have different versions of the same datatable within each tab (with other filters, sorting, or pagination, for example).
Panel tabs always have at least 2 items.
## Content
Tab labels should follow our [content guidelines](/content/writing-for-mirakl).
Labels must be as concise and precise, with no more than 2 words.
# Totalizer Panel
A component to present important figures to the user.
## Overview
Totalizer panels are used to show and consolidate important figures for operators and sellers. It usually displays numbers that the user wants to access quickly in order to make informed decisions.
Totalizer panels are composed of a background icon and a title (mandatory) and can have a Link Button, a subtext, and a tooltip (optional). Each of them has its own loading strategy.
## Guidelines
Totalizer panels must be used within a group of 2 minimum, either above the overall content or within a sidebar.
Use a [Link Button ](/design/components/actions/buttons#link-button)to help users in making quick actions related to your totalizer content.
{% hint style="info" %}
A totalizer panel cannot be used within another panel.
{% endhint %}
Be consistent in using totalizers: avoid mixing different Totalizer variants within the same Totalizer group
If data isn't available, display the totalizer card in red with a dash.
## Content
Totalizer panel content should follow our [content guidelines](/content/writing-for-mirakl).
The totalizer subtext should be written in noun form.
# Card
Cards are a great way to add some hierarchy and organization to a panel.
## Overview
Cards are a flexible component that helps organize content. They enable to display information in a clear and appealing way, making it easier to read and enhancing the overall appearance of the user interface.
Card with grey background
## Guidelines
**Card component must always be used within a panel.** When used outside of a panel, the utilization of the Card component is strictly limited to two defined types: the Clickable Card and the Totalizer Card.
Totalizer and clickable cards are the only cards components to be used outside of a panel
The card component provides two background color options: white and grey. For visual distinction among multiple cards within the same panel, opt for a grey background.
Beyond this, the design allows for full creative flexibility in terms of padding, elements, and media, with the only requirement being consistency.
### Cards or Datatalist ?
[Datalist](/design/components/datalist) in its card variation may look a lot like cards. However, there is a slight difference between those two components.
This is a datalist in a card variation
Datalists are best for displaying a collection of similar items, acting like a simpler version of a datatable without all its functionalities. They allow for easy comparison between items since the type of information displayed remains consistent across the list.
On the other hand, Cards are more versatile and are not limited to showing repetitive information. Instead, each card can present unique content, making them suitable for a wider range of uses where diverse information needs to be displayed in an engaging way.
# Patterns
Cover image
Advanced selection
Allows users to make an informed selection of items with an editable restitution of data.
# Announcing changes and new features
## Overview
When users create an account on Mirakl or discover changes, they might feel excitement, but also stress. Our job is to welcome them in a nice and professional way, or help them navigate those changes and motivate them to use our new features.
Users need to be properly alerted when a new feature is out or a new task can be completed. They might feel curious about what we have in store, so we have to make sure our copy is attractive and shows the value of what we offer.
{% hint style="warning" %}
The welcoming and new features pattern should only be used for major releases or UI updates.
{% endhint %}
## Guidelines
#### **One topic at a time**
Do not confuse users with mixed feature benefits; keep one idea per screen or component.
#### Mind the number of steps
When showing a new feature to Mirakl users, keep the number of steps to a minimum.
#### Show users the value of the service or feature
Users care about what they can achieve with Mirakl, not what Mirakl does. Focus on showcasing the value the feature brings to users.
#### Sound encouraging
Push users to go further with action verbs or expressions sequencing the process. We're here to make users grow, so the content we provide also needs to be educational and accessible.
## Usage
Introducing a new experience consists of two basic parts.
1. A suitable entry point to inform the user of the new feature.
2. Explanatory components that will spotlight the main key points of the feature.
### New experience or feature
#### Entry point
* **Shoutout**
Shoutout messages appear temporarily and push users to interact with the Mirakl interface. There can be one or several chained into a sequence. Follow [message principles](/content/writing-for-mirakl) to write a shoutout.
* **Badge**
The easiest way for users to spot a new item in Mirakl's navigation is through a [badge](/design/components/feedback/badge-status) (NEW or BETA, for example). Keep the badge microcopy concise.
{% hint style="warning" %}
Badge can only be used for new entries in the [sidebar](/design/components/navigation/sidebar) or new tabs within the [page navigation](/design/components/navigation/page-title) component.
{% endhint %}
#### Education
* **Product tour**
Product tour spotlights are meant to help the user focus on a specific new section, button, tab, etc. Follow [message principles](/content/writing-for-mirakl) to write product tour messages.
### Updated experience or feature
#### Entry point
* **Shoutout**
Shoutout messages appear temporarily and push users to interact with the Mirakl interface. There can be one or several chained into a sequence. Follow [message principles](/content/writing-for-mirakl) to write a shoutout.
#### Education
* **Product tour**
Product tour spotlights are meant to help the user focus on a specific new section, button, tab, etc. Follow [message principles](/content/writing-for-mirakl) to write product tour messages.
# Advanced selection
Allows users to make an informed selection of items with an editable restitution of data.
## Overview
There are 2 types of selection patterns at Mirakl. Either the selection is simple with one parameter, in which case we use a [Select picker](/design/components/form/pickers#90df62) and a dropdown menu. But in other cases, users need more time or information to make a clear choice. That's when the advanced selection pattern comes in handy.
### When to use
* When the list of selectable items is long
* When the user needs more context to make an informed decision
* When a visual restitution of the selection is needed, and when that restitution must be actionable and editable
### When to not use
* [When the list of selectable items is less than 10 options](#user-content-fn-1)[^1]
## Guidelines
Several components can trigger an advanced picker modal:
Inline advanced pickerButton (In a toolbar, in a form...)Link button with counterYes per [item]
### Advanced picker modal
1. **Header**: always a sorted column by default
2. **Toolbar**: 3 filters maximum, search bar for filtering data, density management
3. **Bulk**: only used to mass select items, no action is triggered by bulk selection
4. **Pagination**: load more only
### Data restitution
The component you'll use to trigger the advanced picker modal will depend on the data restitution you want on your page.
| Trigger | Data restitution |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Inline advanced picker | Inline advanced picker with item list |
| [Button](/design/components/actions/buttons) | [Datalist](/design/components/datalist), [Datatable](/design/components/datatable) |
| [Link Button](/design/components/actions/buttons#link-button) | [Datalist](/design/components/datalist), [Datatable](/design/components/datatable) |
[^1]:
# Configure options
Simplify user choices in configuring their settings.
**Overview**
Configuring settings can significantly affect user operations, whether options are turned on or off. Clear design simplifies decision-making and minimizes confusion. We employ various design elements such as checkboxes and activable panels to ensure the process is clear and user-friendly.
## **Checkbox**
exemple of how a checkbox is used to activate an option
* **Usage:** Employ a simple checkbox to enable users to opt into a simple feature. Checkboxes are suitable for straightforward options and can be displayed individually or grouped with others that are semantically related to streamline the user interface.
* **Implementation:** Since checkboxes are form elements, a save bar is required to commit any changes made.
## **Activable Panels**
An [Activable Panel](/design/components/structure/panel/activable-panel) can show or hide parts of a form depending on whether a setting is turned on or off. It does not save any changes by itself.
Exemple of the use of an Activable Panel
* **Benefits:** Using these panels helps keep your form neat and easy to understand. It reduces the need for many checkboxes and makes the form less confusing.
* **Important Note:** When you activate a panel, it might show a lot of new information. Make sure that this information is necessary and does not overwhelm the user.
* **Activable Panel or Switch inside the panel ?**
* If activating a setting shows or hides the entire panel, use the Activable Panel.
* If different elements in the panel are shown or hiden separately, use one or several switch within the panel to control these changes.
Exemple of using several switches in a panel
## Radio group card
exemple of a use of Checkbox Group Card to configure options
* **Usage:** Use a Radio Group Card when users need to choose between two or three options, each with its own related settings.
* **Functionality:** This component lets users easily switch between different options. It keeps the user interface tidy and makes it clear when moving from one option to another.
* **Important Note:** Use this component in a column layout, not in a row.
# Deletion
Guidelines for implementing safe, clear, and intentional deletion workflows that protect users from unintended data loss.
Deletion is a critical operation that permanently removes data from the system. Unlike other actions, deletion often cannot be undone and can have serious consequences for business activities. These guidelines ensure users make informed decisions and prevent accidental data loss.
### Types of deletions
#### Permanent Deletion
Data is irreversibly destroyed and cannot be recovered. **Use when:**
* Regulatory or privacy requirements mandate data destruction
* Storage constraints require permanent removal
* Data has no business value for retention
**Examples:** Deleting customer personal data (GDPR compliance), purging old logs, removing test data
#### Soft Deletion (Recommended)
Data is hidden or marked as deleted but can be restored within a timeframe. **Use when:**
* Users may need to recover deleted items
* Audit trails are important
* Regulatory compliance requires retention
**Examples:** Deleted products, deactivating integrations, moving items to trash
{% hint style="success" %}
**Implementation:** Mark items as "deleted" with a timestamp, allow restoration within 30 days, then permanently delete.
{% endhint %}
### Displaying destructive actions within the interface
#### Use destructive components
Use the **Destructive** Button variant to signal critical actions. Destructive actions should be nested in an [ActionMenu](/design/components/actions/action-menu) under a [MenuButton](/design/components/actions/buttons) and regrouped all together at the end of the menu, or placed in non-intrusive locations where they are not immediately visible to users.
Normal actions vs critical actions
#### Implementation examples
**Example of destructive button in a page title:**
Action menu with a destructive ActionMenuItem
{% hint style="success" %}
**Dos:**
* Nest the action in an ActionMenu - using a Destructive ActionMenuItem - under a MenuButton
* Group all destructive actions at the end of the list
{% endhint %}
{% hint style="danger" %}
**Don't**
* Show a destructive action as primary action in PageTitle
{% endhint %}
**Example of a destructive button in a datatable:**
Datatable using trailing actions in an actionMenu with a destructive action
{% hint style="success" %}
**Dos**
* Use datatable trailing actions with an ActionMenu to nest the critical action
{% endhint %}
{% hint style="danger" %}
**Don't**
* Use datatable trailing actions with button to show the critical action within the datatable
{% endhint %}
**Example of a destructive button in bulk actions:**
{% hint style="success" %}
**Dos**
* Nest the critical action under the additional actions MenuButton
{% endhint %}
{% hint style="danger" %}
**Don't**
* Use a button directly visible within the bulk bar
{% endhint %}
#### Always ask user confirmation
**All deletion actions must be confirmed by users through a non-skippable confirmation modal.** This ensures users understand what will be deleted and prevents accidental data loss. Never allow direct deletion through a single click or keyboard shortcut without explicit confirmation.
Simple destructive confirmation Modal
### Critical deletion
Critical actions have serious, often irreversible consequences for business activities such as deleting data, canceling orders, disabling integrations, or removing configurations.
#### What are critical actions?
Operations that:
* Permanently delete, deactivate or destroy data (products, orders, stores, configurations) that will have a business impact
* Break relationships (removing integrations, disconnecting channels)
* Trigger irreversible consequences (canceling live orders, disabling features)
* Affect multiple users or systems (deleting shared resources, removing permissions)
#### Core principles
**Intentionality**
Users must **actively choose** to perform critical actions. Never allow accidental triggers through single clicks, hover-only interactions, or shortcuts.
**Be fully transparent**. The user must understand the consequences before taking action.
* State exactly what will be deleted/affected
* Explain what cannot be undone
* Identify dependent objects or data
When permanent deletion is necessary, make this absolutely clear.
#### Always require user confirmation
All critical deletions must require a **strong** and **non-skippable** confirmation modal.
Strong confirmation modal for a critical and destructive action
**Structure**
1. **Header with status**: State the action clearly
* ✅ "Delete product mapping configuration"
* ❌ "Are you sure?" (too vague)
2. **Description**: Explain consequences without questions
* State what will be deleted
* Clarify irreversibility
* Mention dependencies
3. **Strong confirmation input**: require the user to type the action name before they can confirm the modal.
{% hint style="success" %}
**When to Use:**
* Deleting or permanently removing data
* Canceling active processes with business impact
* Disabling critical integrations
* Removing access or permissions
* Bulk operations affecting multiple items
{% endhint %}
{% hint style="danger" %}
**Do not use for:** Routine actions, reversible changes, low-consequence operations
{% endhint %}
# Displaying data
Datalist or datatable, that is the question.
Our products are designed to handle significant volumes of data : whether detailing orders, stores, or users, to name a few examples.
Therefore, when it comes to displaying data on the Mirakl platform, two useful components can assist you: [Datalist](#07bd9c) and [Datatable](#63069b).
## Datatable
[Datatables](/design/components/datatable) are made to display a large volume of information in a grid format with rows and columns.
### Tabs in datatable
Tabs main objective is **to help users in their variety to perform their jobs to be done** within the same dataset. Therefore, when using tabs in datatables, there's no strict rule – flexibility is key : as long as it serve the end users in their experience.
Tabs are not mandatory, and if employed, they can be utilized in two use cases:
#### 1 - Tabs as quick filters
exemple of using tabs as quick filters
Tabs act as quick filters, allowing users to navigate through specific categories or segments of the dataset.
Examples : quick filters for different stages in a workflow (e.g., acceptance statuses in order tables). \
The default "all" tab provides a comprehensive view, and clicking on other tabs activates corresponding filters (e.g., "in progress" tab shows the filter in the "in progress" toolbar). \
Statuses are visible in the toolbar because users can add/remove other statuses to this view; therefore, it is important to display all of the statuses.
#### 2 - Tabs as separators
exemple of using tabs as q
Tabs act as separators between two different datatables, but their content is related to the same topic.
In this case, an "all" tab is not needed. Also, "statuses" are not visible because tab titles are free of content, not specifically related to a status or to information displayed in the datatable.
Examples : There are two distinct data tables separated by tabs: one for validated data and one for data currently in process. The second one displays information that requires user action to move into the first.
## Datalist
[Datalists](/design/components/datalist) are designed to list objects of similar types.
They are typically used for displaying information that would fits within 1 to 5 columns in a datatable. Datalist provides a more concise option in scenarios, they are well-suited for situations where a straightforward, list-style presentation of data is desired.
### Datatable or datalist?
To decide between the two layouts, first, examine the available properties :
| **Props** | **Datatable** | **Datalist** |
| --------------------- | ------------------------- | --------------------- |
| Has header | ✅ | ❌ |
| Has filters | ✅ | ✅ |
| Horizontal scroll | ✅ | ❌ |
| Responsive management | At`Datatable` level | At row level |
| Pagination | ✅ | ❌ + Load more CTA |
| Sort | At header level, optional | Sort by CTA, optional |
Then, consider the following factors when making your decision:
* **Nature of Data:** Structured data with multiple attributes may benefit from a datatable, while simple lists or suggestions may be better suited for a datalist.
* **User Interactions:** Consider the interactions users will have with the data. If they need to sort, filter, or interact with complex data relationships, a datatable may be more suitable.
# Displaying history
Tracking changes and progression over time.
When it comes to displaying history on our platform, you can choose between two main components: **HistoryTable** and **Timeline**.
## **HistoryTable**
A **HistoryTable** is ideal for displaying detailed records of changes. It allows users to view not just the modifications themselves, but also key information about who made those changes, when they occurred, and what values were changed (before and after the modification).
**Key Features of a HistoryTable**:
* **Bundles of Changes**: Organizes changes into logical groups, helping users see sets of related modifications.
* **Who, When, What**: Provides clear visibility on who initiated the change and when, alongside a snapshot of the values before and after the change.
* **Audit-Ready**: Ideal for scenarios where tracking detailed records of all actions is crucial, especially for auditing purposes.
*Example*: Viewing a list of price updates for a product, with details on who made the change, what the old price was, and what it has been updated to.
{% hint style="info" %}
This pattern requires a combination of a datatable on a full page and a side drawer to display details.
{% endhint %}
## **Timeline**
A **Timeline** focuses on displaying the progression of an object over time. Instead of showing granular details of each change, it presents a high-level view of the object’s history, showing the key milestones in its lifecycle.
**Key Features of a Timeline**:
* **Progressive View**: Visualizes the progression of an object through different stages or statuses.
* **Simplified History**: Instead of showing every single change, it highlights key events that mark significant points in the object's journey.
* **Narrative Flow**: Timelines are ideal when the goal is to understand how an object or entity evolved over time, rather than the specific details of each change.
*Example*: Viewing the status changes of an order, such as "created," "shipped," "delivered," with clear timestamps marking each transition.
{% hint style="info" %}
A timeline can be displayed either on a full page or within a side drawer.
{% endhint %}
{% hint style="info" %}
Timeline or Tasklist ?\
A **Timeline** shows the progression of an item, detailing past actions or upcoming events, while a [**Tasklist**](/design/components/actions/tasklist) helps users follow a process and take actions, focusing on tasks that need to be completed rather than reflecting past events.
{% endhint %}
## **HistoryTable or Timeline?**
When deciding between these two approaches, consider the following criteria:
| **Criteria** | **HistoryTable** | **Timeline** |
| ---------------- | ------------------------------------------------ | --------------------------------------------- |
| Focus on detail | Detailed view of changes (who, what, when) | High-level overview of key events |
| Data granularity | Shows bundles of changes and value modifications | Focuses on significant progression steps |
| Use case | Ideal for auditing or reviewing specific changes | Ideal for tracking the overall flow of events |
| Example | Price updates, user action logs | Status progression of an order |
Choose a **HistoryTable** when users need to dive deep into the specifics of each change, including before-and-after values and the actions taken by users. Opt for a **Timeline** when the goal is to give users a more narrative view of how an object has evolved over time, showing only the most critical events in its history.
# Errors
Allows users to fix problems themselves through thoughtful messaging.
## Overview
An error occurs when something else happens from the initially expected result. It comes in various formats and types, from forgetting to fill in a field to a 404 page by way of some action being impossible to perform.
Errors can happen to any role using the Mirakl platform in many different situations. But what they have in common is that they confuse, annoy, stress, or cause extra work for Mirakl users.
That's why messages should follow [UX writing principles](/content/writing-for-mirakl) (clear and useful especially) and always have the user's feelings in mind.
For sure, an error temporarily breaks the experience, but it does not have to end it.
## Guidelines
#### Focus on the solution, not the problem
Even though it is super important to explain what happened to our users, focus on what they can do to fix the issue, even though it may sound vague to you ("Try again later").
The main takeaway is don't focus on what the user did not do or did wrong. Help them understand what they can do.
{% hint style="success" %}
Impossible to load your order list. Try again later.
{% endhint %}
{% hint style="danger" %}
Your order list would not load.
{% endhint %}
{% hint style="success" %}
Provide at least one email address.
{% endhint %}
{% hint style="danger" %}
Provide at least one email address.
{% endhint %}
#### Use generic language but technical terms
Our users know their business and the vocabulary that comes with it. But this does not mean we write complex sentences and use unneeded jargon. Write error messages in [plain language](https://www.plainlanguage.gov/guidelines/) and focus on clarity.
{% hint style="success" %}
The code challenge you entered is invalid.
{% endhint %}
{% hint style="danger" %}
Invalid "code\_challenge" parameter
{% endhint %}
#### Don't blame the user
Surely you need to explain what kind of problem happened, but this does not mean you have to blame them, even if they are responsible. Focus on the action they need to take to solve it. Always put the error into perspective to de-dramatize the situation when possible.
{% hint style="success" %}
Remember to provide your billing address.
{% endhint %}
{% hint style="danger" %}
You forgot to add your billing address.
{% endhint %}
#### Be as precise as possible (and it's ok if sometimes you can't)
To help users solve their problems, they must first understand what happened. Be as precise as possible when explaining: is it a limited-time problem? Did they forget to add information in a form? Is it the service's fault?
Take the space you need to explain what is going on. If you do not have the space to do so, ask your designer to switch components.
Sometimes, you don't know what's happening and can't be as precise as you wish. Be generic, then, but without being unclear.
{% hint style="success" %}
You cannot delete a section that contains at least one custom field.
{% endhint %}
{% hint style="success" %}
Something went wrong while updating your order. Try again in a few minutes.
{% endhint %}
#### Users don't care about the technical stuff (most of the time)
Even if our product tackles complex processes, that doesn't mean we have to sound complex or showcase our technical knowledge. That's the same for error messages. Focus on what users need to do with terms they understand.
{% hint style="success" %}
You have made too many requests recently. Wait for a while and try again.
{% endhint %}
{% hint style="danger" %}
Time out, too many requests recently.
{% endhint %}
In certain circumstances, technical information like error codes can be useful to some users (think developers). You may add them at the end of your message or in the following line.
#### No jokes, no puns; watch your tone.
Users facing errors can feel stressed or panicked depending on the size of the problem. This is not the time to make puns or jokes that could increase this feeling and delay them in solving the error.
{% hint style="success" %}
Our platform is temporarily down
{% endhint %}
{% hint style="danger" %}
Oops, impossible to log in.
{% endhint %}
## Content
As writers and designers, we love creating efficient and delightful user experiences. Even if something goes wrong, let's ensure the experience we offer is as efficient as possible and gets users back on the right track.
There are 3 main parts within an error message: the explanation of [what went wrong](https://zeroheight.com/065715af6/p/89c6ee-errors/t/7774ff), the [why](https://zeroheight.com/065715af6/p/89c6ee-errors/t/331c9a), and the focus on [how to fix the issue](https://zeroheight.com/065715af6/p/89c6ee-errors/t/924b76).
#### 1. What went wrong
Let's start by explaining the issue, whether small or big. Be as clear as possible with the user in mind and try to [use generic language](https://zeroheight.com/065715af6/p/89c6ee-errors/t/01545c).
{% hint style="success" %}
You are not authorized to access this page.
{% endhint %}
{% hint style="success" %}
Impossible to upload your file
{% endhint %}
{% hint style="info" %}
Do not apologize for minor issues; only say **sorry** for major issues.
{% endhint %}
{% hint style="info" %}
Depending on the components, this information will be placed as a title (empty state, alert) or within the message (snackbar, form field).
{% endhint %}
#### 2. Why
Users are more likely to tolerate the error if they understand why things went wrong. If there's enough space in your component, include it.
{% hint style="success" %}
You cannot reply to this conversation because seller-operator messaging is disabled.
{% endhint %}
{% hint style="success" %}
Unable to upload your file because it exceeds the 1 MB size limit.
{% endhint %}
{% hint style="danger" %}
You cannot reply to this conversation.
{% endhint %}
#### 3. How to fix the issue
Two options here:
* Users cannot do anything about the issue: explain what the product is doing.
* Users can do something: explain what they can do instead, or even better, provide a way out within the error message, like a button.
{% hint style="success" %}
Impossible to load your order list. Try again later.
{% endhint %}
{% hint style="success" %}
The requested resource is currently unavailable. The issue is being fixed so the resource can become available again soon.
{% endhint %}
## Examples in components
#### [Alert](/design/components/feedback/alerts)
Alerts highlight important information that needs to be communicated quickly to the user. If the alert describes an error, the content must explain how this error can be fixed.
#### [Empty state](/design/components/feedback/empty-state)
Empty states should be used when the expected content cannot be displayed. When the user faces network or generic technical issues preventing us from showing them the data they are looking for, text should be clear on what is happening and if the user can do anything about it.
#### [Form](/design/patterns/forms)
When submitting information within a form, users can encounter errors. Make sure users know how they can fix these errors themselves.
#### [Snackbar](/design/components/feedback/snackbar)
Snackbars only appear for 5 seconds and should be used for minor errors only.
## Checklist
* Is it a blocker?
| If yes | Mind your tone, and explain what is happening. |
| ------ | ------------------------------------------------ |
| If no | Be clear and concise, and focus on the solution. |
* Is the user persona technical?
| If yes | Then you may add an error code at the end of your message and use technical jargon. |
| ------ | ----------------------------------------------------------------------------------- |
| If no | Focus on what users need to do with terms they understand. |
* Do you know what caused the error AND is it important for the user to know?
| If yes | Be precise about what went wrong but quickly switch to how users can fix the issue. |
| ------ | ----------------------------------------------------------------------------------- |
| If no | Focus on the solution. |
# Forms
Allow users to submit or edit information.
This section describes all design and content rules for forms using Roma.
\
Some behaviors remains consistent to every forms such as how to manage backlink or error management. Those are General Guidelines.\
But some behaviors or layout may varies. Take a look to dedicated section "Specific guidelines - Creation vs edition mode".
Go to the dedicated section for more information regarding [form components](/design/components/form) (e.g. fields, pickers).
# Form - Creation mode
A creation form is when users create an object or add an element that did not exist before.
## Layout - Overview
### Page Title
Exemple of a Page Title
* **Visibility:** The page title is always visible on a creation form.
* **Content:** "Add *\[object name]*" or "Create **\[object name]**"
* **Navigation:** Include a backlink for easy return to the previous page, unless this is the first page in the hierarchy.
* **Backlink Content:** "Back to *\[landing page title]*", where *\[landing page title]* is the exact title of the return page.
* **Additional Information:** [Learn more about Page Titles and Backlinks](/design/components/navigation/page-title).
### Save Bar
Save Bar in a creation mode form
* **Visibility:** The Save Bar is always visible in creation mode.
* **Functionality:** Both '*Save*' and '*Cancel*' buttons are enabled when the Save Bar is visible.
## Form submission
### Success
*When users have successfully saved the form*
* **Single Object Creation:**
* **Process:** After creating a single object, users are redirected to the previous page, accompanied by a success notification.
* **Notification Content:** "\[Object name] added" or "\[Object name] created".
* **Multiple Object Creation:**
* **Process:** After saving the form, users have the option to create another object.
* **Notification:** Display a success alert with options for additional actions.
Exemple of a success alert when creating multiple objects in a row
### Cancel
*When users clicks Cancel or the backlink without saving form*
* **Form pristine (unmodified)** : no modal + back to previous page (in the hierarchy)
* **Form dirty:** *`Prompt-before-leave`* + back to previous page (in the hierarchy)
exemple of a Prompt Before Leave
### Prevent changes while submission
* **Processing Time:** The form becomes read-only during backend processing to prevent changes.
## Take aways
{% hint style="success" %} **Do**
* Respect Layout guidelines
* Refer to Stepper Form guidelines for long and/or complex forms
* Refer to [Error Management](/design/patterns/forms/error-management) page to guide users through the whole form experience
{% endhint %}
{% hint style="danger" %} **Don't**
* Avoid custom behaviors: keep form creation consistent across all products.
{% endhint %}
# Form - Edition mode
An Edition form is when users edit an object/edit an element that already existed.
## Layout - Overview
### Page Title
exemple of a page title
* **Visibility:** The page title is always visible on a creation form.
* **Content:** "Add *\[object name]*" or "Create **\[object name]**"
* **Navigation:** Include a backlink for easy return to the previous page, unless this is the first page in the hierarchy.
* **Backlink Content:** "Back to *\[landing page title]*", where *\[landing page title]* is the exact title of the return page.
* **Additional Information:** [Learn more about Page Titles and Backlinks](/design/components/navigation/page-title).
### Save Bar
Close-up on Save Bar
* **Visibility:** The Save Bar remains hidden until one field in the form has been changed.
* **Functionality:** Both '*Save*' and '*Cancel*' buttons are enabled when the Save Bar is visible.
{% hint style="info" %}
This behavior cannot be automated in ROMA. Designers must specify to developpers this behavior during handoff.
{% endhint %}
## Form submission
### Success behavior
*When the user successfully changes one or several inputs in the form.*
* Add a success [snackbar](/design/components/feedback/snackbar)
* The form stays in edition mode
* The user stays on the form page
* Follow the \[item] + past participate verb format.
{% hint style="info" %}
You do not need to add words such as "successfully" or "with success". [Learn more](/design/components/feedback/snackbar#0969f1)
{% endhint %}
### Discard edits
When the user clicks Discard or the backlink without saving form.
* **Form Pristine (unmodified)**: no modal + back to previous page
* **Form Dirty**: Confirm Modal + form goes back to the initial state (before changes) + user stays on form page
### Prevent changes while submission
Avoid custom behaviors: keep form creation consistent across all products.
## Take aways
{% hint style="success" %} **Do**
* Respect Layout guidelines
* Refer to [Error Management](/design/patterns/forms/error-management) page to guide users through the whole form experience
{% endhint %}
{% hint style="danger" %} **Don't**
* Custom any behavior : form creation must remain consitent throught all products
* Show the Save Bar before any changes has been made
{% endhint %}
# Form - In a modal
This page describes specific rules to form within a modal.
## Overview
For forms, the main guideline is to display it in a dedicated page. But in few cases it may be complex to create a new page for a form. Thus, to ease the experience, in those cases you may create a form in a modal :
* When there are not many fields (3 to 5 fields)
* When forms are embedded (a form in an another form)
* When creating an object in a form (create a rule, add a parameter (...) in a form)
Form in a modale
## Guidelines
### Save Bar
* **Visibility:** The Save Bar is always shown in a form in modal
* **Functionality:** Both '*Save*' and '*Cancel*' buttons are enabled
### Behaviors
* `Save` action closes the modal and triggers a [snackbar](/design/components/feedback/snackbar) on the main page
* Same [error management](/design/patterns/forms/error-management) as a regular creation form
### Limitations
{% hint style="warning" %}
A modal should not trigger another modal. You may be obliged to do so, but be aware of possible poorer experience. You should test your mock-up in those cases to be sure users are able to navigate through the form.
{% endhint %}
Thus, those inputs may be complex to use in a form within a modal:
* `DateRange Picker`
* `Date Time Picker`
There is one component that can never be used in a form within a modal :
* `Advanced Picker`
However, a modal can trigger overlays such as `Dropdowns`, `Tooltips`, etc.
## Create an object in a form through a modal
When a form involves creating an object, it’s important to determine whether the object should be created within the form itself or through a modal.
1. **Simple Objects**:
* If the object is simple and requires only a few fields, use a specific panel or a card within the form.
* This approach is less intrusive and allows users to quickly input necessary information without navigating away from the form.
2. **Complex Objects**:
* When the object involves dynamic blocks with more than one field, it is better to use a modal.
* Modals provide more flexibility and space to handle complex data inputs.
3. **Benefits of Using Modals**:
* **Separation of Concerns**: Modals allow for a clear distinction between the main form and the sub-form used for creating the object.
* **Error Management**: It becomes easier to handle errors specific to the object creation separately from those of the main form.
* **Data Management**: Results from the modal can be returned and displayed in a datatable within the main form, ensuring a clear organization of nested objects.
4. **Implementation Tips**:
* Ensure the modal is user-friendly and intuitive, providing clear instructions and feedback.
* Use appropriate validations and error messages within the modal to ensure data integrity.
* Upon successful creation of the object, update the datatable in the main form to reflect the new data without requiring a full page refresh.
# Error Management
How we guide users to handle mistakes on their forms
{% hint style="info" %}
Behaviors listed on this page are a*utomatically handled by ROMA (Design + Content).*
{% endhint %}
## Inform users
*When the form cannot be saved due to wrong inputs from the user.*
* Alert Error (red) with number of errors + list of inputs in errors (in the form order) + anchor to each input
* The form stays in creation mode
A form with errors
{% hint style="info" %}
Error for empty fields is automatically managed, content can not be changed ("Required Field")
{% endhint %}
{% hint style="info" %}
For Forms using "Save as draft", it is only possible to save valid values, even just as draft. Otherwise, for unvalid values, error management remains the same
{% endhint %}
## Users correct errors
*When the user tries to correct a field in error state after an unsuccessful save*
* `onBlur` Input in error state changes to default state
* `onChange` Input stays in default state **unless** there is a "front error" (invalid characters; ...). Then, the input changes back to error state
## Technical error
*When a technical error occurs while the user tries to save the form.*
* Snackbar with following content : \[*An error occurred on our end. Try refreshing the page*.]
* The form stays in creation mode
Forms are one of the few cases where a snackbar informs users of a technical error, not a [empty state](https://design.mirakl.com/patterns/loading#loading-error). It allows to retry sending form without losing current page and its informations.
## Frequently Asked Questions
> If my field already has a helptext but is in error when users tries to save the form : what should I do ?
**A field can only have one helptext**. Thus, when an error occurs on a field that already had a helptext, the error state takes over it.
> Can we notify users they made a mistake before they even try to save the form
We don't allow "*as-you-type*" error management. Always let users validate their form before notify errors. It will let them correct themselves before even trying to send form.
> How do we manage Error Management with a confirmation modale to a form ?
Sometimes we add a confirmation modale to a form. It helps users to be more cautious about sensitive actions.\
In this case, Error Management (back and front errors) are both launched when user clicks on `Primary Button` of the modale.
## Key Take Away
{% hint style="success" %} **Do**
* Inform and guide users. They should be able to understand by themselves how to correct their form.
* Use field component on their `Error Variant`
* Add an anchor to each imput for users to access directly from the alert
{% endhint %}
{% hint style="danger" %} **Don't**
Custom Error management : it must remain the same to every form
{% endhint %}
{% hint style="info" %}
Learn more about [Error Management guidelines and content](/design/patterns/errors) through the plateform
{% endhint %}
# Stepper form
Stepper is designed to help users fill a complex or long form. By deviding forms into smaller steps, we reduce users mental load and clarifies information structure.
## Overview
`Stepper` should be used:
* For standard, sequenced experiences
* For complex item creation
`Stepper` should not be used:
* For onboarding experiences. Use the [Onboarding form ](/design/patterns/forms/onboarding-form)instead.
{% hint style="danger" %}
Never add an illustration to a stepper. Use the [Onboarding form ](/design/patterns/forms/onboarding-form)instead.
{% endhint %}
## Guidelines
#### One topic at a time
Do not confuse users with mixed topics within a single step; **keep one idea per screen**.
#### Fields must be easy to fill
Use standard form components such as [fields](/design/components/form/fields), [select](/design/components/form/selection-controls) options, [checkboxes](/design/components/form/selection-controls#41d3fe-1), etc.
#### Provide enough context and guidance
Users need to understand why we're asking for specific information and how we will use that information. Add context and guidance to make the user feel confident.
## Structure
### Page Title
Unlike other forms where [Back link on Page Title](https://design.mirakl.com/components/navigation/page-title) uses "Back to..." structure, here we use "Exit". It helps users understand this link will leave the form, not going back to the previous step.
Therefore, you must not add an "*Exit*" option in the Save Bar : it will unnecessary duplicate the option and confuse users or make the interface appear cluttered.
### Progress steps
Bar with validation steps, only usable within the stepper component
* Keep labels short and consistent (nouns for all steps, actions for all steps).
* Steps are not clickable. Users must complete each step before going to the next one.
### Summary (Optional Layout)
To help users complete forms, a summary can be added to the right side.
Stepper form with a summary
Adding a summary to a stepper form can be useful in the following use cases :
* Provide additional informations related to the form to help users fill in the form (ex : add context to help create a new object)
* Remind users of informations filled in previous steps of current form
For this layout, `Form panel` is 640px, Summary panel is 360px with 24px separation.
{% hint style="info" %}
Responsive : The summary is not necessary for the mobile display. ROMA handle this automatically.
{% endhint %}
### Savebar
`Savebar` actions are standardized.
* One [button group](/design/components/actions/button-group) with Back + Continue actions
* A third action "*Save as draft*" can be added depending on needs. It will save informations as it is and exit the form.
When the user clicks the Primary button on the last step of the Stepper, the Async button gets a Loading status.
Save Bar sticks to the bottom of the page to be always accessible in case of scrolling page. If your page isn't scrollable, Save Bar will stick to Panel Content as following :
## Behaviors
### Last steps
For the last step, `Primary Button` content changes to "**Save**" : it indicate it's the final action on the stepper form. \
When clicked, the `Primary Button` changes its state to 'Loading' before saving and exiting the form.
### Returning on form
If a user exits a stepper form without submitting it, and the form is saved as a draft, when they return, they will start from the first step of the form.
This is because adding a Summary is optional. Therefore, users might not remember the initial steps of the form.
### Error management
{% hint style="info" %}
Errors are managed automatically by Roma.
{% endhint %}
Users are aware of errors when the color of the relevant progress steps changes.
* If there are errors within one step of the stepper, the user is automatically redirected to the relevant step.
* If there are errors within several steps of the stepper, the user is redirected to the first step where there’s an error. The user can then navigate between the steps to solve their errors.
Progress steps in error state
An [alert](/design/components/feedback/alerts) appears at the top of the page, displaying all the errors from the current step.
Error management in forms
Once the errors are resolved, the user must save the step. If they fail to do so and click on the progress steps component, they will trigger a 'prompt before you leave' modal.
If an input is in an error state, but content is already filled in the Summary panel:
* The input field remains in an error state until the user makes changes.
* The content of the input in error is not erased.
* The content in the Summary panel does not change until the user makes changes.
# Onboarding form
The onboarding stepper is dedicated to onboarding experiences for new users. Its simple design helps users provide key information quickly and seamlessly.
### Overview
Within Mirakl, the onboarding stepper should be used:
* When a user is setting up an account for the first time
* When a user is setting up an organization for the first time
* When a seller is creating a store
The onboarding stepper shouldn’t be used:
* For standard, sequenced experiences. Use [Stepper form](/design/patterns/forms/stepper-form) instead.
{% hint style="danger" %}
Do not use a datatable within the onboarding layout.
{% endhint %}
### Guidelines
#### One topic at a time
Do not confuse users with mixed topics within a single step; keep one idea per screen.
#### Mind the number and length of steps
When asking Mirakl users for information, keep the number of steps to an amount users are able to take in (4 or 5).
#### Fields must be easy to fill
Users must fill in their form quickly to secure their arrival on Mirakl. Use standard form components such as [fields](/design/components/form/fields), [select](/design/components/form/selection-controls) options, [checkboxes](/design/components/form/selection-controls#41d3fe-1), etc.
#### Provide enough context and guidance
Users need to understand why we're asking for specific information and how we will use that information. Add context and guidance to make the user feel confident.
### Structure
The onboarding stepper is made of:
* On the right side, an [illustration picked from the Mirakl library](/design/components/images/illustrations) that must be relevant to the overall theme of the form
Illustrations fitting the onboarding stepper
* On the left other side, a form with:
* A logo (optional + can be changed at each step of the form)
* A title
* A progress bar
* Form fields
* Save/Cancel button group
The onboarding stepper has 2 save modes:
* in memory (when the last step is approved)
* in the database (save at the end of each step)
You may add an [activity loader](/design/components/feedback/activity-loader) at the end of your onboarding stepper.
### Error management
{% hint style="info" %}
Errors are managed automatically by Roma.
{% endhint %}
* If there are errors within one step of the stepper, the user is automatically redirected to the relevant step.
* If there are errors within several steps of the stepper, the user is redirected to the first step where there’s an error.
# Loading
Reduces load time frustration and makes the page feel more responsive.
## Overview
Our products handle tons of data for our services to run smoothly. Thus, *some pages* may be technically heavy to load when needing a few API or database calls. To improve the user experience while data is loading, we've defined a loading pattern. It's a temporary animation placeholder representing the page content before it's ready to display.
This animation's main objective is to **enhance perceived performance** by reducing load time frustration and making the page feel more responsive.
{% hint style="info" %}
Loading patterns are meant to be used only when pages have to call different technical services to load content. It has been designed for those key moments when users must wait a few seconds before accessing their data.
{% endhint %}
{% hint style="warning" %}
Do not overuse those patterns for easily accessible content, as it might overload the global user experience.
{% endhint %}
## Skeleton loading
### **When to use it**
`Loading State` is triggered by the user's navigation or action. It appears when users open a new page or click on an action that reloads content.
In most cases, we already know what the page will look like when fully loaded; we miss the real data for a few seconds. In those cases, we favor the use of the `Skeleton Loading Pattern`. It provides a low-fidelity representation of the interface. The real content will take the place of the grey skeleton.
### **How to use it**
We use `Dark Skeleton` on a light background (Greyscale colors) and `Light Skeleton` on a dark background (for the menu, for example).
This behavior is created by the `Skeleton props` of the following components:
* [Page Title](/design/components/navigation/page-title)
* [Page navigation](/design/components/navigation/page-title#8396b2)
* [Cards](/design/components/structure/card)
* [Panels](/design/components/structure/panel)
* [Modal](/design/components/overlays/modal) (only for Modal displaying heavy content, not simple confirmation modal)
Props `Loading: True/False` are already technically integrated into those components. But each element needs to be set up into its loading state.
As a page will mostly always have a `Page Title` there are great chances you can start with this component when setting up the Loading Pattern.
Regarding the actual page content, we aim to provide a close preview of the upcoming content, **but it doesn't have to be 100% accurate**. Be as precise as possible but don't lose yourself in too much detail when creating your prototype.
*It's okay to show only two loading panels when the page will provide three panels.*
Also, some panels may not call the same API or Database. We authorize asynchronous loading between the different panels, meaning some content elements may load faster than others on the same page. However, inside a single panel, we cannot support asynchronous loading. This means that for panels with tabs (inside navigation), all tabs' content will be loaded at once.
Note that `Skeleton Loading Pattern` is fully automated for the following components:
* [Datatable](/design/components/datatable)
* [Datalist ](/design/components/datalist)
### **How to not use it**
* Do not use this pattern if you cannot predict the loading of page content
* If loading data is too unpredictable.
* If you call an external service.
In those cases, use `Spinner Loading Pattern`.
## Spinner loading
### **When to use it**
In rare cases, we cannot predict what the page will look like when fully loaded. It may happen when calling external services (Third-party microservices...). Thus, we cannot provide a low-fidelity representation of the interface loading.
In those cases, we privilege the use of `Spinner Loading Pattern`. It shows a basic animated spinner in the center of the page content. The actual content will load when all of it is available.
### **How to use it**
There is only one greyed spinner for this animation. It has to be placed in the center of the page.
### **How to not use it**
**This pattern must be an exception** when we cannot predict a low-fidelity representation of the page content. It must not be used as an easy-lazy loading pattern.
## Activity loader
For more information on this component, check the [activity loader page](/design/components/feedback/activity-loader).
## Loading error
Errors happen. The loading time may be too long, or we cannot retrieve the data needed to complete page content.
**Users should not wait more than 10 seconds for something to happen on the page,** whether it's a success or a failed loading. If any failed loading happens, we must force the end to Loading State, notify users something went wrong, and provide a solution.
{% hint style="info" %}
Automatically handled by ROMA.
{% endhint %}
[Learn more about Error messages](/design/patterns/errors)
# Progressive disclosure
Reveal gradually information to minimize cognitive load for a more intuitive design experience.
## Progressive Disclosure in Forms
Forms vary from simple layouts with few inputs to complex structures with many components. **Progressive disclosure helps manage this complexity without overwhelming the user.** This approach involves a strategic use of design elements to enhance efficiency and understanding.
### **Structuring Information in panels**
Start by organizing related fields into [panels](/design/components/structure/panel) or using panel separators.
This groups related information together, making it easier to understand and follow. Panels not only help in organizing the form but also make it visually appealing and guide users through the information logically.
Before adding a new panel, consider whether new fields can be accommodated within existing panels.
Example of the use of panels in a form that guides users
### **Dependency Dynamics**
#### **Enabling and Disabling Fields**
Some forms have fields that depend on each other; the selection in one field can enable or disable another. Clearly show these dependencies using tooltips that appear when users hover over a disabled field. This helps users understand why some options are not available.
Example of the use of disable fields in a form that guides users
#### **Enable vs. hide**
* **If a control is not applicable until a choice is made**, hide it at first and reveal it when the triggering choice is selected.
* Rationale: avoids noise when the user cannot act yet.
* **If the user needs awareness** that a control exists but is currently unavailable, show it disabled.
* Rationale: sets expectations and communicates capability, even if it’s not yet actionable.
* **If the dependent control is critical to task completion**, prefer revealing it (enabled) immediately after the trigger is satisfied, keeping focus in context.
{% hint style="info" %}
**Accessibility note**: hidden content must not be reachable by keyboard or screen readers; disabled controls are perceivable but not focusable in many UAs, so provide an accessible explanation (see next section).
{% endhint %}
#### Using SubContentWrapper for Nested Dependencies
Progressive disclosure can reveal content in two fundamentally different ways: **peer-level conditional visibility** or **hierarchical nested content**. Understanding this distinction is critical to choosing the right pattern.
**Peer or Child?**
{% hint style="success" %}
Before revealing content, ask: **"Is the revealed content a peer requirement OR a sub-element of the trigger?"**
{% endhint %}
| Scenario | Relationship | Pattern | Visual treatment |
| ------------------------------------ | ------------------------------- | ------------------------------- | ------------------------------------------- |
| "Enable notifications" → Email field | **Peer** (separate requirement) | Standard progressive disclosure | No wrapper, field appears at same level |
| "Custom shipping" → Carrier options | **Child** (sub-configuration) | SubContentWrapper | Indented with vertical bar, nested visually |
#### **Standard Progressive Disclosure (NO SubContentWrapper)**
**Use when:** Revealed content is a **peer-level requirement** that depends on a choice but is not a sub-element of that choice.**Visual behavior:** Content appears at the same indentation level, no visual nesting.**Example scenarios:**
* ☑ Enable email notifications → \[Email address field appears]
* ☑ Apply discount code → \[Code input field appears]
* ☑ Subscribe to updates → \[Frequency selector appears]
{% hint style="info" %}
**Why no wrapper?** The email field, discount code, and frequency selector are **separate pieces of information** that happen to be required based on a choice. They are not configurations *of* the checkbox—they are peer-level form fields.
{% endhint %}
#### SubContentWrapper (WITH visual nesting)
**Use when:** Revealed content is a **child element or sub-configuration** that belongs structurally to the trigger.**Visual behavior:** Content appears indented with a vertical bar, creating clear parent → child hierarchy.**Example scenarios:**
* ◉ Custom shipping → **\[SubContentWrapper]** Carrier selection, rates, delivery options
* ◉ Enable advanced pricing → **\[SubContentWrapper]** Tier configuration, bulk discounts, rules
* ◉ Payment method: Credit card → **\[SubContentWrapper]** Card details form, billing address
{% hint style="info" %}
**Why use wrapper?** The revealed content is not just "required if you check this"—it's **part of** the thing you're configuring. Carrier options are *sub-options of* custom shipping. Card details are *the configuration of* the credit card payment method.
{% endhint %}
### Stepper forms
For long or complex forms, consider using steppers. Steppers break the form into smaller, manageable steps, helping to reduce cognitive load. They are particularly useful when user choices affect subsequent options. Steppers ensure that the user remains focused on one task at a time, adapting fields based on previous selections.
Example of the use of stepper form that guides users
#### **Considerations for Stepper Implementation**
When considering a stepper, weigh its pros and cons :
#### Pros of Using Stepper Forms
* **Guides Users Through Complex Forms**: Steppers are excellent for navigating users step-by-step through complex object creation, reducing cognitive load and ensuring focus.
* **Adaptive Fields Based on User Choices**: They can dynamically adapt fields and options based on user selections in previous steps.
#### Cons of Using Stepper Forms
* **Not Ideal for Viewing and Editing**: Once an object is created using a stepper, viewing or editing it through the same stepper can be cumbersome. It's more effective to use a single-page form for these actions.
* **Requires Design of Multiple Interfaces**: Implementing steppers necessitates designing both the multi-step creation process and a complementary single-page interface for subsequent viewing and editing.
A single page of an object created through a stepper, allowing users to have a full picture of the object without having to go through the whole stepper
## Applying Progressive Disclosure Beyond Forms
{% hint style="info" %}
We can apply Progressive Disclosure principles when activating options using an Activable Panel. [Learn more about Activating Options](/design/patterns/configure-options).
{% endhint %}
### Expendable Panels
Use panels that expand when clicked, revealing more information. This method keeps pages clear and simple, revealing more content only when needed.
Exemple of how exepandable panels allow to reduce cognitive load
### Side Drawer overlay
A side drawer can show additional details without overcrowding the main page. It's useful for examining supplementary information without leaving the current page.
Use of Side Drawer to diplay more information about an item
### **Limited Display with "See More" Trigger**
Show only part of the content at first, with a 'See More' option for users to view the rest. This keeps the display clean while allowing access to more information as needed.
**Two Ways to Use 'See More':**
1. **Expandable Wrapper**: Clicking the button expands or collapses content within the same section. The hidden content appears directly in the panel where the button is placed.
2. **"See More" Button**: The button opens more content in a different component, like a modal or a new page.
# Writing for Mirakl
Learn what writing meaningful microcopy means and how to achieve it.
## What is UX Writing exactly?
UX writing is about finding the right content and words to design interfaces that will help operators and sellers achieve more.
UX writing is different from copywriting and SEO writing (on the marketing side) as it's not meant to sell or promote anything but to help and guide users throughout a product.
UX writing is also a way of thinking. It's about using research and data to give our users the information they need at the right time and in the right format. Regarding UX writing, the less you see the words, the better.
Thus, every part of the Mirakl platform, even the smallest item, is an opportunity to increase user activity, engagement, retention, and brand preference.
## The 5 pillars of UX Writing
By order of importance:
* **User-driven:** what you write must reflect the user’s needs and feelings (achieved through research, real-life conversations, and interviews)
* **Clear:** what you write must be easy to understand (simple words, little jargon)
* **Concise:** what you write must be easy to scan (short sentences, carefully-picked words)
* **Useful:** what you write must guide or move the user forward (action verbs, guidance)
* **On-brand:** what you write must reflect the brand tone of voice (vocabulary, tone variations)
# Grammar and formatting
Discover our key grammar principles.
## Abbreviations
**Use abbreviations that are familiar to users**, don’t invent new ones. It can be useful to spell out a less common acronym the first time it’s used, and then use uppercase letters.
**Avoid Latin abbreviations**, the English sentence will be clearer to most users.
{% hint style="info" %}
Use 'For example' instead of 'e.g.'
{% endhint %}
**In full sentences, write words entirely**. Avoid short forms unless you have space constraints, in a table for instance.
**Including/Excluding**
{% hint style="success" %}
* Incl. tax
* Excl. tax
{% endhint %}
***
## Active and passive voice
#### Use the active voice rather than the passive voice as much as possible
The active voice says ’who did what’ instead of ‘what was done’. It’s more direct and it’s easier to understand. It'll also drive users to move to the next action.
* Active voice: ‘The client paid their invoice’
* Passive voice: ‘The invoice was paid by the customer’
#### You can use the passive voice in some cases
Sometimes, we need to use the passive voice to put the most important information at the beginning of a sentence. Using the passive voice also avoids blaming users.
* For example: ‘Your subscription hasn’t been paid’ instead of ‘You haven’t paid your subscription’.
***
## American English
We use American English throughout the Mirakl platform. The following common words are spelled this way.
{% hint style="success" %}
* Organization
* Canceled
* Cancelation
* Catalog
{% endhint %}
***
## Capitalization
Use sentence case
It means that only the first word is capitalized unless it’s a proper noun.
{% hint style="success" %}
Quote requests in progress
{% endhint %}
We don't use all caps. It's the written equivalent of shouting, and many people interpret it as aggressive. It's also much harder to read.
***
## Contractions
A contraction is when two or more words are combined to form a new, shortened word.
Always use the long form of auxiliary verbs and avoid contracted forms.
{% hint style="success" %}
* Do not use abrasive cleaners.
* If the unit is not functioning, check the contacts.
{% endhint %}
***
## Directional language
Words like "above", "below", "left", and "right" are directional language. Avoid using them in your writing.
Here are some of the reasons why it shouldn’t be used:
* Sometimes elements move around when screens are resized.
* It requires being able to see the screen and, therefore, is inaccessible to users using screen readers.
* It makes it harder to reuse strings and creates challenges for internationalization (for example, right to left languages).
***
## File formats
Write file formats in uppercase.
{% hint style="success" %}
* CSV
* HTML
* XLSX
{% endhint %}
{% hint style="danger" %}
* .csv
* .html
* .xlsx
{% endhint %}
***
## Lists
#### Bulleted
Use in [**popovers**](/design/components/overlays/popover) if you have more than 2 items.
Use bullet points for lists of items.
For consistency, if you start a list with a verb, use the same structure for the other items.
Don’t use punctuation at the end of the different items and don't use numbered lists.
***
## Modal verbs
Try not to use the following modal verbs, as they can confuse users:
{% hint style="danger" %}
* may, might
* could
* should
* would
{% endhint %}
***
## Dates, numbers, and units
### Dates
{% hint style="info" %}
Local formatting is handled by Roma.
{% endhint %}
{% hint style="success" %}
Nov 25, 2022
{% endhint %}
Mirakl uses the following format: **Month + day, year**
Start with the short version of the month, 3 letters.
Here is the list we use for month short version.
* Jan
* Feb
* Mar
* Apr
* May
* June
* July
* Aug
* Sept
* Oct
* Nov
* Dec
### Times and timezones
Use the 12-hour clock time convention with AM or PM in capital letters. AM stands for Ante Meridiem, meaning before noon, and PM for Post Meridiem, meaning after noon.
{% hint style="success" %}
* 11:10 PM
* 2:00 AM
{% endhint %}
To be more precise, you may want to display both date and time, for example, Nov 25, 2022, 11:10 PM.
### Numbers
Numbers are easier to scan and read than their written form. Avoid writing out numbers as words.
{% hint style="success" %}
Enter 10 in the Timeout field.
{% endhint %}
In English, use a period as a decimal separator and a comma for thousands.
{% hint style="success" %}
This pen is €3.45.
250,000 operation hours
{% endhint %}
When displaying large numbers on graphs, use abbreviated notations such as 'K' for thousands and 'M' for millions to enhance readability and save space. Begin using this format when values exceed 1,000.
{% hint style="success" %}
Write 350,000 as 350k.
Write 350,000,000 as 350M.
Write 350,000,000,000 as 350B.
{% endhint %}
***
## Pronouns
Don't assume the gender or biological sex of a user, use the generic pronoun 'they' instead of he or she.
***
## Punctuation
### Ampersands (&)
Use the word ‘and’ and not the ampersand (&). It’s a lot more accessible.
### Commas
Use a comma to separate two different ideas in a sentence.
{% hint style="success" %}
The machine is ready to start, but it is still on standby.
{% endhint %}
We use the Oxford comma, which is the final comma before “and” or “or” in lists.
{% hint style="success" %}
Additional settings are shown for font, color, and brightness in the figure below.
{% endhint %}
#### Full stops
Don’t use full stop at the end of label, headers, titles, snackbar and so on.
When there are more than 2 sentences, you can add a full stop.
#### Full stops in links
Don’t use a full stop at the end of a link, unless it’s included in a sentence.
In that case, make sure the full stop isn’t part of the link
{% hint style="success" %}
Want to know more about hyperlinks? [Learn more in the hyperlink section](/design/components/navigation/hyperlink)
{% endhint %}
Use a comma before a conjunction in an enumeration (Oxford comma). Separate the last noun in a list from the rest of the list using a comma.
{% hint style="success" %}
Additional settings are shown for font, color, and brightness in the figure below.
{% endhint %}
{% hint style="danger" %}
Additional settings are shown for font, color and brightness in the figure below.
{% endhint %}
### Hyphens
Hyphens slow down reading and comprehension as words with hyphens tend to be longer to scan.
Consider rephrasing the sentence to avoid ambiguity.
{% hint style="info" %}
*This cereal has no sugar* instead of *This cereal is sugar-free*
{% endhint %}
**Be consistent**. If you decide to use a hyphen, use it all the time.
Some words are never hyphenated:
* back office (not back-office)
* markup (not mark-up)
* onboarding (not on-boarding)
Some always are:
* drop-down
***
## Tenses
Prefer simple tenses such as present, past, and future.
Avoid perfect tenses (have + past participle) and continuous tenses (be + verb-ing).
### Past
{% hint style="success" %}
You **created** a new store.
{% endhint %}
### Present
{% hint style="success" %}
Please **enter** a registered email address.
{% endhint %}
### Future
{% hint style="success" %}
The information **will be** lost.
{% endhint %}
# Vocabulary
Learn key Mirakl terminology and how to use it.
# Mirakl products
Company name
Localization
Symbol
Comment
Mirakl
never translate, always use in English, even in non-English languages
™
to protect the company
la marque est la propriété de l'éditeur, interdiction de réutiliser ce nom
Mirakl Platform
never translate, always use in English, even in non-English languages
™
to protect the company concept
la marque est la propriété de l'éditeur, interdiction de réutiliser ce nom
Mirakl Marketplace Platform
never translate, always use in English, even in non-English languages
au titre du droit d'auteur sur les logiciels, le propriétaire conserve le droit de reproduction : interdiction de copier sans son accord
Mirakl Catalog Manager
never translate, always use in English, even in non-English languages
-
official abbreviation is MCM
Mirakl Marketplace Platform for Products
never translate, always use in English, even in non-English languages
-
official abbreviation is MMP
Mirakl Marketplace Platform for Services
never translate, always use in English, even in non-English languages
-
official abbreviation is MPS (but internally, you can hear about "MMS")
Mirakl Catalog Integrator
never translate, always use in English, even in non-English languages
-
official abbreviation is MCI MCI and MCM are exclusive from each other.
Mirakl Connect
never translate, always use in English, even in non-English languages
?
-
Mirakl Ads
never translate, always use in English, even in non-English languages
Mirakl Payout / Payout
never translate, always use in English, even in non-English languages
?
-
Mirakl Nexus
# Which verb to use
## Save vs OK vs Done
Use **Save** when a change is saved immediately. If the context is not clear enough or you feel the need to emphasize the action, use the **Save + \[noun]** structure.
Use **Done** when you need users to confirm a change or an update (usually in a modal) before saving all the changes at the end of a flow.
Use **OK** when you need users to confirm they've read a message, an announcement for example.
## Activate vs Enable
Use **activate** when the meaning is to put into action immediately.
{% hint style="success" %}
As an operator, you then decide to **activate** the feature for your sellers.
{% endhint %}
Use **enable** when the meaning is to give the ability to perform an action.
{% hint style="success" %}
Ask the Mirakl Support Team to **enable** this feature.
{% endhint %}
## Deactivate vs Disable
Use **deactivate** when the meaning is to stop an action or feature immediately.
{% hint style="success" %}
As an operator, you then decide to **deactivate** the feature for your sellers.
{% endhint %}
Use **disable** when the meaning is to remove the ability to perform an action.
{% hint style="success" %}
Ask the Mirakl Support Team to **disable** this feature.
{% endhint %}
## Create vs Add
Use **Create** when you want operators or sellers to design something new within Mirakl.
{% hint style="success" %}
* Create store
* Create channel
* Create order
* Create user
* Create product
* Create shipping method
{% endhint %}
Use **Add** when you add a characteristic to an existing Mirakl object.
{% hint style="success" %}
* Add a shipping fee (to a shipping method)
* Add price (to a product)
{% endhint %}
## Delete vs Remove
Use **Delete** if the item ceases to exist.
Use **Remove** if the item still exists after its removal.
## Compute vs Calculate
Compute and calculate are almost always interchangeable, as are the related forms “computation” and “calculation”.
We use a calculator to perform simple arithmetic operations, whereas a computer is typically used to perform complicated tasks, often involving complex algorithms. You may therefore use the words “calculate” and “calculation” to indicate simplicity and “compute” and “computation” to indicate complexity.
## Select vs Choose
Use **Select** if the user needs to make a choice within a dropdown menu or when the choice sounds very obvious, like selecting a country or a file.
Use **Choose** for more informal or subjective questions.
## Cancel vs Discard
Use **Discard** if the user is about to delete any data, for example, abandoning changes made to a form and staying on the page.
Use **Cancel** if the user wants to stop a specific action, for example, stopping the creation of a user and exiting the page.
## View vs See
Use **View** to make more information appear on the interface or to push users to another page on Mirakl.
{% hint style="success" %}
**View** order details
{% endhint %}
**Show** is a synonym, but we prefer to use **View**.
Use **See** when writing more generic sentences.
## Display vs Appear
Use **Display** when referring to something already visible on the back-office interface.
{% hint style="success" %}
The Orders page **displays** information.
{% endhint %}
Use **Appear** when referring to a pop-up or a message shown in a dedicated dialog box on the back-office interface (usually the consequence of an action).
{% hint style="success" %}
A confirmation message **appears**.
{% endhint %}
## Next vs Continue
**Continue** in the user interface, usually the Save bar, as we prefer verbs.
## Deprecate vs Depreciate
Only use deprecate, but as it sounds technical, you may also use expressions such as "no longer recommends using".
{% hint style="success" %}
Mirakl has deprecated the import feature.
{% endhint %}
