From 49989b1fbb915d02740600ace88c837a553ccd94 Mon Sep 17 00:00:00 2001 From: Diego Andai Date: Fri, 21 Jul 2023 17:35:44 -0400 Subject: [PATCH] [docs][material] Improve documentation about adding custom colors (#37743) --- .../material/components/buttons/buttons-pt.md | 2 +- .../material/components/buttons/buttons-zh.md | 2 +- .../material/components/buttons/buttons.md | 2 +- .../palette/AddingColorTokens.js | 41 +++ .../palette/AddingColorTokens.tsx | 51 ++++ .../palette/AddingColorTokens.tsx.preview | 13 + .../palette/ContrastThreshold.js | 43 +++ .../palette/ContrastThreshold.tsx | 43 +++ .../customization/palette/CustomColor.js | 4 +- .../customization/palette/CustomColor.tsx | 4 +- .../palette/ManuallyProvideCustomColor.js | 42 +++ .../palette/ManuallyProvideCustomColor.tsx | 60 ++++ .../ManuallyProvideCustomColor.tsx.preview | 12 + .../palette/ManuallyProvidePaletteColor.js | 58 ++++ .../palette/ManuallyProvidePaletteColor.tsx | 58 ++++ .../ManuallyProvidePaletteColor.tsx.preview | 18 ++ .../customization/palette/TonalOffset.js | 86 ++++++ .../customization/palette/TonalOffset.tsx | 86 ++++++ .../palette/UsingAugmentColor.js | 48 +++ .../palette/UsingAugmentColor.tsx | 66 +++++ .../palette/UsingAugmentColor.tsx.preview | 18 ++ .../customization/palette/UsingColorObject.js | 25 ++ .../palette/UsingColorObject.tsx | 25 ++ .../palette/UsingColorObject.tsx.preview | 9 + .../customization/palette/UsingStylesUtils.js | 50 ++++ .../palette/UsingStylesUtils.tsx | 68 +++++ .../palette/UsingStylesUtils.tsx.preview | 15 + .../material/customization/palette/palette.md | 273 +++++++++--------- docs/pages/blog/mui-core-v5.md | 5 +- docs/scripts/formattedTSDemos.js | 1 + .../moduleAugmentation/paletteColors.spec.ts | 6 + 31 files changed, 1087 insertions(+), 147 deletions(-) create mode 100644 docs/data/material/customization/palette/AddingColorTokens.js create mode 100644 docs/data/material/customization/palette/AddingColorTokens.tsx create mode 100644 docs/data/material/customization/palette/AddingColorTokens.tsx.preview create mode 100644 docs/data/material/customization/palette/ContrastThreshold.js create mode 100644 docs/data/material/customization/palette/ContrastThreshold.tsx create mode 100644 docs/data/material/customization/palette/ManuallyProvideCustomColor.js create mode 100644 docs/data/material/customization/palette/ManuallyProvideCustomColor.tsx create mode 100644 docs/data/material/customization/palette/ManuallyProvideCustomColor.tsx.preview create mode 100644 docs/data/material/customization/palette/ManuallyProvidePaletteColor.js create mode 100644 docs/data/material/customization/palette/ManuallyProvidePaletteColor.tsx create mode 100644 docs/data/material/customization/palette/ManuallyProvidePaletteColor.tsx.preview create mode 100644 docs/data/material/customization/palette/TonalOffset.js create mode 100644 docs/data/material/customization/palette/TonalOffset.tsx create mode 100644 docs/data/material/customization/palette/UsingAugmentColor.js create mode 100644 docs/data/material/customization/palette/UsingAugmentColor.tsx create mode 100644 docs/data/material/customization/palette/UsingAugmentColor.tsx.preview create mode 100644 docs/data/material/customization/palette/UsingColorObject.js create mode 100644 docs/data/material/customization/palette/UsingColorObject.tsx create mode 100644 docs/data/material/customization/palette/UsingColorObject.tsx.preview create mode 100644 docs/data/material/customization/palette/UsingStylesUtils.js create mode 100644 docs/data/material/customization/palette/UsingStylesUtils.tsx create mode 100644 docs/data/material/customization/palette/UsingStylesUtils.tsx.preview diff --git a/docs/data/material/components/buttons/buttons-pt.md b/docs/data/material/components/buttons/buttons-pt.md index 1bf9e77833d6c1..cfe86949e4f188 100644 --- a/docs/data/material/components/buttons/buttons-pt.md +++ b/docs/data/material/components/buttons/buttons-pt.md @@ -71,7 +71,7 @@ Note that the documentation [avoids](/material-ui/guides/api/#native-properties) {{"demo": "ColorButtons.js"}} -Além de usar as cores de botão padrão, você pode adicionar outras personalizadas ou desativar as que não forem necessárias. See the [Adding new colors](/material-ui/customization/palette/#adding-new-colors) example for more info. +Além de usar as cores de botão padrão, você pode adicionar outras personalizadas ou desativar as que não forem necessárias. See the [Adding new colors](/material-ui/customization/palette/#custom-colors) examples for more info. ## Tamanhos diff --git a/docs/data/material/components/buttons/buttons-zh.md b/docs/data/material/components/buttons/buttons-zh.md index 9c791c4f35ebef..d1be12723fb819 100644 --- a/docs/data/material/components/buttons/buttons-zh.md +++ b/docs/data/material/components/buttons/buttons-zh.md @@ -71,7 +71,7 @@ Note that the documentation [avoids](/material-ui/guides/api/#native-properties) {{"demo": "ColorButtons.js"}} -除了使用默认按钮颜色外，您可以添加自定义颜色，或者禁用任何您不需要的颜色。 See the [Adding new colors](/material-ui/customization/palette/#adding-new-colors) example for more info. +除了使用默认按钮颜色外，您可以添加自定义颜色，或者禁用任何您不需要的颜色。 See the [Adding new colors](/material-ui/customization/palette/#custom-colors) examples for more info. ## 尺寸 diff --git a/docs/data/material/components/buttons/buttons.md b/docs/data/material/components/buttons/buttons.md index c36ddf70130bed..8778a86eba2e40 100644 --- a/docs/data/material/components/buttons/buttons.md +++ b/docs/data/material/components/buttons/buttons.md @@ -77,7 +77,7 @@ Note that the documentation [avoids](/material-ui/guides/api/#native-properties) {{"demo": "ColorButtons.js"}} -In addition to using the default button colors, you can add custom ones, or disable any you don't need. See the [Adding new colors](/material-ui/customization/palette/#adding-new-colors) example for more info. +In addition to using the default button colors, you can add custom ones, or disable any you don't need. See the [Adding new colors](/material-ui/customization/palette/#custom-colors) examples for more info. ## Sizes diff --git a/docs/data/material/customization/palette/AddingColorTokens.js b/docs/data/material/customization/palette/AddingColorTokens.js new file mode 100644 index 00000000000000..377aee03030ac0 --- /dev/null +++ b/docs/data/material/customization/palette/AddingColorTokens.js @@ -0,0 +1,41 @@ +import * as React from 'react'; +import { createTheme, ThemeProvider } from '@mui/material/styles'; +import { blue } from '@mui/material/colors'; +import { Box, Stack } from '@mui/system'; +import { Typography } from '@mui/material'; + +const theme = createTheme({ + palette: { + primary: { + light: blue[300], + main: blue[500], + dark: blue[700], + darker: blue[900], + }, + }, +}); + +export default function AddingColorTokens() { + return ( + + + + light + + + + main + + + + dark + + + + darker + + + + + ); +} diff --git a/docs/data/material/customization/palette/AddingColorTokens.tsx b/docs/data/material/customization/palette/AddingColorTokens.tsx new file mode 100644 index 00000000000000..b9affe98f26dbc --- /dev/null +++ b/docs/data/material/customization/palette/AddingColorTokens.tsx @@ -0,0 +1,51 @@ +import * as React from 'react'; +import { createTheme, ThemeProvider } from '@mui/material/styles'; +import { blue } from '@mui/material/colors'; +import { Box, Stack } from '@mui/system'; +import { Typography } from '@mui/material'; + +declare module '@mui/material/styles' { + interface PaletteColor { + darker?: string; + } + + interface SimplePaletteColorOptions { + darker?: string; + } +} + +const theme = createTheme({ + palette: { + primary: { + light: blue[300], + main: blue[500], + dark: blue[700], + darker: blue[900], + }, + }, +}); + +export default function AddingColorTokens() { + return ( + + + + light + + + + main + + + + dark + + + + darker + + + + + ); +} diff --git a/docs/data/material/customization/palette/AddingColorTokens.tsx.preview b/docs/data/material/customization/palette/AddingColorTokens.tsx.preview new file mode 100644 index 00000000000000..186550fa9a4c2a --- /dev/null +++ b/docs/data/material/customization/palette/AddingColorTokens.tsx.preview @@ -0,0 +1,13 @@ +import { createTheme } from '@mui/material/styles'; +import { blue } from '@mui/material/colors'; + +const theme = createTheme({ + palette: { + primary: { + light: blue[300], + main: blue[500], + dark: blue[700], + darker: blue[900], + }, + }, +}); diff --git a/docs/data/material/customization/palette/ContrastThreshold.js b/docs/data/material/customization/palette/ContrastThreshold.js new file mode 100644 index 00000000000000..3d921d87888ef1 --- /dev/null +++ b/docs/data/material/customization/palette/ContrastThreshold.js @@ -0,0 +1,43 @@ +import * as React from 'react'; +import { createTheme, ThemeProvider, useTheme } from '@mui/material/styles'; +import Button from '@mui/material/Button'; +import { Stack } from '@mui/system'; + +const defaultContrastThresholdTheme = createTheme({}); + +const highContrastThresholdTheme = createTheme({ + palette: { + contrastThreshold: 4.5, + }, +}); + +function ContrastShowcase({ title }) { + const theme = useTheme(); + + return ( + + + {title} + + {theme.palette.contrastThreshold}:1 + + + + + ); +} + +export default function contrastThreshold() { + return ( + + + + + + + + + ); +} diff --git a/docs/data/material/customization/palette/ContrastThreshold.tsx b/docs/data/material/customization/palette/ContrastThreshold.tsx new file mode 100644 index 00000000000000..974ac5ec6dd13b --- /dev/null +++ b/docs/data/material/customization/palette/ContrastThreshold.tsx @@ -0,0 +1,43 @@ +import * as React from 'react'; +import { createTheme, ThemeProvider, useTheme } from '@mui/material/styles'; +import Button from '@mui/material/Button'; +import { Stack } from '@mui/system'; + +const defaultContrastThresholdTheme = createTheme({}); + +const highContrastThresholdTheme = createTheme({ + palette: { + contrastThreshold: 4.5, + }, +}); + +function ContrastShowcase({ title }: { title: string }) { + const theme = useTheme(); + + return ( + + + {title} + + {theme.palette.contrastThreshold}:1 + + + + + ); +} + +export default function contrastThreshold() { + return ( + + + + + + + + + ); +} diff --git a/docs/data/material/customization/palette/CustomColor.js b/docs/data/material/customization/palette/CustomColor.js index ec17f7968cec29..528851ba775065 100644 --- a/docs/data/material/customization/palette/CustomColor.js +++ b/docs/data/material/customization/palette/CustomColor.js @@ -5,7 +5,9 @@ import Button from '@mui/material/Button'; const theme = createTheme({ palette: { neutral: { - main: '#64748B', + light: '#838fa2', + main: '#64748b', + dark: '#465161', contrastText: '#fff', }, }, diff --git a/docs/data/material/customization/palette/CustomColor.tsx b/docs/data/material/customization/palette/CustomColor.tsx index 47a0c8bbff768b..3352f82cc6b05a 100644 --- a/docs/data/material/customization/palette/CustomColor.tsx +++ b/docs/data/material/customization/palette/CustomColor.tsx @@ -5,7 +5,9 @@ import Button from '@mui/material/Button'; const theme = createTheme({ palette: { neutral: { - main: '#64748B', + light: '#838fa2', + main: '#64748b', + dark: '#465161', contrastText: '#fff', }, }, diff --git a/docs/data/material/customization/palette/ManuallyProvideCustomColor.js b/docs/data/material/customization/palette/ManuallyProvideCustomColor.js new file mode 100644 index 00000000000000..1cc610f8740d42 --- /dev/null +++ b/docs/data/material/customization/palette/ManuallyProvideCustomColor.js @@ -0,0 +1,42 @@ +import * as React from 'react'; +import { createTheme, ThemeProvider } from '@mui/material/styles'; +import Button from '@mui/material/Button'; +import { Box, Stack } from '@mui/system'; +import { Typography } from '@mui/material'; + +const theme = createTheme({ + palette: { + ochre: { + main: '#E3D026', + light: '#E9DB5D', + dark: '#A29415', + contrastText: '#242105', + }, + }, +}); + +export default function Palette() { + return ( + + + + + + light + + + + main + + + + dark + + + + + + ); +} diff --git a/docs/data/material/customization/palette/ManuallyProvideCustomColor.tsx b/docs/data/material/customization/palette/ManuallyProvideCustomColor.tsx new file mode 100644 index 00000000000000..5ce5415cd030c4 --- /dev/null +++ b/docs/data/material/customization/palette/ManuallyProvideCustomColor.tsx @@ -0,0 +1,60 @@ +import * as React from 'react'; +import { createTheme, ThemeProvider } from '@mui/material/styles'; +import Button from '@mui/material/Button'; +import { Box, Stack } from '@mui/system'; +import { Typography } from '@mui/material'; + +// Augment the palette to include an ochre color +declare module '@mui/material/styles' { + interface Palette { + ochre: Palette['primary']; + } + + interface PaletteOptions { + ochre?: PaletteOptions['primary']; + } +} + +// Update the Button's color options to include an ochre option +declare module '@mui/material/Button' { + interface ButtonPropsColorOverrides { + ochre: true; + } +} + +const theme = createTheme({ + palette: { + ochre: { + main: '#E3D026', + light: '#E9DB5D', + dark: '#A29415', + contrastText: '#242105', + }, + }, +}); + +export default function Palette() { + return ( + + + + + + light + + + + main + + + + dark + + + + + + ); +} diff --git a/docs/data/material/customization/palette/ManuallyProvideCustomColor.tsx.preview b/docs/data/material/customization/palette/ManuallyProvideCustomColor.tsx.preview new file mode 100644 index 00000000000000..c81e9d503e5719 --- /dev/null +++ b/docs/data/material/customization/palette/ManuallyProvideCustomColor.tsx.preview @@ -0,0 +1,12 @@ +import { createTheme } from '@mui/material/styles'; + +const theme = createTheme({ + palette: { + ochre: { + main: '#E3D026', + light: '#E9DB5D', + dark: '#A29415', + contrastText: '#242105', + }, + }, +}); diff --git a/docs/data/material/customization/palette/ManuallyProvidePaletteColor.js b/docs/data/material/customization/palette/ManuallyProvidePaletteColor.js new file mode 100644 index 00000000000000..486fdcfacbf47f --- /dev/null +++ b/docs/data/material/customization/palette/ManuallyProvidePaletteColor.js @@ -0,0 +1,58 @@ +import * as React from 'react'; +import { createTheme, ThemeProvider } from '@mui/material/styles'; +import Button from '@mui/material/Button'; +import { Box, Stack } from '@mui/system'; +import { unstable_capitalize as capitalize } from '@mui/utils'; +import { Typography } from '@mui/material'; + +const theme = createTheme({ + palette: { + primary: { + main: '#FF5733', + // light: will be calculated from palette.primary.main, + // dark: will be calculated from palette.primary.main, + // contrastText: will be calculated to contrast with palette.primary.main + }, + secondary: { + main: '#E0C2FF', + light: '#F5EBFF', + // dark: will be calculated from palette.secondary.main, + contrastText: '#47008F', + }, + }, +}); + +function ColorShowcase({ color }) { + return ( + + + + + light + + + + main + + + + dark + + + + + ); +} + +export default function Palette() { + return ( + + + + + + + ); +} diff --git a/docs/data/material/customization/palette/ManuallyProvidePaletteColor.tsx b/docs/data/material/customization/palette/ManuallyProvidePaletteColor.tsx new file mode 100644 index 00000000000000..3fce59774a0eb3 --- /dev/null +++ b/docs/data/material/customization/palette/ManuallyProvidePaletteColor.tsx @@ -0,0 +1,58 @@ +import * as React from 'react'; +import { createTheme, ThemeProvider } from '@mui/material/styles'; +import Button from '@mui/material/Button'; +import { Box, Stack } from '@mui/system'; +import { unstable_capitalize as capitalize } from '@mui/utils'; +import { Typography } from '@mui/material'; + +const theme = createTheme({ + palette: { + primary: { + main: '#FF5733', + // light: will be calculated from palette.primary.main, + // dark: will be calculated from palette.primary.main, + // contrastText: will be calculated to contrast with palette.primary.main + }, + secondary: { + main: '#E0C2FF', + light: '#F5EBFF', + // dark: will be calculated from palette.secondary.main, + contrastText: '#47008F', + }, + }, +}); + +function ColorShowcase({ color }: { color: 'primary' | 'secondary' }) { + return ( + + + + + light + + + + main + + + + dark + + + + + ); +} + +export default function Palette() { + return ( + + + + + + + ); +} diff --git a/docs/data/material/customization/palette/ManuallyProvidePaletteColor.tsx.preview b/docs/data/material/customization/palette/ManuallyProvidePaletteColor.tsx.preview new file mode 100644 index 00000000000000..3b1f010f2dc3cf --- /dev/null +++ b/docs/data/material/customization/palette/ManuallyProvidePaletteColor.tsx.preview @@ -0,0 +1,18 @@ +import { createTheme } from '@mui/material/styles'; + +const theme = createTheme({ + palette: { + primary: { + main: '#FF5733', + // light: will be calculated from palette.primary.main, + // dark: will be calculated from palette.primary.main, + // contrastText: will be calculated to contrast with palette.primary.main + }, + secondary: { + main: '#E0C2FF', + light: '#F5EBFF', + // dark: will be calculated from palette.secondary.main, + contrastText: '#47008F', + }, + }, +}); diff --git a/docs/data/material/customization/palette/TonalOffset.js b/docs/data/material/customization/palette/TonalOffset.js new file mode 100644 index 00000000000000..35d2cbf218fae3 --- /dev/null +++ b/docs/data/material/customization/palette/TonalOffset.js @@ -0,0 +1,86 @@ +import * as React from 'react'; +import { createTheme, ThemeProvider, useTheme } from '@mui/material/styles'; +import { blue } from '@mui/material/colors'; +import { Box, Stack } from '@mui/system'; +import { Typography } from '@mui/material'; + +const defaultTonalOffsetTheme = createTheme({ + palette: { + primary: { + main: blue[500], + }, + }, +}); + +const higherTonalOffsetTheme = createTheme({ + palette: { + primary: { + main: blue[500], + }, + tonalOffset: 0.5, + }, +}); + +const asymmetricTonalOffsetTheme = createTheme({ + palette: { + primary: { + main: blue[500], + }, + tonalOffset: { + light: 0.1, + dark: 0.9, + }, + }, +}); + +function ColorShowcase({ title, color }) { + const { + palette: { tonalOffset }, + } = useTheme(); + + let caption; + if (typeof tonalOffset === 'number') { + caption = tonalOffset; + } else { + caption = `{ light: ${tonalOffset.light}, dark: ${tonalOffset.dark} }`; + } + + return ( + + + {title} + + {caption} + + + light + + + + main + + + + dark + + + + + ); +} + +export default function TonalOffset() { + return ( + + + + + + + + + + + + ); +} diff --git a/docs/data/material/customization/palette/TonalOffset.tsx b/docs/data/material/customization/palette/TonalOffset.tsx new file mode 100644 index 00000000000000..f2f8e34e43b424 --- /dev/null +++ b/docs/data/material/customization/palette/TonalOffset.tsx @@ -0,0 +1,86 @@ +import * as React from 'react'; +import { createTheme, ThemeProvider, useTheme } from '@mui/material/styles'; +import { blue } from '@mui/material/colors'; +import { Box, Stack } from '@mui/system'; +import { Typography } from '@mui/material'; + +const defaultTonalOffsetTheme = createTheme({ + palette: { + primary: { + main: blue[500], + }, + }, +}); + +const higherTonalOffsetTheme = createTheme({ + palette: { + primary: { + main: blue[500], + }, + tonalOffset: 0.5, + }, +}); + +const asymmetricTonalOffsetTheme = createTheme({ + palette: { + primary: { + main: blue[500], + }, + tonalOffset: { + light: 0.1, + dark: 0.9, + }, + }, +}); + +function ColorShowcase({ title, color }: { title: string; color: string }) { + const { + palette: { tonalOffset }, + } = useTheme(); + + let caption; + if (typeof tonalOffset === 'number') { + caption = tonalOffset; + } else { + caption = `{ light: ${tonalOffset.light}, dark: ${tonalOffset.dark} }`; + } + + return ( + + + {title} + + {caption} + + + light + + + + main + + + + dark + + + + + ); +} + +export default function TonalOffset() { + return ( + + + + + + + + + + + + ); +} diff --git a/docs/data/material/customization/palette/UsingAugmentColor.js b/docs/data/material/customization/palette/UsingAugmentColor.js new file mode 100644 index 00000000000000..5d7919258d4f16 --- /dev/null +++ b/docs/data/material/customization/palette/UsingAugmentColor.js @@ -0,0 +1,48 @@ +import * as React from 'react'; +import { createTheme, ThemeProvider } from '@mui/material/styles'; +import Button from '@mui/material/Button'; +import { Box, Stack } from '@mui/system'; +import { Typography } from '@mui/material'; + +let theme = createTheme({ + // Theme customization goes here as usual, including tonalOffset and/or + // contrastThreshold as the augmentColor() function relies on these +}); + +theme = createTheme(theme, { + // Custom colors created with augmentColor go here + palette: { + salmon: theme.palette.augmentColor({ + color: { + main: '#FF5733', + }, + name: 'salmon', + }), + }, +}); + +export default function Palette() { + return ( + + + + + + light + + + + main + + + + dark + + + + + + ); +} diff --git a/docs/data/material/customization/palette/UsingAugmentColor.tsx b/docs/data/material/customization/palette/UsingAugmentColor.tsx new file mode 100644 index 00000000000000..156772c3cca3a4 --- /dev/null +++ b/docs/data/material/customization/palette/UsingAugmentColor.tsx @@ -0,0 +1,66 @@ +import * as React from 'react'; +import { createTheme, ThemeProvider } from '@mui/material/styles'; +import Button from '@mui/material/Button'; +import { Box, Stack } from '@mui/system'; +import { Typography } from '@mui/material'; + +// Augment the palette to include a salmon color +declare module '@mui/material/styles' { + interface Palette { + salmon: Palette['primary']; + } + + interface PaletteOptions { + salmon?: PaletteOptions['primary']; + } +} + +// Update the Button's color options to include a salmon option +declare module '@mui/material/Button' { + interface ButtonPropsColorOverrides { + salmon: true; + } +} + +let theme = createTheme({ + // Theme customization goes here as usual, including tonalOffset and/or + // contrastThreshold as the augmentColor() function relies on these +}); + +theme = createTheme(theme, { + // Custom colors created with augmentColor go here + palette: { + salmon: theme.palette.augmentColor({ + color: { + main: '#FF5733', + }, + name: 'salmon', + }), + }, +}); + +export default function Palette() { + return ( + + + + + + light + + + + main + + + + dark + + + + + + ); +} diff --git a/docs/data/material/customization/palette/UsingAugmentColor.tsx.preview b/docs/data/material/customization/palette/UsingAugmentColor.tsx.preview new file mode 100644 index 00000000000000..f87bb4a7cbbfdc --- /dev/null +++ b/docs/data/material/customization/palette/UsingAugmentColor.tsx.preview @@ -0,0 +1,18 @@ +import { createTheme } from '@mui/material/styles'; + +let theme = createTheme({ + // Theme customization goes here as usual, including tonalOffset and/or + // contrastThreshold as the augmentColor() function relies on these +}); + +theme = createTheme(theme, { + // Custom colors created with augmentColor go here + palette: { + salmon: theme.palette.augmentColor({ + color: { + main: '#FF5733', + }, + name: 'salmon', + }), + }, +}); diff --git a/docs/data/material/customization/palette/UsingColorObject.js b/docs/data/material/customization/palette/UsingColorObject.js new file mode 100644 index 00000000000000..10563367b5fb76 --- /dev/null +++ b/docs/data/material/customization/palette/UsingColorObject.js @@ -0,0 +1,25 @@ +import * as React from 'react'; +import { createTheme, ThemeProvider } from '@mui/material/styles'; +import { lime, purple } from '@mui/material/colors'; +import Button from '@mui/material/Button'; +import { Stack } from '@mui/system'; + +const theme = createTheme({ + palette: { + primary: lime, + secondary: purple, + }, +}); + +export default function Palette() { + return ( + + + + + + + ); +} diff --git a/docs/data/material/customization/palette/UsingColorObject.tsx b/docs/data/material/customization/palette/UsingColorObject.tsx new file mode 100644 index 00000000000000..10563367b5fb76 --- /dev/null +++ b/docs/data/material/customization/palette/UsingColorObject.tsx @@ -0,0 +1,25 @@ +import * as React from 'react'; +import { createTheme, ThemeProvider } from '@mui/material/styles'; +import { lime, purple } from '@mui/material/colors'; +import Button from '@mui/material/Button'; +import { Stack } from '@mui/system'; + +const theme = createTheme({ + palette: { + primary: lime, + secondary: purple, + }, +}); + +export default function Palette() { + return ( + + + + + + + ); +} diff --git a/docs/data/material/customization/palette/UsingColorObject.tsx.preview b/docs/data/material/customization/palette/UsingColorObject.tsx.preview new file mode 100644 index 00000000000000..d2ff5249809ef5 --- /dev/null +++ b/docs/data/material/customization/palette/UsingColorObject.tsx.preview @@ -0,0 +1,9 @@ +import { createTheme } from '@mui/material/styles'; +import { lime, purple } from '@mui/material/colors'; + +const theme = createTheme({ + palette: { + primary: lime, + secondary: purple, + }, +}); diff --git a/docs/data/material/customization/palette/UsingStylesUtils.js b/docs/data/material/customization/palette/UsingStylesUtils.js new file mode 100644 index 00000000000000..a049bfbfadbd68 --- /dev/null +++ b/docs/data/material/customization/palette/UsingStylesUtils.js @@ -0,0 +1,50 @@ +import * as React from 'react'; +import { + createTheme, + ThemeProvider, + alpha, + getContrastRatio, +} from '@mui/material/styles'; +import Button from '@mui/material/Button'; +import { Box, Stack } from '@mui/system'; +import { Typography } from '@mui/material'; + +const violetBase = '#7F00FF'; +const violetMain = alpha(violetBase, 0.7); + +const theme = createTheme({ + palette: { + violet: { + main: violetMain, + light: alpha(violetBase, 0.5), + dark: alpha(violetBase, 0.9), + contrastText: getContrastRatio(violetMain, '#fff') > 4.5 ? '#fff' : '#111', + }, + }, +}); + +export default function Palette() { + return ( + + + + + + light + + + + main + + + + dark + + + + + + ); +} diff --git a/docs/data/material/customization/palette/UsingStylesUtils.tsx b/docs/data/material/customization/palette/UsingStylesUtils.tsx new file mode 100644 index 00000000000000..81b585ab5f5030 --- /dev/null +++ b/docs/data/material/customization/palette/UsingStylesUtils.tsx @@ -0,0 +1,68 @@ +import * as React from 'react'; +import { + createTheme, + ThemeProvider, + alpha, + getContrastRatio, +} from '@mui/material/styles'; +import Button from '@mui/material/Button'; +import { Box, Stack } from '@mui/system'; +import { Typography } from '@mui/material'; + +// Augment the palette to include a violet color +declare module '@mui/material/styles' { + interface Palette { + violet: Palette['primary']; + } + + interface PaletteOptions { + violet?: PaletteOptions['primary']; + } +} + +// Update the Button's color options to include a violet option +declare module '@mui/material/Button' { + interface ButtonPropsColorOverrides { + violet: true; + } +} + +const violetBase = '#7F00FF'; +const violetMain = alpha(violetBase, 0.7); + +const theme = createTheme({ + palette: { + violet: { + main: violetMain, + light: alpha(violetBase, 0.5), + dark: alpha(violetBase, 0.9), + contrastText: getContrastRatio(violetMain, '#fff') > 4.5 ? '#fff' : '#111', + }, + }, +}); + +export default function Palette() { + return ( + + + + + + light + + + + main + + + + dark + + + + + + ); +} diff --git a/docs/data/material/customization/palette/UsingStylesUtils.tsx.preview b/docs/data/material/customization/palette/UsingStylesUtils.tsx.preview new file mode 100644 index 00000000000000..1f164d21ef5cab --- /dev/null +++ b/docs/data/material/customization/palette/UsingStylesUtils.tsx.preview @@ -0,0 +1,15 @@ +import { createTheme, alpha, getContrastRatio } from '@mui/material/styles'; + +const violetBase = '#7F00FF'; +const violetMain = alpha(violetBase, 0.7); + +const theme = createTheme({ + palette: { + violet: { + main: violetMain, + light: alpha(violetBase, 0.5), + dark: alpha(violetBase, 0.9), + contrastText: getContrastRatio(violetMain, '#fff') > 4.5 ? '#fff' : '#111', + }, + }, +}); diff --git a/docs/data/material/customization/palette/palette.md b/docs/data/material/customization/palette/palette.md index e563ed3aed1e9c..41d9877e7cf57a 100644 --- a/docs/data/material/customization/palette/palette.md +++ b/docs/data/material/customization/palette/palette.md @@ -2,29 +2,51 @@

The palette enables you to modify the color of the components to suit your brand.

-## Palette colors +## Color tokens -The theme exposes the following palette colors (accessible under `theme.palette.`): +Palette colors are represented by four tokens: -- _primary_ - used to represent primary interface elements for a user. It's the color displayed most frequently across your app's screens and components. -- _secondary_ - used to represent secondary interface elements for a user. It provides more ways to accent and distinguish your product. Having it is optional. -- _error_ - used to represent interface elements that the user should be made aware of. -- _warning_ - used to represent potentially dangerous actions or important messages. -- _info_ - used to present information to the user that is neutral and not necessarily important. -- _success_ - used to indicate the successful completion of an action that user triggered. +- `main`: The main shade of the color +- `light`: A lighter shade of `main` +- `dark`: A darker shade of `main` +- `contrastText`: Text color, intended to contrast with `main` -If you want to learn more about color, you can check out [the color section](/material-ui/customization/color/). +Here's how Material UI's default theme defines the primary color tokens: -## Default values +```js +const primary = { + main: '#1976d2', + light: '#42a5f5', + dark: '#1565c0', + contrastText: '#fff', +}; +``` + +See the [Color](/material-ui/customization/color/) documentation for details on the Material Design color system. + +## Default colors + +The theme exposes the following default palette colors (accessible under `theme.palette.*`): + +- `primary` - for primary interface elements. +- `secondary` - for secondary interface elements. +- `error` - for elements that the user should be made aware of. +- `warning` - for potentially dangerous actions or important messages. +- `info` - for highlighting neutral information. +- `success` - for indicating the successful completion of an action that the user triggered. -You can explore the default values of the palette using [the theme explorer](/material-ui/customization/default-theme/?expand-path=$.palette) or by opening the dev tools console on this page (`window.theme.palette`). +See Material Design's [Color System](https://m2.material.io/design/color/the-color-system.html) for details on color usage and guidelines. + +### Values + +You can explore the default palette values using [the theme explorer](/material-ui/customization/default-theme/?expand-path=$.palette), or by opening the dev tools console on this page (`window.theme.palette`). {{"demo": "Intentions.js", "bg": "inline", "hideToolbar": true}} The default palette uses the shades prefixed with `A` (`A200`, etc.) for the secondary palette color, and the un-prefixed shades for the other palette colors. -## Customization +### Customization You may override the default palette values by including a palette object as part of your theme. If any of the: @@ -38,173 +60,128 @@ If any of the: palette color objects are provided, they will replace the default ones. -The palette color value can either be a [color](/material-ui/customization/color/#2014-material-design-color-palettes) object, or an object with one or more of the keys specified by the following TypeScript interface: +This can be achieved by either using a color object or by providing the colors directly: -```ts -interface PaletteColor { - light?: string; - main: string; - dark?: string; - contrastText?: string; -} -``` +#### Using a color object -### Using a color object +The most direct way to customize a palette color is to import and apply one or more [color objects](/material-ui/customization/color/#2014-material-design-color-palettes), as shown below: -The simplest way to customize a palette color is to import one or more of the provided colors -and apply them: +{{"demo": "UsingColorObject.js", "defaultCodeOpen": true }} -```js -import { createTheme } from '@mui/material/styles'; -import blue from '@mui/material/colors/blue'; +#### Providing the colors directly -const theme = createTheme({ - palette: { - primary: blue, - }, -}); -``` +To modify each color directly, provide an object with one or more of the color tokens. +Only the `main` token is required; `light`, `dark`, and `contrastText` are optional, and if not provided, then their values are calculated automatically: -### Providing the colors directly +{{"demo": "ManuallyProvidePaletteColor.js" }} -If you wish to provide more customized colors, you can either create your own palette color, -or directly supply colors to some or all of the `theme.palette` keys: +### Contrast threshold -```js -import { createTheme } from '@mui/material/styles'; +The `contrastText` token is calculated using the `contrastThreshold` value, to maximize the contrast between the background and the text. -const theme = createTheme({ - palette: { - primary: { - // light: will be calculated from palette.primary.main, - main: '#ff4400', - // dark: will be calculated from palette.primary.main, - // contrastText: will be calculated to contrast with palette.primary.main - }, - secondary: { - light: '#0066ff', - main: '#0044ff', - // dark: will be calculated from palette.secondary.main, - contrastText: '#ffcc00', - }, - // Provide every color token (light, main, dark, and contrastText) when using - // custom colors for props in Material UI's components. - // Then you will be able to use it like this: `