The JLL theme for MUI is built based on the JLL Design System guidelines using JLL Design Tokens.
Users can use this theme with MUI to build JLL Design System compatible UIs with ease.

Installation

The JLL theme for MUI is available as an npm package, through JLL Azure Artifacts under Jll.Capability feed.
To use the package users should have access to the feed. If not, please reach out to JLL Design System Support Team.
Once you have the access, you need to connect to the feed to setup .npmrc file.

Once you have configured your local .npmrc file, you should be able to install the package.

npm install @jll/jll.capability.designsystem.restyles.mui

Usage

Import jllTheme from @jll/jll.capability.designsystem.restyles.mui.
To get all the MUI components in JLL theme add the MUI ThemeProvider at root level of your application, and pass jllTheme to theme property of MUI's ThemeProvider.

import React from "react";
import ReactDOM from "react-dom/client";
import { ThemeProvider } from "@mui/material/styles";
import jllTheme from "@jll/jll.capability.designsystem.restyles.mui";
import App from "./App";

const root = ReactDOM.createRoot(
  document.getElementById("root") as HTMLElement
);

root.render(
  <React.StrictMode>
    <ThemeProvider theme={jllTheme}>
      <App />
    </ThemeProvider>
  </React.StrictMode>
);

If there is a need to override or extend the theme further, use the provided themeOptions.

import { themeOptions } from "@jll/jll.capability.designsystem.restyles.mui";
import { createTheme } from "@mui/material";
import { ThemeProvider } from "@mui/material/styles";
import { merge } from "lodash";
import App from "./App";

const customTheme = createTheme(
  merge({}, themeOptions, {
    palette: {
      error: {
        main: "#d622c7",
      },
    },
  })
);

export const Application = () => (
  <ThemeProvider theme={customTheme}>
    <App />
  </ThemeProvider>
);

Please refer to this documentation to learn more about customizing the MUI theme and components.

Typescript

To support JLL design system components, we have extended few MUI components variants and colors. The package also contains the type definitions of the extensions. If you're using TypeScript and you need to make use of these extensions, import the typings anywhere in your application code: For example add the import in global.d.ts file under types folder in your root directory.

// src/types/global.d.ts
import "@jll/jll.capability.designsystem.restyles.mui/dist/augmentation";

With the above setting, you can directly use all the MUI components as described in MUI Documentation.

Note: If you need to also add your own augments to components already augmented by JLL DS Restyles, you will need to copy-paste the augments to your project, so that all the augments for a component can be co-located within the same file. see this issue.

Example

Below is the example of MUI Button component with JLL Theme applied.

Exceptions

The JLL Theme for MUI is crafted based on the JLL Design System components design. The JLL Theme for MUI uses the JLL Design Systems color, spacing, typography, border radii and elevation to override the base MUI Component design.

There are a few limitations to what extent the override can be done on the MUI Components to match it to JLL Design System Components.

• Overlay on the component to represent different states (active, hover, focused) of the component are not overridden to match JLL Design System due to technical limitation.
  For example, Checkbox and Radio button overlay status default to MUI Implementations.

• Size of a few components are not pixel perfect to JLL Design System, as MUI uses different SVG’s on these components.
  For example, Radio button and Checkbox size are made close to JLL Design System Radio button and Checkbox.

• Jll MUI theme spacing are discrete values (array of integers), unlike the default spacing which is a number/scale factor, and spacing is continuous with multiple of this scale factor.
  JLL MUI theme spacing is [0, 2, 4, 8, 12, 16, 24, 32, 40, 56, 72, 88, 104, 138, 164, 196, 228].
  Thus, theme.spacing(2) means 4px
  And sx={{ m: 0.5 }} would result in error, use only discrete values like sx={{ m: 1 }} which would result in margin 2px.

Disclaimer

MUI offers many variants and features on each component. In JLL Theme, we have overridden some specific variants of the component to derive JLL Design System compatible components design.

Please go through the components variants demonstrated in the MUI Components section.

If the project is following JLL Design System, it is advised to use only those variants listed in the component design section. Though other variants are available to use based on the need.

If you notice any discrepancy in the component design, please contact JLL Design System Support Team