[docs][material] Improve documentation about adding custom colors (#3…

…7743)
mui · Jul 21, 2023 · 49989b1 · 49989b1
1 parent 35291e7
commit 49989b1
Show file tree

Hide file tree

Showing 31 changed files with 1,087 additions and 147 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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 (
+    <ThemeProvider theme={theme}>
+      <Stack direction="row" gap={1}>
+        <Stack alignItems="center">
+          <Typography variant="body2">light</Typography>
+          <Box sx={{ bgcolor: `primary.light`, width: 40, height: 20 }} />
+        </Stack>
+        <Stack alignItems="center">
+          <Typography variant="body2">main</Typography>
+          <Box sx={{ bgcolor: `primary.main`, width: 40, height: 20 }} />
+        </Stack>
+        <Stack alignItems="center">
+          <Typography variant="body2">dark</Typography>
+          <Box sx={{ bgcolor: `primary.dark`, width: 40, height: 20 }} />
+        </Stack>
+        <Stack alignItems="center">
+          <Typography variant="body2">darker</Typography>
+          <Box sx={{ bgcolor: `primary.darker`, width: 40, height: 20 }} />
+        </Stack>
+      </Stack>
+    </ThemeProvider>
+  );
+}
diff --git a/docs/data/material/customization/palette/AddingColorTokens.tsx 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 (
+    <ThemeProvider theme={theme}>
+      <Stack direction="row" gap={1}>
+        <Stack alignItems="center">
+          <Typography variant="body2">light</Typography>
+          <Box sx={{ bgcolor: `primary.light`, width: 40, height: 20 }} />
+        </Stack>
+        <Stack alignItems="center">
+          <Typography variant="body2">main</Typography>
+          <Box sx={{ bgcolor: `primary.main`, width: 40, height: 20 }} />
+        </Stack>
+        <Stack alignItems="center">
+          <Typography variant="body2">dark</Typography>
+          <Box sx={{ bgcolor: `primary.dark`, width: 40, height: 20 }} />
+        </Stack>
+        <Stack alignItems="center">
+          <Typography variant="body2">darker</Typography>
+          <Box sx={{ bgcolor: `primary.darker`, width: 40, height: 20 }} />
+        </Stack>
+      </Stack>
+    </ThemeProvider>
+  );
+}
diff --git a/docs/data/material/customization/palette/AddingColorTokens.tsx.preview 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
@@ -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 (
+    <Stack gap={1} alignItems="center">
+      <span>
+        <b>{title}</b>
+      </span>
+      <span>{theme.palette.contrastThreshold}:1</span>
+      <Stack direction="row" gap={1}>
+        <Button variant="contained" color="warning">
+          Warning
+        </Button>
+      </Stack>
+    </Stack>
+  );
+}
+
+export default function contrastThreshold() {
+  return (
+    <Stack direction="row" gap={4}>
+      <ThemeProvider theme={defaultContrastThresholdTheme}>
+        <ContrastShowcase title="Default contrast threshold" />
+      </ThemeProvider>
+      <ThemeProvider theme={highContrastThresholdTheme}>
+        <ContrastShowcase title="Higher contrast threshold" />
+      </ThemeProvider>
+    </Stack>
+  );
+}
diff --git a/docs/data/material/customization/palette/ContrastThreshold.tsx 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 (
+    <Stack gap={1} alignItems="center">
+      <span>
+        <b>{title}</b>
+      </span>
+      <span>{theme.palette.contrastThreshold}:1</span>
+      <Stack direction="row" gap={1}>
+        <Button variant="contained" color="warning">
+          Warning
+        </Button>
+      </Stack>
+    </Stack>
+  );
+}
+
+export default function contrastThreshold() {
+  return (
+    <Stack direction="row" gap={4}>
+      <ThemeProvider theme={defaultContrastThresholdTheme}>
+        <ContrastShowcase title="Default contrast threshold" />
+      </ThemeProvider>
+      <ThemeProvider theme={highContrastThresholdTheme}>
+        <ContrastShowcase title="Higher contrast threshold" />
+      </ThemeProvider>
+    </Stack>
+  );
+}
diff --git 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
@@ -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
@@ -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 (
+    <ThemeProvider theme={theme}>
+      <Stack gap={2} alignItems="center">
+        <Button variant="contained" color="ochre">
+          Ochre
+        </Button>
+        <Stack direction="row" gap={1}>
+          <Stack alignItems="center">
+            <Typography variant="body2">light</Typography>
+            <Box sx={{ bgcolor: 'ochre.light', width: 40, height: 20 }} />
+          </Stack>
+          <Stack alignItems="center">
+            <Typography variant="body2">main</Typography>
+            <Box sx={{ bgcolor: 'ochre.main', width: 40, height: 20 }} />
+          </Stack>
+          <Stack alignItems="center">
+            <Typography variant="body2">dark</Typography>
+            <Box sx={{ bgcolor: 'ochre.dark', width: 40, height: 20 }} />
+          </Stack>
+        </Stack>
+      </Stack>
+    </ThemeProvider>
+  );
+}
diff --git a/docs/data/material/customization/palette/ManuallyProvideCustomColor.tsx 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 (
+    <ThemeProvider theme={theme}>
+      <Stack gap={2} alignItems="center">
+        <Button variant="contained" color="ochre">
+          Ochre
+        </Button>
+        <Stack direction="row" gap={1}>
+          <Stack alignItems="center">
+            <Typography variant="body2">light</Typography>
+            <Box sx={{ bgcolor: 'ochre.light', width: 40, height: 20 }} />
+          </Stack>
+          <Stack alignItems="center">
+            <Typography variant="body2">main</Typography>
+            <Box sx={{ bgcolor: 'ochre.main', width: 40, height: 20 }} />
+          </Stack>
+          <Stack alignItems="center">
+            <Typography variant="body2">dark</Typography>
+            <Box sx={{ bgcolor: 'ochre.dark', width: 40, height: 20 }} />
+          </Stack>
+        </Stack>
+      </Stack>
+    </ThemeProvider>
+  );
+}
diff --git a/docs/data/material/customization/palette/ManuallyProvideCustomColor.tsx.preview 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',
+    },
+  },
+});