[docs] Add palette TypeScript override example

docs/src/modules/components/AppFrame.js

@@ -286,7 +286,7 @@ function AppFrame(props) {
               aria-label={t('editWebsiteColors')}
               component={Link}
               naked
-              href="/customization/color/#color-tool"
+              href="/customization/color/#playground"
               data-ga-event-category="header"
               data-ga-event-action="colors"
             >

docs/src/pages/customization/breakpoints/breakpoints.md

@@ -115,7 +115,7 @@ const theme = createMuiTheme({
 
 Feel free to have as few or as many breakpoints as you want, naming them in whatever way you'd prefer for your project.
 
-```tsx
+```js
 const theme = createMuiTheme({
   breakpoints: {
     values: {
@@ -125,11 +125,13 @@ const theme = createMuiTheme({
     },
   },
 });
+```
 
-declare module "@material-ui/core/styles/createBreakpoints"
-{
-  interface BreakpointOverrides
-  {
+If you are using TypeScript, you would also need to use [module augmentation](/guides/typescript/#customization-of-theme) for the theme to accept the above values.
+
+```ts
+declare module "@material-ui/core/styles/createBreakpoints" {
+  interface BreakpointOverrides {
     xs: false; // removes the `xs` breakpoint
     sm: false;
     md: false;

docs/src/pages/customization/color/color.md

@@ -4,53 +4,45 @@
 
 The Material Design [color system](https://material.io/design/color/) can be used to create a color theme that reflects your brand or style.
 
-## Color system
+## Picking colors
 
-### Important Terms
-
-#### "Palette"
-
-A palette is a collection of colors, i.e. hues and their shades. Material-UI provides all colors from the Material Design guidelines.
-[This color palette](#color-palette) has been designed with colors that work harmoniously with each other.
-
-#### "Hue" & "Shade"
-
-A single color within the palette is made up of a hue such as "red", and shade, such as "500".
-"red 50" is the lightest shade of red (*pink!*), while "red 900" is the darkest.
-In addition, most hues come with "accent" shades, prefixed with an `A`.
+### Official color tool
 
-### Examples
+The Material Design team has also built an awesome palette configuration tool: [material.io/resources/color/](https://material.io/resources/color/).
+This can help you create a color palette for your UI, as well as measure the accessibility level of any color combination.
 
-The Material Design color palette comprises primary and accent colors that can be used for illustration or to develop your brand colors.
-They’ve been designed to work harmoniously with each other.
+<a href="https://material.io/resources/color/#!/?view.left=0&view.right=0&primary.color=3F51B5&secondary.color=F44336" target="_blank" rel="noopener nofollow">
+  <img src="/static/images/color/colorTool.png" alt="Official color tool" style="width: 574px" />
+</a>
+<br />
+<br />
 
-For instance, you can refer to complementary primary and accent colors (for example 'red 500' & 'purple A200'), like so:
+The output can be fed into `createMuiTheme()` function:
 
 ```js
-import purple from '@material-ui/core/colors/purple';
-import red from '@material-ui/core/colors/red';
-
-const primary = red[500]; // #F44336
-const accent = purple['A200']; // #E040FB
-const accent = purple.A200; // #E040FB (alternative method)
-```
-
-### Color palette
-
-Given a *HUE* (red, pink, etc.) and a *SHADE* (500, 600, etc.) you can import the color like this:
-
-```jsx
-import HUE from '@material-ui/core/colors/HUE';
+import { createMuiTheme } from '@material-ui/core/styles';
 
-const color = HUE[SHADE];
+const theme = createMuiTheme({
+  palette: {
+    primary: {
+      light: '#757ce8',
+      main: '#3f50b5',
+      dark: '#002884',
+      contrastText: '#fff',
+    },
+    secondary: {
+      light: '#ff7961',
+      main: '#f44336',
+      dark: '#ba000d',
+      contrastText: '#000',
+    },
+  },
+});
 ```
 
-{{"demo": "pages/customization/color/Color.js", "hideToolbar": true, "bg": "inline"}}
-
-## Color tool
+### Playground
 
-To test a [material.io/design/color](https://material.io/design/color/) color scheme with the Material-UI
-documentation, simply select colors using the palette and sliders below.
+To test a [material.io/design/color](https://material.io/design/color/) color scheme with the Material-UI documentation, simply select colors using the palette and sliders below.
 Alternatively, you can enter hex values in the Primary and Secondary text fields.
 
 {{"demo": "pages/customization/color/ColorTool.js", "hideToolbar": true, "bg": true}}
@@ -63,7 +55,9 @@ import purple from '@material-ui/core/colors/purple';
 
 const theme = createMuiTheme({
   palette: {
-    primary: purple,
+    primary: {
+      main: purple[500],
+    },
     secondary: {
       main: '#f44336',
     },
@@ -75,40 +69,45 @@ Only the `main` shades need be provided (unless you wish to further customize `l
 
 If you are using the default primary and / or secondary shades then by providing the color object, `createMuiTheme()` will use the appropriate shades from the material color for main, light and dark.
 
-### Official color tool
+### Tools by the community
 
-The Material Design team has also built an awesome palette configuration tool: [material.io/tools/color](https://material.io/tools/color/).
-This can help you create a color palette for your UI, as well as measure the accessibility level of any color combination.
+- [create-mui-theme](https://react-theming.github.io/create-mui-theme/): Is an online tool for creating Material-UI themes via Material Design Color Tool.
+- [material-ui-theme-editor](https://in-your-saas.github.io/material-ui-theme-editor/): A tool to generate themes for your Material-UI applications by just selecting the colors and having a live preview.
+- [Material palette generator](https://material.io/inline-tools/color/): The Material palette generator can be used to generate a palette for any color you input.
 
-<a href="https://material.io/tools/color/#!/?view.left=0&view.right=0&primary.color=3F51B5&secondary.color=F44336" target="_blank" rel="noopener nofollow">
-  <img src="/static/images/color/colorTool.png" alt="Official color tool" style="width: 574px" />
-</a>
+## 2014 Material Design color palettes
 
-The output can be fed into `createMuiTheme()` function:
+These color palettes, originally created by Material Design in 2014, are comprised of colors designed to work together harmoniously, and can be used to develop your brand palette. To generate your own harmonious palettes, use the palette generation tool.
+
+### Important Terms
+
+- **Palette**: A palette is a collection of colors, i.e. hues and their shades. Material-UI provides all colors from the Material Design guidelines.
+[This color palette](#color-palette) has been designed with colors that work harmoniously with each other.
+- **Hue" & "Shade**: A single color within the palette is made up of a hue such as "red", and shade, such as "500".
+"red 50" is the lightest shade of red (*pink!*), while "red 900" is the darkest.
+In addition, most hues come with "accent" shades, prefixed with an `A`.
+
+### Color palette
+
+Given a *HUE* (red, pink, etc.) and a *SHADE* (500, 600, etc.) you can import the color like this:
 
 ```jsx
-import { createMuiTheme } from '@material-ui/core/styles';
+import HUE from '@material-ui/core/colors/HUE';
 
-const theme = createMuiTheme({
-  palette: {
-    primary: {
-      light: '#757ce8',
-      main: '#3f50b5',
-      dark: '#002884',
-      contrastText: '#fff',
-    },
-    secondary: {
-      light: '#ff7961',
-      main: '#f44336',
-      dark: '#ba000d',
-      contrastText: '#000',
-    },
-  },
-});
+const color = HUE[SHADE];
 ```
 
-### Tools by the community
+{{"demo": "pages/customization/color/Color.js", "hideToolbar": true, "bg": "inline"}}
 
-- [create-mui-theme](https://react-theming.github.io/create-mui-theme/): Is an online tool for creating Material-UI themes via Material Design Color Tool.
-- [material-ui-theme-editor](https://in-your-saas.github.io/material-ui-theme-editor/): A tool to generate themes for your Material-UI applications by just selecting the colors and having a live preview.
-- [Material palette generator](https://material.io/inline-tools/color/): The Material palette generator can be used to generate a palette for any color you input.
+### Examples
+
+For instance, you can refer to complementary primary and accent colors, "red 500" and "purple A200" like so:
+
+```js
+import purple from '@material-ui/core/colors/purple';
+import red from '@material-ui/core/colors/red';
+
+const primary = red[500]; // #f44336
+const accent = purple['A200']; // #e040fb
+const accent = purple.A200; // #e040fb (alternative method)
+```

docs/src/pages/customization/palette/palette.md

@@ -2,49 +2,55 @@
 
 <p class="description">The palette enables you to modify the color of the components to suit your brand.</p>
 
-## Intentions
+## Palette colors
 
-A color intention is a mapping of a palette to a given intention within your application.
-The theme exposes the following color intentions:
+A color intention is a mapping of a palette color to a given intention within your application.
+The theme exposes the following palette colors (accessible under `theme.palette.`):
 
-- primary - used to represent primary interface elements for a user.
-- secondary - used to represent secondary interface elements for a user.
-- 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.
-
-The default palette uses the shades prefixed with `A` (`A200`, etc.) for the secondary intention,
-and the un-prefixed shades for the other intentions.
+- *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.
 
 If you want to learn more about color, you can check out [the color section](/customization/color/).
 
+## Default values
+
+You can explore the default values of the palette using [the theme explorer](/customization/default-theme/?expand-path=$.palette) or by opening the dev tools console on this page (`window.theme.palette`).
+
 {{"demo": "pages/customization/palette/Intentions.js", "bg": "inline", "hideToolbar": true}}
 
-### Customization
+The default palette uses the shades prefixed with `A` (`A200`, etc.) for the secondary intention,
+and the un-prefixed shades for the other intentions.
+
+## Customization
 
 You may override the default palette values by including a palette object as part of your theme.
+If any of the:
+
+- [`palette.primary`](/customization/default-theme/?expand-path=$.palette.primary)
+- [`palette.secondary`](/customization/default-theme/?expand-path=$.palette.secondary)
+- [`palette.error`](/customization/default-theme/?expand-path=$.palette.error)
+- [`palette.warning`](/customization/default-theme/?expand-path=$.palette.warning)
+- [`palette.info`](/customization/default-theme/?expand-path=$.palette.info)
+- [`palette.success`](/customization/default-theme/?expand-path=$.palette.success)
 
-If any of the [`palette.primary`](/customization/default-theme/?expand-path=$.palette.primary),
-[`palette.secondary`](/customization/default-theme/?expand-path=$.palette.secondary),
-[`palette.error`](/customization/default-theme/?expand-path=$.palette.error),
-[`palette.warning`](/customization/default-theme/?expand-path=$.palette.warning),
-[`palette.info`](/customization/default-theme/?expand-path=$.palette.info) or
-[`palette.success`](/customization/default-theme/?expand-path=$.palette.success)
-'intention' objects are provided, they will replace the defaults.
+palette color objects are provided, they will replace the defaults.
 
-The intention value can either be a [color](/customization/color/) object, or an object with one or more of the keys specified by the following TypeScript interface:
+The palette color value can either be a [color](/customization/color/#2014-material-design-color-palettes) object, or an object with one or more of the keys specified by the following TypeScript interface:
 
 ```ts
-interface PaletteIntention {
+interface PaletteColor {
   light?: string;
   main: string;
   dark?: string;
   contrastText?: string;
 }
 ```
 
-**Using a color object**
+### Using a color object
 
 The simplest way to customize an intention is to import one or more of the provided colors
 and apply them to a palette intention:
@@ -60,7 +66,7 @@ const theme = createMuiTheme({
 });
 ```
 
-**Providing the colors directly**
+### Providing the colors directly
 
 If you wish to provide more customized colors, you can either create your own color object,
 or directly supply colors to some or all of the intention's keys:
@@ -119,11 +125,56 @@ Note that "contrastThreshold" follows a non-linear curve.
 
 ### Example
 
-{{"demo": "pages/customization/palette/Palette.js"}}
+{{"demo": "pages/customization/palette/Palette.js", "defaultCodeOpen": true}}
+
+### Adding new colors
 
-## Color tool
+You can add new colors inside and outside the palette of the theme as follow:
 
-Need inspiration? The Material Design team has built an awesome [palette configuration tool](/customization/color/#color-tool) to help you.
+```js
+import { createMuiTheme } from '@material-ui/core/styles';
+
+const theme = createMuiTheme({
+  status: {
+    danger: '#e53e3e',
+  },
+  palette: {
+    neutral: {
+      main: '#5c6ac4',
+    },
+  },
+});
+```
+
+If you are using TypeScript, you would also need to use [module augmentation](/guides/typescript/#customization-of-theme) for the theme to accept the above values.
+
+```ts
+declare module '@material-ui/core/styles/createMuiTheme' {
+  interface Theme {
+    status: {
+      danger: React.CSSProperties['color'],
+    }
+  }
+  interface ThemeOptions {
+    status: {
+      danger: React.CSSProperties['color']
+    }
+  }
+}
+
+declare module "@material-ui/core/styles/createPalette" {
+  interface Palette {
+    neutral: Palette['primary'];
+  }
+  interface PaletteOptions {
+    neutral: PaletteOptions['primary'];
+  }
+}
+```
+
+## Picking colors
+
+Need inspiration? The Material Design team has built an [palette configuration tool](/customization/color/#picking-colors) to help you.
 
 ## Dark mode
 
@@ -179,7 +230,3 @@ function App() {
   );
 }
 ```
-
-## Default values
-
-You can explore the default values of the palette using [the theme explorer](/customization/default-theme/?expand-path=$.palette) or by opening the dev tools console on this page (`window.theme.palette`).

docs/src/pages/customization/theming/theming.md

@@ -84,11 +84,12 @@ import green from '@material-ui/core/colors/green';
 
 const theme = createMuiTheme({
   palette: {
-    primary: purple,
-    secondary: green,
-  },
-  status: {
-    danger: 'orange',
+    primary: {
+      main: purple[500],
+    },
+    secondary: {
+      main: green[500],
+    },
   },
 });
 ```