[core] Revise the theme.palette.primary & secondary approach (#9794)

* [core] Revise the theme.palette.primary & secondary approach

#8075 (comment)

Closes 8075

* Revise the theme.palette.primary & secondary approach
* Update & expand createPalette tests
* Update createMuiTheme tests
* colorManipulator refactoring
* Bump package size

.size-limit

@@ -2,12 +2,12 @@
   {
     "description": "The initial cost people pay for using one component",
     "path": "test/size/overhead.js",
-    "limit": "25.6 KB"
+    "limit": "26 KB"
   },
   {
     "description": "The size of the whole library.",
     "path": "build/index.js",
-    "limit": "95.6 KB"
+    "limit": "96 KB"
   },
   {
     "description": "The main bundle of the documentation",

docs/src/modules/components/AppDrawer.js

@@ -20,7 +20,7 @@ const styles = theme => ({
   title: {
     color: theme.palette.text.secondary,
     '&:hover': {
-      color: theme.palette.primary[500],
+      color: theme.palette.primary.main,
     },
   },
   // https://github.com/philipwalton/flexbugs#3-min-height-on-a-flex-container-wont-apply-to-its-flex-items

docs/src/modules/components/Link.js

@@ -16,10 +16,10 @@ const styles = theme => ({
     color: 'inherit',
   },
   variantPrimary: {
-    color: theme.palette.primary[500],
+    color: theme.palette.primary.main,
   },
   variantAccent: {
-    color: theme.palette.secondary.A400,
+    color: theme.palette.secondary.main,
   },
   variantButton: {
     '&:hover': {

docs/src/modules/components/MarkdownElement.js

@@ -198,7 +198,7 @@ const styles = theme => ({
     },
     '& a, & a code': {
       // Style taken from the Link component
-      color: theme.palette.secondary.A400,
+      color: theme.palette.secondary.main,
       textDecoration: 'none',
       '&:hover': {
         textDecoration: 'underline',

docs/src/modules/styles/getPageContext.js

@@ -4,14 +4,12 @@ import { create, SheetsRegistry } from 'jss';
 import rtl from 'jss-rtl';
 import { createMuiTheme, createGenerateClassName, jssPreset } from 'material-ui/styles';
 import blue from 'material-ui/colors/blue';
-import pink from 'material-ui/colors/pink';
 
 export function getTheme(theme) {
   return createMuiTheme({
     direction: theme.direction,
     palette: {
-      primary: blue,
-      secondary: pink,
+      primary: { light: blue[300], main: blue[500], dark: blue[700] },
       type: theme.paletteType,
     },
   });

docs/src/pages/customization/CssInJs.js

@@ -14,7 +14,7 @@ const styles = theme => ({
     },
   },
   primary: {
-    color: theme.palette.primary[500],
+    color: theme.palette.primary.main,
   },
 });
 

docs/src/pages/customization/Palette.js

@@ -1,18 +1,12 @@
 import React from 'react';
 import { MuiThemeProvider, createMuiTheme } from 'material-ui/styles';
 import purple from 'material-ui/colors/purple';
-import green from 'material-ui/colors/green';
-import red from 'material-ui/colors/red';
 import Button from 'material-ui/Button';
 
 const theme = createMuiTheme({
   palette: {
-    primary: purple, // Purple and green play nicely together.
-    secondary: {
-      ...green,
-      A400: '#00e677',
-    },
-    error: red,
+    primary: { main: purple[500] }, // Purple and green play nicely together.
+    secondary: { main: '#11cb5f' }, // This is just green.A700 as hex.
   },
 });
 

docs/src/pages/customization/WithTheme.js

@@ -6,7 +6,7 @@ import { withTheme } from 'material-ui/styles';
 function WithTheme(props) {
   const { theme } = props;
   const primaryText = theme.palette.text.primary;
-  const primaryColor = theme.palette.primary[500];
+  const primaryColor = theme.palette.primary.main;
 
   const styles = {
     primaryText: {

docs/src/pages/customization/themes.md

@@ -1,24 +1,23 @@
 # Themes
 
-Themes let you apply a consistent tone to your app.
-It allows you to **customize all design aspects** of your project in order to meet the specific needs of your business or brand.
+The theme specifies the color of the components, darkness of the surfaces, level of shadow, appropriate opacity of ink elements, etc.
 
-The theme specifies the darkness of the surfaces, level of shadow, appropriate opacity of ink elements, etc.
-To promote greater consistency between apps, light and dark themes are available to choose from.
-We use [jss](https://github.com/cssinjs/jss) under the hood.
+Themes let you apply a consistent tone to your app. It allows you to **customize all design aspects** of your project in order to meet the specific needs of your business or brand.
+
+To promote greater consistency between apps, light and dark theme types are available to choose from. By default, components use the light theme type.
 
 ## Theme provider
 
-If you wish to customise the theme, you need to use the `MuiThemeProvider` component in order to inject a theme into your application. 
+If you wish to customize the theme, you need to use the `MuiThemeProvider` component in order to inject a theme into your application. 
 However, this is optional; Material-UI components come with a default theme.
 
-`MuiThemeProvider` relies on the context feature of React to pass the theme down,
+`MuiThemeProvider` relies on the context feature of React to pass the theme down to the components,
 so you need to make sure that `MuiThemeProvider` is a parent of the components you are trying to customize.
 You can learn more about this in [the API section](#muithemeprovider).
 
 ## Theme configuration variables
 
-Changing the theme configuration variables is the most effective way to match Material-UI to your needs. By default, your Material-UI application will use the light theme.
+Changing the theme configuration variables is the most effective way to match Material-UI to your needs.
 
 ### Palette
 
@@ -30,18 +29,71 @@ The theme expose the following color intentions:
 
 - 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 careful of.
+- error - used to represent interface elements that the user should be made aware of.
+
+The default palette uses the shades prefixed with `A` (`A200`, etc.) for the accent color 
+and the un-prefixed shades for the other intentions, 
+but you are free to select any shade when customizing the colors, 
+or simply pass in any HTML color value as a string.
 
-The palette uses the shades prefixed with `A` (`A200`, etc.) for the accent color and the hues unprefixed for the other intentions.
 If you want to learn more about color, you can check out [the color section](/style/color).
 
+#### Default palette
+
+You may override the default palette values by including a `palette` object as part of your theme. 
+The following example illustrates how you could recreate the the default palette values. 
+
+
+```jsx
+import { createMuiTheme } from 'material-ui/styles';
+import indigo from 'material-ui/colors/indigo';
+import pink from 'material-ui/colors/pink';
+import red from 'material-ui/colors/red';
+
+const defaultTheme = createMuiTheme()
+
+// All the following keys are optional.
+// We try our best to provide a great default value.
+const theme = createMuiTheme({
+  palette: {
+    contrastThreshold: 3.1,
+    tonalOffset: 0.07,
+    primary: {
+      light: indigo[300],
+      main: indigo[500],
+      dark: indigo[700],
+      contrastText: defaultTheme.palette.getContrastText(indigo[500]),
+    },
+    secondary: {
+      light: pink.A200,
+      main: pink.A400,
+      dark: pink.A700,
+      contrastText: defaultTheme.palette.getContrastText(pink.A400),
+    },
+    error: red.A400,
+  },
+});
+```
+
+If `palette.primary` or `palette.secondary` objects are provided, 
+they will replace the defaults.
+
+If the `dark` and / or `light` keys are omitted, their value(s) will be calculated from `main`, 
+according to the `tonalOffset` value.
+
+If `contrastText` is omitted, its value will be calculated to contrast with `main`, 
+according to the`contrastThreshold` value.
+
+Both the `tonalOffset` and `contrastThreshold` values may be customized as needed. 
+Note that `contrastThreshold` follows a non-linear curve.
+
 #### Example
 
 {{"demo": "pages/customization/Palette.js"}}
 
 ### Dark/light theme
 
-You can make a theme dark by setting `type` to `dark`.
+You can make the theme dark by setting `type` to `dark`.
 
 {{"demo": "pages/customization/DarkTheme.js", "hideEditButton": true}}
 
@@ -53,7 +105,7 @@ The theme provides a **limited set of type sizes** that work well together along
 These sizes are used across the components.
 
 Have a look at the following example regarding changing the default values, such as the font family.
-If you want to learn more about typograpy, you can check out [the typography section](/style/typography).
+If you want to learn more about typography, you can check out [the typography section](/style/typography).
 
 {{"demo": "pages/customization/TypographyTheme.js"}}
 
@@ -73,7 +125,7 @@ html {
 }
 ```
 
-*You need to apply the above CSS on the html element of this page to see the below demo render correctly*
+*You need to apply the above CSS on the html element of this page to see the below demo rendered correctly*
 
 {{"demo": "pages/customization/FontSizeTheme.js"}}
 

docs/src/pages/demos/expansion-panels/DetailedExpansionPanel.js

@@ -40,7 +40,7 @@ const styles = theme => ({
     padding: `${theme.spacing.unit}px ${theme.spacing.unit * 2}px`,
   },
   link: {
-    color: theme.palette.primary[500],
+    color: theme.palette.primary.main,
     textDecoration: 'none',
     '&:hover': {
       textDecoration: 'underline',

docs/src/pages/demos/grid-list/SingleLineGridList.js

@@ -20,7 +20,7 @@ const styles = theme => ({
     transform: 'translateZ(0)',
   },
   title: {
-    color: theme.palette.primary[200],
+    color: theme.palette.primary.light,
   },
   titleBar: {
     background:

docs/src/pages/demos/grid-list/grid-list.md

@@ -27,7 +27,7 @@ The overlay can accommodate a `title`, `subtitle` and secondary action - in this
 ## Advanced Grid list
 
 This example demonstrates "featured" tiles, using the `rows` and `cols` props to adjust the size of the tile, and the `padding` prop to adjust the spacing.
-The tiles have a customised titlebar, positioned at the top and with a custom gradient `titleBackground`.
+The tiles have a customized titlebar, positioned at the top and with a custom gradient `titleBackground`.
 The secondary action `IconButton` is positioned on the left.
 
 {{"demo": "pages/demos/grid-list/AdvancedGridList.js", "hideEditButton": true}}

docs/src/pages/demos/menus/ListItemComposition.js

@@ -11,7 +11,7 @@ import SendIcon from 'material-ui-icons/Send';
 const styles = theme => ({
   menuItem: {
     '&:focus': {
-      backgroundColor: theme.palette.primary[500],
+      backgroundColor: theme.palette.primary.main,
       '& $text, & $icon': {
         color: theme.palette.common.white,
       },

docs/src/pages/demos/tables/EnhancedTable.js

@@ -19,6 +19,7 @@ import IconButton from 'material-ui/IconButton';
 import Tooltip from 'material-ui/Tooltip';
 import DeleteIcon from 'material-ui-icons/Delete';
 import FilterListIcon from 'material-ui-icons/FilterList';
+import { lighten } from 'material-ui/styles/colorManipulator';
 
 let counter = 0;
 function createData(name, calories, fat, carbs, protein) {
@@ -98,12 +99,12 @@ const toolbarStyles = theme => ({
   highlight:
     theme.palette.type === 'light'
       ? {
-          color: theme.palette.secondary.A700,
-          backgroundColor: theme.palette.secondary.A100,
+          color: theme.palette.secondary.dark,
+          backgroundColor: lighten(theme.palette.secondary.light, 0.4),
         }
       : {
-          color: theme.palette.secondary.A100,
-          backgroundColor: theme.palette.secondary.A700,
+          color: lighten(theme.palette.secondary.light, 0.4),
+          backgroundColor: theme.palette.secondary.dark,
         },
   spacer: {
     flex: '1 1 100%',

docs/src/pages/guides/ReactJss.js

@@ -7,7 +7,7 @@ import Typography from 'material-ui/Typography';
 // 1. We define the styles.
 const styles = theme => ({
   root: {
-    color: props => (props.variant === 'primary' ? theme.palette.primary[500] : 'inherit'),
+    color: props => (props.variant === 'primary' ? theme.palette.primary.main : 'inherit'),
     textDecoration: 'inherit',
     '&:hover': {
       textDecoration: 'underline',

docs/src/pages/guides/interoperability.md

@@ -105,7 +105,7 @@ In the following demo we demonstrate how to use `injectSheet()` and "the styles
 const styles = theme => ({
  root: {
    color: props => (props.variant === 'primary'
-     ? theme.palette.primary[500]
+     ? theme.palette.primary.main
      : 'inherit'),
    textDecoration: 'inherit',
  },

docs/src/pages/layout/MediaQuery.js

@@ -9,10 +9,10 @@ const styles = theme => ({
   root: {
     padding: theme.spacing.unit,
     [theme.breakpoints.up('md')]: {
-      backgroundColor: theme.palette.primary[500],
+      backgroundColor: theme.palette.primary.main,
     },
     [theme.breakpoints.down('sm')]: {
-      backgroundColor: theme.palette.secondary.A400,
+      backgroundColor: theme.palette.secondary.main,
     },
   },
 });

pages/_document.js

@@ -33,7 +33,7 @@ class MyDocument extends Document {
           */}
           <link rel="manifest" href="/static/manifest.json" />
           {/* PWA primary color */}
-          <meta name="theme-color" content={pageContext.theme.palette.primary[500]} />
+          <meta name="theme-color" content={pageContext.theme.palette.primary.main} />
           <link
             rel="stylesheet"
             href="https://fonts.googleapis.com/css?family=Roboto:300,400,500"

pages/index.js

@@ -21,8 +21,8 @@ const styles = theme => ({
     justifyContent: 'center',
     alignItems: 'center',
     backgroundColor:
-      theme.palette.type === 'light' ? theme.palette.primary[500] : theme.palette.primary[800],
-    color: theme.palette.getContrastText(theme.palette.primary[500]),
+      theme.palette.type === 'light' ? theme.palette.primary.main : theme.palette.primary.dark,
+    color: theme.palette.getContrastText(theme.palette.primary.main),
   },
   content: {
     paddingTop: theme.spacing.unit * 8,

src/AppBar/AppBar.js

@@ -37,12 +37,12 @@ export const styles = theme => ({
     color: theme.palette.getContrastText(theme.palette.background.appBar),
   },
   colorPrimary: {
-    backgroundColor: theme.palette.primary[500],
-    color: theme.palette.getContrastText(theme.palette.primary[500]),
+    backgroundColor: theme.palette.primary.main,
+    color: theme.palette.primary.contrastText,
   },
   colorAccent: {
-    backgroundColor: theme.palette.secondary.A200,
-    color: theme.palette.getContrastText(theme.palette.secondary.A200),
+    backgroundColor: theme.palette.secondary.light,
+    color: theme.palette.getContrastText(theme.palette.secondary.light),
   },
 });
 

src/Badge/Badge.js

@@ -34,12 +34,12 @@ export const styles = theme => ({
     zIndex: 1, // Render the badge on top of potential ripples.
   },
   colorPrimary: {
-    backgroundColor: theme.palette.primary[500],
-    color: theme.palette.getContrastText(theme.palette.primary[500]),
+    backgroundColor: theme.palette.primary.main,
+    color: theme.palette.primary.contrastText,
   },
   colorAccent: {
-    backgroundColor: theme.palette.secondary.A200,
-    color: theme.palette.getContrastText(theme.palette.secondary.A200),
+    backgroundColor: theme.palette.secondary.light,
+    color: theme.palette.getContrastText(theme.palette.secondary.light),
   },
 });
 

src/BottomNavigation/BottomNavigationAction.js

@@ -23,7 +23,7 @@ export const styles = theme => ({
   },
   selected: {
     paddingTop: 6,
-    color: theme.palette.primary[500],
+    color: theme.palette.primary.main,
   },
   selectedIconOnly: {
     paddingTop: theme.spacing.unit * 2,