@mott-macdonald/smi-react-ui-kit

v5.0.0

Published

4 days ago

The MUI theme for Mott MacDonald Moata Apps

0High
0Medium
0Low

ruatara

wangxingkai

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.

Supported MUI versions

Since v5.0.0, the kit supports MUI Material v7 and v9 with a single published package (@mui/material peer range: ^7.0.0 || ^9.0.0):

Apps on Material v7 can upgrade the kit with zero code changes and stay on v7.
Apps ready for Material v9 use the exact same kit version — migrate whenever it suits your roadmap (see Migrating your app to MUI v9).
Every release is CI-verified against the floor of each supported major (7.0.0 / 9.0.0) — see docs/mui-peer-compatibility.md for how this works.
MUI X packages are not peers of the kit; they follow your app. Supported pairings: Material 7 ↔ X v8, Material 9 ↔ X v9.
@mui/lab is no longer required (dropped as a peer in v5.0.0). MUI v6 support was also dropped in v5.0.0 — upgrade to Material v7 first if you are still on v6.

Installation

Installation for a new project

Add this package and its peer dependencies to your project:

pnpm add @mott-macdonald/smi-react-ui-kit @emotion/react @emotion/styled @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 MUI CSS theme variables documentation for more information.

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 (
    <StyledEngineProvider injectFirst>
      <ThemeProvider theme={theme} defaultMode="light">
        <CssBaseline />
        ...
      </ThemeProvider>
    </StyledEngineProvider>
  );
}

export default App;

without CSS Variables (the legacy approach)

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 (
    <StyledEngineProvider injectFirst>
      <ThemeProvider theme={themes.light}>
        <CssBaseline />
        ...
      </ThemeProvider>
    </StyledEngineProvider>
  );
}

export default App;

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

Installation alongside legacy version (v1) for a staged upgrade to the latest version

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

First edit the package.json as follows:

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

Update all import from "@mott-macdonald/smi-react-ui-kit" to use "@mott-macdonald/legacy-smi-react-ui-kit"
Rename the ThemeProvider component imported from the legacy version to LegacyThemeProvider
Install the latest version using the process above, including adding the ThemeProvider component.
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.
```
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:

import './muiClassNameSetup';

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

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>
);

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

// 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 (
    <StyledEngineProvider injectFirst>
      <LegacyThemeProvider>
        <LegacyGlobalStyles />
        <ThemeProvider theme={theme} defaultMode="light">
          <CssBaseline />
          ...
        </ThemeProvider>
      </LegacyThemeProvider>
    </StyledEngineProvider>
  );
}

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.

Migrating your app to MUI v9

The kit itself needs nothing from you — the same package serves v7 and v9. The steps below migrate your app's own code off the APIs MUI removed in v9. They were validated end-to-end on a production Moata app (~800 source files, 105 type errors → 0 in roughly an hour).

There is no MUI Material v8 — Material jumped from 7 to 9 to realign its major with MUI X.

Step 1 — Upgrade the kit first (while still on v7)

pnpm add @mott-macdonald/smi-react-ui-kit@^5.0.0

No code changes needed; ship this independently. Remove @mui/lab from your dependencies too if you only had it for the kit.

Step 2 — Bump the MUI packages

pnpm add @mui/material@^9.0.0 @mui/icons-material@^9.0.0
# plus the ones your app uses, paired to v9:
pnpm add @mui/x-data-grid@^9.0.0 @mui/x-tree-view@^9.0.0 @mui/x-date-pickers@^9.0.0
# @mui/lab has no stable v9 — if you use lab components (e.g. TabContext/TabPanel):
pnpm add @mui/[email protected]

Step 3 — Run the official codemod

npx @mui/codemod@latest v9.0.0/system-props src

This migrates the removed system props (<Box p={1}>, Stack alignItems, …) to sx and typically clears ~90% of the type errors. Run pnpm lint afterwards — the codemod occasionally emits a duplicate sx key, which lint catches.

Step 4 — Fix the remainder by hand

The complete list we hit in practice (pnpm check-types is your work list):

| v9 removal | Fix | | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Grid direction="column" (type no longer allows it) | sx={{ flexDirection: { xs: 'column', sm: 'row' } }} — identical CSS | | Checkbox/Switch inputProps | slotProps={{ input: { 'aria-label': … } }} | | Dialog/Modal disableEscapeKeyDown | Handle the 'escapeKeyDown' reason in onClose instead | | <Typography paragraph> | sx={{ mb: 2 }} | | Autocomplete renderTags | renderValue + getItemProps({ index }); extract key and pass it explicitly (spreading it warns) | | System props on a component={Stack} host (e.g. alignItems on DialogTitle) | Move them into sx |

Step 5 — Verify

pnpm check-types + tests + build, then a visual pass. Things that changed by design in v9 (not bugs): ListItemIcon default min-width is 36px (was 56px) so icon menus render tighter; Stepper renders <ol>/<li> with keyboard navigation; browser floors are Chrome 117 / Firefox 121 / Safari 17.

Full details: official v9 upgrade guide · docs/mui-peer-compatibility.md

Usage

In the most part, once the theme is added to the project, you should follow the guidelines and examples provided in the MUI 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.

Using the theme value in JS

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.

<Box sx={(theme) => ({ ... })}>...</Box>

Using Icons

Importing

The icons are packaged separately and can be imported using:

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:

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:

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

export const ExampleButton = () => (
  <button type="button">
    <AlertIcon sx={{ color: '#333', fontSize: '1.5rem' }} />
  </button>
);

with SCSS Modules:

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

export const ExampleButton = () => (
  <button type="button">
    <AlertIcon className={styles.icon} />
  </button>
);

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

Styling library recommendations

We would recommend that new projects use the recommended approach to styling components for MUI, 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 MUI 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 MUI documentation here

Nesting the theme (for dark backgrounds) [deprecated]

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.

<ThemeProvider theme={theme} defaultMode="light">
  <LightBackgroundContent />
  <div data-mui-color-scheme="dark">
    <DarkBackgroundContent />
  </div>
</ThemeProvider>

Check out Force a specific color scheme

without CSS Variables

<ThemeProvider theme={themes.light}>
  <LightBackgroundContent />
  <ThemeProvider theme={themes.dark}>
    <DarkBackgroundContent />
  </ThemeProvider>
</ThemeProvider>

Check out Nesting the theme

Development

If you are contributing with an AI coding agent, AGENTS.md is the single source of truth for agent instructions (repo-specific gotchas and workflow rules).

Prerequisites

Node.js LTS v24 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.6.3 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.

Quick start

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.

# Clone the repository
git clone [email protected]: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

Build

To build a new version, bundle this kit:

pnpm build

Linting

ESLint and Prettier run automatically on staged files before each commit (via husky + lint-staged).

To run ESLint manually:

# Auto-fix problems (mutates files)
pnpm lint
# Check only, no fixes (what CI runs)
pnpm lint:ci

Testing and type checking

CI requires both to pass on every pull request:

# Run unit tests with Vitest
pnpm test
# TypeScript type check
pnpm check-types

Adding New Icons

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

Select the icon element in the Moata library Figma file. (Make sure the selected element is the icon with the correct size)
Use the Export feature to download the icon as an SVG file. (Make sure the Export settings are set to the values below )
Add the icon SVG file to /icon-svgs. (Make sure the SVG file name is in PascalCase)
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

pnpm build:icons

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

CHANGELOG

We use changesets to manage package versions and changelogs.

For each pull request, please make sure to add a changeset by running the following command:

pnpm changeset to trigger change log and follow the steps. Please remember to add and commit the change log after it has been created.
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

Experimental Releases

We have an experimental branch and an experimental npm dist-tag for publishing experimental releases, which are intended for testing and feedback collection before we are ready to make a stable release.

The experimental releases will be published with a version like 0.0.0-experimental-20260101-abcdefg, where the date and git hash can help identify when the release was made and what commits are included.

Working on Experimental Releases

If you want to work on an experimental release, please create a new branch from experimental branch, and make your changes there.

When your changes are ready, you can follow the standard pull request and versioning process to open a pull request to merge your branch back to experimental branch.

Once your branch is merged back to experimental branch, the CI will automatically run tests and publish a new experimental release.

License

See LICENSE file - or this public copy

License subject to change: current version: v20190514.