Rename the packages

[oliviertassinari]

We are making a change to the terminology used in the project to support the long-term direction. The high order bit is that MUI describes the name of the project/company, core prefixes the core components (the simple, design ones).

Current:

• @material-ui/core Material design system
• @material-ui/unstyled The unstyled components
• @material-ui/system The design system CSS utilities
• @material-ui/styled-engine The styled() adapter around emotion
• @material-ui/styled-engine-sc The styled() adapter around styled-components
• @material-ui/icons

Target:

• @mui/material Material design system
• @mui/core The unstyled components
• @mui/joy The second design system, code name Joy.
• @mui/system The design system CSS utilities
• @mui/styled-engine The styled() adapter around emotion
• @mui/styled-engine-sc The styled() adapter around styled-components
• @mui/icons-material

This is the result of a longer discussion that happened in https://www.notion.so/mui-org/Rearranging-the-packages-2f700caf8b5e48559fe86ebb648ed91a.
See mui/mui-x#2313 for the counterparts on MUI X.

Why each change?

1. MUI over Material-UI

• A large part of the community is confusing Material-UI with Material Design, or even Google, MUI distinguishes ourselves. One recent example is: https://retool.com/blog/react-component-libraries/

Developed by Google in 2014, Material-UI is a general-purpose customizable component library to build React applications.

• @mui is shorter to write, read, and pronounce. I have seen a growing number of instances where community members shorten us to MUI, because simpler.
• The core components, while mainly currently providing a Material Design UI are meant to be heavily customizable. It has been one of our main focuses in v5 compared to v4. The change acknowledges it.
• This change laid the groundwork for what's coming next. We have a growing set of unstyled components, a second design system, and a low-code builder coming.

2. The core prefix

Pros

• The flagship product is the core components, coming in different flavors: multiple themes (light/dark), multiple design systems: Material, Joy and without styles, hooks. Sharing the same prefix between them signals that they are meant to implement the same component scope, to be almost interchangeable.

Cons

• It's more to read, and write. If size is the main concern, we could use "md" over "material". For instance, it's used by Mdbootstrap.

  • @material-ui/core is 17 chars
  • @mui/core-material is 18 chars
  • @mui/material is 13 chars
  • @mui/md is 7 chars
  • @mui/core-md is 12 chars

3. The unstyled components

We have been hesitating between 4 different names for these components:

• "unstyled" to emphasize on how they are different from the current mostly used components
• "headless" to emphasize on the hooks that are available
• "base" to emphasize on the foundational nature of the package, to resonate with its primary use case.
• "" nothing, to emphasize on how joy and material are built on top of it.

We have picked "base", so far.

The execution steps

• Keep the change silent until the community has a migration story, it would be only frustrating otherwise
• Release v5.0.0-rc.0 with the new package names. It reproduces the strategy we used from material-ui v0 to @material-ui/core v1. It's also the strategy used by Chakra between v0 and v1.
  We have considered doing it sooner, between two v5 beta, but it would make it harder for MUI X to support v4 with v5.
  If we really want to do it sooner, it's an option.
• Deprecate the last v5 beta releases with a link that expands on the new names of the packages. https://www.npmjs.com/package/@material-ui/core/v/5.0.0-beta.5

• Update the git folder structure to reflect the new names
• Add a section in the v5 release blog post about the change of names, explaining the story behind it and what comes next.

cc @mui-org/core

[eps1lon]

@mui/core-base this sounds redundant. Why not just

-@material-ui/core-material
+@mui/material
-@mui/core-base
+@mui/core 
-@mui/core-xxx
+@mui/xxx

Also gets rid of potential confusion around "unstyled" which will never be actually unstyled.

[oliviertassinari]

@mui/core-base this sounds redundant.

@eps1lon The alternative was @mui/core-unstyled. Michal, Marija, Danilo were in favor of using "base".

@mui/material

Interesting proposal. It similar to the exisiting @angular/material approach. I see two aspects to consider:

• How does it fit if we add a new product/project under the @mui org? For instance a low-code UI builder @mui/studio-cli, @mui/studio-pro.
• Would it be clear enough that only the core components are in this package?

[eps1lon]

How does it fit if we add a new product/project under the @mui org? For instance a low-code UI builder @mui/studio-cli, @mui/studio-pro.

Do you think it does not fit? If so: why?

The alternative was @mui/core-unstyled. Michal, Marija, Danilo where in favor of using "base".

core-unstyled would be just as redundant.

[oliviertassinari]

Do you think it does not fit? If so: why?

I imagine that it could be confused by the community in two cases when they see @mui/material

• they might expect it to be the material design theme of the low-code solutions, nop, that would be @mui/studio/material or @mui/studio-material
• or they might expect the package to include all the components, advanced included, nop, that would likely be @mui/x-data-grid/material or @mui/x-data-grid-material.

I'm not saying it's a deal-breaker, only that it's part of the tradeoff. I would personally vote to be verbose to minimize any possible confusions.

One change that resonates with me is

-@mui/core-base
+@mui/core

I prefer @mui/core-unstyled, but @mui/core seems better than @mui/core-base because "core" and "base" are synonyms?

[michaldudak]

One issue with @mui/core is that it's too similar to the current @material-ui/core and people may be confused it's a totally different package. Other than that, I'm OK with it.

Assuming we go with @mui/core, how do you think we should name the components in this package? [Component]Core feels a bit weird to me.

[oliviertassinari]

@michaldudak Great points.

Maybe another concern to consider is: what will developers say to their peers, e.g. on Twitter to mention they use the base components? "I'm using MUI Base"?

[eps1lon]

Maybe another concern to consider is: what will developers say to their peers, e.g. on Twitter to mention they use the base components? "I'm using MUI Base"?

What is the concern here? You're now arguing against your proposal.

they might expect it to be the material design theme of the low-code solutions, nop, that would be @mui/studio/material or @mui/studio-material

I don't follow this. I firmly belive you're making this up. These are literally different names.

[oliviertassinari]

What is the concern here? You're now arguing against your proposal.

I'm exploring the merit of the proposal. I don't think that it matter who it comes from. If we want to deliver a new product that resonates with a different audience, we need a name that can be identified. If we think that it's clear enough, then it is all good.

Danilo has used a different framing, pushing for MUI Core for being the main product, with material design, and the unstyled components features. In which framing, how clearly can developers identify which feature they use is less relevant.

Does it make sense?

I don't follow this. I firmly believe you're making this up. These are literally different names.

We have opened two positions to hire people to work on MUI Studio. I have no idea how we will handle the theming part of it. I'm making these names up. I have used this to argue that core as prefix segments more clearly the different products, which we might or not leverage as we grow with more packages.

[danilo-leal]

Danilo has used a different framing, pushing for MUI Core for being the main product, with material design, and the unstyled components features. In which framing, how clearly can developers identify which feature they use is less relevant.

The story I'm trying to tell is that the MUI company has two main flagship products if you will: a set of Core and Advanced components. Other products (templates, design kits, low code) would all be built leveraging one or both of these sets. Both of them could be available with Material Design, the 2nd DS, and/or unstyled. Using the prefix also helps to create a clear boundary for the business model around each of them: Core components are open source maintained while Advanced (x) are open-core. The new website is planned to have a page regarding the Core and Advanced components, trying to explain what they are and how they differ from one another.

Not saying that /material or /joy wouldn't work. But as we're trying to separate the two sets, having the prefix helps me quickly figure out what I'm getting out of the package, which is something I'd be in some doubt by only /material or /joy.

The same for only using /core... It's definitely prettier, shorter. But I'm not sure what a package with only /core would have (well, I guess you could say the same for /core-base though. So might as well take that into account 😅). And there's also the confusion around today's reality (@material-ui/core) and the upcoming unstyled version. But if we'd have a /core + a /core-material it's not hard to guess that the lonely Core is without styles?! Well, even then, I'd personally prefer having the base there so we can reference each thing clearly:

• Core components: a set of foundational components to build UIs.
• • Core Base: core components unstyled.
• • Core Material/Joy: core components with A/B design system.

Does it makes sense?

[eashish93]

What about this ?

@mui/theme/material
@mui/theme/xxx
@mui/system
@mui/pro/datagrid
@mui/studio/cli
@mui/studio/pro

[siriwatknp]

In my opinion, I don't think there will be a developer look at the package name first and try to guest what's inside. I believe that they all start by copying the package name in getting started section. So I think the shorter name, the better. Even though someone is confused about what's is @mui/core or @mui/material, they will google it and land on our documentation.

So I think @mui/material is better than @mui/core-material

@oliviertassinari @danilo-leal Do we need to also consider the new icon packages now? because we might have 2 in the future (or maybe not).

• @mui/icons-material
• @mui/icons-joy

[oliviertassinari]

I have updated the milestone to reflect the previous plan we had on Notion: https://www.notion.so/mui-org/Rollout-strategy-5167e83974e042d7b07ece884e1c3b47, the one we started to organize for. This was meant for v5. e.g. MUI X will include it in v5-beta.0. It's how we started to organize the priorities 11 days ago. I have updated a bit the wording where the temporality was confusing. cc @danilo-leal to make sure I didn't alter the intent.

Regarding going forward, in #27803 we talk about either this should move this effort to v6 or keep it in v5. It remembers me of a previous discussion around moving the full unstyled effort off v5, to keep v5 manageable. Here, I would argue that Material-UI -> MUI is 1/10 the effort, with 1/2 already done. More details on what's left in: #27825

I have also updated the issue's description to be more detailed. This issue no longer only about the what but also covers the why and how. This is meant to bring transparency, to move information that is privately available in Notion to GitHub.

[oliviertassinari]

@siriwatknp I propose we have a vote, let's see what resonates the most. Better to be sure before we make a change that is hard to revert:

• 🚀

@mui/core-material Material design system
@mui/core-base The unstyled components
@mui/core-joy The second design system, code name Joy.
@mui/system The design system CSS utilities
@mui/styled-engine The styled() adapter around emotion
@mui/styled-engine-sc The styled() adapter around styled-components
@mui/icons-material

• 🎉

@mui/material Material design system
@mui/core The unstyled components
@mui/joy The second design system, code name Joy.
@mui/system The design system CSS utilities
@mui/styled-engine The styled() adapter around emotion
@mui/styled-engine-sc The styled() adapter around styled-components
@mui/icons-material

• 👀

@mui/core-md Material design system
@mui/core-base The unstyled components
@mui/core-joy The second design system, code name Joy.
@mui/system The design system CSS utilities
@mui/styled-engine The styled() adapter around emotion
@mui/styled-engine-sc The styled() adapter around styled-components
@mui/icons-material

[mbrookes]

The styled() adapter

So, @mui/styled-adapter?

[m4theushw]

The styled() adapter

So, @mui/styled-adapter?

Should we mention that it's around emotion?

To me, @mui/styled-engine-sc sounds like an extension of @mui/styled-engine. Also, I wouldn't see a problem if we expanded the styled-components abbreviation to be more meaningful.

This is what I had in mind:

-@mui/styled-engine
-@mui/styled-engine-sc
+@mui/emotion-adapter
+@mui/styled-components-adapter

[eps1lon]

@m4theushw The idea is that the emotion adapter is the default one. That's why it doesn't have a suffix.

[oliviertassinari]

It looks like we have a more popular option on #27666 (comment):

@mui/material Material design system
@mui/core The unstyled components
@mui/joy The second design system, code name Joy.
@mui/system The design system CSS utilities
@mui/styled-engine The styled() adapter around emotion
@mui/styled-engine-sc The styled() adapter around styled-components
@mui/icons-material

Should we update the "target"? For the new core, I guess we can suffix the unstyled components exported with "Base"?

@m4theushw In the topic of the styled engine/adapters, there is a potential third candidate that optimizes for bundle size: #27776.

[oliviertassinari]

I have updated the "target". Also, the next release of MUI X, next week, will be with the following package names:

• @mui/x-data-grid DataGrid
• @mui/x-data-grid-pro DataGridPro

mui/mui-x#2434

[michaldudak]

I guess we can suffix the unstyled components exported with "Base"

Makes sense (and has the advantage of being shorter than "Unstyled"). The only issue is that it'll clash with the existing ButtonBase and SwitchBase. We are going to ultimately get rid of them, but for the time being, we can rename these two unstyled components when reexporting from Material (or do not reexport at all).

For Material/Joy components we won't append anything to component names, right? (so there will be Button, not ButtonMaterial)

[siriwatknp]

For Material/Joy components we won't append anything to component names, right? (so there will be Button, not ButtonMaterial)

Yes, please. At least, I don't see a reason to prepend design system name to component.

[oliviertassinari]

I have added a warning on the latest v5 releases, e.g. https://www.npmjs.com/package/@material-ui/core/v/5.0.0-beta.5.

Regarding the last step, should it be to rename the git folders?

/packages/material-ui-codemod/ -> /packages/mui-codemod/
/packages/material-ui-docs/ -> /packages/mui-docs/
/packages/material-ui-envinfo/ -> /packages/mui-envinfo/
/packages/material-ui-icons/ -> /packages/mui-icons-material/
/packages/material-ui-lab/ -> /packages/mui-lab/
/packages/material-ui-private-theming/ -> /packages/mui-private-theming/
/packages/material-ui-styled-engine-sc/ -> /packages/mui-styled-engine-sc/
/packages/material-ui-styled-engine/ -> /packages/mui-styled-engine/
/packages/material-ui-styles/ -> /packages/mui-styles/
/packages/material-ui-system/ -> /packages/mui-system/
/packages/material-ui-types/ -> /packages/mui-types/
/packages/material-ui-unstyled/ -> /packages/mui-core/
/packages/material-ui-utils/ -> /packages/mui-utils/
/packages/material-ui/ -> /packages/mui-material/

[mnajdova]

This was resolved by #28049 & #28185. I am closing it.