UX/UI guidelines

Table of Contents

General page template

Data grid

Dialog

💡 Use the Dialog component instead of a modal. The modal is the low-level element meant to block the interaction. The Dialog is based on a modal, but specializes in providing information and further actions.

A Dialog is composed of three main parts:

  • Title. Contain a brief, clear statement or question. It should communicate the Dialog’s purpose.

    Background color is secondary.

  • Content. Anything needed for the context, from supporting text to full-size form.

    With long content, use the scroll=paper.

  • Actions. There’s always a way to go back (Cancel). And the main action is on the right. The label should reflect the action performed when clicked.

    If any required field is in the content, the action button is disabled until they are completed.

    Cancel. Text button, primary color.

    Action. Contained button, primary color.

Example text field with guidance above

Responsiveness is configured as follow:

> 🚧 TBD (full-width + variable maxWidth depending on breakpoints?).

Icons

Material Icons should be in the Outlined style by default.

Required fields

When information is required to proceed:

  • Required field(s) should show an asterisk * after the label.

  • Above required field(s), explain what the asterisk does. This message is displayed once, after any title and before required field(s).

    Add * Required fields., with the typography style subtitle2.

  • The action button below the field(s) is enabled only when all required fields are completed.

Example text field with guidance above

Theme

Main colors

  • You can find matching primary and secondary colors using a palette generator like Coolors. If you already have a primary color in mind, you can also generate a matching secondary color with a Color Wheel.

Generate MUI color variants for theme.json

  • Use the MUI Theme Creator. On the bottom-right you can edit a main color to automatically generate its light and dark variants, with the needed corresponding contrastText color.

    Note those are different from a light/dark app theme. They are a lighter and darker shade of the main color. You can use them to play with contrast in the interface.

Check contrast

  • It’s a good practice to check contrast. Online palette and color tools tend to rely on varying contrast standards. Better to double check and choose which contrast standard you want to aim for.

  • MUI uses colors in different contexts. To prevent any issue, try your colors’ contrasts accordingly. Check primary and secondary as background for their corresponding contrastText. Check also primary and secondary as text on a white and black background, to make sure it works on a light or dark theme.

    Note that you don’t necessarily need your colors to have a good contrast in light and dark mode out-of-the-box. When switching mode, colors can be further adjusted to better work in the other mode.

  • It’s good to have some contrast between primary and secondary. You don’t need a standard-level contrast. But a secondary component on a primary background can be a thing (like a badge with number of notifications). If primary and secondary are too close, the interface will become less clear.

Generate appbar-chip-inactive colors

  • If your primary color is darker than your secondary. Use secondary dark as appbar-chip-inactive main and Generate MUI color variants from it.
  • If your primary color is lighter than your secondary. Use secondary light as appbar-chip-inactive main and Generate MUI color variants from it.

Tooltip