Introduction

In the previous chapter we learnt the basics of the Mews Design System and we now know where we can find all the resources we need in order to get familiar with the documentation, the components and any other useful resources. In this chapter we will focus mainly on how to use components in your products.

Things like how to import a component, how to work with a component’s API, how to style the components based on your design and how to combine multiple components together will be covered in this chapter.

Component pick

The first challenge you will face when it’s time to implement any design using the design system is how to pick the right component. We expect that in the majority of cases comparing the design you are working of with the various resources you have available, from the components section to the Storybook, is going to make it clear enough which component you should pick.

Nevertheless we have some components that might look similar while they serve completely different needs. If you find out in a situation like this where you are not fully sure with component to pick we suggest you to speak to your designer. This is very important and should be always the first step you take when you have any doubts. Your designer can tell which components they used for the design you working on and this eliminate any doubt you might have. If your designer has used a custom component please remind them that is something very strongly discourage and it’s better to get in touch with the design system team instead of bending design system rules or coming up with something completely custom.

It’s important that you don’t try to bend the limitation of a component in order to have it fit your design, in this case probably the component you picked is not the correct one or a core component for your needs doesn’t exist yet and therefore you might want to contribute and extend a core component or create a new component in your workspace. We will cover both scenarios in one of the next chapters. In most scenarios the core components of the Mews Design System should cover all of your needs though but if you want to know more about how to contribute you can check the contribution documentation.

Component structure

Before starting to import and consume a component we suggest after you have checked the documentation here and the Storybook to have a look at the code behind the component in order to understand the options the component has to offer. The core components of the Mews Design System tend to follow the same structure and this will help you in feeling familiar while inspecting any component once you have checked one of two.

The Button core component files in mews-js/optimus

As an example let’s focus on the Button component:

• Button.spec.tsx: few of our core components have also tests. If so they will be in a file like this one
• Button.story.tsx: if a component has a story that you can find in our Storybook this is where its code live
• Button.tsx: each component has a main file that is named like the folder
• ButtonLoader.tsx: if the component requires some extra elements we tend to put them in a separate file
• getButtonStyles.tsx: some components have intricate styling depending on the states of the various props. The related logic lives in this file
• index.ts: here we define the exports for the component
• style.ts: the styling for the component is all defined in this file
• type.ts: usually the types for the component can be found in the main file but if they are complicated or shared between files in the same component we keep theme in a separate file

Not all the components follow exactly this structure. It depends for example on how complex they are, if they are building blocks or layout components, if they are more of helper components and so on but this will give a general idea of a component structure.

Use a component

Once you have found the right component and done an initial inspection of the component itself it’s time to start to use the component and add it to your codebase and make it work based on the design you are following and your needs.

Import

The first thing you have to do is to import the component in your codebase. You are already working in the mews-js repository and that is a monorepo where the Mews Design System also lives, in the optimus package. So you can simply import it like below where you intend to use a component. In this specific case we are showing the import of the Button component as an example.

                                                                                                                                                        
                                                                                                                                                        
                                                                                                                                                            import { Button } from '@optimus-web/core';
                                                                                                                                                        
                                                                                                                                                            

In case you are working on a project where no other components from the design system have been imported yet then you’ll have to also add the package to your dependencies list in your package.json file.

                                                                                                                                                        
                                                                                                                                                        
                                                                                                                                                            {
                                                                                                                                                            ...,
                                                                                                                                                            "dependencies": {
                                                                                                                                                                ...,
                                                                                                                                                                "@optimus-web/core": "1.0.0",
                                                                                                                                                                ...
                                                                                                                                                            },
                                                                                                                                                            ...
                                                                                                                                                        }
                                                                                                                                                        
                                                                                                                                                            

Once you have imported the component you can start using treating it like a normal React Component.

API/props

Each component has a series of props that you can use to adjust the component to your needs in terms of the way the component looks and its functionalities. Let’s focus again on the Button component as an example.

                                                                                                                                                        
                                                                                                                                                        
                                                                                                                                                            import { Button } from '@optimus-web/core';
                                                                                                                                                        
                                                                                                                                                        export const MyComponent = (
                                                                                                                                                            <div>
                                                                                                                                                                <h1>Title</h1>
                                                                                                                                                                <Button size="medium">Click me</Button>
                                                                                                                                                            </div>
                                                                                                                                                        );
                                                                                                                                                        
                                                                                                                                                            

As you can see in the above example we import Button from the design system and then we use it in our MyComponent. We are also using one of the props of the Button, size in this case, and give it a value. Because we use TypeScript if you have your IDE, Visual Studio Code for example, that you use properly setup you should have autocomplete functionalities to help you use the correct Prop for the component. TypeScript helps you also understand if a Prop is required, so it always has to be passed and defined, and the type of each Prop so if for a Prop that’s expecting a boolean you pass instead a string as its value your IDE will have inform you of the mistake you just have made.

Combine components

In the example above the MyComponent is a very basic component. In most cases you will have to deal with complex logic and import other components you have already created. Furthermore, it is common to work with multiple core components within the same file, often combining and nesting them together. This involves importing multiple components and displaying them in your file in a specific way. For example you will have a card with an icon, a button and an header inside. So you will have to import four different components and our icon assets. Let’s take the MyComponent again as an example and make it a bit more complicated and close to real case scenario.

                                                                                                                                                        
                                                                                                                                                        
                                                                                                                                                            import { useState } from 'react';
                                                                                                                                                        import { Button, Drawer, IconName, Stack, Typography } from '@optimus-web/core';
                                                                                                                                                        
                                                                                                                                                        export const MyComponent = () => {
                                                                                                                                                            const [open, setOpen] = useState(false);
                                                                                                                                                        
                                                                                                                                                            return (
                                                                                                                                                                <Stack vertical>
                                                                                                                                                                    <Typography textStyle="titleLargeStrong">Menu</Typography>
                                                                                                                                                                    <Button size="medium" onClick={() => setOpen(true)} icon={IconName.Menu} variant="secondary">
                                                                                                                                                                        Click me
                                                                                                                                                                    </Button>
                                                                                                                                                                    <Drawer open={open} onClose={() => setOpen(false)} closeHandler="arrow">
                                                                                                                                                                        <Typography textStyle="bodyMediumStrong">Menu</Typography>
                                                                                                                                                                    </Drawer>
                                                                                                                                                                </Stack>
                                                                                                                                                            );
                                                                                                                                                        };
                                                                                                                                                        
                                                                                                                                                            

In the above code snippets as you can see we are combining various core components and making them work together. Usually a design you will receive is made with multiple components. As suggested before our Storybook is your best tool for playing with component and getting yourself familiar with them. This in the end will give you the ability to understand which components you have to pick and combine for achieving the desired output.

Outro

In this chapter we learnt the basic of using the core components of the Mews Design System. If you are familiar with React you should be able to get up to speed and take advantage of our components in no time. We do understand though that some components are more complicated than others offering many many options and variations and that in some cases it is visually possible to achieve the same outcome in various different ways. Also you might not always agree with our choices in terms of API and levels of flexibility we chose for a component and that’s understandable. That’s why it’s important to remember that for any question you might have we always available to help in the #rnd-designsystem-support channel and also that you have always have the option to suggest changes for our components and develop your own component that will live in your workspace in case you need a more bespoke solution.

Where next

Introduction

In the first chapter, Where to Begin, we introduced you to the design-tokens repository where we store our design tokens. The repository acts as a single source of truth for out tokens and connect the tokens used in Figma by the designers to the tokens used in the core components of the Mews Design System. In this chapter we will go more in depth about our design tokens explaining how we keep the single source of truth and how other developers can use the tokens when building part of a product or a new component.

Why we use tokens

When we build and style any of our core components we use various styling values like font size, background colour and border radius that are decided and defined by our designers. Those values have been carefully picked and are part of a system and follow multiple criteria. We could just inspect a piece of design and copy and paste the value we can see in Figma in the styling file for the component we are working on.

The problem with this approach is that now the same value lives in two different places, in design and code, with no connection meaning if the designers change a value in a design file that will not reflect and there is has to be communicated to developers and a developer has to find where the value is used in the codebase and update it.

As you can see this is not scalable, it is very prone to human error and lacks the usefulness of relying on a single source of truth system.

How we use tokens

It should be now clear what are the advantages of using tokens. Let’s go a bit more in depth and explore how we use tokens when developing our core component and how they help us staying more aligned with designers.

As said above a token can be any sort of styling values but our tokens are not the core value let’s say 8px for example but instead we have for example spacing.100 and this helps us extracting the value from the name so if in the future we end up changing our spacing scale we just have to change the value behind the name of the tokens because the name will still be valid. The same goes for a colour token, we don’t have red but instead danger as the name of the token.

The token names are created and managed by designers in Figma using a tool called Token Studio that is then connected to the design-tokens repository and published as a npm package. Contrary to the core components of the Mews Design System the tokens are accessible outside the monorepo and are available in multiple formats for different usage.

The tokens for the light theme coming from Figma

How we build tokens

As mentioned above tokens go from Figma to a npm package, but how? Because the most important aspect of tokens or any tool that is supposed to help designs and developers collaborate is to be always synchronised we developed a system that allows us to consider the design-tokens repository as our single source of truth. That means that the most up to date tokens live there and in case of conflicts with other tools the tokens in the repository should be considered the correct ones. Let’s quickly go trough the system we have in place. We store the tokens coming from Token Studio in JSON format divided by theme.

For each theme we then create the output tokens in a variety of formats for different usage. This is useful because as we said above the repository is detached from the monorepo and the tokens are used not just in mews-js for also for the mobile design system for example and potentially can be consumed by other internal projects using CSS or JSON. The conversion and creation of tokens is done just running the build script that underneath relies on Style Dictionary and token-transformer.

The tokens transformed and built in TypeScript for the light theme

Any time new tokens are pushed from Token Studio a PR opens and use developers in the Design System team we check if everything looks as expected. In case we reject the changes or we make changes straight in code the designers will see in Token Studio an income changes and therefore they can pull the changes. In this way we can keep the designers and developers in sync while using different tools.

Once all the tokens are created we prepare a new version of the package picking the version number based on Semantic Versioning and we then push and publish the new package. Most of these tasks are automated thanks to multiple GitHub Actions. We try to make the process as straightforward as possible because the repository cannot be a bottleneck for the designers wanting to add and update tokens. Of course once a new version is published you’ll have to update the version number where you are consuming the package.

The various GitHub Actions we use for publishing the design-tokens package

How you can use tokens

We have explained why we use tokens and how we build tokens, let’s focus now on tokens can be used in code for styling whatever you are building or working on in general. Unless you are building a new component from scratch, something that we are going to focus on in another chapter, you probably won’t use tokens much, unless you need to add some custom styling to your product, and even less you will contribute in terms of adding more tokens to the package.

Utils

The design-tokens package is imported and used in the Mews Design System in the monorepo. We built multiple utilities that help using the tokens and are exposed so they can be used also in other packages in the monorepo.

Let’s check the main ones quickly and see when and where you could take advantage of the utils:

• getToken: this getter should be used anytime you want to use a token. Pass the token inside a string and you are done. If your IDE is setup correctly you should also get autocomplete so you can avoid trying to guess the name of the tokens. Just remember that number tokens usually are missing the unit that has to be added after.
• getSpacingToken: this a subset of the more generic getToken and should be used specifically for spacing tokens that generally are related to margin, padding and so on. You can just pass the value of the spacing as string. As above don’t forget to add the unit at the end.
• getTextTokenPreset: this getter covers everything related to typography. Pass the string of the text preset you need and it will style font size, family and weight plus line height and letter spacing. Try to avoid to style anything related to text manually but instead always relies on the these presets.

The various utilities that allow you to use tokens in your project

Contribute

In general we expect tokens used almost never directly and only sometimes in your project mainly leveraging the utils we just described above. If for whatever reason you find yourself in a specific situation where you are building your own components and none of the tokens available cover your specific case you should talk to your designer first and try to find out why an already existing tokens was not used. If your designer has already discussed this with the Design System team then the team itself will be responsible for adding the new token and publish the new version of the package. If this doesn’t work as expected and you don’t see the token you were expecting while using the latest version of the design-tokens package feel free to send a message to our Slack support channel.

Design

While inspecting a design you should be able to see the name of the token used and that will be very useful when you are then moving into the code and try to understand which token you should use. As said above if your designer has used a custom value instead of a token try to speak with them and understand why this is happening. Specially if you are just using a component you should almost never overwrite the value or replace the tokens used with others. The only difference present between tokens in Figma and in GitHub is that designers use dot case format while in code we rely on Pascal Case.

Outro

In this chapter we introduced you to the concept of design tokens explaining why they are extremely useful and how we have structure our pipeline in order to connect design and code and have the tokens always in sync. We expect you to use tokens through components instead of a direct usage but we understand that sometimes custom styling is needed and that’s why we told you a bit more about the various utilities you can use. Also if are building a new component you are going to use tokens a lot and you should avoid at all cost using value not connected to tokens. In case you need new tokens we are here to support you, tokens have been picked and structure in a very meticulous way so new tokens have to be added follow a specific criteria.

Where next

Introduction

In the Introduction to Components chapter we dedicated a section to how to combine components. There we explained how in most cases when working on your product you are going to end up combining multiple components together in order to achieve the desired outcome based on the design you have.

In the specific code example in that section we introduced one of the layout components, Stack, that you have available and can help work on UI composition and complex sections and even pages that can even adapt to different screen sizes.

Challenges

Even if you are familiar with the various components of the Mews Design System and you know how to adapt them to the design given you might still find issues when you dealing with a page block or even an entire page. This is understandable considering the challenges that creating a layout presents. Components in isolation are in general straightforward but when we are dealing with UI composition there are extra things to take into consideration. Starting from how to deal with spacing between various elements to how to adapt the layout based on different viewports.

You could deal yourself with aligning various components on a page but this first requires a lot of extra work, custom styling and unnecessary markup, but also leads to inconsistency between pages and layout because we can’t expect different engineering to all think, build and deal with composition in the same way.

That’s why the rest of the chapter will be dedicated to walk you through the various layout components the design system has, explaining how to use them and also very important when to use them. Those components are intended to help you solving the various challenges described above that you have to deal with when doing UI composition.

Resources

In order to achieve various type of layouts we have available three different components that can be used mainly as wrapper for other components for UI composition. These components are fairly powerful and come with a lot of options and settings so it might require a bit of time in order to achieve something as close as possible to the new design you are working of.

Before we go into more details for each components you should probably start checking the section on Layout in our documentation and the layout stories in our Storybook. The are few components in that section, some of which are components that combines multiple other components together while other are specific helpers for UI composition and those are the same ones that you can find documented as mentioned above. We are going to focus here mainly on those 3 components covered in the Layout documentation.

Container

Let’s start focusing on the Container component. As mentioned in the documentation you should use Container as a wrapper for other single or multiple components for spacing, positioning and so on instead of creating a custom component or try to adjust the styling of an already existing component in order to have it align in a specific way or have some custom dimensions.

Consider Container as a div that can take various CSS properties, like position, display, width, height, padding and so on. It can easily be combined with other containers as parent, sibling or child and also offers responsive behaviour but we are going to focus on the Responsive Style API in a bit.

The related story exposes all the different props so please play with the controls to see the changes in the story.

Stack

If you find yourself in a situation where you have to align various components, let’s say a bunch of card or even a bunch of containers, and you are struggling to have the right spacing and alignment between them then you might want to have all of them wrapped in a Stack component.

As the name suggested, with Stack, you can decide how various components will stack on top or next of each others. The component is very powerful and the API quite extensive so you will probably be a bit confused when starting to use Stack and might even think that something is not achievable. As usual we suggest to play a bit with the story so you can gather some knowledge and feel a bit confident in combining different props in order to achieve a layout close enough to the design you got provided.

An example of a complex card you create using the Stack component

Something to mention for this component, that you check in its documentation, is that it is composed by both the Stack element but also the StackItem element. So you can have each item in the stack to behave differently from the others and achieve very complex UI composition. Similar to Container also Stack can take advantage of the Responsive Style API and behave differently based on the device viewport. We suggest to have a read of the Overview page to see how you can compose an entire UI block step by step.

Grid

The last layout component we offer is Grid. If you are a bit familiar with the CSS grid layout you probably already understand how this component can help you when dealing with UI composition. As much as Container is just div you can use for position and spacing what you have with Grid is a wrapper that allows you to align any type of other elements in a grid system.

Also similar to Stack you can apply props to both the parent and children wrapping them inside a GridItem element. The API of CSS grid layout is fairly intricate and the same can be said for our component, as usual check the documentation to start navigating the various props offered. Even if this can be seens as a limitation at the beginning you will find out quickly while starting using Grid that possibilities are endless and allow to achieve quite complex UI composition.

Grid combined with Responsive Styles gives a fully adaptable layout

As said for the all the other components have the story alongside ready for some quick prototyping. Something to keep in mind that is specifically true for Grid but can be applied also to Container and Stack is that you can probably produce the same UI using one or the other component and different props. So we leave to you the decision to make on which of those layout components are the best to use for your specific usage.

Responsive Styles

We already mentioned in this chapter the Responsive Style API. This API is specifically been made to work with the above 3 layout components in order to make them even more flexible and powerful for any needs related to responsive design. The API is structured like an object and inside it you can pass all the properties of the component you are using with.

So you can have a default spacing for the Stack component but then have different spacing for any of different breakpoints we offer as part of the API. That means that for example you could have a 3 columns grid that becomes a 2 columns grid for tablet screen sizes and down to a more simple 1 column layout for phone screen sizes.

We offer various breakpoints that can use with the Responsive Styles API

Having this extra API as part of the layout components avoids the need to create extra components to handle different viewports or to create custom logic in order to deal with various devices. When using Responsive Styles try always to cover all the possible scenarios and speak first to your designers in order to understand what’s expected in terms of UI composition for various users and devices.

Best practices

UI composition is quite tricky at first and might feel even more so when you have the limitation of trying to avoid custom components and custom styling but instead use the components that the Mews Design System provides you with. The tools at your disposal are meant to speed up your work, make you productive and help you solving the problems that really matter but composing a complicated UI has a steep learning curve so you might feel at the beginning that these layout components are slowing you down.

As already mentioned we highly recommend to have the Storybook open and ready for you to prototype with. Once you have managed to combine the various props that make you achieve the desired outcome then try to see if you can simplify your solution while making it more robust. As much as this is about creating a UI that reflects the design you are working with it should also be about code maintainability and readability.

If your solution is quite convoluted and not flexible at all you might want to spend a bit more time on it, maybe try to break down the page in more individual blocks so you can make each of them more flexible. We also suggest you to have an open conversation with your designer when dealing with UI composition. It’s part of our job as engineer to collaborate with designers and suggest better alternative and guide them to what’s possible to achieve in terms of a product appearance and functionality. This is even more true when we have to think about responsive design and how the layout of a page should change based on the width of the screen.

Outro

In this chapter we introduced you to the 3 layout components: Container, Stack and Grid. Each of them serves a specific scope and can all be combined together to achieve any type of UI compositions. Those components are complex and offers multiple options so take your time and try different solutions. There should never be a need to create any custom components or wrap a bunch of component in a custom div with some custom styling. Don’t forget to consider responsive design and test the layout with various type of content also. Our products supports various languages plus even if some products don’t have a mobile version for example that doesn’t mean that some users don’t use them on very narrow screens. So always try to achieve a flexible layout that is easy to maintain and can be expanded if and when needed.

Where next

Introduction

In the previous chapter we introduced you to the contribution process, explaining how, when and where you should contribute. In this last chapter we are going to discuss what you should take into consideration when you decide to build a new component. We are going to suggest you best practises and guide you in order to achieve the same qualify of the already existing core component of the Mews Design System. Don’t forget that we always available not just for code review and also for more generic support and guidance.

Plan accordingly

Building a new component from scratch it’s not easy task and it does require attention to details and proper planning. First of all don’t just start building something as a solo effort but always have the involvement from your designer and follow the official process for contributing so create the documentation required and follow the steps illustrated in the contribution documentation.

When it’s finally time for you start coding the new component think about how the component is expected to be used and where. A collaboration with your designer is fundamental, because even if they considered everything, you have noticed in the codebase something new that requires something else to be taken into consideration when developing the component or even a similar piece of UI that already exists.

Also remember that a component should be agnostic and have the flexibility needed to be used by others, so plan the API accordingly and don’t build something too rigid. If what you are trying is going to be used just in your products then it should live in the B2B or GX workspace, but if you know already that are multiple teams needs it then it should live in the Core library. If this is the case involve other teams in order to build something useful for all the teams that need it.

Always keep out business logic from the component you are building. Even if the component is going to live in one specific workspace it should just be a pure UI component and don’t have any data in it. We highly recommend to have the component with the other components in the UI package in the mews-js repository. This helps discoverability, so other teams can see and use your component instead of writing something very similar, while keeping business logic far and detached.

A new component should live in UI package

Keep it simple

When building a component is easy to think too much about the possible use cases and wanting to cover future and unknown scenarios. This is a good intention for sure but can bring to very complicated components that are difficult to work with and maintain. You should consider what you are building as an initial version of the component, something that can always be improved once the usage is more clear or other engineers start using the component.

Keeping it simple means also don’t be too clever when writing the code and abstract too much. You might be very familiar with the component because you are creating it but then other engineers will have to use it and they might find the API too complex for example or finding that the component has been built in a very different ways compared to all the other components. We want to make the work easier for other engineers when they use our components so this should be taken into consideration.

Following the above point of simplicity and good DX you should avoid using third party libraries almost always. A library is usually not required when dealing with UI and it’s something that should be left as part of the component usage in the product. This helps massively with maintainability, because no dependencies apart from the standard ones make a component more robust and future proof.

We don’t want to try to reinvent the wheel when you start to writing code for your new component therefore please take inspiration from the other components that already exist in the Mews Design System. The component you are building should be structured in the same way anyway so keep styles and types in separate files, use named exports, write simple React and all this will help you shipping a components that you and other engineers find very easy to understand and use.

Keep the structure of your component similar to the one of already existing components

Consider everything

Even if you are trying to keep it simple when developing your new components there are still a lot of things to consider. Take your time thinking deeply about the API, double checking with your designer if everything got covered and going through the review part is a process that can easily take many days. As always we can support you not just during the review phase but even during the development process if you any questions to ask or you are stuck on something. Reach us in our support channel and we will do our best to help you.

The main thing to consider during the deployment of the component is how to present the component itself and make it discoverable and usable to and for others. Therefore you should spend a bit of time building an extensive story for the component. You can have a look at the codebase for other stories and how they render in any of the Storybook workspaces. Everything that is customizable in the component should have a control well specified where it very clear what kind of options are available. If the component has multiple variations you might even want create 2 stories, a playground one and an overview one without any control.

A story well written with plenty of controls is required for any new component

The nature of a design system component is to be flexible and usable in different scenarios. You should keep this in mind during the developing phase and it’s something you should test against. Is the component responsive and adapts to various viewports and types of content? Is the component accessible and users can use it without a mouse or via a screen reader? Are you using the correct tokens and not adding any custom colors or spacing value? Please check everything before submitting your work for review to avoid request for changes.

Going back to the discoverability you should not forget about documentation. If the component doesn’t live in the core workspace you are responsible for adding the technical documentation for you component. If you build something that other engineers find difficult to use because they don’t understand how or the example and API are not well explained then the component is like if it doesn’t exist. These last bits can seem tedious and feel almost pointless but are very important for sharing the great work you have done. Once everything is ready don’t forget to inform us and others of the availability of the new component so we can help you to spread the word.

Outro

In this last chapter we described the process of building a new component from the start to the end. There is a lot to take in but this is necessary for creating a component that is useful and usable not just by your team but also by others and follows the necessary requirements and has the same quality of the core components of the Mews Design system. When possible try to avoid creating a complex component or a component that does too many things. Keep it simple, take your time and follow the various steps and the information you can find available. If you have arrived at this point after reading all the other chapters you should have everything covered, and if you only reading this specific chapter maybe spend a bit more times on the others and as always get in touch with us for any help you might need.

Where next