[system][docs] Experimental API's in official docs makes us uncertain what to expect and if it is ok to base a decision on it

[CoennW]

Related page

https://mui.com/material-ui/experimental-api/css-theme-variables/migration/

Kind of issue

Missing information

Issue description

While discussing and exploring on how to evolve our code base we looked into the CSS theme variables API. We agreed on that this is something that we want to use and would help us with styling solutions.

While we found an issue like issue 41070. For us, it is still hard to make decisions based on experimental API's. While the documentation also says that it is a feature added in 'v5.6.0' (implies it is here to stay), even with documentation on how to migrate, the experimental tag implies that it is possible that it might be removed.

How should we interpret these experimental documented API's? Are these always included with next major releases? Or is there nothing to say about a stable release? Can we already base a decision on something experimental as it is an 'added feature'? Or does it imply we can't/should not do that as it is experimental?

Is there something the team of MUI can add to these 'experimental' but added as feature API's to make this more clear for us, the users?

Context

Thinking and decide about the best current solutions that have an long term effect and the direction of our own code base.

Search keywords: CSS variables experimental release production expectation advice

[DiegoAndai]

Hey @CoennW, thanks for reaching out!

I understand why you are hesitant to rely on experimental features. Regarding the CssVarsProvider, we don't expect the API to change. The only blocker for removing the experimental flag is optimizing the extendTheme function. We will work on this soon and expect to remove the flag by around Q2 2024: #41070.

I'll leave this open in case anyone has the same concern before we remove the flag.

[CoennW]

Hi @DiegoAndai ,

Looking good! The CssVarsProvider is already working flawlessly 💯. We'll keep an eye out for the removal of the experimental flag.

Thank you for the response.

[siriwatknp]

@CoennW Thanks for the feedback. FYI, we have merged CssVarsProvider into ThemeProvider to reduce API surface and prevent the confusion between the two.

We are deprecating the CssVarsProvider (you can still use it), but I recommend to switch to ThemeProvider when we release the stable version of v6.

The switch should be straightforward, just replace CssVarsProvider with ThemeProvider and extendTheme with createTheme and use cssVariables: true:

const theme = createTheme({
  cssVariables: {
    colorSchemeSelector: 'data-mui-color-scheme', // change to 'class' if you'd like
  },
  colorSchemes: { …your existing code }
});

<ThemeProvider theme={theme}>

[siriwatknp]

I'm closing this because we are about to release v6 stable with the CSS variables support, so it's definitely ok to use it.