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
Always compare the design you have to implement with the components available in order to pick the correct one. If you can’t find the perfect component don’t try to hack one of the core components in order to fit your needs.
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
Check the structure of a core component helps you understand its options and how you can use it for your needs. Components are structured in similar way so once you have inspected few of them you are able to find what you need more easily.
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
The core components are default React components so once you import them from our package you can use them in your files and take advantage of the APIs in order to have them looking and behaving the way you want to.
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
Check the Where to begin chapter
Check the Introduction to tokens chapter
Check the UI composition chapter
Check the Building components tab