---

This is the latest version. The legacy version (v1) can be found on the branch v1.

---

Moata React UI Kit

Storybook Documentations

Figma Moata Design System

Moata React UI Kit is a MUI theme for Mott MacDonald Moata projects.

This UI Kit is for Mott MacDonald authorized projects only. Please refer to the LICENSE section if you intend to download the published source code.

Installation

$3

Add this package and its peer dependencies to your project:

``sh
pnpm add @mott-macdonald/smi-react-ui-kit @emotion/react @emotion/styled @mui/lab @mui/material
`

#### with CSS Variables (the recommended approach)

The CSS variables theme gives us a way to reference the theme variables in our own CSS/SCSS files.

All CSS variables are prefixed with --moata- to avoid conflicts with other CSS variables.

In MUI components, you can use the theme.vars.palette.* to reference the CSS variables version of the theme values. (Notice the .vars in the properties path)

Check out the Material-UI CSS theme variables documentation for more information.

`tsx
import { StyledEngineProvider, ThemeProvider, CssBaseline } from '@mui/material';
// this would patch the typing of the theme under MUI components' sx,
// so that we can reference the CSS variables version of the theme values from theme.vars.*.
import type {} from '@mui/material/themeCssVarsAugmentation';

import { cssVarsTheme as theme } from '@mott-macdonald/smi-react-ui-kit';

import '@mott-macdonald/smi-react-ui-kit/fonts.css';

function App() {
return (



...


);
}

export default App;
`

#### without CSS Variables (the legacy approach)

`tsx
import { StyledEngineProvider, ThemeProvider, CssBaseline } from '@mui/material';

import { themes } from '@mott-macdonald/smi-react-ui-kit';

import '@mott-macdonald/smi-react-ui-kit/fonts.css';

function App() {
return (



...


);
}

export default App;
`

From this point on, use any component from the Material-UI library and follow the usage guidelines and examples provided from that project.

$3

This library can be installed alongside the previous version. To achieve this:

1. First edit the package.json as follows:

`diff
- "@mott-macdonald/smi-react-ui-kit": "{VERSION}",
+ "@mott-macdonald/legacy-smi-react-ui-kit": "npm:@mott-macdonald/smi-react-ui-kit@legacy",
`

2. Update all import from "@mott-macdonald/smi-react-ui-kit" to use "@mott-macdonald/legacy-smi-react-ui-kit"

3. Rename the ThemeProvider component imported from the legacy version to LegacyThemeProvider

4. Install the latest version using the process above, including adding the ThemeProvider component.

5. Add a new file in the root of the document called muiClassNameSetup.ts. And add a custom ClassNameGenerator so that the Mui class names don't clash. As described here.

`tsx
import { unstable_ClassNameGenerator as ClassNameGenerator } from '@mui/material/className';
ClassNameGenerator.configure((componentName) => moata-${componentName});
`

Import this at the top of your main.tsx file (the entry point of your app).

Your main.tsx file should now look something like this:

`tsx
import './muiClassNameSetup';

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App.tsx';

createRoot(document.getElementById('root')!).render(



);
`

Your App.tsx file should now look something like this:

`tsx
// Legacy version
import {
ThemeProvider as LegacyThemeProvider,
GlobalStyles as LegacyGlobalStyles,
} from '@mott-macdonald/legacy-smi-react-ui-kit';

// Latest version
import { StyledEngineProvider, ThemeProvider, CssBaseline } from '@mui/material';
import type {} from '@mui/material/themeCssVarsAugmentation';
import { cssVarsTheme as theme } from '@mott-macdonald/smi-react-ui-kit';
import '@mott-macdonald/smi-react-ui-kit/fonts.css';

function App() {
return (





...



);
}

export default App;
`

Both version of the UI-Kit can now be used in the same project. The components used from UI-Kit v1 can then be migrated to use the latest UI-Kit one by one.

Usage

In the most part, once the theme is added to the project, you should follow the guidelines and examples provided in the Material-UI documentation, and by the wider community.

Additionally, the Storybook in this project is a good place to look for some useful examples of common UI components found in Moata projects. Examples include how to build a "Detail menu", "Detail panel", and "Collapsible side panel", etc.

$3

The active theme can be accessed by using the useTheme() hook available from @mui/material.

But, most of the time, you would use MUI components' sx prop to reference the theme values.

`tsx
({ ... })}>...
`

$3

#### Importing

The icons are packaged separately and can be imported using:

`tsx
import { Alert as AlertIcon } from '@mott-macdonald/smi-react-ui-kit/icons';
`

View all of the available icons in the storybook here

If there are icons missing that you need, please email:

- daisy@mettle-studio.com
- alex@mettle-studio.com

They can arrange for the new icon to be created, exported, and added to this project.

#### Styling

The icons are MUI SvgIcon components.

By default, the icons inherit the color and font-size of the parent element. When we want to adjust the color and size of icons, we should adjust them by changing the color and font-size CSS properties.

##### with sx prop:

`tsx
import { Alert as AlertIcon } from '@mott-macdonald/smi-react-ui-kit/icons';
import styles from './example-button.module.scss';

export const ExampleButton = () => (



);
`

##### with SCSS Modules:

`tsx
import { Alert as AlertIcon } from '@mott-macdonald/smi-react-ui-kit/icons';
import styles from './example-button.module.scss';

export const ExampleButton = () => (



);
`

`scss
// example-button.module.scss
.icon {
color: #333;
font-size: 1.5rem;
}
`

$3

We would recommend that new projects use the recommended approach to styling components for Material-UI, which is to use the sx prop and the styled function provided by material-ui. See the help here.

The aim should be to never use the basic html elements. e.g. You should never use a div element. We should always use the Box provided by the Material-UI library, or the other layout elements provided by the library.

See the storybook for good examples of this.

However, a number of styling approaches are supported, as documented in the Material-UI documentation here

$3

The new Design System has dropped scenarios of nesting the theme to enable the possibility of switching the theme dynamically in the future.

DO NOT use the examples below in new projects.

---

As described here, it is possible to nest the theme. This is very useful as many Moata app have sections with dark backgrounds, where the dark theme should be used.

#### with CSS Variables

The data-mui-color-scheme attribute is a constant that we defined in the theme. It is used to switch the theme dynamically.

Adding data-mui-color-scheme="dark" to the parent element, the dark theme will be applied to all children.

`tsx






`

Check out Force a specific color scheme

#### without CSS Variables

`tsx






`

Check out Nesting the theme

Development

$3

- Node.js LTS v22 or above - LTS versions are preferred Download Node
- Recommend using fnm or nvm to manage Node.js versions. Checkout fnm, nvm for macOS, nvm-windows for Windows
- pnpm ^10.0.0 Install pnpm
- Github Package Token
1. Login to Github and Navigate to https://github.com/settings/tokens
2. Select "Personal access tokens", and then click on "Generate new token"
3. Pick a name for your new token, in the scopes section, select only read:packages
4. Click "Generate token" near the bottom of the page, and make sure to copy and save the token to a secure place
5. Make sure that the environment variable NPM_AUTH_TOKEN is made available in your system. For example, if you are using bash, make sure the variable is set to the token acquired in step 4. For windows, see How to Set Env Variables in Windows 10

If you run into NPM errors related to credentials when running pnpm install, please check:

- Check with your lead if you have necessary access rights including access to internal NPM packages used in this repository.
- The environment variable NPM_AUTH_TOKEN is made available in your system.
- The repository is cloned with SSH instead of HTTPS.

$3

Clone the repository and develop components with storybook.

Note: It's important to clone the repository with SSH, HTTPS won't work in the dependency installation step.

`sh


Clone the repository

git clone git@github.com:mottmac-moata/moata-react-ui-kit.git

Install dependencies

pnpm install

Start Storybook dev server (and watch changes)

pnpm storybook

Go to http://localhost:6006

`

$3

By default, without pre-generating a trusted certificate, the Storybook dev server will start over HTTP.

Recommand using mkcert to generate a locally trusted certificate.

1. Install the mkcert.
2. Run the following commands to generate a trusted certificate in the root repo directory.

`sh


Created a new local CA

mkcert -install

Create certificate folder

mkdir .https

Created a new certificate

mkcert -key-file .https/key.pem -cert-file .https/cert.pem localhost
`

$3

To build a new version, bundle this kit:

`sh
pnpm build
`

$3

Eslint and prettier runs automatically after each git commit command.

To run eslint manually:

`sh
pnpm lint
`

$3

- Icons must be created by the Mott Macdonald design team.
- All icons should be included in the "Motata Library" Figma file.
- Icons must be 24x24 pixels with an live area 20x20 pixels.\
(refer to Material Design Icon Principles for more information)

To add a new icon

1. Select the icon element in the Moata library Figma file. (Make sure the selected element is the icon with the correct size)
2. Use the Export feature to download the icon as an SVG file. (Make sure the Export settings are set to the values below )
3. Add the icon SVG file to /icon-svgs. (Make sure the SVG file name is in PascalCase)
4. Run the build icons script to generate the new icon component.

#### Figma export settings

Ensure the following settings are used.

- [x] Ignore overlapping layers
- [x] Simplify stroke
- [ ] Include "id" attribute

#### Build Icons

`sh
pnpm build:icons
`

The script used to build the icons (/scripts/build-icons.js) can be used in other projects to build custom icon sets.
But all icons should be approved by the Moata design team (email: alex@mettle-studio.com), and preferably, all icons should be added to this package
so that they are available to other projects.

$3

We use changesets to manage package versions and changelogs.

Use pnpm changeset to trigger change log and follow the steps. Please remember
to add and commit the change log after it has been created.

Use pnpm changeset --empty` to create a empty change log without a version bump when you are only doing repo maintenance that does not affect the built artifacts.

Best practices and documentation can be found here - Adding a changeset

License

See LICENSE file - or this public copy

License subject to change: current version: v20190514.