[docs] Improve /customization/typography/ (#17307)

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

@@ -261,3 +261,7 @@ function MyComponent(props) {
 
 export default withWidth()(MyComponent);
 ```
+
+## Default values
+
+You can explore the default values of the breakpoints using [the theme explorer](/customization/default-theme/?expend-path=$.breakpoints) or by opening the dev tools console on this page (`window.theme.breakpoints`).

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

@@ -177,3 +177,7 @@ const theme = createMuiTheme({
 ```
 
 {{"demo": "pages/customization/palette/DarkTheme.js"}}
+
+## Default values
+
+You can explore the default values of the palette using [the theme explorer](/customization/default-theme/?expend-path=$.palette) or by opening the dev tools console on this page (`window.theme.palette`).

docs/src/pages/customization/spacing/spacing.md

@@ -2,17 +2,16 @@
 
 <p class="description">Use the theme.spacing() helper to create consistent spacing between the elements of your UI.</p>
 
-Material-UI uses [a recommended 8px scaling factor by default](https://material.io/design/layout/understanding-layout.html).
+Material-UI uses [a recommended 8px scaling factor](https://material.io/design/layout/understanding-layout.html) by default.
 
 ```js
-const styles = theme => ({
-  root: {
-    // JSS uses px as the default units for this CSS property.
-    padding: theme.spacing(2), // = 8 * 2
-  },
-});
+const theme = createMuiTheme();
+
+theme.spacing(2) // = 8 * 2
 ```
 
+## Custom spacing
+
 You can change the spacing transformation by providing:
 
 - a number
@@ -48,8 +47,14 @@ theme.spacing(2); // = 8
 ## Multiple arity
 
 The `theme.spacing()` helper accepts up to 4 arguments.
-You can use the arguments to reduce the boilerplate:
-```diff
--  padding: `${theme.spacing(1)}px ${theme.spacing(2)}px`,
-+  padding: theme.spacing(1, 2), // '8px 16px'
+You can use the arguments to reduce the boilerplate. Instead of doing:
+
+```js
+padding: `${theme.spacing(1)}px ${theme.spacing(2)}px`, // '8px 16px'
+```
+
+you can do:
+
+```js
+padding: theme.spacing(1, 2), // '8px 16px'
 ```

docs/src/pages/customization/typography/TypographyVariants.js

@@ -0,0 +1,31 @@
+import React from 'react';
+import { createMuiTheme } from '@material-ui/core/styles';
+import { ThemeProvider } from '@material-ui/styles';
+import Typography from '@material-ui/core/Typography';
+import Button from '@material-ui/core/Button';
+
+const theme = createMuiTheme({
+  typography: {
+    subtitle1: {
+      fontSize: 12,
+    },
+    body1: {
+      fontWeight: 500,
+    },
+    button: {
+      fontStyle: 'italic',
+    },
+  },
+});
+
+export default function TypographyVariants() {
+  return (
+    <ThemeProvider theme={theme}>
+      <div>
+        <Typography variant="subtitle1">subtitle</Typography>
+        <Typography>body1</Typography>
+        <Button>Button</Button>
+      </div>
+    </ThemeProvider>
+  );
+}

docs/src/pages/customization/typography/TypographyVariants.tsx

@@ -0,0 +1,31 @@
+import React from 'react';
+import { createMuiTheme } from '@material-ui/core/styles';
+import { ThemeProvider } from '@material-ui/styles';
+import Typography from '@material-ui/core/Typography';
+import Button from '@material-ui/core/Button';
+
+const theme = createMuiTheme({
+  typography: {
+    subtitle1: {
+      fontSize: 12,
+    },
+    body1: {
+      fontWeight: 500,
+    },
+    button: {
+      fontStyle: 'italic',
+    },
+  },
+});
+
+export default function TypographyVariants() {
+  return (
+    <ThemeProvider theme={theme}>
+      <div>
+        <Typography variant="subtitle1">subtitle</Typography>
+        <Typography>body1</Typography>
+        <Button>Button</Button>
+      </div>
+    </ThemeProvider>
+  );
+}

docs/src/pages/customization/typography/typography.md

@@ -2,14 +2,11 @@
 
 <p class="description">The theme provides a set of type sizes that work well together, and also with the layout grid.</p>
 
-The following example demonstrates how to change the [default values](/customization/default-theme/?expend-path=$.typography) of the typography in the theme.
-You can learn more about how to use the [Typography component](/components/typography/) by checking out the dedicated page.
-
-{{"demo": "pages/customization/typography/TypographyTheme.js"}}
-
 ## Font family
 
-You can use the system font instead of the default Roboto font.
+You can change the font family with the `theme.typography.fontFamily` property.
+
+For instance, this demo use the system font instead of the default Roboto font:
 
 ```js
 const theme = createMuiTheme({
@@ -30,7 +27,7 @@ const theme = createMuiTheme({
 });
 ```
 
-## Self-host fonts
+### Self-hosted fonts
 
 To self-host fonts, download the font files in `ttf`, `woff`, and/or `woff2` formats and import them into your code.
 
@@ -55,25 +52,13 @@ const raleway = {
 };
 ```
 
-Then, you can change the theme to use this new font.
-In order to globally define Raleway as a font face the [`CssBaseline`](/components/css-baseline/) component needs to be used.
+Next, you need to change the theme to use this new font.
+In order to globally define Raleway as a font face, the [`CssBaseline`](/components/css-baseline/) component can be used (or any other CSS solution of your choice).
 
 ```js
 const theme = createMuiTheme({
   typography: {
-    fontFamily: [
-      'Raleway',
-      '-apple-system',
-      'BlinkMacSystemFont',
-      '"Segoe UI"',
-      'Roboto',
-      '"Helvetica Neue"',
-      'Arial',
-      'sans-serif',
-      '"Apple Color Emoji"',
-      '"Segoe UI Emoji"',
-      '"Segoe UI Symbol"',
-    ].join(','),
+    fontFamily: 'Raleway, Arial',
   },
   overrides: {
     MuiCssBaseline: {
@@ -89,7 +74,7 @@ const theme = createMuiTheme({
 
 Material-UI uses `rem` units for the font size.
 The browser `<html>` element default font size is `16px`, but browsers have an option to change this value,
-so `rem` units allow us to accommodate the user's settings, resulting in a much better user experience.
+so `rem` units allow us to accommodate the user's settings, resulting in a better accessibility support.
 Users change font size settings for all kinds of reasons, from poor eyesight to choosing optimum settings
 for devices that can be vastly different in size and viewing distance.
 
@@ -111,7 +96,7 @@ The computed font size by the browser follows this mathematical equation:
 ![font-size](/static/images/font-size.gif)
 <!-- https://latex.codecogs.com/gif.latex?computed&space;=&space;specification&space;\frac{typography.fontSize}{14}&space;\frac{html&space;font&space;size}{typography.htmlFontSize} -->
 
-## HTML font size
+### HTML font size
 
 You might want to change the `<html>` element default font size. For instance, when using the [10px simplification](https://www.sitepoint.com/understanding-and-using-rem-units-in-css/).
 We provide a `htmlFontSize` theme property for this use case.
@@ -137,7 +122,7 @@ html {
 
 {{"demo": "pages/customization/typography/FontSizeTheme.js"}}
 
-## Responsive font sizes
+### Responsive font sizes
 
 The typography variants properties map directly to the generated CSS.
 You can use [media queries](/customization/breakpoints/#api) inside them:
@@ -162,8 +147,57 @@ To automate this setup, you can use the [`responsiveFontSizes()`](/customization
 
 You can see this in action in the example below. adjust your browser's window size, and notice how the font size changes as the width crosses the different [breakpoints](/customization/breakpoints/):
 
+```js
+import { createMuiTheme, responsiveFontSizes } from '@material-ui/core/styles';
+
+let theme = createMuiTheme();
+theme = responsiveFontSizes(theme);
+```
+
 {{"demo": "pages/customization/typography/ResponsiveFontSizes.js"}}
 
-## Fluid font sizes
+### Fluid font sizes
 
 To be done: [#15251](https://github.com/mui-org/material-ui/issues/15251).
+
+## Variants
+
+The typography object comes with [13 variants](/components/typography/#component) by default:
+
+- h1
+- h2
+- h3
+- h4
+- h5
+- h6
+- subtitle1
+- subtitle2
+- body1
+- body2
+- button
+- caption
+- overline
+
+Each of these variants can be customized individually:
+
+```js
+const theme = createMuiTheme({
+  typography: {
+    subtitle1: {
+      fontSize: 12,
+    },
+    body1: {
+      fontWeight: 500,
+    },
+    button: {
+      fontStyle: 'italic',
+    },
+  },
+});
+```
+
+{{"demo": "pages/customization/typography/TypographyVariants.js"}}
+
+## Default values
+
+You can explore the default values of the typography using [the theme explorer](/customization/default-theme/?expend-path=$.typography) or by opening the dev tools console on this page (`window.theme.typography`).

packages/material-ui/src/Tooltip/Tooltip.js

@@ -13,6 +13,10 @@ import { useForkRef } from '../utils/reactHelpers';
 import { useIsFocusVisible } from '../utils/focusVisible';
 import useTheme from '../styles/useTheme';
 
+function round(value) {
+  return Math.round(value * 1e5) / 1e5;
+}
+
 export const styles = theme => ({
   /* Styles applied to the Popper component. */
   popper: {
@@ -35,7 +39,7 @@ export const styles = theme => ({
     fontFamily: theme.typography.fontFamily,
     padding: '4px 8px',
     fontSize: theme.typography.pxToRem(10),
-    lineHeight: `${theme.typography.round(14 / 10)}em`,
+    lineHeight: `${round(14 / 10)}em`,
     maxWidth: 300,
     wordWrap: 'break-word',
     fontWeight: theme.typography.fontWeightMedium,
@@ -44,7 +48,7 @@ export const styles = theme => ({
   touch: {
     padding: '8px 16px',
     fontSize: theme.typography.pxToRem(14),
-    lineHeight: `${theme.typography.round(16 / 14)}em`,
+    lineHeight: `${round(16 / 14)}em`,
     fontWeight: theme.typography.fontWeightRegular,
   },
   /* Styles applied to the tooltip (label wrapper) element if `placement` contains "left". */