[RFC] Material You support implementation strategy in Material UI

[mnajdova]

Motivation

The #29345 Adopt Material Design 3 / Material You issue is now one of the top 5 most upvoted issues. Moreover, the Material Design 3 design kits are at 50% of the downloads of Material Design 2 (at the time of writing). It's time we start with the adoption 🎉. The goal of this RFC is to open up discussion for the different approaches we can take for adding a support for the new version of Material Design.

Requirements

No matter what implementation strategy we will choose, it will need to support the following:

• no breaking changes (should be implemented as an opt-in feature)
• should allow progressive migration

Options

In order to make the implementation easier, we are going to be adding a new theme creator that will prepare the theme structure for Material You. This theme will be a merged version of the themes for Material Design 2 & Material Design 3. The reason of this is to allow us to be able to progressively upgrade to the new design system (in addition to this, not all components have specification for Material You, so we will need to have them render by default in the old Material Design 2 version for the time being). Because of some possible conflicts, some keys will be defined under an object with the md3 key. This can be further polished and discussed in the pull request for it.

In addition to this, we will be exposing a module augmentation file that can be imported in userland to ensure type safety.

The different implementation strategy is in terms how the components will be adding the styles for the different versions of the design systems. Here we have two options:

Option 1 - The Material UI components would be adding the styles for both design systems

Proof of concept 👉 #34622

In this implementation strategy, we would be updating the existing Material UI components, that based on the theme context would render different styles (note that the styles will not be merged, only the styles for the specific version of the design system will be added on the component). This is an example usage:

import * as React from 'react';
import {
  Button,
  unstable_createMD3Theme as createMD3Theme,
  ThemeProvider
} from '@mui/material';

const theme = createMD3Theme();

function App() {
  return (
    <ThemeProvider theme={theme}>
      <Button variant="filled">Material You button</Button>
      <Button variant="filled" disableMaterialYou>Material Design 2 button</Button>
    </ThemeProvider>
  )
}

👍 Pros:

• Ease of implementation - will take least time to be implemented

👎Cons:

• Increases the bundle-size of the components - they now bundle the styles for both Material Design versions
• Less type safe - in order for it to works some props for the components will be relaxed (for example the Button component's varaint prop will need to support both the MD2 and the MD3 variants)

Option 2 - Add new component that will host the Material You styles

Proof of concept 👉 #34650

In this implementation strategy, we would be adding a brand new component that will host only the styles for Material You. For this implementation we would use the @mui/base package's headless hooks. This will be closer to how some of the future versions of Material UI components will anyway look like, which basically means that we would be step ahead when working on the future release.

import * as React from 'react';
import {
  Button,
  Unstable_Button2 as MD3Button, // or Unstable_MD3Button
  unstable_createMD3Theme as createMD3Theme,
  ThemeProvider
} from '@mui/material';

const theme = createMD3Theme();

function App() {
  return (
    <ThemeProvider theme={theme}>
      <MD3Button variant="filled">Material You button</MD3Button>
      <Button>Material Design 2 button</Button>
    </ThemeProvider>
  )
}

👍 Pros:

• Better tree shaking - only the styles used will be bundled
• It can help with future adoption with new major version, as the components will be based on @mui/base already
• Better type safety (at least on the component's props API)

👎 Cons:

• There may be unexpected changes in behavior of the components
• The implementation would take more time
• Maintenance - we will need to make sure bugs are fixed in both versions of the components

Additional comments

For those who can't wait, the community already started with adding Material You themes that can serve as a great starting point for the implementation - #29345 (comment). The problem with this is that the three object is big and not tree-shakable so be aware of it. In addition of this, the customization of the components is becoming a bit harder, as the styles for both design systems are added on the components.

Other options?

Please feel free to propose other options for implementation if you can think of any.

[o-alexandrov]

How about Option 3?

Steps to make it work:

1. copy @mui/material (v2) to @mui/material-base
2. extend from (import) @mui/material-base in @mui/material (v2), so feature-parity is preserved
3. create @mui/material-v3
4. gradually update each component
   • work would be divided per component, same as you did when introduced V5
     • a developer updates a component: in base, material (v2) and material-v3
       • removes differences between v2 and v3 from base
       • moves v2-related aspects to v2 and v3-related to v3

Notes:

• v3 would have a separate theme context, so 2 Material themes could coexist in the same project
• the separation between packages would allow you to simply remove @mui/material (then, v3, v4, etc.) package(s) (directory) in the future
• once @mui/material-base is stable, it would be a lot simpler for you to introduce future versions of Material Guidelines @mui/material-v4 (v5, etc.)

How users would use V3

Users have an option to stay at v2 or gradually switch every component one by one

[mnajdova]

Could be, we will see how much similarities in the end will end up the same and we can extract them for sure 👍

[oliviertassinari]

Thoughts on Option 3:

1. one vs. two npm packages. It would lead to the introduction of a new npm package. While it's great to help track progress, the long-term goal is to have a single Material Design version, so I think it would make this goal harder. Now, if @mui/material-v3 is called @mui/material-next then it would solve this concern because it sets clearer expectations of what will happen once mature enough (MD2 is going away). I think that it's not specific to Option 3. Option 2 could also have two different packages.
2. one vs. two theme context. This is an interesting notion. I think that it's not specific to Option 3. Option 2 could also have two different React contexts. It's also worth noting that in Option 1. We could make a enableMaterialYou prop, meaning opt-in, when disableMaterialYou is opt-out.
3. I think that we are already at full capacity in terms of surface area. If we take the Tooltip, the logic (not the styles) is implemented in 3 different ways between MUI Base, Joy UI, and Material UI. We need to aim for MUI Base's logic tooltip implementation to eventually be the only one & shared. I think that a 4th Tooltip implementation would be a deal breaker.

I haven't used plain @mui/base or MUI Joy (the latter I'd never)

@o-alexandrov Do you see no use case for MUI Joy because you are always following Material Design? Or is it about something else?
The whole bet we have for MUI Joy is that with the same DX as Material UI but a style closer to where your designer is asking you to follow you could have a better customization experience.

[o-alexandrov]

@o-alexandrov Do you see no use case for MUI Joy because you are always following Material Design?
The whole bet we have for MUI Joy is that with the same DX as Material UI but a style closer to where your designer is asking you to follow you could have a better customization experience.

@oliviertassinari thank you for the kind interest. I'll be transparent because I depend on your success :D and I hope the transparency below would be useful to you.

The reasons why I believe no one should be interested in MUI Joy are:

1. if a business has a custom design, pick @mui/base (unstyled components you introduced in v5)
2. if a business wants to extend from a design guideline, business should pick the only popular guidelines (as the rest are incomparably less popular) either: Google's Material Design, Microsoft's Fluent UI, or Apple Human Guidelines

So if a business likes MUI Joy's design, imho the business is just wrong, as UX is the key of the design whereas popularity is the driver of the UX (the more popular a design is, the more familiar a user is with design; the more familiar a user is with the design, the more-and-more convenient the design becomes for the user)

• MUI is not a fashion driver in the industry, imho, you can't dictate the trend (at least yet), so you shouldn't get involved with creating your own vision (MUI Joy)
  • and it's naive to think MUI has better designers than Google, Apple, and Microsoft

[oliviertassinari]

@o-alexandrov Awesome, thanks for sharing these thoughts! If you are concerned about our bandwidth, we are growing the core team, so exploring Joy UI shouldn't impact the success of what you depend on.

I won't expand too much so we keep the conversation focused on option 3. I think that your points are very true, what you are saying makes a lot of sense. However, from how we saw people behave, we have identified a. Bootstrap/Bulma b. Tailwind UI/Chakra as demonstrating that there is likely a space/demand for something between 1. fully custom design because too resource demanding and 2. very popular UX patterns (Google, Microsoft, Apple, Ant in China) because too classic look & feel.

[o-alexandrov]

@oliviertassinari I agree, there's market for MUI Joy, because the people who choose Bootstrap, Bulma, Tailwind UI/Chakra, and now MUI Joy are just making a mistake.

There's a reason why people went to Bootstrap though, Bootstrap was released (2011) before Material Design was announced (2012).

• and once Bootstrap was first, they got the market, and people got in this wrong way of thinking or never doubt their choices

[oliviertassinari]

@mnajdova Thanks for putting this together! So, from what I understand, there are a couple of core tradeoffs that we need to decide on:

1. one vs. two npm packages. Do we bring Material You support through @mui/material-next or in @mui/material directly? On one hand, a single package is easier to manage, but on the other, two different packages help to measure the traction, and maybe the migration progress for developers.
2. one vs. two theme context. While it seems to be a no-brainer to have two different create context functions if it can maximize code-splitting, would having two different theme context providers be worth the extra implementation overhead? On one hand, having two different theme contexts would force us to have two different components, but on the other hand, maybe it could make the migration easier for mature codebases.
3. build on top of Material UI or MUI Base. While the long-term goal is to move Material UI to be built on top of MUI Base (a great forcing function to find bugs, fix inconsistencies, and regressions of MUI Base compared to Material UI), is Material You the right time to do it? On one hand, it's a great new feature, hence a nice drive for the community to take the BCs in, if not now when? but on the other hand, if the community is quickly moving to Material You, then we might not be able to take in the extra delay, the more isolation between changes, the better.

[mnajdova]

1. one vs. two npm packages. Do we bring Material You support through @mui/material-next or in @mui/material directly? On one hand, a single package is easier to manage, but on the other, two different packages help to measure the traction, and maybe the migration progress for developers.

I would go with a different package: @mui/material-next. Would be great to measure traction for it, and maybe make a decision on when to do the switch with it to replace the official @mui/material components.

2. one vs. two theme context. While it seems to be a no-brainer to have two different create context functions if it can maximize code-splitting, would having two different theme context providers be worth the extra implementation overhead? On one hand, having two different theme contexts would force us to have two different components, but on the other hand, maybe it could make the migration easier for mature codebases.

I remember we had a discussion for different theme contexts multiple time, but as far as I remember it is currently not support in emotion. The last time we had this discussion was when Joy UI was started as an effort. @siriwatknp do you remember what was the resolution to it, or could you maybe link the issue about it?

The alternative would be to have what we have now (add the specifics for the non-default theme under a key in the theme md3 for example)

3. build on top of Material UI or MUI Base. While the long-term goal is to move Material UI to be built on top of MUI Base (a great forcing function to find bugs, fix inconsistencies, and regressions of MUI Base compared to Material UI), is Material You the right time to do it? On one hand, it's a great new feature, hence a nice drive for the community to take the BCs in, if not now when? but on the other hand, if the community is quickly moving to Material You, then we might not be able to take in the extra delay, the more isolation between changes, the better.

To be honest, this is the one I am most not certain about. My gut feeling says that we should not mix together these two sets of breaking changes. This is one of the things in my opinion we did wrong in v5 - mixing the styling engine change with all the other breaking changes. In addition to this, in v6 we don't plan to migrate the Material UI components to MUI Base just yet anyway. Having all this said, I would vote for copying the existing Material UI components and replacing only the styles associated with he component and the necessary API changes that anyway differ between Material Design 2 and Material You, for example, variant names etc.

[oliviertassinari]

Actually, exploring these tradeoffs a bit more, I come up with the following decision tree:

• If we answer Material UI in 3. I think that we can't create yet another 4th implementation of the Tooltip, nor create a Material UI base set of components. It would defeat the purpose of going with Material UI as the base (simplicity and speed) and it would move us too far from the target depending on MUI Base. So, I think that it would lead us to answer one in 1 and 2. It's effectively Option 1 in the initial proposal.
• If we answer MUI Base in 3. I think that answering two in 1. would allow us to keep track of the migration, to what will eventually be Material UI v6. Ideally, we would answer two in 2. But I agree with you, there is a roadblock with Emotion. I actually have a friend (a Java developer) who recently asked me if he could use Joy UI's accordion with Material UI. I linked him https://mui.com/joy-ui/guides/using-joy-ui-and-material-ui-together/#case-a-joy-ui-in-a-material-ui-project but he gave up, too complex for his problem. So it's close to Option 2 in the initial proposal, but a bit different.

It feels like having broad input from the community on this could be important (spreading this thread more). Do developers want:

• Material You sooner at the cost of some extra bundle size and maybe some MD2 + MD3 confusing APIs. How much % of an increase are we talking about?
• Or do they want an isolated Material You + MUI Base foundation but at the cost of a potential longer migration experience, and slower delivery time?

[mnajdova]

It feels like having broad input from the community on this could be important (spreading this thread more). Do developers want:

Material You sooner at the cost of some extra bundle size and maybe some MD2 + MD3 confusing APIs. How much % of an increase are we talking about?
Or do they want an isolated Material You + MUI Base foundation but at the cost of a potential longer migration experience, and slower delivery time?

Agree on this one, we should definitely ask what the community thinks about this. In terms of how bigger the bundle size will be, it's honestly a bit hard to estimate in general, as not all components will have the same amount of overrides needed.

From #34622 I could get the following analyses:

Button.js ⬆️65%

• master: 17K
• [POC] Add support for Material You (alter the existing components) #34622: 29K

CRA using the theme creator + Button ⬆️6%

• master 215.71 KB
• [POC] Add support for Material You (alter the existing components) #34622: 227.57 KB

[oliviertassinari]

how bigger the bundle size will be

@mnajdova From how I can read #34622 (comment) I have:

• +926 B for the new Button component styles, which is a big one. So with 143 components in Material UI, maybe we are talking about +40 kB gzipped?
• +3.2 kB for the new default MD3 theme. To put in perspective with a createTheme that is 7.0 kB gzipped

[mnajdova]

I want to add on this, that not everything is implemented at this moment (on theme level at least), as I recently found out that some tokens are missing in https://github.com/material-foundation/material-tokens. I am adding them as I need them in the component, but I the biggest chunk of the theme - palette, typescale etc. are already included. I believe we can use these numbers as an orientation tough.

[shahyar]

One important aspect to be aware of here: #30485

Since work has already begun on migrating to CSS variables, and effectively every component will have some work to apply the M3 changes, it doesn't make sense to proceed without it. I'd suggest we actually do both in tandem, and then one could just use the MD3 theme generator to output the CSS vars (tokens) that are needed for the theme.

Though some things would be missing that MUI needs, like spacing vars.

[mnajdova]

MD2 already supports the CSS variables, see https://mui.com/material-ui/getting-started/overview/

The MD3 components will also support both the default ThemeProvider and the CSS variables provider. If we decide to support one, it will be the new CSS vars provider.

[samuelsycamore]

Our Twitter poll results suggest that the majority of the community would prefer to have a separate package for MD3 components. So in that case, it looks like we'd be building the new components on top of MUI Base (as we had planned to do with Material UI in the future).