Design tokens, CSS classes, mixins and CSS parts - when to use each

A guide to MDS styling tools: enhance styling flexibility, reusability, and consistency in your application.

24 October 2024

The Maersk Design System offers a wide range of options when it comes to styling your application.

In your code, you can use our Foundations CSS classes, design tokens (CSS properties) and Sass mixins and CSS parts.

Each of these options has its own use-case and benefits. In this article, I will explain when to use each of them and how to use them in your code.

Styling your application

The recommended rules are:

Use our Foundations CSS classes for basic styling of your application, for adding proper font style, or background color, border color, etc. to some elements in your application (see the full list of available CSS classes).
Use CSS properties and design tokens for adding specific theme colors, spacing, border radiuses, etc. inside your applications stylesheet (see the full list of available design tokens and CSS properties).
Use Sass mixins to apply breakpoints or typography in your code (see the full list of available Sass mixins).

Why should I use the MDS styling tools?

Using the MDS styling tools in your application:

Ensures consistency - the tools MDS provides enforce an uniform design language across all platforms and applications.
Follows MDS guidelines - your product will be consistent with the Maersk brand.
Makes your code more maintainable and scalable.
Makes your application more accessible and responsive.
Takes advantage of the MDS theming system.

Foundations CSS classes

Adding an import to Foundations CSS in your application is the easiest way to use MDS styles in your code.

All you need to do is choose an MDS theme, include Foundations CSS in your code and add mds class to the root element of HTML. By doing that, you will get default styling for main elements in your application, like headings, paragraphs, lists, etc.

\n\n"}]">

mds-content

Foundations CSS also includes an mds-content class. Adding this to a content container e.g. an <article /> element will ensure that you get default spacing (paddings and margins) headings, paragraphs, lists, etc.

Typography and colours

Apart from default styles for HTML elements and CSS resets, Foundations CSS provides you with extra CSS classes that you can add to any element in your application. Those CSS classes include:

typography classes for styling headings and text
text colors
background colors and font color that should be used on them for accessibility reasons
border colors

The full list of all available CSS classes that you can take advantage of in your code can be found in our Storybook.

CSS properties and design tokens

Design tokens represent the core elements of our design system. They are named variables which are used to store visual design values such as colours, typography, spacing etc. and act as a bridge between design and code, ensuring consistency across platforms and devices

Design tokens are the foundation of all MDS components, and should be used to style your application, especially if you want to take advantage of theming in your application and allow users are able to switch between light and dark theme.

MDS distributes design tokens as a NPM package, which you can install using npm or yarn, or you can use them by simply adding link in your HTML to the CSS stylesheet from our CDN.

Design tokens are distributed as CSS properties, and you can see our guide on how to use design tokens and CSS properties in your application.

You can use any design token offered by MDS in your code. For example, you can use the color tokens to add specific background color to i.e. banner, or border radius token to make sure your boxes have the right border radius.

Here you can find the full list of available design tokens on the Themes & tokens page.

Sass mixins

Sass mixins are a great way to add responsive design or to apply different font styles to your application. They can also be an alternative to the MDS CSS classes and as Foundations CSS includes some CSS resets, it might be that you don’t want to use it directly in your application.

MDS distributes all available sass mixins as part of @maersk-global/mds-foundations NPM package.

You can simply import them in your sass file and include desired mixin, whenever you need it.

Here you can find the full list of available sass mixins.

Styling MDS components with CSS parts

All MDS components are built with web components, meaning their functionality and styles are encapsulated and isolated from the rest of your code. This offers several benefits, making MDS components consistent, reliable, and safe to integrate into your application without concerns about style conflicts. However, this also means you cannot directly modify or override their styles as you would with components from JavaScript frameworks.

For some DOM elements within MDS components we expose CSS parts, which you can target in your code.

Excessive custom styling may cause components to diverge from the Maersk brand!

Use CSS parts and overrides very sparingly, otherwise you will not be able to maintain alignment with the brand guidelines.

If you absolutely need to override some properties of the MDS component, make sure to use our design tokens in order to assign a new value. By doing so, you make sure that you are still aligned with the Maersk brand and that your product is consistent with the rest of the Maersk applications. In addition, this will allow you to take advantage of theming in your code and allow users to switch between light and dark theme.