Our requirements

A single base theme for each customer.
- The base theme will reflect the customer’s brand and any bespoke additions or changes to DCB Admin.
- The base theme will define styles for typography, presentation and components. Colours will be defined separately.
The option to develop further colour themes for each customer.
- In the future we intend to offer the ability for users to select alternative colour schemes via a theme switcher. Users will only be able to change colours, not any typography or component styles.
Each theme will need a dark and a light mode as a minimum.

Theme structure

Each theme should have its own file, containing a dark and light mode colour palette. This allows us to easily differentiate between colours associated with each theme
Typography and component styles should be separated out to form the base theme. These styles will be applied to all the colour themes and should only be defined once. Separating them out will mean we do not have to duplicate unchanging styles for each colour theme.
For customers who need to change typography and component styles, a new base theme file can be created. This base theme can be reused like the original baseTheme file, within each theme.

How to add a new theme

Create a new file in the themes folder, and name it myTheme.ts (replace myTheme with the name of your theme). This is where we will keep all the theme colours.

In this file, make two new objects, one called myThemeLight and the other called myThemeDark. We will use these to separate out light and dark mode colours.

// Light palette
const myThemeLight = {

};

// Dark palette
const myThemeDark = {

};

export { myThemeLight, myThemeDark }

Import the createTheme function from @mui/material/styles. This will generate a theme based on the options received.

import { createTheme } from "@mui/material/styles";

// Light palette
const myThemeLight = {

};

// Dark palette
const myThemeDark = {

};

export { myThemeLight, myThemeDark }

Import baseTheme, and use the spread operator to gain all styles from the base file.

import { createTheme } from "@mui/material/styles";
import baseTheme from "./baseTheme";

// Light palette
const myThemeLight = {
  ...baseTheme
};

// Dark palette
const myThemeDark = {
  ...baseTheme
};

export { myThemeLight, myThemeDark }

Define a colour palette, and specify what mode this colour palette is for: “light" or “dark"

const myThemeLight = createTheme({
  ...baseTheme
  palette: {
    main: "#.....",
  },
})

Repeat for the other mode.
For adding styles to typography or components, import the mergeThemeStyles helper function. This can be used to add on to existing typography styles in the baseTheme. It can also be used to add new colour styles without specifying them in the baseTheme.

import { mergeThemeStyles } from "src/helpers/mergeThemeStyles";

typography: mergeThemeStyles(baseTheme.typography, {
  h1: {
    // specify styles here...
  }
})

Adding colours to components

Colours should not be added to the base theme, this is because the base theme should be as generic as possible for other themes to inherit from. Colours should be defined in each theme file, in both light and dark mode.

Find the CSS to target through the Material UI docs, or the CSS inspector
Add colour within relevant class

MuiButton: {
  styleOverrides: {
    root: {
      backgroundColor: "purple"
    }
  }
}

One-off customisations

For one-off customisations (e.g. setting one button to be pink) the sx prop should be used. The sx prop is just like using style, and can be used with any Material UI component.

Colours should not be defined within the sx prop, but should instead be defined within the theme and referred to using the useTheme hook.

Define colour within the theme

  palette: {
    main: "#.....",
    myButtonBackground: "#FFC0CB"
  }

Import useTheme into component, and reference the colour in the sx prop

import { useTheme } from "@mui/material/styles";

export default function ButtonRenderer() {
  const theme = useTheme();
  
  return(
    <Button sx={{ backgroundColor: theme.palette.primary.myButtonBackground }}>
      I am a pink button
    </Button
  )
}

Custom CSS classes for increased specificity

This may require further testing.

This can be used when variants, or the default classes of a component, are not enough. An example of where custom CSS classes may be used, could be when creating a variation of a variant that uses the same styles, but applies some additional styles on top.

Choose a name for the class, and specify the styling. Make sure to use the &. before it.

"&.RedContainedButton": {
  backgroundColor: "red"
}

Add the classname prop to the component

<Button variant="contained" className="RedContainedButton"> Red contained button</Button>

Theming in DCB Admin