diff --git a/docs/data/material/experimental-api/css-theme-variables/overview.md b/docs/data/material/experimental-api/css-theme-variables/overview.md index 20af073e857ccc..319b88daaf169f 100644 --- 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 new file mode 100644 index 00000000000000..cbbdc835b12d7c --- /dev/null +++ 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 ( + + + + ); +} 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 new file mode 100644 index 00000000000000..cbbdc835b12d7c --- /dev/null +++ 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 ( + + + + ); +} 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 new file mode 100644 index 00000000000000..511e5c2381dd78 --- /dev/null +++ b/docs/data/material/experimental-api/css-theme-variables/usage/CssVarsBasic.tsx.preview @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/data/material/experimental-api/css-theme-variables/usage.md b/docs/data/material/experimental-api/css-theme-variables/usage/usage.md similarity index 96% rename from docs/data/material/experimental-api/css-theme-variables/usage.md rename to docs/data/material/experimental-api/css-theme-variables/usage/usage.md index a1ea23f2a64609..f6bd3f239a5fe5 100644 --- a/docs/data/material/experimental-api/css-theme-variables/usage.md +++ b/docs/data/material/experimental-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 ...; -} -``` - 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 index 32f12482f900e1..ee5db55177a68a 100644 --- 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 index 182c27e2d146bd..50811f2f187adf 100644 --- 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 ; diff --git a/packages/mui-system/src/cssVars/createCssVarsProvider.js b/packages/mui-system/src/cssVars/createCssVarsProvider.js index 8e00154609e3a4..ddd9398f91ce53 100644 --- a/packages/mui-system/src/cssVars/createCssVarsProvider.js +++ b/packages/mui-system/src/cssVars/createCssVarsProvider.js @@ -337,11 +337,11 @@ 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, /** @@ -349,7 +349,7 @@ export default function createCssVarsProvider(options) { */ modeStorageKey: PropTypes.string, /** - * The window that attaches the 'storage' event listener + * The window that attaches the 'storage' event listener. * @default window */ storageWindow: PropTypes.any,