[docs] Add live demo with CssVarsProvider (#38792)

Signed-off-by: Olivier Tassinari <[email protected]> Co-authored-by: Danilo Leal <[email protected]>
mui · Sep 18, 2023 · 1ad6d26 · 1ad6d26
1 parent 5fc9508
commit 1ad6d26
Show file tree

Hide file tree

Showing 8 changed files with 61 additions and 24 deletions.
diff --git a/docs/data/material/experimental-api/css-theme-variables/overview.md b/docs/data/material/experimental-api/css-theme-variables/overview.md
@@ -27,11 +27,11 @@ With these variables, you can inject a theme into your app's stylesheet _at buil
 
 For server-side applications, there are some trade-offs to consider:
 
-|                                                      | Compare to the default method | Reason                                                                                                       |
-| :--------------------------------------------------- | :---------------------------- | :----------------------------------------------------------------------------------------------------------- |
-| HTML size                                            | Bigger                        | CSS variables are generated for both light and dark mode at build time.                                      |
-| [First Contentful Paint (FCP)](https://web.dev/fcp/) | Larger                        | Since the HTML size is generally bigger, the time to download the HTML before showing the content is longer. |
-| [Time to Interactive (TTI)](https://web.dev/tti/)    | Smaller (for dark mode)       | Stylesheets are not regenerated between light and dark mode, so it takes less time for JavaScript to run.    |
+|                                                      | Compare to the default method | Reason                                                                                                         |
+| :--------------------------------------------------- | :---------------------------- | :------------------------------------------------------------------------------------------------------------- |
+| HTML size                                            | Bigger                        | CSS variables are generated for both light and dark mode at build time.                                        |
+| [First Contentful Paint (FCP)](https://web.dev/fcp/) | Longer                        | Since the HTML size is bigger, the time to download the HTML before showing the content is a bit longer.       |
+| [Time to Interactive (TTI)](https://web.dev/tti/)    | Shorter (for dark mode)       | Stylesheets are not regenerated between light and dark mode, a lot less time is spent running JavaScript code. |
 
 :::warning
 The comparison described in the table above may not be applicable to large and complex applications since there are so many factors that can impact performance metrics.
@@ -46,6 +46,8 @@ Adopting CSS variables requires some shifts in your mental model of theming and
 **[Default approach](/material-ui/customization/dark-mode/)**: Light and dark colors are created separately.
 
 ```js
+import { createTheme } from '@mui/material/styles';
+
 const lightTheme = createTheme();
 
 const darkTheme = createTheme({
@@ -58,6 +60,8 @@ const darkTheme = createTheme({
 **CSS theme variables**: Light and dark colors are consolidated into a theme.
 
 ```js
+import { experimental_extendTheme as extendTheme } from '@mui/material/styles';
+
 // `extendTheme` is a new API
 const theme = extendTheme({
   colorSchemes: {

diff --git a/docs/data/material/experimental-api/css-theme-variables/usage/CssVarsBasic.js b/docs/data/material/experimental-api/css-theme-variables/usage/CssVarsBasic.js
@@ -0,0 +1,18 @@
+import * as React from 'react';
+import {
+  experimental_extendTheme as extendTheme,
+  Experimental_CssVarsProvider as CssVarsProvider,
+} from '@mui/material/styles';
+import Button from '@mui/material/Button';
+
+const theme = extendTheme({
+  cssVarPrefix: 'md-demo',
+});
+
+export default function CssVarsBasic() {
+  return (
+    <CssVarsProvider theme={theme}>
+      <Button variant="contained">Hello world</Button>
+    </CssVarsProvider>
+  );
+}
diff --git a/docs/data/material/experimental-api/css-theme-variables/usage/CssVarsBasic.tsx b/docs/data/material/experimental-api/css-theme-variables/usage/CssVarsBasic.tsx
@@ -0,0 +1,18 @@
+import * as React from 'react';
+import {
+  experimental_extendTheme as extendTheme,
+  Experimental_CssVarsProvider as CssVarsProvider,
+} from '@mui/material/styles';
+import Button from '@mui/material/Button';
+
+const theme = extendTheme({
+  cssVarPrefix: 'md-demo',
+});
+
+export default function CssVarsBasic() {
+  return (
+    <CssVarsProvider theme={theme}>
+      <Button variant="contained">Hello world</Button>
+    </CssVarsProvider>
+  );
+}
diff --git a/docs/data/material/experimental-api/css-theme-variables/usage/CssVarsBasic.tsx.preview b/docs/data/material/experimental-api/css-theme-variables/usage/CssVarsBasic.tsx.preview
@@ -0,0 +1,3 @@
+<CssVarsProvider theme={theme}>
+  <Button variant="contained">Hello world</Button>
+</CssVarsProvider>
diff --git a/...rimental-api/css-theme-variables/usage.md → ...al-api/css-theme-variables/usage/usage.md b/...rimental-api/css-theme-variables/usage.md → ...al-api/css-theme-variables/usage/usage.md
@@ -7,14 +7,6 @@
 The CSS variables API relies on a new experimental provider for the theme called `Experimental_CssVarsProvider` to inject styles into Material UI components.
 In addition to providing the theme in the inner React context, this new provider also generates CSS variables out of all tokens in the theme that are not functions, and makes them available in the context as well.
 
-```js
-import { Experimental_CssVarsProvider as CssVarsProvider } from '@mui/material/styles';
-
-function App() {
-  return <CssVarsProvider>...</CssVarsProvider>;
-}
-```
-
 Once the `App` renders on the screen, you will see the CSS theme variables in the html `:root` stylesheet.
 The variables are flattened and prefixed with `--mui` by default:
 
@@ -29,6 +21,10 @@ The variables are flattened and prefixed with `--mui` by default:
 }
 ```
 
+The following demo uses `--md-demo` as a prefix for the variables:
+
+{{"demo": "CssVarsBasic.js", "defaultCodeOpen": true}}
+
 :::info
 The `CssVarsProvider` is built on top of the [`ThemeProvider`](/material-ui/customization/theming/#themeprovider) with extra features like CSS variable generation, storage synchronization, unlimited color schemes, and more.
 :::
@@ -167,7 +163,6 @@ const StyledComponent = styled('button')(({ theme }) => ({
 
 - `defaultMode?: 'light' | 'dark' | 'system'` - Application's default mode (`light` by default)
 - `disableTransitionOnChange : boolean` - Disable CSS transitions when switching between modes
-- `prefix: string` - CSS variable prefix
 - `theme: ThemeInput` - the theme provided to React's context
 - `modeStorageKey?: string` - localStorage key used to store application `mode`
 - `attribute?: string` - DOM attribute for applying color scheme

diff --git a/docs/data/system/experimental-api/css-theme-variables/css-theme-variables.md b/docs/data/system/experimental-api/css-theme-variables/css-theme-variables.md
@@ -27,11 +27,11 @@ You can checkout the [advantages](https://mui.com/material-ui/experimental-api/c
 
 For server-side applications, there are some trade-offs to consider:
 
-|                                                      | Compare to the default method | Reason                                                                                                       |
-| :--------------------------------------------------- | :---------------------------- | :----------------------------------------------------------------------------------------------------------- |
-| HTML size                                            | Bigger                        | CSS variables are generated for both light and dark mode at build time.                                      |
-| [First Contentful Paint (FCP)](https://web.dev/fcp/) | Larger                        | Since the HTML size is generally bigger, the time to download the HTML before showing the content is longer. |
-| [Time to Interactive (TTI)](https://web.dev/tti/)    | Smaller (for dark mode)       | Stylesheets are not regenerated between light and dark mode, so it takes less time for JavaScript to run.    |
+|                                                      | Compare to the default method | Reason                                                                                                         |
+| :--------------------------------------------------- | :---------------------------- | :------------------------------------------------------------------------------------------------------------- |
+| HTML size                                            | Bigger                        | CSS variables are generated for both light and dark mode at build time.                                        |
+| [First Contentful Paint (FCP)](https://web.dev/fcp/) | Longer                        | Since the HTML size is bigger, the time to download the HTML before showing the content is bit longer.         |
+| [Time to Interactive (TTI)](https://web.dev/tti/)    | Shorter (for dark mode)       | Stylesheets are not regenerated between light and dark mode, a lot less time is spent running JavaScript code. |
 
 :::warning
 The comparison described in the table above may not be applicable to large and complex applications since there are so many factors that can impact performance metrics.
@@ -209,7 +209,6 @@ See the complete usage of `createVssVarsProvider` in [Material UI](https://githu
 
 - `defaultMode?: 'light' | 'dark' | 'system'` - Application's default mode (`light` by default)
 - `disableTransitionOnChange : boolean` - Disable CSS transitions when switching between modes
-- `prefix: string` - CSS variable prefix
 - `theme: ThemeInput` - the theme provided to React's context
 - `modeStorageKey?: string` - localStorage key used to store application `mode`
 - `attribute?: string` - DOM attribute for applying color scheme

diff --git a/docs/pages/material-ui/experimental-api/css-theme-variables/usage.js b/docs/pages/material-ui/experimental-api/css-theme-variables/usage.js
@@ -4,7 +4,7 @@ import {
   demos,
   docs,
   demoComponents,
-} from 'docs/data/material/experimental-api/css-theme-variables/usage.md?@mui/markdown';
+} from 'docs/data/material/experimental-api/css-theme-variables/usage/usage.md?@mui/markdown';
 
 export default function Page() {
   return <MarkdownDocs demos={demos} docs={docs} demoComponents={demoComponents} />;

diff --git a/packages/mui-system/src/cssVars/createCssVarsProvider.js b/packages/mui-system/src/cssVars/createCssVarsProvider.js
@@ -337,19 +337,19 @@ export default function createCssVarsProvider(options) {
      */
     disableStyleSheetGeneration: PropTypes.bool,
     /**
-     * Disable CSS transitions when switching between modes or color schemes
+     * Disable CSS transitions when switching between modes or color schemes.
      */
     disableTransitionOnChange: PropTypes.bool,
     /**
-     * The document to attach the attribute to
+     * The document to attach the attribute to.
      */
     documentNode: PropTypes.any,
     /**
      * The key in the local storage used to store current color scheme.
      */
     modeStorageKey: PropTypes.string,
     /**
-     * The window that attaches the 'storage' event listener
+     * The window that attaches the 'storage' event listener.
      * @default window
      */
     storageWindow: PropTypes.any,