Skip to content

Commit 49989b1

Browse files
DiegoAndaiDiegoAndai
authoredJul 21, 2023
[docs][material] Improve documentation about adding custom colors (#37743)
·
v7.0.1v5.14.2
1 parent 35291e7 commit 49989b1

31 files changed

+1087
-147
lines changed
 

‎docs/data/material/components/buttons/buttons-pt.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ Note that the documentation [avoids](/material-ui/guides/api/#native-properties)
7171

7272
{{"demo": "ColorButtons.js"}}
7373

74-
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.
74+
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.
7575

7676
## Tamanhos
7777

‎docs/data/material/components/buttons/buttons-zh.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ Note that the documentation [avoids](/material-ui/guides/api/#native-properties)
7171

7272
{{"demo": "ColorButtons.js"}}
7373

74-
除了使用默认按钮颜色外，您可以添加自定义颜色，或者禁用任何您不需要的颜色。 See the [Adding new colors](/material-ui/customization/palette/#adding-new-colors) example for more info.
74+
除了使用默认按钮颜色外，您可以添加自定义颜色，或者禁用任何您不需要的颜色。 See the [Adding new colors](/material-ui/customization/palette/#custom-colors) examples for more info.
7575

7676
## 尺寸
7777

‎docs/data/material/components/buttons/buttons.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ Note that the documentation [avoids](/material-ui/guides/api/#native-properties)
7777

7878
{{"demo": "ColorButtons.js"}}
7979

80-
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.
80+
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.
8181

8282
## Sizes
8383

‎docs/data/material/customization/palette/AddingColorTokens.js

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
import * as React from 'react';
2+
import { createTheme, ThemeProvider } from '@mui/material/styles';
3+
import { blue } from '@mui/material/colors';
4+
import { Box, Stack } from '@mui/system';
5+
import { Typography } from '@mui/material';
6+
7+
const theme = createTheme({
8+
palette: {
9+
primary: {
10+
light: blue[300],
11+
main: blue[500],
12+
dark: blue[700],
13+
darker: blue[900],
14+
},
15+
},
16+
});
17+
18+
export default function AddingColorTokens() {
19+
return (
20+
<ThemeProvider theme={theme}>
21+
<Stack direction="row" gap={1}>
22+
<Stack alignItems="center">
23+
<Typography variant="body2">light</Typography>
24+
<Box sx={{ bgcolor: `primary.light`, width: 40, height: 20 }} />
25+
</Stack>
26+
<Stack alignItems="center">
27+
<Typography variant="body2">main</Typography>
28+
<Box sx={{ bgcolor: `primary.main`, width: 40, height: 20 }} />
29+
</Stack>
30+
<Stack alignItems="center">
31+
<Typography variant="body2">dark</Typography>
32+
<Box sx={{ bgcolor: `primary.dark`, width: 40, height: 20 }} />
33+
</Stack>
34+
<Stack alignItems="center">
35+
<Typography variant="body2">darker</Typography>
36+
<Box sx={{ bgcolor: `primary.darker`, width: 40, height: 20 }} />
37+
</Stack>
38+
</Stack>
39+
</ThemeProvider>
40+
);
41+
}

‎docs/data/material/customization/palette/AddingColorTokens.tsx

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
import * as React from 'react';
2+
import { createTheme, ThemeProvider } from '@mui/material/styles';
3+
import { blue } from '@mui/material/colors';
4+
import { Box, Stack } from '@mui/system';
5+
import { Typography } from '@mui/material';
6+
7+
declare module '@mui/material/styles' {
8+
interface PaletteColor {
9+
darker?: string;
10+
}
11+
12+
interface SimplePaletteColorOptions {
13+
darker?: string;
14+
}
15+
}
16+
17+
const theme = createTheme({
18+
palette: {
19+
primary: {
20+
light: blue[300],
21+
main: blue[500],
22+
dark: blue[700],
23+
darker: blue[900],
24+
},
25+
},
26+
});
27+
28+
export default function AddingColorTokens() {
29+
return (
30+
<ThemeProvider theme={theme}>
31+
<Stack direction="row" gap={1}>
32+
<Stack alignItems="center">
33+
<Typography variant="body2">light</Typography>
34+
<Box sx={{ bgcolor: `primary.light`, width: 40, height: 20 }} />
35+
</Stack>
36+
<Stack alignItems="center">
37+
<Typography variant="body2">main</Typography>
38+
<Box sx={{ bgcolor: `primary.main`, width: 40, height: 20 }} />
39+
</Stack>
40+
<Stack alignItems="center">
41+
<Typography variant="body2">dark</Typography>
42+
<Box sx={{ bgcolor: `primary.dark`, width: 40, height: 20 }} />
43+
</Stack>
44+
<Stack alignItems="center">
45+
<Typography variant="body2">darker</Typography>
46+
<Box sx={{ bgcolor: `primary.darker`, width: 40, height: 20 }} />
47+
</Stack>
48+
</Stack>
49+
</ThemeProvider>
50+
);
51+
}

‎docs/data/material/customization/palette/AddingColorTokens.tsx.preview

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
import { createTheme } from '@mui/material/styles';
2+
import { blue } from '@mui/material/colors';
3+
4+
const theme = createTheme({
5+
palette: {
6+
primary: {
7+
light: blue[300],
8+
main: blue[500],
9+
dark: blue[700],
10+
darker: blue[900],
11+
},
12+
},
13+
});

‎docs/data/material/customization/palette/ContrastThreshold.js

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import * as React from 'react';
2+
import { createTheme, ThemeProvider, useTheme } from '@mui/material/styles';
3+
import Button from '@mui/material/Button';
4+
import { Stack } from '@mui/system';
5+
6+
const defaultContrastThresholdTheme = createTheme({});
7+
8+
const highContrastThresholdTheme = createTheme({
9+
palette: {
10+
contrastThreshold: 4.5,
11+
},
12+
});
13+
14+
function ContrastShowcase({ title }) {
15+
const theme = useTheme();
16+
17+
return (
18+
<Stack gap={1} alignItems="center">
19+
<span>
20+
<b>{title}</b>
21+
</span>
22+
<span>{theme.palette.contrastThreshold}:1</span>
23+
<Stack direction="row" gap={1}>
24+
<Button variant="contained" color="warning">
25+
Warning
26+
</Button>
27+
</Stack>
28+
</Stack>
29+
);
30+
}
31+
32+
export default function contrastThreshold() {
33+
return (
34+
<Stack direction="row" gap={4}>
35+
<ThemeProvider theme={defaultContrastThresholdTheme}>
36+
<ContrastShowcase title="Default contrast threshold" />
37+
</ThemeProvider>
38+
<ThemeProvider theme={highContrastThresholdTheme}>
39+
<ContrastShowcase title="Higher contrast threshold" />
40+
</ThemeProvider>
41+
</Stack>
42+
);
43+
}

‎docs/data/material/customization/palette/ContrastThreshold.tsx

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import * as React from 'react';
2+
import { createTheme, ThemeProvider, useTheme } from '@mui/material/styles';
3+
import Button from '@mui/material/Button';
4+
import { Stack } from '@mui/system';
5+
6+
const defaultContrastThresholdTheme = createTheme({});
7+
8+
const highContrastThresholdTheme = createTheme({
9+
palette: {
10+
contrastThreshold: 4.5,
11+
},
12+
});
13+
14+
function ContrastShowcase({ title }: { title: string }) {
15+
const theme = useTheme();
16+
17+
return (
18+
<Stack gap={1} alignItems="center">
19+
<span>
20+
<b>{title}</b>
21+
</span>
22+
<span>{theme.palette.contrastThreshold}:1</span>
23+
<Stack direction="row" gap={1}>
24+
<Button variant="contained" color="warning">
25+
Warning
26+
</Button>
27+
</Stack>
28+
</Stack>
29+
);
30+
}
31+
32+
export default function contrastThreshold() {
33+
return (
34+
<Stack direction="row" gap={4}>
35+
<ThemeProvider theme={defaultContrastThresholdTheme}>
36+
<ContrastShowcase title="Default contrast threshold" />
37+
</ThemeProvider>
38+
<ThemeProvider theme={highContrastThresholdTheme}>
39+
<ContrastShowcase title="Higher contrast threshold" />
40+
</ThemeProvider>
41+
</Stack>
42+
);
43+
}

‎docs/data/material/customization/palette/CustomColor.js

+3-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@ import Button from '@mui/material/Button';
55
const theme = createTheme({
66
palette: {
77
neutral: {
8-
main: '#64748B',
8+
light: '#838fa2',
9+
main: '#64748b',
10+
dark: '#465161',
911
contrastText: '#fff',
1012
},
1113
},

‎docs/data/material/customization/palette/CustomColor.tsx

+3-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@ import Button from '@mui/material/Button';
55
const theme = createTheme({
66
palette: {
77
neutral: {
8-
main: '#64748B',
8+
light: '#838fa2',
9+
main: '#64748b',
10+
dark: '#465161',
911
contrastText: '#fff',
1012
},
1113
},

‎docs/data/material/customization/palette/ManuallyProvideCustomColor.js

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import * as React from 'react';
2+
import { createTheme, ThemeProvider } from '@mui/material/styles';
3+
import Button from '@mui/material/Button';
4+
import { Box, Stack } from '@mui/system';
5+
import { Typography } from '@mui/material';
6+
7+
const theme = createTheme({
8+
palette: {
9+
ochre: {
10+
main: '#E3D026',
11+
light: '#E9DB5D',
12+
dark: '#A29415',
13+
contrastText: '#242105',
14+
},
15+
},
16+
});
17+
18+
export default function Palette() {
19+
return (
20+
<ThemeProvider theme={theme}>
21+
<Stack gap={2} alignItems="center">
22+
<Button variant="contained" color="ochre">
23+
Ochre
24+
</Button>
25+
<Stack direction="row" gap={1}>
26+
<Stack alignItems="center">
27+
<Typography variant="body2">light</Typography>
28+
<Box sx={{ bgcolor: 'ochre.light', width: 40, height: 20 }} />
29+
</Stack>
30+
<Stack alignItems="center">
31+
<Typography variant="body2">main</Typography>
32+
<Box sx={{ bgcolor: 'ochre.main', width: 40, height: 20 }} />
33+
</Stack>
34+
<Stack alignItems="center">
35+
<Typography variant="body2">dark</Typography>
36+
<Box sx={{ bgcolor: 'ochre.dark', width: 40, height: 20 }} />
37+
</Stack>
38+
</Stack>
39+
</Stack>
40+
</ThemeProvider>
41+
);
42+
}

‎docs/data/material/customization/palette/ManuallyProvideCustomColor.tsx

+60
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
import * as React from 'react';
2+
import { createTheme, ThemeProvider } from '@mui/material/styles';
3+
import Button from '@mui/material/Button';
4+
import { Box, Stack } from '@mui/system';
5+
import { Typography } from '@mui/material';
6+
7+
// Augment the palette to include an ochre color
8+
declare module '@mui/material/styles' {
9+
interface Palette {
10+
ochre: Palette['primary'];
11+
}
12+
13+
interface PaletteOptions {
14+
ochre?: PaletteOptions['primary'];
15+
}
16+
}
17+
18+
// Update the Button's color options to include an ochre option
19+
declare module '@mui/material/Button' {
20+
interface ButtonPropsColorOverrides {
21+
ochre: true;
22+
}
23+
}
24+
25+
const theme = createTheme({
26+
palette: {
27+
ochre: {
28+
main: '#E3D026',
29+
light: '#E9DB5D',
30+
dark: '#A29415',
31+
contrastText: '#242105',
32+
},
33+
},
34+
});
35+
36+
export default function Palette() {
37+
return (
38+
<ThemeProvider theme={theme}>
39+
<Stack gap={2} alignItems="center">
40+
<Button variant="contained" color="ochre">
41+
Ochre
42+
</Button>
43+
<Stack direction="row" gap={1}>
44+
<Stack alignItems="center">
45+
<Typography variant="body2">light</Typography>
46+
<Box sx={{ bgcolor: 'ochre.light', width: 40, height: 20 }} />
47+
</Stack>
48+
<Stack alignItems="center">
49+
<Typography variant="body2">main</Typography>
50+
<Box sx={{ bgcolor: 'ochre.main', width: 40, height: 20 }} />
51+
</Stack>
52+
<Stack alignItems="center">
53+
<Typography variant="body2">dark</Typography>
54+
<Box sx={{ bgcolor: 'ochre.dark', width: 40, height: 20 }} />
55+
</Stack>
56+
</Stack>
57+
</Stack>
58+
</ThemeProvider>
59+
);
60+
}

‎docs/data/material/customization/palette/ManuallyProvideCustomColor.tsx.preview

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
import { createTheme } from '@mui/material/styles';
2+
3+
const theme = createTheme({
4+
palette: {
5+
ochre: {
6+
main: '#E3D026',
7+
light: '#E9DB5D',
8+
dark: '#A29415',
9+
contrastText: '#242105',
10+
},
11+
},
12+
});

‎docs/data/material/customization/palette/ManuallyProvidePaletteColor.js

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
import * as React from 'react';
2+
import { createTheme, ThemeProvider } from '@mui/material/styles';
3+
import Button from '@mui/material/Button';
4+
import { Box, Stack } from '@mui/system';
5+
import { unstable_capitalize as capitalize } from '@mui/utils';
6+
import { Typography } from '@mui/material';
7+
8+
const theme = createTheme({
9+
palette: {
10+
primary: {
11+
main: '#FF5733',
12+
// light: will be calculated from palette.primary.main,
13+
// dark: will be calculated from palette.primary.main,
14+
// contrastText: will be calculated to contrast with palette.primary.main
15+
},
16+
secondary: {
17+
main: '#E0C2FF',
18+
light: '#F5EBFF',
19+
// dark: will be calculated from palette.secondary.main,
20+
contrastText: '#47008F',
21+
},
22+
},
23+
});
24+
25+
function ColorShowcase({ color }) {
26+
return (
27+
<Stack gap={2} alignItems="center">
28+
<Button variant="contained" color={color}>
29+
{capitalize(color)}
30+
</Button>
31+
<Stack direction="row" gap={1}>
32+
<Stack alignItems="center">
33+
<Typography variant="body2">light</Typography>
34+
<Box sx={{ bgcolor: `${color}.light`, width: 40, height: 20 }} />
35+
</Stack>
36+
<Stack alignItems="center">
37+
<Typography variant="body2">main</Typography>
38+
<Box sx={{ bgcolor: `${color}.main`, width: 40, height: 20 }} />
39+
</Stack>
40+
<Stack alignItems="center">
41+
<Typography variant="body2">dark</Typography>
42+
<Box sx={{ bgcolor: `${color}.dark`, width: 40, height: 20 }} />
43+
</Stack>
44+
</Stack>
45+
</Stack>
46+
);
47+
}
48+
49+
export default function Palette() {
50+
return (
51+
<ThemeProvider theme={theme}>
52+
<Stack direction="row" gap={8}>
53+
<ColorShowcase color="primary" />
54+
<ColorShowcase color="secondary" />
55+
</Stack>
56+
</ThemeProvider>
57+
);
58+
}

‎docs/data/material/customization/palette/ManuallyProvidePaletteColor.tsx

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
import * as React from 'react';
2+
import { createTheme, ThemeProvider } from '@mui/material/styles';
3+
import Button from '@mui/material/Button';
4+
import { Box, Stack } from '@mui/system';
5+
import { unstable_capitalize as capitalize } from '@mui/utils';
6+
import { Typography } from '@mui/material';
7+
8+
const theme = createTheme({
9+
palette: {
10+
primary: {
11+
main: '#FF5733',
12+
// light: will be calculated from palette.primary.main,
13+
// dark: will be calculated from palette.primary.main,
14+
// contrastText: will be calculated to contrast with palette.primary.main
15+
},
16+
secondary: {
17+
main: '#E0C2FF',
18+
light: '#F5EBFF',
19+
// dark: will be calculated from palette.secondary.main,
20+
contrastText: '#47008F',
21+
},
22+
},
23+
});
24+
25+
function ColorShowcase({ color }: { color: 'primary' | 'secondary' }) {
26+
return (
27+
<Stack gap={2} alignItems="center">
28+
<Button variant="contained" color={color}>
29+
{capitalize(color)}
30+
</Button>
31+
<Stack direction="row" gap={1}>
32+
<Stack alignItems="center">
33+
<Typography variant="body2">light</Typography>
34+
<Box sx={{ bgcolor: `${color}.light`, width: 40, height: 20 }} />
35+
</Stack>
36+
<Stack alignItems="center">
37+
<Typography variant="body2">main</Typography>
38+
<Box sx={{ bgcolor: `${color}.main`, width: 40, height: 20 }} />
39+
</Stack>
40+
<Stack alignItems="center">
41+
<Typography variant="body2">dark</Typography>
42+
<Box sx={{ bgcolor: `${color}.dark`, width: 40, height: 20 }} />
43+
</Stack>
44+
</Stack>
45+
</Stack>
46+
);
47+
}
48+
49+
export default function Palette() {
50+
return (
51+
<ThemeProvider theme={theme}>
52+
<Stack direction="row" gap={8}>
53+
<ColorShowcase color="primary" />
54+
<ColorShowcase color="secondary" />
55+
</Stack>
56+
</ThemeProvider>
57+
);
58+
}

‎docs/data/material/customization/palette/ManuallyProvidePaletteColor.tsx.preview

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
import { createTheme } from '@mui/material/styles';
2+
3+
const theme = createTheme({
4+
palette: {
5+
primary: {
6+
main: '#FF5733',
7+
// light: will be calculated from palette.primary.main,
8+
// dark: will be calculated from palette.primary.main,
9+
// contrastText: will be calculated to contrast with palette.primary.main
10+
},
11+
secondary: {
12+
main: '#E0C2FF',
13+
light: '#F5EBFF',
14+
// dark: will be calculated from palette.secondary.main,
15+
contrastText: '#47008F',
16+
},
17+
},
18+
});

‎docs/data/material/customization/palette/TonalOffset.js

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
import * as React from 'react';
2+
import { createTheme, ThemeProvider, useTheme } from '@mui/material/styles';
3+
import { blue } from '@mui/material/colors';
4+
import { Box, Stack } from '@mui/system';
5+
import { Typography } from '@mui/material';
6+
7+
const defaultTonalOffsetTheme = createTheme({
8+
palette: {
9+
primary: {
10+
main: blue[500],
11+
},
12+
},
13+
});
14+
15+
const higherTonalOffsetTheme = createTheme({
16+
palette: {
17+
primary: {
18+
main: blue[500],
19+
},
20+
tonalOffset: 0.5,
21+
},
22+
});
23+
24+
const asymmetricTonalOffsetTheme = createTheme({
25+
palette: {
26+
primary: {
27+
main: blue[500],
28+
},
29+
tonalOffset: {
30+
light: 0.1,
31+
dark: 0.9,
32+
},
33+
},
34+
});
35+
36+
function ColorShowcase({ title, color }) {
37+
const {
38+
palette: { tonalOffset },
39+
} = useTheme();
40+
41+
let caption;
42+
if (typeof tonalOffset === 'number') {
43+
caption = tonalOffset;
44+
} else {
45+
caption = `{ light: ${tonalOffset.light}, dark: ${tonalOffset.dark} }`;
46+
}
47+
48+
return (
49+
<Stack gap={1} alignItems="center">
50+
<span>
51+
<b>{title}</b>
52+
</span>
53+
<span>{caption}</span>
54+
<Stack direction="row" gap={1}>
55+
<Stack alignItems="center">
56+
<Typography variant="body2">light</Typography>
57+
<Box sx={{ bgcolor: `${color}.light`, width: 40, height: 20 }} />
58+
</Stack>
59+
<Stack alignItems="center">
60+
<Typography variant="body2">main</Typography>
61+
<Box sx={{ bgcolor: `${color}.main`, width: 40, height: 20 }} />
62+
</Stack>
63+
<Stack alignItems="center">
64+
<Typography variant="body2">dark</Typography>
65+
<Box sx={{ bgcolor: `${color}.dark`, width: 40, height: 20 }} />
66+
</Stack>
67+
</Stack>
68+
</Stack>
69+
);
70+
}
71+
72+
export default function TonalOffset() {
73+
return (
74+
<Stack direction="row" gap={8}>
75+
<ThemeProvider theme={defaultTonalOffsetTheme}>
76+
<ColorShowcase title="Default tonal offset" color="primary" />
77+
</ThemeProvider>
78+
<ThemeProvider theme={higherTonalOffsetTheme}>
79+
<ColorShowcase title="Higher tonal offset" color="primary" />
80+
</ThemeProvider>
81+
<ThemeProvider theme={asymmetricTonalOffsetTheme}>
82+
<ColorShowcase title="Asymmetric tonal offset" color="primary" />
83+
</ThemeProvider>
84+
</Stack>
85+
);
86+
}

‎docs/data/material/customization/palette/TonalOffset.tsx

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
import * as React from 'react';
2+
import { createTheme, ThemeProvider, useTheme } from '@mui/material/styles';
3+
import { blue } from '@mui/material/colors';
4+
import { Box, Stack } from '@mui/system';
5+
import { Typography } from '@mui/material';
6+
7+
const defaultTonalOffsetTheme = createTheme({
8+
palette: {
9+
primary: {
10+
main: blue[500],
11+
},
12+
},
13+
});
14+
15+
const higherTonalOffsetTheme = createTheme({
16+
palette: {
17+
primary: {
18+
main: blue[500],
19+
},
20+
tonalOffset: 0.5,
21+
},
22+
});
23+
24+
const asymmetricTonalOffsetTheme = createTheme({
25+
palette: {
26+
primary: {
27+
main: blue[500],
28+
},
29+
tonalOffset: {
30+
light: 0.1,
31+
dark: 0.9,
32+
},
33+
},
34+
});
35+
36+
function ColorShowcase({ title, color }: { title: string; color: string }) {
37+
const {
38+
palette: { tonalOffset },
39+
} = useTheme();
40+
41+
let caption;
42+
if (typeof tonalOffset === 'number') {
43+
caption = tonalOffset;
44+
} else {
45+
caption = `{ light: ${tonalOffset.light}, dark: ${tonalOffset.dark} }`;
46+
}
47+
48+
return (
49+
<Stack gap={1} alignItems="center">
50+
<span>
51+
<b>{title}</b>
52+
</span>
53+
<span>{caption}</span>
54+
<Stack direction="row" gap={1}>
55+
<Stack alignItems="center">
56+
<Typography variant="body2">light</Typography>
57+
<Box sx={{ bgcolor: `${color}.light`, width: 40, height: 20 }} />
58+
</Stack>
59+
<Stack alignItems="center">
60+
<Typography variant="body2">main</Typography>
61+
<Box sx={{ bgcolor: `${color}.main`, width: 40, height: 20 }} />
62+
</Stack>
63+
<Stack alignItems="center">
64+
<Typography variant="body2">dark</Typography>
65+
<Box sx={{ bgcolor: `${color}.dark`, width: 40, height: 20 }} />
66+
</Stack>
67+
</Stack>
68+
</Stack>
69+
);
70+
}
71+
72+
export default function TonalOffset() {
73+
return (
74+
<Stack direction="row" gap={8}>
75+
<ThemeProvider theme={defaultTonalOffsetTheme}>
76+
<ColorShowcase title="Default tonal offset" color="primary" />
77+
</ThemeProvider>
78+
<ThemeProvider theme={higherTonalOffsetTheme}>
79+
<ColorShowcase title="Higher tonal offset" color="primary" />
80+
</ThemeProvider>
81+
<ThemeProvider theme={asymmetricTonalOffsetTheme}>
82+
<ColorShowcase title="Asymmetric tonal offset" color="primary" />
83+
</ThemeProvider>
84+
</Stack>
85+
);
86+
}

‎docs/data/material/customization/palette/UsingAugmentColor.js

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
import * as React from 'react';
2+
import { createTheme, ThemeProvider } from '@mui/material/styles';
3+
import Button from '@mui/material/Button';
4+
import { Box, Stack } from '@mui/system';
5+
import { Typography } from '@mui/material';
6+
7+
let theme = createTheme({
8+
// Theme customization goes here as usual, including tonalOffset and/or
9+
// contrastThreshold as the augmentColor() function relies on these
10+
});
11+
12+
theme = createTheme(theme, {
13+
// Custom colors created with augmentColor go here
14+
palette: {
15+
salmon: theme.palette.augmentColor({
16+
color: {
17+
main: '#FF5733',
18+
},
19+
name: 'salmon',
20+
}),
21+
},
22+
});
23+
24+
export default function Palette() {
25+
return (
26+
<ThemeProvider theme={theme}>
27+
<Stack gap={2} alignItems="center">
28+
<Button variant="contained" color="salmon">
29+
Salmon
30+
</Button>
31+
<Stack direction="row" gap={1}>
32+
<Stack alignItems="center">
33+
<Typography variant="body2">light</Typography>
34+
<Box sx={{ bgcolor: 'salmon.light', width: 40, height: 20 }} />
35+
</Stack>
36+
<Stack alignItems="center">
37+
<Typography variant="body2">main</Typography>
38+
<Box sx={{ bgcolor: 'salmon.main', width: 40, height: 20 }} />
39+
</Stack>
40+
<Stack alignItems="center">
41+
<Typography variant="body2">dark</Typography>
42+
<Box sx={{ bgcolor: 'salmon.dark', width: 40, height: 20 }} />
43+
</Stack>
44+
</Stack>
45+
</Stack>
46+
</ThemeProvider>
47+
);
48+
}

‎docs/data/material/customization/palette/UsingAugmentColor.tsx

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
import * as React from 'react';
2+
import { createTheme, ThemeProvider } from '@mui/material/styles';
3+
import Button from '@mui/material/Button';
4+
import { Box, Stack } from '@mui/system';
5+
import { Typography } from '@mui/material';
6+
7+
// Augment the palette to include a salmon color
8+
declare module '@mui/material/styles' {
9+
interface Palette {
10+
salmon: Palette['primary'];
11+
}
12+
13+
interface PaletteOptions {
14+
salmon?: PaletteOptions['primary'];
15+
}
16+
}
17+
18+
// Update the Button's color options to include a salmon option
19+
declare module '@mui/material/Button' {
20+
interface ButtonPropsColorOverrides {
21+
salmon: true;
22+
}
23+
}
24+
25+
let theme = createTheme({
26+
// Theme customization goes here as usual, including tonalOffset and/or
27+
// contrastThreshold as the augmentColor() function relies on these
28+
});
29+
30+
theme = createTheme(theme, {
31+
// Custom colors created with augmentColor go here
32+
palette: {
33+
salmon: theme.palette.augmentColor({
34+
color: {
35+
main: '#FF5733',
36+
},
37+
name: 'salmon',
38+
}),
39+
},
40+
});
41+
42+
export default function Palette() {
43+
return (
44+
<ThemeProvider theme={theme}>
45+
<Stack gap={2} alignItems="center">
46+
<Button variant="contained" color="salmon">
47+
Salmon
48+
</Button>
49+
<Stack direction="row" gap={1}>
50+
<Stack alignItems="center">
51+
<Typography variant="body2">light</Typography>
52+
<Box sx={{ bgcolor: 'salmon.light', width: 40, height: 20 }} />
53+
</Stack>
54+
<Stack alignItems="center">
55+
<Typography variant="body2">main</Typography>
56+
<Box sx={{ bgcolor: 'salmon.main', width: 40, height: 20 }} />
57+
</Stack>
58+
<Stack alignItems="center">
59+
<Typography variant="body2">dark</Typography>
60+
<Box sx={{ bgcolor: 'salmon.dark', width: 40, height: 20 }} />
61+
</Stack>
62+
</Stack>
63+
</Stack>
64+
</ThemeProvider>
65+
);
66+
}

‎docs/data/material/customization/palette/UsingAugmentColor.tsx.preview

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
import { createTheme } from '@mui/material/styles';
2+
3+
let theme = createTheme({
4+
// Theme customization goes here as usual, including tonalOffset and/or
5+
// contrastThreshold as the augmentColor() function relies on these
6+
});
7+
8+
theme = createTheme(theme, {
9+
// Custom colors created with augmentColor go here
10+
palette: {
11+
salmon: theme.palette.augmentColor({
12+
color: {
13+
main: '#FF5733',
14+
},
15+
name: 'salmon',
16+
}),
17+
},
18+
});

‎docs/data/material/customization/palette/UsingColorObject.js

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
import * as React from 'react';
2+
import { createTheme, ThemeProvider } from '@mui/material/styles';
3+
import { lime, purple } from '@mui/material/colors';
4+
import Button from '@mui/material/Button';
5+
import { Stack } from '@mui/system';
6+
7+
const theme = createTheme({
8+
palette: {
9+
primary: lime,
10+
secondary: purple,
11+
},
12+
});
13+
14+
export default function Palette() {
15+
return (
16+
<ThemeProvider theme={theme}>
17+
<Stack direction="row" gap={4}>
18+
<Button variant="contained">Primary</Button>
19+
<Button variant="contained" color="secondary">
20+
Secondary
21+
</Button>
22+
</Stack>
23+
</ThemeProvider>
24+
);
25+
}

‎docs/data/material/customization/palette/UsingColorObject.tsx

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
import * as React from 'react';
2+
import { createTheme, ThemeProvider } from '@mui/material/styles';
3+
import { lime, purple } from '@mui/material/colors';
4+
import Button from '@mui/material/Button';
5+
import { Stack } from '@mui/system';
6+
7+
const theme = createTheme({
8+
palette: {
9+
primary: lime,
10+
secondary: purple,
11+
},
12+
});
13+
14+
export default function Palette() {
15+
return (
16+
<ThemeProvider theme={theme}>
17+
<Stack direction="row" gap={4}>
18+
<Button variant="contained">Primary</Button>
19+
<Button variant="contained" color="secondary">
20+
Secondary
21+
</Button>
22+
</Stack>
23+
</ThemeProvider>
24+
);
25+
}

‎docs/data/material/customization/palette/UsingColorObject.tsx.preview

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
import { createTheme } from '@mui/material/styles';
2+
import { lime, purple } from '@mui/material/colors';
3+
4+
const theme = createTheme({
5+
palette: {
6+
primary: lime,
7+
secondary: purple,
8+
},
9+
});

‎docs/data/material/customization/palette/UsingStylesUtils.js

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
import * as React from 'react';
2+
import {
3+
createTheme,
4+
ThemeProvider,
5+
alpha,
6+
getContrastRatio,
7+
} from '@mui/material/styles';
8+
import Button from '@mui/material/Button';
9+
import { Box, Stack } from '@mui/system';
10+
import { Typography } from '@mui/material';
11+
12+
const violetBase = '#7F00FF';
13+
const violetMain = alpha(violetBase, 0.7);
14+
15+
const theme = createTheme({
16+
palette: {
17+
violet: {
18+
main: violetMain,
19+
light: alpha(violetBase, 0.5),
20+
dark: alpha(violetBase, 0.9),
21+
contrastText: getContrastRatio(violetMain, '#fff') > 4.5 ? '#fff' : '#111',
22+
},
23+
},
24+
});
25+
26+
export default function Palette() {
27+
return (
28+
<ThemeProvider theme={theme}>
29+
<Stack gap={2} alignItems="center">
30+
<Button variant="contained" color="violet">
31+
Violet
32+
</Button>
33+
<Stack direction="row" gap={1}>
34+
<Stack alignItems="center">
35+
<Typography variant="body2">light</Typography>
36+
<Box sx={{ bgcolor: 'violet.light', width: 40, height: 20 }} />
37+
</Stack>
38+
<Stack alignItems="center">
39+
<Typography variant="body2">main</Typography>
40+
<Box sx={{ bgcolor: 'violet.main', width: 40, height: 20 }} />
41+
</Stack>
42+
<Stack alignItems="center">
43+
<Typography variant="body2">dark</Typography>
44+
<Box sx={{ bgcolor: 'violet.dark', width: 40, height: 20 }} />
45+
</Stack>
46+
</Stack>
47+
</Stack>
48+
</ThemeProvider>
49+
);
50+
}

‎docs/data/material/customization/palette/UsingStylesUtils.tsx

+68
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
import * as React from 'react';
2+
import {
3+
createTheme,
4+
ThemeProvider,
5+
alpha,
6+
getContrastRatio,
7+
} from '@mui/material/styles';
8+
import Button from '@mui/material/Button';
9+
import { Box, Stack } from '@mui/system';
10+
import { Typography } from '@mui/material';
11+
12+
// Augment the palette to include a violet color
13+
declare module '@mui/material/styles' {
14+
interface Palette {
15+
violet: Palette['primary'];
16+
}
17+
18+
interface PaletteOptions {
19+
violet?: PaletteOptions['primary'];
20+
}
21+
}
22+
23+
// Update the Button's color options to include a violet option
24+
declare module '@mui/material/Button' {
25+
interface ButtonPropsColorOverrides {
26+
violet: true;
27+
}
28+
}
29+
30+
const violetBase = '#7F00FF';
31+
const violetMain = alpha(violetBase, 0.7);
32+
33+
const theme = createTheme({
34+
palette: {
35+
violet: {
36+
main: violetMain,
37+
light: alpha(violetBase, 0.5),
38+
dark: alpha(violetBase, 0.9),
39+
contrastText: getContrastRatio(violetMain, '#fff') > 4.5 ? '#fff' : '#111',
40+
},
41+
},
42+
});
43+
44+
export default function Palette() {
45+
return (
46+
<ThemeProvider theme={theme}>
47+
<Stack gap={2} alignItems="center">
48+
<Button variant="contained" color="violet">
49+
Violet
50+
</Button>
51+
<Stack direction="row" gap={1}>
52+
<Stack alignItems="center">
53+
<Typography variant="body2">light</Typography>
54+
<Box sx={{ bgcolor: 'violet.light', width: 40, height: 20 }} />
55+
</Stack>
56+
<Stack alignItems="center">
57+
<Typography variant="body2">main</Typography>
58+
<Box sx={{ bgcolor: 'violet.main', width: 40, height: 20 }} />
59+
</Stack>
60+
<Stack alignItems="center">
61+
<Typography variant="body2">dark</Typography>
62+
<Box sx={{ bgcolor: 'violet.dark', width: 40, height: 20 }} />
63+
</Stack>
64+
</Stack>
65+
</Stack>
66+
</ThemeProvider>
67+
);
68+
}

‎docs/data/material/customization/palette/UsingStylesUtils.tsx.preview

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
import { createTheme, alpha, getContrastRatio } from '@mui/material/styles';
2+
3+
const violetBase = '#7F00FF';
4+
const violetMain = alpha(violetBase, 0.7);
5+
6+
const theme = createTheme({
7+
palette: {
8+
violet: {
9+
main: violetMain,
10+
light: alpha(violetBase, 0.5),
11+
dark: alpha(violetBase, 0.9),
12+
contrastText: getContrastRatio(violetMain, '#fff') > 4.5 ? '#fff' : '#111',
13+
},
14+
},
15+
});

‎docs/data/material/customization/palette/palette.md

+133-140
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,51 @@
22

33
<p class="description">The palette enables you to modify the color of the components to suit your brand.</p>
44

5-
## Palette colors
5+
## Color tokens
66

7-
The theme exposes the following palette colors (accessible under `theme.palette.`):
7+
Palette colors are represented by four tokens:
88

9-
- _primary_ - used to represent primary interface elements for a user. It's the color displayed most frequently across your app's screens and components.
10-
- _secondary_ - used to represent secondary interface elements for a user. It provides more ways to accent and distinguish your product. Having it is optional.
11-
- _error_ - used to represent interface elements that the user should be made aware of.
12-
- _warning_ - used to represent potentially dangerous actions or important messages.
13-
- _info_ - used to present information to the user that is neutral and not necessarily important.
14-
- _success_ - used to indicate the successful completion of an action that user triggered.
9+
- `main`: The main shade of the color
10+
- `light`: A lighter shade of `main`
11+
- `dark`: A darker shade of `main`
12+
- `contrastText`: Text color, intended to contrast with `main`
1513

16-
If you want to learn more about color, you can check out [the color section](/material-ui/customization/color/).
14+
Here's how Material UI's default theme defines the primary color tokens:
1715

18-
## Default values
16+
```js
17+
const primary = {
18+
main: '#1976d2',
19+
light: '#42a5f5',
20+
dark: '#1565c0',
21+
contrastText: '#fff',
22+
};
23+
```
24+
25+
See the [Color](/material-ui/customization/color/) documentation for details on the Material Design color system.
26+
27+
## Default colors
28+
29+
The theme exposes the following default palette colors (accessible under `theme.palette.*`):
30+
31+
- `primary` - for primary interface elements.
32+
- `secondary` - for secondary interface elements.
33+
- `error` - for elements that the user should be made aware of.
34+
- `warning` - for potentially dangerous actions or important messages.
35+
- `info` - for highlighting neutral information.
36+
- `success` - for indicating the successful completion of an action that the user triggered.
1937

20-
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`).
38+
See Material Design's [Color System](https://m2.material.io/design/color/the-color-system.html) for details on color usage and guidelines.
39+
40+
### Values
41+
42+
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`).
2143

2244
{{"demo": "Intentions.js", "bg": "inline", "hideToolbar": true}}
2345

2446
The default palette uses the shades prefixed with `A` (`A200`, etc.) for the secondary palette color,
2547
and the un-prefixed shades for the other palette colors.
2648

27-
## Customization
49+
### Customization
2850

2951
You may override the default palette values by including a palette object as part of your theme.
3052
If any of the:
@@ -38,173 +60,128 @@ If any of the:
3860

3961
palette color objects are provided, they will replace the default ones.
4062

41-
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:
63+
This can be achieved by either using a color object or by providing the colors directly:
4264

43-
```ts
44-
interface PaletteColor {
45-
light?: string;
46-
main: string;
47-
dark?: string;
48-
contrastText?: string;
49-
}
50-
```
65+
#### Using a color object
5166

52-
### Using a color object
67+
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:
5368

54-
The simplest way to customize a palette color is to import one or more of the provided colors
55-
and apply them:
69+
{{"demo": "UsingColorObject.js", "defaultCodeOpen": true }}
5670

57-
```js
58-
import { createTheme } from '@mui/material/styles';
59-
import blue from '@mui/material/colors/blue';
71+
#### Providing the colors directly
6072

61-
const theme = createTheme({
62-
palette: {
63-
primary: blue,
64-
},
65-
});
66-
```
73+
To modify each color directly, provide an object with one or more of the color tokens.
74+
Only the `main` token is required; `light`, `dark`, and `contrastText` are optional, and if not provided, then their values are calculated automatically:
6775

68-
### Providing the colors directly
76+
{{"demo": "ManuallyProvidePaletteColor.js" }}
6977

70-
If you wish to provide more customized colors, you can either create your own palette color,
71-
or directly supply colors to some or all of the `theme.palette` keys:
78+
### Contrast threshold
7279

73-
```js
74-
import { createTheme } from '@mui/material/styles';
80+
The `contrastText` token is calculated using the `contrastThreshold` value, to maximize the contrast between the background and the text.
7581

76-
const theme = createTheme({
77-
palette: {
78-
primary: {
79-
// light: will be calculated from palette.primary.main,
80-
main: '#ff4400',
81-
// dark: will be calculated from palette.primary.main,
82-
// contrastText: will be calculated to contrast with palette.primary.main
83-
},
84-
secondary: {
85-
light: '#0066ff',
86-
main: '#0044ff',
87-
// dark: will be calculated from palette.secondary.main,
88-
contrastText: '#ffcc00',
89-
},
90-
// Provide every color token (light, main, dark, and contrastText) when using
91-
// custom colors for props in Material UI's components.
92-
// Then you will be able to use it like this: `<Button color="custom">`
93-
// (For TypeScript, you need to add module augmentation for the `custom` value)
94-
custom: {
95-
light: '#ffa726',
96-
main: '#f57c00',
97-
dark: '#ef6c00',
98-
contrastText: 'rgba(0, 0, 0, 0.87)',
99-
},
100-
// Used by `getContrastText()` to maximize the contrast between
101-
// the background and the text.
102-
contrastThreshold: 3,
103-
// Used by the functions below to shift a color's luminance by approximately
104-
// two indexes within its tonal palette.
105-
// E.g., shift from Red 500 to Red 300 or Red 700.
106-
tonalOffset: 0.2,
107-
},
108-
});
109-
```
82+
A higher contrast threshold value increases the point at which a background color is considered light, and thus given a dark `contrastText`.
83+
Note that the contrast threshold follows a non-linear curve, and defaults to a value of 3 which indicates a minimum contrast ratio of 3:1.
11084

111-
As in the example above, if the palette color contains custom colors using any of the
112-
"main", "light", "dark" or "contrastText" keys, these map as follows:
85+
{{"demo": "ContrastThreshold.js" }}
11386

114-
- If the "dark" and / or "light" keys are omitted, their value(s) will be calculated from "main",
115-
according to the "tonalOffset" value.
116-
- If "contrastText" is omitted, its value will be calculated to contrast with "main",
117-
according to the "contrastThreshold" value.
87+
### Tonal offset
11888

119-
Both the "tonalOffset" and "contrastThreshold" values may be customized as needed.
120-
The "tonalOffset" value can either be a number between 0 and 1, which will apply to both light and dark variants, or an object with light and dark variants specified by the following TypeScript type:
89+
The `light` and `dark` tokens are calculated using the `tonalOffset` value, to shift the `main` color's luminance.
90+
A higher tonal offset value will make `light` tokens lighter, and `dark` tokens darker.
12191

122-
```ts
123-
type PaletteTonalOffset =
124-
| number
125-
| {
126-
light: number;
127-
dark: number;
128-
};
129-
```
92+
:::warning
93+
This only applies when working with custom colors—it won't have any effect on the [default values](#default-values).
94+
:::
13095

131-
A higher value for "tonalOffset" will make calculated values for "light" lighter, and "dark" darker.
132-
A higher value for "contrastThreshold" increases the point at which a background color is considered
133-
light, and given a dark "contrastText". Note that "contrastThreshold" follows a non-linear curve, and
134-
starts with a value of 3 (requiring a minimum contrast ratio of 3:1).
96+
For example, the tonal offset default value `0.2` shifts the luminance by approximately two indexes, so if the `main` token is `blue[500]`, then the `light` token would be `blue[300]` and `dark` would be `blue[700]`.
13597

136-
### Accessibility
98+
The tonal offset value can be either a number between 0 and 1 (which would apply to both `light` and `dark` tokens) or an object with `light` and `dark` keys specified:
13799

138-
To meet the minimum contrast of at least 4.5:1 as defined in [WCAG 2.1 Rule 1.4.3](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html), create a custom theme with `contrastThreshold: 4.5`.
100+
{{"demo": "TonalOffset.js" }}
139101

140-
```js
141-
import { createTheme } from '@mui/material/styles';
102+
## Custom colors
142103

143-
const theme = createTheme({
144-
palette: {
145-
// Used by `getContrastText()` to maximize the contrast between
146-
// the background and the text.
147-
contrastThreshold: 4.5,
148-
},
149-
});
150-
```
104+
:::warning
105+
Unlike [default colors](#default-colors), tokens for custom colors are _not_ automatically calculated.
106+
:::
151107

152-
### Example
108+
To add custom colors, you must either provide the tokens manually, or generate them using the `augmentColor` utility:
153109

154-
{{"demo": "Palette.js", "defaultCodeOpen": true}}
110+
### Provide tokens manually
155111

156-
### Adding new colors
112+
The most straightforward approach is to define all tokens—`main`, `light`, `dark`, and `contrastText`—manually:
157113

158-
You can add new colors inside and outside the palette of the theme as follows:
114+
{{"demo": "ManuallyProvideCustomColor.js" }}
159115

160-
```js
161-
import { createTheme } from '@mui/material/styles';
116+
If you need to manipulate colors, `@mui/material/styles` provides [a set of utilities](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/styles/index.d.ts#L52-L67) to help with this.
117+
The following example uses the `alpha` and `getContrastRatio` utilities to define tokens using opacity:
162118

163-
const theme = createTheme({
164-
status: {
165-
danger: '#e53e3e',
166-
},
167-
palette: {
168-
primary: {
169-
main: '#0971f1',
170-
darker: '#053e85',
171-
},
172-
neutral: {
173-
main: '#64748B',
174-
contrastText: '#fff',
175-
},
176-
},
177-
});
119+
{{"demo": "UsingStylesUtils.js" }}
120+
121+
### Generate tokens using augmentColor utility
122+
123+
Alternatively, you can generate the `light`, `dark` and `contrastText` tokens using the palette's `augmentColor` utility, which is the same function used for the default palette colors.
124+
This requires creating the theme in two steps and providing the `main` token on which the other will be based on:
125+
126+
{{"demo": "UsingAugmentColor.js" }}
127+
128+
The [contrast threshold](#contrast-threshold) and [tonal offset](#tonal-offset) values will apply for the colors defined using this utility.
129+
130+
### Using in components
131+
132+
After adding a custom color, you will be able to use it in components just like you do with default palette colors:
133+
134+
```js
135+
<Button color="custom">
178136
```
179137

180138
### TypeScript
181139

182-
You have to use [module augmentation](/material-ui/guides/typescript/#customization-of-theme) to add new variables to the `Palette` and `PaletteOptions`.
140+
If you're using TypeScript, then you need to use [module augmentation](/material-ui/guides/typescript/#customization-of-theme) for custom colors.
141+
142+
To add a custom color to the palette, you must add it to the `Palette` and `PaletteOptions` interfaces:
183143

184144
<!-- tested with packages/mui-material/test/typescript/augmentation/paletteColors.spec.ts -->
185145

186146
```ts
187147
declare module '@mui/material/styles' {
188-
interface Theme {
189-
status: {
190-
danger: React.CSSProperties['color'];
191-
};
148+
interface Palette {
149+
custom: Palette['primary'];
192150
}
193151

194-
interface ThemeOptions {
195-
status: {
196-
danger: React.CSSProperties['color'];
197-
};
152+
interface PaletteOptions {
153+
custom?: PaletteOptions['primary'];
198154
}
155+
}
156+
```
199157

200-
interface Palette {
201-
neutral: Palette['primary'];
202-
}
158+
To use a custom color for the `color` prop of a component, you must add it to the component's `PropsColorOverrides` interface.
159+
The example below shows how to do this with a Button component:
203160

204-
interface PaletteOptions {
205-
neutral: PaletteOptions['primary'];
161+
<!-- tested with packages/mui-material/test/typescript/augmentation/paletteColors.spec.ts -->
162+
163+
```ts
164+
declare module '@mui/material/Button' {
165+
interface ButtonPropsColorOverrides {
166+
custom: true;
206167
}
168+
}
169+
```
170+
171+
## Adding color tokens
172+
173+
To add a new [color token](#color-tokens), include it in the color's object as follows:
207174

175+
{{"demo": "AddingColorTokens.js" }}
176+
177+
### TypeScript
178+
179+
If you're using TypeScript, then you'll need to use [module augmentation](/material-ui/guides/typescript/#customization-of-theme) to add the new color token to the `PaletteColor` and `SimplePaletteColorOptions` interfaces as follows:
180+
181+
<!-- tested with packages/mui-material/test/typescript/augmentation/paletteColors.spec.ts -->
182+
183+
```ts
184+
declare module '@mui/material/styles' {
208185
interface PaletteColor {
209186
darker?: string;
210187
}
@@ -215,7 +192,23 @@ declare module '@mui/material/styles' {
215192
}
216193
```
217194

218-
{{"demo": "CustomColor.js"}}
195+
## Non-palette colors
196+
197+
To learn how to add colors outside of `theme.palette`, see [Theming—Custom variables](/material-ui/customization/theming/#custom-variables).
198+
199+
## Accessibility
200+
201+
To meet the minimum contrast of at least 4.5:1 as defined in [WCAG 2.1 Rule 1.4.3](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html), create a custom theme with a [contrast threshold](#contrast-threshold) value of 4.5 as follows:
202+
203+
```js
204+
import { createTheme } from '@mui/material/styles';
205+
206+
const theme = createTheme({
207+
palette: {
208+
contrastThreshold: 4.5,
209+
},
210+
});
211+
```
219212

220213
## Picking colors
221214

‎docs/pages/blog/mui-core-v5.md

+3-2
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,8 @@ This release features some major highlights:
5555
- [Unstyled components and hooks](#unstyled-components-and-hooks)
5656
- [Second design system](#second-design-system)
5757
- [MUI X](#mui-x)
58-
- [Design kits](#design-kits-2)
58+
- [Design kits](#design-kits-1)
59+
- [Thank you](#thank-you)
5960

6061
## High-level goals for v5
6162

@@ -197,7 +198,7 @@ For this reason, v5 comes with the capability to extend the built-in behavior of
197198
This was one of the most upvoted GitHub issues: [#13875](https://github.com/mui/material-ui/issues/13875).
198199
In practice, this change makes the MUI Core components extendable placeholders.
199200

200-
**First**, you can use the [existing style mapping](/material-ui/customization/palette/#adding-new-colors) of the components.
201+
**First**, you can use the [existing style mapping](/material-ui/customization/palette/#custom-colors) of the components.
201202
For example, you can add a new `neutral` color to the palette, and the Button computes the right derivative colors.
202203

203204
```jsx

‎docs/scripts/formattedTSDemos.js

+1
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ const ignoreList = [
1313
'/pages.ts',
1414
'docs/data/joy/getting-started/templates',
1515
'docs/data/base/components/select/UnstyledSelectIntroduction.tsx',
16+
'docs/data/material/customization/palette',
1617
];
1718

1819
const fse = require('fs-extra');

‎packages/mui-material/test/typescript/moduleAugmentation/paletteColors.spec.ts

+6
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,12 @@ declare module '@mui/material/styles' {
2828
}
2929
}
3030

31+
declare module '@mui/material/Button' {
32+
interface ButtonPropsColorOverrides {
33+
neutral: true;
34+
}
35+
}
36+
3137
const theme = createTheme({
3238
status: {
3339
danger: '#e53e3e',

0 commit comments

Comments
 (0)
Please sign in to comment.