[RFC] Second design system and theme structure

[siriwatknp]

Introduction

We've mentioned in the v5 release blog post, a previous GitHub discussion, and on some issues here and there, that we were planning to develop a second design system. Instead of being a second theme of @mui/material, we concluded that it should rather be an actual design system, guided by a specific design language. One of the main benefits of thinking of it as a design system is that it can be a stand-alone product, with different default values, and therefore in its own package. Our main purpose with this is to expand the MUI audience – developers that appreciate the level of quality the library delivers but are tired of Material Design. We'll also use this opportunity to experiment with improvements and ideas that are a bit too risky/heavy to initially do on the @mui/material package. We're definitely focusing on having a great visual design out of the box plus powerful customizability features so you can make it our own.

It will be built on top of our developing unstyled components - which will also be very convenient since it's an opportunity to stress-test both packages at the same time. We hope to create a feedback loop that increases the speed of evolution of both. We're aiming at having a similar set of components compared to the @mui/material (though not all available on the first release).

We've been using a codename for it, which is Joy (it's one option for its definitive name, let us know your thoughts on it too!). This is the first look at the initial work on its theme structure. But before diving into it, let me state what the objectives and non-objectives of this write-up are, so that we can have a more assertive discussion and focus on what we have so far:

Objectives

This discussion is meant mainly to get early feedback on the default theme structure and some ideas about the implementation. We'll also share thoughts (and early prototypes) about how to customize and extend it.

Non-objectives

We do not expect to discuss the presented content in detail, such as an API specification, for example. There's also no definition around the design direction as of now, so we won't be presenting any values for the properties of the theme nor talking about visual design as a whole.

---

If you are ready, let's dive in.

Rethinking the Theme

Customizability will be a huge part of Joy. Even though we're focusing on having sensible and opinionated defaults that act as a great starting point for your projects, we'll still optimize it for extensive customizability. To do so, we have been studying ways to add improvements to the current theming approach in @mui/material v5. We'll first introduce them on Joy to get early feedback and iterate until they are solid enough, so later on we can bring them back to the @mui/material as well. Among them are:

1. Theme & Color schemes definition

Sometimes, we use the word theme referring to the whole design language (specific values for each styling property) of an application (Material Design, iOS, Microsoft's Fluent, etc). Other times, we use theme referring only to the color scheme currently selected (light or dark). This can get confusing especially if you have an API where, on your ThemeProvider component, you pass to the theme prop a lightTheme or darkTheme value. Most often, this means that only colors are changing, all other properties remain intact.

To improve on that, we're thinking of separating both concepts as it seems way more intuitive when dealing with colors. For example, you could have a theme called MyCompanyTheme which is comprised of specific values for each styling property. This theme can have many color schemes: light, dark, true dark, comfort, aqua, you name it. You'd define the different sets of palettes at the beginning of the theme. We'll talk about what the code would look like in the Unlimited color schemes section.

This picture above illustrates the terms design system, theme, and colorSchemes. This does not mean that Joy will provide a Material or iOS Theme by default.

2. Adopting CSS variables

CSS variables will play an important role in Joy. This allows for building APIs that provide a much better customization experience and with a high percentage of browsers supporting it already, we are confident to bring it in. Some highlights of things we can do with it:

2.1. Perfect dark mode

The flashy dark mode problem is one we've been aware of for some time now. With CSS variables, we can create a stylesheet that contains all of the color schemes at build time and then pick the right color when a user enter the website. The picture below shows the high-level flow of how perfect dark mode can be achieved.

To understand this in more detail, check the dedicated RFC.

2.2. Component customization via variables

As we've said, Joy components will be built on top of the unstyled ones. To visualize how CSS variables actually provide a better customization experience, let's use one of the unstyled components already available: the switch. A switch basically has two parts: the track and the thumb.

Let's say we want to do something basic such as reducing the size of the thumb to be a little smaller. On @mui/material v5 this is how we'd normally do that:

<Switch
  sx={{
    '& .MuiSwitch-thumb': {
      size: '12px',
      height: '12px',
    }
  }}
/>

Unfortunately, the result is not really that good. Only changing the thumb size actually messes up its positioning and makes the overall component disproportionate. To fix that, we'd also have to change the track width and fix the position. But with CSS variables, we can compose the styling of each part of the component so they actually change accordingly - or synchronized, if you will. We couldn't do that before using JavaScript. Here's a proof of concept using CSS variables to compose the Switch component. You can play around with the properties values in the panel. You'll see that as you change one, the others follow.

Screen.Recording.2564-10-08.at.15.26.29.mov

We also used this POC to experiment with having multiple color schemes. But we're going to dive more into this below. If you use this Switch and wanted to customize it, you could do it by just changing the values for some of its variables (basically, in code, what is happening on the proof of concept GUI):

<Switch
  sx={{
    --switch-track-width: '106px',
    --switch-track-height: '16px',
    --switch-track-radius: '26px',
    --switch-thumb-size: '51px',
    --switch-thumb-offset: '-18px',
  }}
/>

2.3. Adaptive component

A very common example is Icon. This component can be placed inside other components such as Button, Typography, ListItem, Menu, etc. To make it look great inside these components, the parent component needs to control the styles of the icon. @mui/material is using CSS specificity to do that. Here is an example of the Material Button:

...(ownerState.size === 'medium' && {
  '& > *:nth-of-type(1)': {
    fontSize: 20,
  },
}),

// by default the code below renders a good looking button.
<Button startIcon={<SomeIcon />}>Button</Button>

This isn't intuitive when it comes to customization. Without looking at the code, you would expect this to work:

<Button startIcon={<SomeIcon size="large" />}>Button</Button> // with props
<Button startIcon={<SomeIcon sx={{ fontSize: '24px' }} />}>Button</Button> // with custom size

Unfortunately, it doesn't because the size="large" or sx props can't beat the CSS specificity coming from the Button. To achieve it, you have to increase the specificity higher than the Button with this nasty code:

<Button
  startIcon={<SomeIcon />} // or use inline style 😢
  sx={{ 
    [`& .MuiButton-startIcon > *:nth-of-type(1)`]: {
      fontSize: "30px"
    }
  }}
>Button</Button>

This customization issue applies to other components as well, not just Icon.

CSS variables are very useful to create a component that can adapt to the parent and also allow customization from developer without creating nested specificity. Take the Icon as an example, Joy icons can looks like this:

const Icon = styled('svg')({
  width: 'var(--svg-size, 24px)',
  height: 'var(--svg-size, 24px)',
})

By default, Icon's size will be 24px because there is no variable --svg-size declared at the upper scope. Now, the Button can control the icon size by declaring the variable.

const Button = styled('button')(({ size }) => ({
  '--svg-size': '20px',
	...size === 'large' && {
    '--svg-size': '24px',
  }
}))

// both buttons looks great by default
<Button startIcon={<SomeIcon />}>Button</Button>
<Button startIcon={<SomeIcon />} size="large">Button</Button>

The customization works without CSS specificity 🎉 because the icon will use the nearest variable which is the one on the icon (30px)

<Button startIcon={<SomeIcon sx={{ '--svg-icon': '30px' />}>Button</Button>

Here is a POC with more parent components using this approach.

2.4. Improved debugging experience

The CSS variables help developers and also designers to understand the token structure of a given element without even touching the codebase. It's way easier to read and to play around with values to reach the desired design.

Screen.Recording.2564-10-08.at.13.15.06.mov

2.5. Side benefits

From the POC, we found that CSS variables provide some side benefits that we get for free!

• Slight performance improvement

  In the current approach used by @mui/material, toggling between modes causes the whole application to re-render and recalculate the styles (className change) so that they reflect the change on the screen. This process could take around 100-300ms but it ultimately depends on the number of components on the page. With the use of CSS variables, the processing time drops significantly because the className doesn't regenerate* (the component still re-renders though). For more details about this topic, check out this blog post from Kent C Dodds.

  Here is a quick benchmark between @mui/material v5 and the POC version. We profiled the rendering time versus x number of Switches when toggling between light & dark mode.

  	10 switches	100 switches	500 switches	1000 switches
  @mui/material	~25ms	~75ms	~360ms	~600ms
  POC (CSS Variables)	~8ms	~11ms	~37ms	~60ms

  Note: This benchmark is done on macOS Big Sur, MacBook Pro (13-inch, M1, 2020) Memory 16 GB.

  The result shows that the CSS variables approach is significantly more performant than the current implementation in @mui/material. Here are the links that you can compare by yourself.

  • @mui/material Switch
  • CSS Variables Switch

• Variable Reference

  It is quite common to want to refer to other variables when defining a theme. Take this as example in @mui/material v5. The button color should use the palette.primary.main. To make this value reusable, we'd need to abstract the primary.main color to a variable:

  const primary = {
    main: '#ff5252',
  }
  <ThemeProvider
    theme={{
      palette: {
        primary,
      },
      components: {
        MuiButton: {
          styleOverrides: {
            color: primary.main,
          }
        }
      }
    }}
  />

  But with CSS variables, you can just refer to a variable via var(--_{variable-name}_). This is the native syntax for using another variable in CSS:

  <CssVarsProvider
    theme={{
      colorSchemes: {
        light: {
          palette:{
            primary: {
              main: '#ff5252',
            },
          }
        },
        dark: {...}
      },
      shadow: {
        md: '0 0 12px 0 rgba(0,0,0,0.12)',
      },
      components: {
        MuiButton: {
          styleOverrides: {
            color: 'var(--palette-primary-main)',
            border: '1px solid var(--palette-primary-main)',
            boxShadow: 'var(--shadow-md)',
          }
        }
      }
    }}
  />

• Works well with other styling methods
  There is no limit If you need to use other methods for styling. For example, you can use a pure CSS stylesheet and refer to the variables generated by MUI:

  // custom-stylesheet.css
  .custom-component {
    color: --joy-palette-brand-500;
  }

3. The default theme structure

When looking for opportunities we could bring to the Joy theme structure, in comparison to the Material default, we noticed that it could benefit from the use of more low-level tokens, as this enforces even more consistency in the components while providing a set of opinionated values. "Low-level" implies that we'll have different layers of abstraction for given properties of the theme. A lower level token would be descriptive, holding the hard value of a given property and a high level would be semantic, holding indication info for how to use it. There will be instances where it's good to have it and others were not necessarily. We'll dive into the examples but keep in mind that this is all regarding the default structure - what comes out of the box for you. If these don't make sense to you, you'll be able to change them to fit whatever structure you wish.

3.1. Colors

Colors are probably the most illustrative example of the separation between descriptive and semantic tokens. To start, we'd have colors declared descriptively in a 50 to 900 value range. For example:

export const grey = {
    50: '',
    // ...
    900: '',
};

export const blue = {
    50: '',
    // ...
    900: '',
};

export const red = {
    50: '',
    // ...
    900: '',
};

On the semantic side of things, we'd have the following structure:

  palette: {
    brand: 'var(--palette-blue-500)',
    highlight: 'var(--palette-gray-400)',,
    danger: 'var(--palette-red-500)',,
    warning: ...,
    success: ...,
    text: {
      headings: '',
      mainContent: '',
      blockquote: '',
    },
    bgBrand: {
      subtle: 'var(--palette-blue-200)',
      plain: 'var(--palette-brand)',
      strong: 'var(--palette-blue-700)',
    },
    bgNeutral: {
      suble: ...,
      plain: ...,
      strong: ...,
    },
    bgHighlight: {
      suble: ...,
      plain: ...,
      strong: ...,
    },
    bgDanger: {
      suble: ...,
      plain: ...,
      strong: ...,
    }
  }

Instead of having primary and secondary, which can cause confusion as to where to use which, we'd have instead only a brand color, the one that is the defining color for your product and company. Also, instead of having a light, main and dark value for each color, we'd have only one that defines each semantic variant:

• Highlight: meant for components like info callouts.
• Danger: we changed from error to danger because it sounds like a more broad use case word to use. For example, if you want your button to be red when in a deleting account use case, it's weird to use the "error" color, it's not an error at all. It's just a "dangerous" activity, one to be very aware of - probably with irreversible consequences.
• Warning and success weren't changed.
• Text: instead of having primary and secondary text color variants, we'd have variants for a specific type of text like heading, main content (body page paragraphs), blockquotes, etc.
• Background: we'd have a three intensity scale of background for every semantic variant.

3.2. Typography

Similar to colors, the idea is to have every low-level property defined in a descriptive way and then use them for semantic variations. The descriptive values structure:

  htmlFontSize: 16,
  fontFamily: {
    sans: '',
    mono: '',
  },
  fontSize: { // example values
    xs: pxToRem(12), // 0.75rem
    sm: pxToRem(14), // 0.875rem
    md: pxToRem(16), // 1rem
    lg: pxToRem(20), // 1.25rem
    xl: pxToRem(24), // 1.5rem
    xl2: pxToRem(30), // 1.875rem
    xl3: pxToRem(36), // 2.25rem
    xl4: pxToRem(42), // 2.625rem
    xl5: pxToRem(50), // 3.125rem
    xl6: pxToRem(62), // 3.875rem
  },
  fontWeight: {
    regular: 500,
    medium: 600,
    bold: 700,
  },
  lineHeight: {
    normal: 1.5,
    sm: 1,
    ...
    lg: 3,
  },

And the semantic value structure, which directly consumes the descriptive tokens:

  h1: {
    fontFamily: fontFamily.sans,
    fontWeight: fontWeight.bold,
    fontSize: fontSize.xl6,
    color: palette.text.headings,
    lineHeight: lineHeight.normal,
  },

You'll notice that we're also using an xs to xl6 scale for font sizes. This is mainly to give a broad range of choices but constrained into a sufficient set of sizes that match one another. We'd also have a different (compared to the Material Design) set of semantic variants. There'd be one to hold each font size variant. We're still discussing these specifically but the current list is this:

  h1...h5
  subtitle
  body
  caption
  detail
  overline

3.3. Shadow

We're planning on having only 4 levels of shadow, ranging from extra small to large. In addition, since shadow can have multiple layers, we plan to add the ring property for more convenient customization. The ring property acts as an inner shadow to make an element stand out from the rest. We are still working on the conclusion about making it visible/invisible in the default theme.

shadow: {
	none: 'none',
	ring: '0 0 0 0 rgba(0,0,0,0)', // this mean the ring is invisible
	xs: 'var(--shadows-ring), 0 1px 2px 0 rgba(0, 0, 0, 0.05)',
	sm: 'var(--shadows-ring), 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06)',
	md: 'var(--shadows-ring), 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)',
	lg: 'var(--shadows-ring), 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05)',
}

3.4. Shape properties

We're also planning on tokenizing properties that are usually applied to shapes (your everyday div or <Box>) to enforce consistency. The idea is to have extra-small to extra-large scale for them:

borderRadius: {
  xs: '',
  sm: '',
  md: '',
  lg: '',
  xl: ''
},

3.5. Other properties

There were some properties that didn't need to be changed from Material Design, we believe them to be good enough already:

  breakpoints: {
    values: {
      xs: 0,
      sm: 600,
      md: 900,
      lg: 1200,
      xl: 1536
    }
  },
  direction: 'ltr',
  spacing: 'f n(4)',
  transition: {
    easing: {
      easeInOut,
      easeOut,
      easeIn,
      sharp,
    },
    duration: {
      shorter: '',
      short: '',
      normal: '',
      long: 375,
    },
  },

4. Unlimited color schemes

Light and dark will be built-in color schemes but really there won't be any limitation whatsoever to adding more custom ones. On the Switch demo mentioned above, there's already a proof of concept of this working.

// NOT available on npm yet, just for demonstration purposes.
import { CssVarsProvider, useColorScheme } from '@mui/joy/styles';

declare module "@mui/joy/styles" {
  interface JoyColorSchemesOverrides {
    // extend two more color schemes to your application
    comfort: true,
    trueDark: true,
  }
}

<CssVarsProvider
  theme={{
    colorSchemes: { // light & dark are built-in
      comfort: {
        palette: {
          brand: '#888',
        }
      },
      trueDark: {
        palette: {
          brand: '#000',
        }
      }
    }
  }}
/>
  {children}
</CssVarsProvider>

// somewhere in your application
const { allColorSchemes } = useColorScheme();

// You can get all color schemes defined in the theme via this variable.
console.log(allColorSchemes); // ["light", "dark", "comfort", "trueDark"]

Next steps

We hope that with this write-up we can gather as much feedback as we can to refine the overall idea and to start development with a clearer design in mind. As the development of the unstyled component progresses (you can help out with that!), we'll be getting them into Joy. Meanwhile, we're also evolving with designs explorations.

Closed feedback group

For this project, we're considering forming a closed group of contributors willing to test Joy and provide quick feedback. We're aiming to have the first iteration, with the first set of components, available in this quarter, so the folks in it would be of immense help to achieve this deadline. There's a comment in this discussion where you can leave a "hey! I'm interested in being a part of the feedback group" message as a thread. Let us know ways to contact you as well. We appreciate anyone that is available to help! :)

Other discussion about Joy

• Joy color system

[NMinhNguyen]

But with CSS variables, we can compose the styling of each part of the component so they actually change accordingly - or synchronized, if you will. We couldn't do that before using JavaScript.

Could you please elaborate on what wasn't possible before using JavaScript? Shouldn't you be able to accept a size prop and derive whatever other values you need from it?

[siriwatknp]

My point is about the customization experience that we can bring to developers which is not possible before. The Switch implementation without CSS variables could look something like this:

.track {
  width: 64px;
  height: 24px;
  border-radius: 24px;
};
.thumb {
  width: 20px;
  height: 20px;
  left: 4px;
  &.checked {
    left: 36px;
  }
}

As you can see, all of the variables are hard-coded which is not a good experience when you want to customize it. Let's say you want to increase the width of the track to 80px. Ideally, you would expect everything to just work but it is not. You have to do the math and override the left property in the checked state so that the thumb is on the edge of the track.

// example of overrides
.track {
  width: 80px;
}
.thumb.checked {
  left: 52px; // you have to calculate this value by yourself
}

Using javascript to observe the width and automatically update the left for you is totally KO.

Note: In the real world, customization is more complex than this. Check out this customization example and you will see the amount of code that you need to override.

CSS Variables is a game-changer for us. We can use it to refer to other variables so that it is dynamically updated itself. Here is the Switch implementation with CSS variables.

.track {
    height: var(--switch-track-height);
    width: var(--switch-track-width);
}
.thumb {
  width: var(--switch-thumb-width);
  height: var(--switch-thumb-size);
  left: calc(50% - var(--switch-track-width) / 2 + var(--switch-thumb-width) / 2 + var(--switch-thumb-offset));
  &.active {
    left: calc(50% + var(--switch-track-width) / 2 - var(--switch-thumb-width) / 2 - var(--switch-thumb-offset));
  }
}

With this, you never have to think about the left property again because it will make the thumb always stay at the edge of the track. But if you need to adjust it, there is no limit to that. Check out full demo and try to change width, height, ...etc (you will see that the component is resilient).

In summary, CSS variables give us (MUI) as a UI library to design necessary variables for each component so that you can customize them the way you intended to. I hope this gives you a better idea about it.

[NMinhNguyen]

I hope this gives you a better idea about it.

Absolutely, thanks for the detailed write-up, it makes perfect sense. Excited for this new approach :)

[oliviertassinari]

2.3. Adaptive component

I personally don't resonate with the solution or the change proposed. I mean, I don't see how it solve the root problem (forcing developers to learn something in this context):

1. From what I understand, child components would need to have a CSS variable for every single CSS property that a parent component might want to adapt. This is extra complexity.
2. Developers would still need to learn when to use a CSS variable and not use the regular customization API. This seems to be no different to have to learn when to increase specificity. If the argument is that the customization happens on the element itself, then, we can teach how to do it:

<Button startIcon={<SomeIcon sx={{ '&&': { fontSize: '24px' } }} />}>Button</Button>

I think that using the React context, with an inversion of who owns the style (the icon, not the button) would solve the root pain. But in some cases, it might be overkill or seen as a leaky abstraction.

[siriwatknp]

@oliviertassinari

I don't see how it solve the root problem

In my opinion, the root problem is "it is not predictable" (Ref issue). Take this as an example:

// current Button from `@mui/material`
<Button startIcon={<AddIcon size="small" />} /> // It should work, but it isn't
<Button startIcon={<AddIcon sx={{ fontSize: 20 }} />} /> // It should work, but it isn't

startIcon is a slot, therefore you expect to give it a prop to adjust the size (either size or sx).

using CSS variable, it make the customization predictable without opening the dev tool.

<Button startIcon={<AddIcon size="small" />} /> // works
<Button startIcon={<AddIcon sx={{ fontSize: 20 }} />} /> // works

Here is the POC

---

child components would need to have a CSS variable for every single CSS property that a parent component might want to adapt

Yes. I don't see that it is a bad idea. In Icon, this is what it looks like:

const Icon = style('svg')(() => ({
  margin: "var(--svg-margin)",
  width: "var(--svg-size, 24px)", // default as 24px
  height: "var(--svg-size, 24px)", // default as 24px
  fill: "var(--svg-color, #121212)", // default as #121212
}))

There is no difference compare to not using CSS variables (from the Icon perspective).

---

1. This is extra complexity

How is it become an extra complexity? comparing implementation between

• nesting class

  const Button = styled('button')(({ theme }) => ({
    '& > *:nth-of-type(1)': {
      fontSize: 18,
    },
  }))

• css vars

  const Button = styled('button')(({ theme }) => ({
    '--svg-size': 18, // it can be an object like classes if you think this is too hard-coded
  }))

  Isn't it simpler?

---

2. Developers would still need to learn when to use a CSS variable and not use the regular customization API

No, they don't need to learn and they don't need to know that it is using CSS variable behind the scene. Here is one example:

<Button startIcon={<AddIcon size="small" />} />
<Button startIcon={<AddIcon sx={{ fontSize: 20 }} />} />

This works on their screen and they don't need to know that it is using CSS variable.

---

I think that using the React context, with an inversion of who owns the style (the icon, not the button) would solve the root pain. But in some cases, it might be overkill or seen as a leaky abstraction.

Definitely not a good idea. This is the customization limitation that was not possible without CSS variables. Now we have the tool, we should leverage it without the need of JS.

Another point is that developer can create their own custom components that work with MUI component pretty easy because it is just plain css.

[chloepoulterdesign]

I'm really concerned by this.
Evaluating a new design system shouldn't start with the implementation; it needs to start with the values, impression and emotions core to the experience that the user will feel; the design language.
Your implementation ideas sound fantastic and would tempt my dev team to no end. However, I can't see, understand or evaluate this potential new design system because you've not prototyped what it would produce.

We're all here to make great user experiences. We can't do that without devs or designers - so great job working to make the lives of your customers better - but please don't forget that our customers are the end goal here; are the true consumers of MUI, and how we devs and designers will ultimately choose which library to use.
As much as MUI provides us an easy library of components, Material Design offers us the fundamental principles and values (Design language) that make those components work - MUI will need to develop a design language for themselves (that's as sophisticated as Material, or Carbon, or similar) before any designer will be able to recommend this system.

[danilo-leal]

Hey @chloepoulterdesign, thanks for leaving your input. You're completely right and I agree with you! We'll soon release a page that hints a bit at the design direction we're taking for this DS while also showcasing some of the things made possible by this implementation proposal here. With this post, we're presenting the technical features we're about to bring to this new DS, which we'll also, later on, bring to the Material package as well because we believe it improves overall DX (like CSS variables, for instance).

In the meantime, I've been working in the design direction in the background which will be progressively defined as we release small alpha versions of this and get feedback from the community. So, we have a path there until the first stable release of it. But, keep in mind that although we definitely want an out-of-the-box great design direction, this DS will be all about customizability, it could be seen as a starting point. So, if you happen to work in an org that has its own language defined, you'll be able to print it into it, just as it is already possible to do with the Material package, completely overriding Material Design.

Overall, don't be concerned :) I hope to hear more from you and have your feedback!

[edazpotato]

This looks really good. I'm glad that you're thinking about how theming would work nice and early, since that's such a big part of what makes MUI awsome. I can't wait to see the post about what the actual design will look like (so exciting!).

One thing I'm curious about is whether or not joy will support using forms of shape other than just roundness. Material claims to support using angled corners, but I've never seen a real app using them. In my opinion, if joy does support other forms of shape it will really stand out among the crowd of design systems which currently don't have too much uniqueness.

I would also love to be included in the feedback group. You can contact me here on github, on twitter (@edazpotato), and on discord (Edaz#5671).

[danilo-leal]

Thanks, @edazpotato for leaving your input! I'll be contacting you very soon :)

[mwskwong]

I'm really looking forward to this new design system. I originally thought it will more like a new theme, but it seems that it is a complete overhaul.

I'm wondering are you planning to move some of the designs (e.g. perfect dark mode, CSS variables) back to @mui/material once you are done with Joy?

[siriwatknp]

I originally thought it will more like a new theme, but it seems that it is a complete overhaul.

A new theme would not help us improve the customization experience for developers. On the other hand, a new design system gives us an opportunity to experiment with new ideas and improvements without impacting the stable @mui/material. For example, we are aiming to combine loading and IconButton that you see in material into a single button component. This should make the component easier to use and reduce some unnecessary duplicates.

// Before
<LoadingButton />
<IconButton><Icon /></IconButton>

// In Joy
<Button loading />
<Button><Icon /></Button>

Here is the sneak peek of the Joy button

move some of the designs (e.g. perfect dark mode, CSS variables) back to @mui/material once you are done with Joy?

Absolutely, once we are confident about any improvements we have done on Joy, we will try to bring them back to @mui/material. One thing that I am pretty sure of is the CSS variables

[mwskwong]

Also, let say I want to migrate from @mui/material to @mui/joy in the future. I guess there will be a codemod for it as well? At least it won't be more challenging than migrating from MUI v4 to v5?

[aaronadamsCA]

Some feedback from an implementation perspective.

Color

Color contrast is a big gap in MUI5 today. For example, there are no precomputed values for primary color variants with minimum WCAG contrast against white and black. As such, it's hard to build safe, performant components that work well with any MUI theme.

Most modern design systems address this either in their descriptive tokens, or in their semantic tokens; I think you might need to pick one approach up front to achieve your stated aims for themes and color schemes.

• MD3 and Carbon guarantee contrast using descriptive tokens. For example, MD3 guarantees you can use white on 0-50, black on 60-100; Carbon makes similar guarantees with different values.
  • This is arguably a lot easier to implement, since you've got a direct relationship between tonal value and luminosity, and therefore contrast.
  • But this is a LOT harder to design. Go pop a nice vibrant orange into the Material Design 3 palette generator, and notice that your primary theme color is now a deep brown—probably not at all what you wanted!
• HIG guarantees contrast using semantic tokens. It offers "default" and "accessible" versions of every system color, and varies them between light and dark modes, too.
  • This allows effective separation of brand color from accessible color; you can have nice bright orange visual elements that suit your brand, alongside deep brown typographic elements that meet WCAG requirements.
  • But it also requires greater thought given to contrast colors. A bright yellow contrasts best with black, whereas a vibrant blue contrasts best with white; assuming each color scheme can only use its own colors, and that runtime contrast calculations are to be avoided, then this probably requires one contrast token for every color token (theme A = black on bright yellow, theme B = white on vibrant blue).

I'm hoping you can find a good general purpose solution that will allow us to build hundreds of components that can work dependably with hundreds of very different themes. It seems like you're on the right track, but I feel like you might need more than an additional bgXxx key with 3 extra values.

Typography

I'd love to see a more modern set of semantic variants.

• In my opinion MD3 was smart to make a clean break from 2014 decisions that left us with overly specific variants like "overline", plus HTML1 leftovers like h1...h6.
• Looking across the board, many other design systems have also dropped h1 through h6 in favor of true semantics like "title" or "heading".
• By comparison the MUI5 variants and API can be confusing; <Typography variant="h3" component="h2" /> to reduce heading size without changing the underlying HTML hierarchy is not a very natural API. I think something like <Typography component="h2" variant="headingMedium" /> (or <Typography component="h5" variant="labelLarge" />) could perhaps be easier to both teach and learn.
  • This would also require changing variantMapping. Variant-to-component mapping is not exactly the most intuitive part of today's API either, but it could probably be made to work fine with this.

And this last part probably goes without saying, but hopefully we can get built-in type sizes, line heights, and gutters that are actually usable out of the box! There's a good reason the MUI website overrides all of the MUI5 typographic defaults, and I'm sure most end users are doing the same.

[stunaz]

hello, please can someone point me to the current documentation of joy?

[danilo-leal]

Hey @stunaz, there still isn't any structured documentation for it. Glad you're interested in it, though!

[siriwatknp]

@stunaz Here is the alpha version! https://mui.com/joy-ui/getting-started/overview/

[eashish93]

Is it possible to get rid of emotion or any css-in-js lib (I prefer tailwind and css modules only).

[oliviertassinari]

@eashish93 See #30660 it's part of the roadmap. We are exploring a very close API to today's but with built-time CSS extraction to remove the runtime. Also, note the existence of https://github.com/unocss/unocss.

[eashish93]

yeah, unocss is also great

[zgover]

Following the release of Joy, are there any plans or discussions around the support of Material 3 design system updates?

[oliviertassinari]

You can follow #29345.

We have also open https://mui.com/careers/react-engineer-core/ to help on this. The number of PRs and Issues we close every month has indicated to us that we are spread too thin between the different products: we are closing fewer issues and PRs on average a month than we were during v4's lifecycle. The new role will help us spin our flywheel: https://mui-org.notion.site/Strategy-6945959c64cc4c7784cbe2770bd9772d#5dd52736ece04a4682fef3da361d05ab.

[vitalijalbu]

Hi, I'm also looking for an ios like theming in MUI, or similar. I like joy but it's not really what I want. Anyone has his own custom UI?

[siriwatknp]

I am working on the iOS theme on top of Joy UI. Will share the progress soon!

[vitalijalbu]

wow really, maybe i can help you.. can you share some preview with me pls? my email: [email protected] thanks

[siriwatknp]

Here is the draft: #34994

Preview: https://deploy-preview-34994--material-ui.netlify.app/joy-ui/getting-started/templates/ios/

[wangyg115]

Is there release planning for Joy UI 5.0.0-stable?

[danilo-leal]

Another way to frame it would be: what is one problem that Joy UI is: 1) not solving for you; 2) is solving but could be better? 😬

[wangyg115]

Datepicker, Snackbar components are often used in my case, are these components included in the stable release? If there is a list of all components in stable version, it would be better.

[danilo-leal]

By the time of stable, I'm not really sure about the Date Picker as that's an MUI X (advanced, open-core) component that currently only has its version built on top of Material UI. It will absolutely come at some point though (including all the other X components, too). @siriwatknp Snackbar is something that sounds doable as we already have the UnstyledSnackbar from Base, right? What do you think?

[oliviertassinari]

I would connect this comment with #36279, and the benefit of having more pages in the docs where developers can quickly grasp what's WIP vs. unstable vs. stable.

[danilo-leal]

That's an excellent idea! @wangyg115 I just created the issue requesting the Snackbar (#36603) feel free to drop your thumbs up there + add any details/specific feature you'd like to see on the component 👍

[mwskwong]

Are there any plans to auto-generate a palette based on a baseline color, similar to how Material generates light and dark based on the main color?

[siriwatknp]

We will provide a tool that generates a palette based on a main color but we will not do it in runtime like Material UI because we don't want JS runtime overhead.

Most of the time, your theme would be set once initially so it makes more sense to be static as much as possible. I am pretty sure that this approach is better in the long run and I see a lot of opportunities that we can do in the future, e.g. a compiler that turn theme into plain CSS file to remove JS overhead (improve TBT score)

Here is an initial version of the tool (palette customizer) #35741

[kriskw1999]

I have read all the manifest and I really like idea behind it. A more flexible and more Joyfully design can be something great, I would really like to contribute to it in any way, let me know if and how can I do it!

[danilo-leal]

Hey @kriskw1999, thanks for the message, we really appreciate it! Feel free to go over the issues list, filter for package: joy, see what we have opened there, and then tag either @siriwatknp or me to further discuss! That's one way you could contribute 😬 The other would be to: install the package on a project of your own, taste it a bit, and create issues yourself for stuff we haven't yet added it! You're totally encouraged to work on them, tool!

[kxseilerjo]

Is this the right place to ask if you have on the agenda making switching from Material-UI towards Joy simple?

[danilo-leal]

Heya @kxseilerjo! It's definitely on our radar. We expect to tackle more design and customization experience-related questions in Material UI v7. We're already prototyping and discussing some things internally, though, so expect us to be able to give a more detailed answer later this quarter. A super smooth migration in both directions, whatever that comes to look like, is totally something we want to provide.

[markedwards]

Can I ask for a little more info regarding the warning about a development pause here: https://mui.com/joy-ui/getting-started/#introduction

We are early in a project and will definitely be using @mui, but we would greatly prefer not to inherit all of the Material Design baggage, and the more neutral design of Joy seems like a great fit.

Which of these is true:

1. Joy is in a generally stable state and considered usable in production, but is not the current focus for new feature work
2. Joy should not be used in production, it is not yet ready
3. neither of the above

Thanks for any guidance!

[danilo-leal]

Hey, @markedwards! I'd say 1 is true—given Joy UI draws a lot from Material UI, there's a robust system in place already, even if it still has the alpha tag on it. And even if it's not our priority at the moment, again because of the shared infrastructure, here and there, we put out bug fixes. I can't say for sure, though, if we'll ever invest efforts to properly turn into stable, and that's because we're actively focused on prototyping a world where, for Material UI v7, choosing different design languages (i.e., Material Design vs. something else like Joy Design) is an incredibly easy toggle, much more than today. Hope that helps with the immediate question & gives a little glimpse of the future vision.

[markedwards]

Thanks for the input @danilo-leal! We haven't found any issues so far, and it does seem like using a lighter weight @mui/material.

Just to probe the point a bit further -- it sort of sounds like Joy might be a dead end. Having not looked much at MUI v7 yet, is the a reasonable path forward from Joy if we chose to continue with it? Would it be better to just adopt MUI v7 early?

[danilo-leal]

I will say, though, that from a visual design standpoint, you can get to the same place using Material UI just by leveraging theming. Check out this demo repo I put together as an illustration of that.

We haven't put out too detailed information about Material UI v7 yet aside from the plan of being very design-focused, unlike v6. I think it's safe to say that whatever there is of Joy UI today will continue to exist, but many of the things we prototyped on it might be ported over to Material UI, as well as providing an alternative design language, by default, instead of just Material Design. All in all, more concrete/practical info coming after the v6 stable release.

[kamavingah]

Hey there!

Some background

Our team has been building a big business web application for several years. Since the frontend library we initially used is no longer maintained and not backed by a company we decided to rebuild all our core components using a new library and revamp our theming configuration. While prototyping using different libraries Joy UI stood out as the one that delivered

• the best developer experience (by far)
• the best look and feel
• the best theming options

so we decided to go with it.

All this happened before you issued the warning about the development pause (https://mui.com/joy-ui/getting-started/#introduction).

Our (very positive) thoughts on Joy UI

As many others already stated we also do not like the look and feel of Material UI out of the box. The current theming options also do not fulfil our requirements. The variety of components and their functionalities on the other hand are perfect for our use case (complex combo boxes, lots of forms, dropdown-menus, dialogs etc.).

Therefore Joy UI ticked all our boxes and more. It really is a breeze to not only use the components it ships with, but also to use them as building blocks to build more complex custom components. We also really enjoy the theming experience. Our app now enables users to create their own themes and implementing this feature was extremely smooth. Furthermore the built-in accessibility features are on point.

It still has some very minor cosmetic bugs here and there (I already reported some of them), these were however never really an issue. In its current form Joy UI is already very stable.

Some things we really (really!) like about Joy UI and currently use and leverage:

• Its (already plentiful) components and their variants
• The functional configurability of the components (their props)
• The style configurability of the components
• The theme configurability (adding custom colors, customizing variants...)
• The modularity of the components (everything can be used as a building block)
• The documentation website (editing/prototyping components directly on the website)
• The look and feel of the default theme
• The TypeScript support
• The built-in accessiblity features

Questions about the development pause

As you can imagine the warning about the development pause was a bit of a shock to us.

• Could you please elaborate a bit more on the answers you gave @markedwards in the previous comment?
• Will Joy UI ever get a stable version?
• If not
  • will Joy UI (its theming abilities and its components) become part of Material UI?
  • will porting from Joy UI to Material UI (its theme AND its components) be easy?
• Can you provide any (realistic) timeframe about when these decisions will be made?

Final remarks

If it would help you in any way, we can happily provide some more information about how we specifically used Joy UI components and why we think it's awesome. We would also be willing to pay for something like Joy UI (for example if you offer it in addition or as part of MUI X). We also gladly continue to provide bug reports and/or contributions if you can ensure that Joy UI (in one form or another) does have a definitive stable future.

It truly is a joy to develop with and its features are already plenty and very stable. Thank you very much for building such an awesome product!

tl;dr

• Joy UI is amazing. 😮
• Shut up and take our money 💰.

[kamavingah]

One addition: besides Joy UI we already use the MUI X Data Grid in its free version and manually apply our Joy UI styles to it. We will very likely purchase the paid version of MUI X and would welcome a Joy UI Data Grid as mentioned in mui/mui-x#11118

[kamavingah]

I very much appreciate all your upvotes and heart emoji reactions :) I know you are busy with other things right now, but could someone maybe chime in and give a quick update on this situation?

[siriwatknp]

First, I really appreciate your positive feedbacks about Joy UI. We started Joy UI to be a second choice apart from Material UI but it turns out that we don't have enough capacity to move forward with both libraries. Now, we decided to focus on Material UI (v6 is about to be released) and v7 till Q2 2025 (roughly) to make the customization best of the industry while supporting multiple design system.

So we are not continue adding new features to Joy UI and will decide the future of Joy UI after we have a working prototype of Material UI v7. One possibility that I see is that Joy UI could become a theme of Material UI (the API should be the same).