[RFC] Strategy for adopting CSS variables in @mui/material

[siriwatknp]

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

[michaldudak]

@siriwatknp Since CssVarsProvider uses GlobalStyles, how will it be possible to have nested themes? Isn't the inner theme going to replace the values of the outer one?

[siriwatknp]

Isn't the inner theme going to replace the values of the outer one?

Developers can assign different prefixes to CssVarsProvider for the nested theme. However, the HTML build (for SSR) will be larger because CSS variables are doubled.

In my opinion, it is better to discuss using real scenarios and work backward. I feel like at the end the nested theme might be a rare case because the CSS variables approach forces the app to have a single provider.

[RemyMachado]

Trying to workaround the lack of css properties, I came around an issue:
How to use theme breakpoints inside css modules, since @media (min-width: var(--breakpoints-md)) wouldn't work?
I have a really dirty workaround. At the moment I'm exporting scss variables to inject in MUI theme, so I end up with two source of truth:

• scss vars for breakpoints
• js theme for everything else

@siriwatknp Did you already work something out?

[siriwatknp]

Can you share more details about exporting SCSS variables to inject in MUI theme, How do you do that? a sample repo would be really nice.

For breakpoints, I think it will be the same (using JS) since CSS variables do not support @media (min-width: var(--breakpoints-md)).
So, in some component it will still use JS like this:

{
  [theme.breakpoints.up('sm')]: { ... }
}

[RemyMachado]

At the moment I can give you code samples.

I export my breakpoints from .scss

// _breakpoints.module.scss
...
$xxs: 320px;
...

$breakpoints: (
  'zero': $zero,
  'xxs': $xxs,
  'xs': $xs,
  'vs': $vs,
  'sm': $sm,
  'md': $md,
  'lg': $lg,
  'xl': $xl,
);

/* exporting for JS */
:export {
  @each $key, $value in $breakpoints {
    #{unquote($key)}: $value;
  }
}

Then import, parse and inject them in the theme:

import { Breakpoint } from '@mui/material/styles'
import { createBreakpoints } from '@mui/system'

import breakpoints from 'styles/themes/_breakpoints.module.scss'

const customBreakpointValues = {
  values: {
    zero: parseInt(breakpoints.zero, 10), // custom
    xxs: parseInt(breakpoints.xxs, 10), // custom
    xs: parseInt(breakpoints.xs, 10),
    vs: parseInt(breakpoints.vs, 10), // custom
    sm: parseInt(breakpoints.sm, 10),
    md: parseInt(breakpoints.md, 10),
    lg: parseInt(breakpoints.lg, 10),
    xl: parseInt(breakpoints.xl, 10),
  },
}

const customBreakpointKeys: { keys: Breakpoint[] } = {
  keys: ['zero', 'xxs', 'xs', 'vs', 'sm', 'md', 'lg', 'xl'],
}

const customBreakpoints = createBreakpoints({
  values: customBreakpointValues.values,
  keys: customBreakpointKeys.keys,
})

export default customBreakpoints

// theme
{
  ...
  breakpoints: customBreakpoints,
  ...
}

Finally, I use scss import for breakpoints, and var(...) from JS for everything else:

@use 'styles/themes/breakpoints.module';

@media (min-width: breakpoints.$md) {
    ...
    color: var(--color-primary);
}

This is the best I could come up with. Hoping for a cleaner solution to emerge get standardized.

[siriwatknp]

Got it. I would say that it is about "integrating MUI with other styling solutions via CSS variables" topic which is another step in the future after we have CSS variables feature in place. From my gut feeling, it might be a tool or CLI that sync the JS and other styling solution but it is too soon to say.

For the time being, this will be out of the scope of this RFC. Does it make sense to you?

[RemyMachado]

Yes you are right, one step at a time. However, I wonder who wants to use CSS properties inside CSS, but keep using JS for breakpoints, this is non-sense. Since, the breakpoints export looks way harder to implement, I would say let's see that afterward, but we should keep it in mind while building this RFC. 😄

[DiMatteoL]

Currently, it's possible to make this work for some components (like the Select component), but not for others (like the Button component):

export const baseTheme = createTheme({
  palette: {
    text: {
      primary: "var(--text-primary)",
      secondary: "var(--text-secondary)",
      disabled: "var(--text-disabled)",
    },
    action: {
      active: "var(--action-active)",
      hover: "var(--action-hover)",
      selected: "var(--action-selected)",
      disabled: "var(--action-disabled)",
      disabledBackground: "var(--action-disabled-background)",
    },
    background: {
      default: "var(--background)",
      paper: "var(--background)",
    },

    divider: "var(--divider)",
    primary: { main: "#9147FF" },
    secondary: { main: "#2a48f3" },
  },
});

export const globalStyles = css`
  :root {
    --background: #fff;
    --text-primary: #121212;
    --text-secondary: rgba(0, 0, 0, 0.6);
    --text-disabled: rgba(0, 0, 0, 0.38);
    --action-active: rgba(0, 0, 0, 0.54);
    --action-hover: rgba(0, 0, 0, 0.04);
    --action-selected: rgba(0, 0, 0, 0.08);
    --action-disabled: rgba(0, 0, 0, 0.26);
    --action-disabled-background: rgba(0, 0, 0, 0.12);
    --divider: rgba(0, 0, 0, 0.12);
  }

  [data-theme="dark"] {
    --background: #121212;
    --text-primary: #fff;
    --text-secondary: rgba(255, 255, 255, 0.7);
    --text-disabled: rgba(255, 255, 255, 0.5);
    --action-active: #fff;
    --action-hover: rgba(255, 255, 255, 0.08);
    --action-selected: rgba(255, 255, 255, 0.16);
    --action-disabled: rgba(255, 255, 255, 0.3);
    --action-disabled-background: rgba(255, 255, 255, 0.12);
    --divider: rgba(255, 255, 255, 0.12);

    .MuiOutlinedInput-notchedOutline {
      // MUI hard codes border colors for outline inputs.
      border-color: var(--action-disabled);
    }
  }
`;

The reason I'm saying this is: why would just simply allowing CSS variables inside the theme be a bad idea ?

[siriwatknp]

Thanks for the idea, I also had this thought about this approach and the main reason is about breaking change and migration experience.

• This way is definitely a breaking change that needs to wait until v6.
• We can't do gradual adoption (all the components need to be compatible with CSS variables at the same time)
• It is tough to adopt CSS variables for the existing apps. Imagine that the theme value has changed to CSS variable and you have some runtime calculation, it will break. We have learned in v4->v5 that this is not a great experience and we try to avoid that.

Note
The approach I proposed also allows you to add custom variables directly to the theme.

<CssVarsProvider
  theme={{
    colorSchemes:{
      light: {
        customColor: 'var(--palette-text-primary)',
      }
    }
  }}
>

[mnajdova]

How to deal with the current color manipulation at runtime?

Maybe we should still export the palette with the specific values as part of the theme, and allow developers to use the JS transformations. We should not make the DX worse than before. Apart from colors, I don't really see another part of the theme that would be necessary to be available as a plan JS object.

[siriwatknp]

Maybe we should still export the palette with the specific values as part of the theme

The approach I proposed keep the existing theme the same, only append vars field to the theme. So the theme.palette[...] remains the same.

We should not make the DX worse than before

Can you elaborate on this? which proposed DX do you think it is worse than before?

[mnajdova]

Off-topic: Isn't it possible even now for people that want to try this to use the CssVarsProvider and use the CSS variables for example in the style overrides for the components?

[siriwatknp]

Not yet, the CssVarsProvider is exported from mui-joy. We haven't started any effort on the mui-material yet.

[mnajdova]

Right, I thoughts it's in the system for some reason. Alright

[siriwatknp]

The system exposes a factory function createCssVarsProvider so that the design system package (Material & Joy) can share the same functionality with some differences in theme structure (including types).

[siriwatknp]

The API is available in Material UI and Joy UI, so I'm closing this.