[material-ui] Refine extendTheme and CssVarsProvider API

[siriwatknp]

closes #42887, closes #41070

📖 docs: Basic usage and Advanced config

Motivation

The experimental API was lacking some of the behaviors

• It provides both light and dark modes by default. This is not a good behavior for apps with only light or dark mode. The way it should be is to start with light by default and let users configure params based on their usage.
• It's not possible to use a class selector [system] getColorSchemeSelector() move away from data-color-scheme "attribute value" selector #42887
• It's not possible to use @media prefers-color-scheme
• The API to customize the selector is too hard to understand without documentation

Changes

Start with light by default

When using CssVarsProvider without a custom theme, the behavior is the same as ThemeProvider except that the theme CSS variables are generated.

See docs.

Switch to dark application

const theme = extendTheme({ colorSchemes: { dark: true } });

<CssVarsProvider theme={theme}>

Light and Dark

When light and dark are enable, the @media (prefers-color-scheme) is used.

const theme = extendTheme({ colorSchemes: { light: true, dark: true } });

<CssVarsProvider theme={theme}>

To customize the selector, set colorSchemeSelector: 'class' | 'data':

const theme = extendTheme({
  colorSchemes: { light: true, dark: true },
  colorSchemeSelector: 'class', // .dark, .light
});

<CssVarsProvider theme={theme}>

• The basic usage shows the media option.
• The custom selector is in advanced configuration.

System preference

System preference is enabled by default regardless of the selector. So, for light and dark apps, the mode will be system by default.

color-scheme

Css color-scheme is enable by default to use the right scheme based on the generated style-sheet, user can disable it with:

extendTheme({
  disableCssColorScheme: true,
})

Removed APIs

 <CssVarsProvider
-  defaultMode="..." // replaced by `defaultColorScheme` in the extendTheme
-  colorSchemeSelector="…" // replaced by `colorSchemeSelector` in the extendTheme
/>

---

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

[mui-bot]

Netlify deploy preview

• docs/data/material/customization/css-theme-variables/usage.md
• docs/data/joy/customization/dark-mode/dark-mode.md
• docs/data/joy/getting-started/tutorial/tutorial.md
• docs/data/joy/integrations/material-ui/material-ui.md
• docs/data/material/customization/css-theme-variables/configuration.md

@material-ui/core: parsed: +0.32% , gzip: +0.44%
@material-ui/system: parsed: +1.57% , gzip: +1.64%
@mui/joy: parsed: +0.21% , gzip: +0.30%
@mui/joy/ModalOverflow: parsed: +0.93% , gzip: +1.27%
@mui/joy/FormLabel: parsed: +0.93% , gzip: +1.25%
@mui/joy/Typography: parsed: +0.89% , gzip: +1.17%
@mui/joy/CardCover: parsed: +0.94% , gzip: +1.20%
@mui/joy/FormHelperText: parsed: +0.93% , gzip: +1.19%
@mui/joy/CardContent: parsed: +0.93% , gzip: +1.19%
@mui/joy/Link: parsed: +0.83% , gzip: +1.09%
@mui/joy/AvatarGroup: parsed: +0.93% , gzip: +1.18%
@mui/joy/StepIndicator: parsed: +0.93% , gzip: +1.18%
@mui/joy/Skeleton: parsed: +0.83% , gzip: +1.05%
@mui/joy/ScopedCssBaseline: parsed: +0.93% , gzip: +1.15%
@mui/joy/AccordionDetails: parsed: +0.92% , gzip: +1.11%
@mui/joy/Checkbox: parsed: +0.78% , gzip: +0.96%
@mui/joy/Tabs: parsed: +0.88% , gzip: +1.06%
@mui/joy/Box: parsed: +1.03% , gzip: +1.23%
@mui/joy/Input: parsed: +0.82% , gzip: +1.01%
@mui/joy/ListItemDecorator: parsed: +0.94% , gzip: +1.12%
and 66 more changes

Bundle size report

Details of bundle changes (Toolpad)
Details of bundle changes

Generated by 🚫 dangerJS against b8b95ea

[siriwatknp]

"class" is obvious but what do you expect to be for "selector"? if it's a data-attribute, may be "data" is better?

Yes, "data" would be better. I'll let you decide if it's necessary or not, "class" might be enough.

Thanks, I'll go with data as well.

The PR is ready for another review. Argos changes are expected.

[DiegoAndai]

Nice work @siriwatknp, I only have one question regarding the docs

[DiegoAndai]

If I understand correctly, you either provide

colorSchemes: { light: true, dark: true }

or

colorSchemeSelector: 'media'

right?

If this is the case, then I would show colorSchemes: { light: true, dark: true } for this example and leave colorSchemeSelector for the advanced section. I think colorSchemes: { light: true, dark: true } is more beginner friendly. What do you think?

[siriwatknp]

Opps, this is my mistake.

colorSchemeSelector: 'media' alone won't work because the there is only light color scheme by default, so colorSchemes: { light: true, dark: true } is required.

I will update the docs and add a warning in development.

[siriwatknp]

Done!

[DiegoAndai]

Two final minor improvements to the guide, but otherwise LGTM 😊

Nice job @siriwatknp

[oliviertassinari]

"we"

Suggested change

	In the example below, we're using a `Select` component that calls `setMode` from the `useColorSchemes()` hook to handle the mode switching.
	The example below uses a `Select` component that calls `setMode` from the `useColorSchemes()` hook to handle the mode switching.