[joy] Refine the default theme

[siriwatknp]

closes #35788
closes #37663
closes #36782
closes #37663
closes #37967
closes #38165

Migration docs: https://deploy-preview-36843--material-ui.netlify.app/joy-ui/migration/migrating-default-theme/
New Tabs design: https://deploy-preview-36843--material-ui.netlify.app/joy-ui/react-tabs/
Migration tested: https://codesandbox.io/s/joy-cra-ts-forked-mtdp6g?file=/src/App.tsx

Try it out

We really appreciate it if you could try the new changes in your existing Joy UI project.

1. Replace the @mui/joy version in your package.json with this:

   - "@mui/joy": "5.0.0-alpha.x"
   + "@mui/joy": "https://pkg.csb.dev/mui/material-ui/commit/2c04ead4/@mui/joy"

2. run yarn install (you might have to run it twice because the first time might see an error).

3. Follow the migration docs

Review recommendation

Better to go through the migration docs because it is the source of all breaking changes.

Changes

Tokens removed

• palette.info
• letterSpacing

Typography

h1
h2
h3
h4
- h5
- h6
- body1
- body2
- body3
- body4
- body5
+ title-lg
+ title-md
+ title-sm
+ body-lg
+ body-md
+ body-sm
+ body-xs

The composition of title-* and body-* is improved. When using them together with an icon, there is no need to add extra margin at all. For example:

// Before
<SvgIcon sx={{ mt: '2px' }}>
<div>
  <Typography fontWeight="lg" mb={0.25}>Title</Typography>
  <Typography level="body2">Description</Typography>
</div>

// After
<SvgIcon>
<div>
  <Typography level="title-md">Title</Typography>
  <Typography level="body-sm">Description</Typography>
</div>

Before	After

Templates

Before	After

• I have followed (at least) the PR section of the contributing guide.

[mui-bot]

Netlify deploy preview

• docs/data/joy/migration/migrating-default-theme.md
• docs/data/joy/components/autocomplete/autocomplete.md
• docs/data/joy/components/button-group/button-group.md
• docs/data/joy/components/button/button.md
• docs/data/joy/components/card/card.md

@mui/joy: parsed: -0.99% 😍, gzip: +0.27%

Bundle size report

Details of bundle changes (Toolpad)
Details of bundle changes

Generated by 🚫 dangerJS against 44712e9

[siriwatknp]

@danilo-leal I started by removing some font-size, font-weight and levels that are not likely to be used to keep the theme as lean as possible.

For font-size, I think if it is lower than 12px it is very hard to read so I don't think < xs should be in the default theme.

For h5 and h6, I follow tailwindcss typography:

But now we have. Please don't use h5 or h6 in your content, Medium only supports two heading levels for a reason, you animals. I honestly considered using a before pseudo-element to scream at you if you use an h5 or h6.

[zanivan]

I've reduced the amount of typography, but didn't delete the remain font sizes, should we do it?

[zanivan]

I've reduced a bit the radius, but it's not set in stone, what do you think?

[zanivan]

Sorry @siriwatknp, I got carried away and ended up committing all the changes at once 😅
I've let some comments on the changes, but it'd be nice to review everything and reassure that I didn't do anything wrong.

Besides the comments I left in the file, I'd like to ask a few more things:

1. How/where is defined the placeholder texts?
2. How should we remove the "info" palette?
3. Could we have more semantic names for texts sizes? I think it'd improve the user experience, providing names like "Title-xl", "Title-md", "body-sm", and so on. What do you think?

[siriwatknp]

How/where is defined the placeholder texts?

We don't have a theme token that is specific to the placeholder text. They can be configured through component variables, for example, the Input:

How should we remove the "info" palette?

I can help with that.

Could we have more semantic names for texts sizes? I think it'd improve the user experience, providing names like "Title-xl", "Title-md", "body-sm", and so on. What do you think?

Do you mean in theme.typography? The benefit I see is that they are more explicit than body1, 2, 3 (who knows if 1 is bigger or smaller than 2). However, we should do the POC of the typography set with demo components and templates too validate that they are useful and intuitive.

[zanivan]

We don't have a theme token that is specific to the placeholder text. They can be configured through component variables, for example, the Input:

Would it be possible to have a token for it? I think opacity could be a bit tricky to contrast when dealing with so many variables.

Do you mean in theme.typography? The benefit I see is that they are more explicit than body1, 2, 3 (who knows if 1 is bigger or smaller than 2). However, we should do the POC of the typography set with demo components and templates too validate that they are useful and intuitive.

I'm not sure if it'd be in theme.typography, but the idea is to have something like <Typography level="body-lg">Hello, World!</Typography>, instead of <Typography level="body1">Hello, World!</Typography>. I reckon this would really help in moments where the user needs a smaller text, and could just add a sm instead of remembering which body to use. But yeah, definitely should try on POCs before.

[siriwatknp]

Would it be possible to have a token for it? I think opacity could be a bit tricky to contrast when dealing with so many variables.

What do you think about adding the token to palette.text.placeholder?

[zanivan]

What do you think about adding the token to palette.text.placeholder?

I was testing the contrast here and probably we would have to have one for each variant (plain, solid,soft and outlined). What do you think we could do then?

[siriwatknp]

Opportunities for improvement:

• Line height seems wrong (using rem) 👉 /experiments/joy/prose/
• Disabled state 👉 /experiments/joy/global-variants/ with neutral palette
• neutral can be darker 👉 /experiments/joy/global-variants/ (will try different tokens for some components)
• more typography levels
• remove letter spacing scale? Yes.
• color token for icon, e.g. palette.text.icon. We should have tokens for color with states.
• add shadow-opacity

[zanivan]

I was looking at the components at /experiments/joy/global-variants/ and the only thing that still needs major adjustments is the primary warning card. Isn't it following the tokens set on extendedTheme?

[zanivan]

@siriwatknp I've updated the typography according to what we discussed on the Figma file.

Also, I was making some tests at /experiments/joy/global-variants/ and I think we could bump up a bit the opacity of placeholders. I tried 0.7, and I think it's a sweet spot between being recognized as a placeholder, but still being able to be differentiated from the filled label.

[zanivan]

@siriwatknp I tweaked the shadows, surfaces, some icon colors, and the disabled button. Also, I updated the email template to remove the custom styles to make it closer to the default as possible.

[siriwatknp]

@zanivan I adjust the global variant tokens a bit (disabled and some neutral palette tokens). I think the before version is too light and too close to the disabled state, so I increase the contrast a little bit more and also make the disabled state lighter. Let me know what you think!

Before:

After:

[siriwatknp]

@siriwatknp When do You plan to merge it? I could really use to this changes.

@td5999 I plan to merge it this week and it will be released next week with v5.0.0-beta.0.

[sernstberger]

These changes are great. It's exciting that Joy is moving to beta!

[Studio384]

@Studio384 @td5999 Would you mind checking the "Try it out" in the PR description? Would love you to see if there is anything missing before we merge this PR.

I generally like the changes, I do prefer the old grey scale tho, so definitly going to restore that in the implementations we use (or at least the blue shine in it). :) Anyways great work!

[siriwatknp]

@Studio384 @td5999 Would you mind checking the "Try it out" in the PR description? Would love you to see if there is anything missing before we merge this PR.

I generally like the changes, I do prefer the old grey scale tho, so definitly going to restore that in the implementations we use (or at least the blue shine in it). :) Anyways great work!

Thanks for the feedback! in that case you can take a look at this migration doc on how to use the previous neutral and primary colors.

[mwskwong]

I tried it for a while. And I notice some things that we might want to improve.

1. Default icon color - Should --joy-palette-text-icon be darker instead? It looks a bit out of place.
   
   

2. BG color in light color scheme - body and level1 shares the same color code, unlike dark color scheme, not sure if that's intentional.

3. The default body text color becomes --joy-palette-text-secondary instead of --joy-palette-text-primary.

[siriwatknp]

@mwskwong Thanks for the feedback!

Default icon color - Should --joy-palette-text-icon be darker instead? It looks a bit out of place.

I feel like the icon color should be lighter than the text to be complementary. That's why I choose neutral.400 as a default icon color.

Some inspiration:

• https://tailwindui.com/components/application-ui/application-shells/sidebar

No worry if you want to change it, you can override it via the theme:

extendTheme({
  colorSchemes: {
    light: {
      palette: {
        text: {
          icon: 'var(--joy-palette-neutral-600)',
        }
      }
    },
    dark: { … },
  }
})

BG color in light color scheme - body and level1 shares the same color code, unlike dark color scheme, not sure if that's intentional.

I think @zanivan has fixed it in the latest commit.

The default body text color becomes --joy-palette-text-secondary instead of --joy-palette-text-primary.

Yes, the previous version does not have much contrast between texts. I feel like the new version looks a lot better.

Anyway, you can override the theme level as you like:

extendTheme({
  typography: {
    'body-md': {
      color: 'var(--joy-palette-text-primary)',
    },
    …
  }
})

[oliviertassinari]

I didn't have the time to dive into this PR, instead I put together all the opportunities that I could spot in the latest release at https://www.notion.so/mui-org/Olivier-design-review-on-Joy-Design-3ada9a7bcfa44b9fab1fe5032dfb33bb and public link.

Overall, I love that we are allocating time to shape the look & feel, I think it's a high ROI effort 👍

[clarkmcc]

I'm not sure if this was the change that caused it, but some recent design changes seemed to break the design of my existing project, and event some of the examples, for example the solid card design doesn't look quite right.

[danilo-leal]

@clarkmcc Hey! Feel free to open an issue in case we can help with any issues due to recent Joy UI updates ⎯ anyhow, it's super cool you're using it; appreciate you giving it a shot!

In this case, although it definitely doesn't look nice, it's not technically broken. That's due to Joy UI's global variants feature, which allows all components to have the same variant set, and their styles to be defined in one place only. It's conceptually a sweet feature and, overall, works fine. But, there are many cases, such as this Card one, where certain variants simply don't make sense (or even look broken, as you pointed out). The tentative solution we're flirting with is "turning off" non-sensical variants for specific components, which still allows us to keep the benefits of globally defined variant styles. There are also other options in the table and it's generally something we want to sort through before the stable version ⎯ so, keep an eye out!