Design System Onboarding

Elevating your experience with Mews Design System


In this section we will focus on giving you the resources needed to start to get yourself familiar with the Mews Design System, from where to find the documentation to how to check the code behind each component. At the end of this chapter you will be able to navigate through our documentation, Storybook and code in order to find what you need.

Official documentation is the main central point, single source of truth, where all the information can be found. The Components section is where you can find the documentation for various components. All of our components are documented here and in the React tab you will able to check the code, paired with an interactive preview coming from our Storybook, and the API for each component.

The Button component React documentation

The Button component React documentation

We are in process of standardize the React documentation section so each component is structured in the same way:

  • Status: find out if the documentation is up to date or not
  • Resources: Storybook and GitHub links
  • Example: live, interactive example with below code snippet of a simple usage
  • API: list of all the APIs for the component with a brief description, the type of prop and it’s default value if present

We try to keep the documentation always up to date and to document any of the core components. If you think that something doesn’t look right or it’s missing please check the Need help? page for getting in touch with us.


While the documentation of the components is the best place where to start you might prefer a tool more tailored for developers or you are more interested in testing various settings for each component. If that is the case you can also check our Storybook.

The welcome page of the Mews Design System Storybook

The welcome page of the Mews Design System Storybook

Each story usually has a Playground that allows you to play with the Controls of the story in order to check all the different options available. The Controls tab can be found in the sidebar. There all the various props for the component can be changed in order to test the different options both in terms of behaviour and visual appearance the component offers.
Some stories will have an Overview option where you check multiple options at the same time
You have also the ability to check how different component looks based on the theme. You can switch between the four themes we have at the moment:

  • B2B
  • B2B Dark
  • GX
  • GX Dark

You can find the theme switcher in the toolbar at the top.
You will learn more about how theming works in one of the chapters.
The Storybook is always up to date, meaning the URL, always shows the most recent build so can you can use it as a reference for the most recent state of a component and check they way it looks and behave.

Code repositories

If you want to get more in depth in terms of checking the components and the design system in general you can have a look the optimus package in the mews-js repository. The name optimus was the previous name of the design system and it’s still present here and there in some places at Mews. The mews-js repository is a structured as a monorepo and the design system is one of its packages. Here you will able to find the code of all the components, utilities, helpers, theming, Storybook and so on. Spend some time inspecting the various folders and files so you can get familiar with how we structure our components and use it as a guidance when and if you have to build your own component. We will talk more about how we structure the folders and files inside the package in the next chapters on how to use a component and how to build a new component.

Monorepo package structure

optimus package folders structure in mews-js repository

optimus package folders structure in mews-js repository

This is a small breakdown of the different folder part of the optimus package:

  • assets: all the assets that are part of the design systems; icons and pictograms
  • breakpoints: our components tend to be responsive but we also offer utilities related to breakpoint ranges and have different settings or components based on breakpoints
  • common: generic functions like getters and so on that are used in multiple places by different components
  • core: where all the components live. Check below for an overview of how each component is structured
  • draft: in the past we used to keep components in different folders based on their status. We then abandoned this structure but some components haven’t been moved yet
  • fonts: the fonts used in the design system
  • helpers: various helpers that are usually used as part of a component. You can see the stories for some of these in our Storybook
  • icons: related to the icons you can find in the assets folder here we just deal with the name of those icons
  • legacy: similar to the draft folder here we used to have legacy components. There are none left anymore apart for some old imports. Here we also keep anything related to the legacy theming optimus used to be based on. As said before you will learn more about theming in a successive chapter
  • localization: by default localisation and content for a component in handled in the products and not in the design system but some elements that are part of a component, i.e. table controls, have translation at a component level.
  • masks: various date and time pickers components have a mask that help the user to understand the expected formatting. This is handled by the files in this folders. Validation and data formatting should be handled at products level.
  • staging: similar to draft and legacy folders this is some tech debt left from the structure of the previous version of the design system
  • storybook: everything to do with our Storybook
  • theme: in this theme folder we define the theming wrapper, Optimus Provider, that is used in the products for applying a specific theme

design-tokens repository

The design-tokens repository in GitHub

The design-tokens repository in GitHub

As you have probably noticed inspecting any of our core components we use design tokens for applying styling to components. Such tokens are imported and consumed from the design-tokens repository.
In this repository we import the tokens that designers create and maintain in Figma, using Token Studio, and we transform them in various formats and then publish them as an NPM package. Contrary to the design system itself that being part of a monorepo can only be used inside its own repository, the design-tokens package can be imported in any other Mews repository if needed. The repository has an extensive and up to date README so if you want to understand a bit more abut its structure and functionality please dive deep. We are also going to talk more about tokens in general and how we convert and consume them in one the next chapters.