Since most checklists in #27651 are done and browser support is also promising (96%), we are in a good stage to move forward to bring CSS variables to @mui/material. We believe that it will open a lot of opportunities described in #27651.

Overall, CSS variables can be applied to at least 2 levels.

• theme level: Turn theme (JS object) into CSS variables that all components inside the tree can use.
• component level: A specific component can have its own meaningful variables that communicate within the component.

At the first stage, we want to achieve only the theme level because this has obvious benefits such as

• achieving perfect dark mode
• consolidate design tokens in the right place which let developers use other CSS solution (SASS, CSS modules) more efficiently.

Also, we need some time to validate if CSS variables is the real deal, then we can move forward with the component level which requires more effort and care.

Goal

The intention of this RFC is to share the strategy and iterate with the community on the best approach of adopting CSS variables in @mui/material (both for existing and new applications). However, we don't expect to spend any effort on the implementation/migration in Q1 2022.

The proposed strategy aims to go with NO breaking change but it might change as the discussion goes.

Duration

I think we can keep this RFC at least for a quarter (Q1 2022) and see the feedback from everyone about the final strategy.

Expecting DX

These are the things that the final strategy should aim for:

• NO breaking change (I am not sure if we can achieve this but at least as little as possible).
• CSS variables for @mui/material should be considered as a feature, meaning that developers can decide not to use it if they don't want to.
• Lean toward gradual adoption (converting everything to CSS variables at once might break a lot of things, so it is nice if we can provide a way for developers to convert each part of their application to CSS variables if they'd like).
• Automate with Codemod if possible.

Proposed strategy

The final strategy should answer all of these questions:

• How to generate CSS variables from the theme?
• Which theme tokens will be generated as CSS variables?
• How does the component access CSS variables inside the theme?
• How to deal with the current color manipulation at runtime?
• What needs to be done for existing apps to adopt CSS variables?

The proposed strategy below aims toward NO breaking change. Please review and ask questions as much as possible so that we have the best way to proceed with.

How to generate CSS variables from the theme?

Expose a provider that produces CSS variables from the theme input and attaches them globally.

- import { ThemeProvider } from '@mui/material/styles';
+ import { CSSVarsProvider } from '@mui/material/styles';

function App() {
  return (
-    <ThemeProvider theme={theme}>...</ThemeProvider>
+    <CSSVarsProvider theme={theme}>...<CssVarsProvider>
  )
}

Behind the scene, CSSVarsProvider uses ThemeProvider so the components inside the tree can still receive the same theme.

CssVarsProvider will read the theme, create variables, and attach them globally via GlobalStyles. Here is an example of some variables from the theme:

{
  palette: {
    primary: {
      main: '#1976d2' // => --md-palette-primary-main: #1976d2; where `md` is a prefix that developers can configure.
    },
    text: {
      primary: 'rgba(0, 0, 0, 0.87)', // => '--md-palette-text-primary: rgba(0, 0, 0, 0.87);
    }
  }
}

Which theme tokens will be generated as CSS variables?

According to the current default theme structure, these are the estimated tokens that will be generated as CSS variables.

• non function value
• palette.* (excluding palette.mode, palette.contrastThreshold, palette.tonalOffset because they are for JS usage)
• zIndex.*
• shadows.*
• typography
  • htmlFontSize
  • fontFamily
  • fontSize
  • fontWeightLight
  • fontWeightRegular
  • fontWeightMedium
  • fontWeightBold

How does the component access CSS variables inside the theme?

The safest way is to add a new field in the theme to reference CSS variables. The vars key contains all references to the generated CSS variables.

// theme
{
  palette: { // palette is the theme input
    primary: {
      main: '#1976d2',
    },
  },
  vars: { // attached to theme by `CssVarsProvider`
    palette: {
      primary: {
        main: 'var(--md-palette-primary-main)',
      }
    }
  }
}

Then a component can use it like this:

// this is not the full code of Badge component
const BadgeBadge = styled('span')(({ theme, ownerState }) => ({
-  fontFamily: theme.typography.fontFamily,
-  fontWeight: theme.typography.fontWeightMedium,
+  fontFamily: theme.vars.typography.fontFamily,
+  fontWeight: theme.vars.typography.fontWeightMedium,
  ...(ownerState.color !== 'default' && {
-    backgroundColor: theme.palette[ownerState.color].main,
-    color: theme.palette[ownerState.color].contrastText,
+    backgroundColor: theme.vars.palette[ownerState.color].main, // var(--md-palette-...-main)
+    color: theme.vars.palette[ownerState.color].contrastText, // var(--md-palette-...-contrastText)
  }),
}))

The benefits of using new key (vars) are:

• Almost 0% of breaking the existing application that want to adopt CSS variables. (I cannot think of a case that it will break)
• Allow gradual migration without a separated branch. For example, we can merge this change to production without impacting the existing users:

  // Badge
  const BadgeBadge = styled('span')(({ theme: { vars, ...theme }, ownerState }) => ({
    fontFamily: (vars || theme).typography.fontFamily,
    fontWeight: (vars || theme).typography.fontWeightMedium,
    ...(ownerState.color !== 'default' && {
      backgroundColor: (vars || theme).palette[ownerState.color].main,
      color: (vars || theme).palette[ownerState.color].contrastText,
    }),
  }))

  CssVars support can be checked by looking at theme.vars. If there is no theme.vars, fallback to existing behavior.
• Able to create CSS var that reference to other variable

  <CssVarsProvider
    theme={{
      customColor: 'var(--palette-primary-main)',
    }}
  />
  // the stylesheet will contain { --customColor: var(--palette-primary-main); }
  // which you can use this variable via `theme.vars.customColor` in JS.

The downsides

• Typing 3 more characters.

How to deal with the current color manipulation at runtime?

There are a lot of components that are using javascript to manipulate color from the theme at runtime. For example:

// A part of the styles in Button.js
{
  ...(ownerState.variant === 'text' &&
        ownerState.color !== 'inherit' && {
          backgroundColor: alpha(
            theme.palette[ownerState.color].main,
            theme.palette.action.hoverOpacity,
          ),
        }),
}

There is no way to convert color using only CSS at the moment of writing (it is possible in CSS color level 5 but that's a long way to go).

The only workaround with CSS variables is to create a channel variable with a combination of an opacity variable:

--primary-mainChannel: 12 34 233;
--action-hoverOpacity: 0.3;
background-color: rgba(var(--primary-mainChannel) / var(--action-hoverOpacity));
// similar to alpha(theme.palette[ownerState.color].main, theme.palette.action.hoverOpacity)

With this approach, the implementation will be like this:

// A part of the styles in Button.js
{
  ...(ownerState.variant === 'text' &&
        ownerState.color !== 'inherit' && {
          backgroundColor: `rgba(${theme.vars.palette[ownerState.color].channelMain} / ${theme.vars.palette.action.hoverOpacity})`
        }),
}

Note

1. the channel variables will be automatically created.
2. We might expose a function that combines channel + opacity so that there is no need to think about using / or ,

What needs to be done for existing apps to adopt CSS variables?

1. Replace ThemeProvider with CssVarsProvider

- import { ThemeProvider } from '@mui/material/styles';
+ import { CSSVarsProvider } from '@mui/material/styles';

function App() {
  return (
-    <ThemeProvider theme={theme}>...</ThemeProvider>
+    <CSSVarsProvider theme={theme}>...<CssVarsProvider>
  )
}

2. Move palette inside colorSchemes

This is quite different from ThemeProvider approach. It changes from switching between themes to preparing all the themes beforehand. This step is required if you have a custom theme to make the flicker issue for SSR goes away.

You don't need to worry about this process, we will create a thorough docs for this part again.

function App() {
  return (
    <CssVarsProvider
      theme={{
        colorSchemes: {
          light: {
            palette: {
              ...
            }
          },
          dark: {
            palette: {
              ...
            }
          }
        }
      }}
    >
      ...
    </CssVarsProvider>
  )
}

3. Update toggle UI to use useColorScheme hook

// example code, naming could be changed
import { useColorScheme } from '@mui/material/styles';

function Toggle() {
  const { mode, setMode } = useColorScheme();
  return (
    <button onClick={() => setMode(mode === 'dark' ? 'light' : 'dark')}>
      {mode === 'dark' ? 'light' : 'dark'}
    </button>
  )
}

The CssVarsProvider handles the local storage sync for you, so you can remove that part from the codebase. (We will provide an option to use custom storage if you'd like)

cc @mui-org/core @mui-org/x @mui-org/contributors