From 5e797e96b4c627b8b9642def4d0ab3a3815154a9 Mon Sep 17 00:00:00 2001
From: Matt <github@nospam.33m.co>
Date: Wed, 4 Mar 2020 14:43:13 +0000
Subject: [PATCH] [docs] Simplify some demos (#19608)

---
 .../pages/components/buttons/UploadButtons.js | 22 -----
 .../components/buttons/UploadButtons.tsx      | 22 -----
 .../pages/components/checkboxes/checkboxes.md |  6 +-
 .../radio-buttons/FormControlLabelPosition.js |  2 +-
 .../FormControlLabelPosition.tsx              |  2 +-
 .../radio-buttons/RadioButtonsGroup.js        | 65 ++-----------
 .../radio-buttons/RadioButtonsGroup.tsx       | 67 ++------------
 .../components/radio-buttons/radio-buttons.md |  6 +-
 .../components/slider/ContinuousSlider.js     |  5 +-
 .../components/slider/ContinuousSlider.tsx    |  5 +-
 .../pages/components/slider/DiscreteSlider.js | 83 ++---------------
 .../components/slider/DiscreteSlider.tsx      | 91 +++----------------
 .../components/slider/DiscreteSliderLabel.js  | 56 ++++++++++++
 .../components/slider/DiscreteSliderLabel.tsx | 58 ++++++++++++
 .../components/slider/DiscreteSliderMarks.js  | 56 ++++++++++++
 .../components/slider/DiscreteSliderMarks.tsx | 58 ++++++++++++
 .../components/slider/DiscreteSliderSteps.js  | 36 ++++++++
 .../components/slider/DiscreteSliderSteps.tsx | 36 ++++++++
 .../components/slider/DiscreteSliderValues.js | 58 ++++++++++++
 .../slider/DiscreteSliderValues.tsx           | 58 ++++++++++++
 docs/src/pages/components/slider/slider.md    | 52 ++++++++---
 .../src/pages/components/switches/switches.md |  8 +-
 22 files changed, 519 insertions(+), 333 deletions(-)
 create mode 100644 docs/src/pages/components/slider/DiscreteSliderLabel.js
 create mode 100644 docs/src/pages/components/slider/DiscreteSliderLabel.tsx
 create mode 100644 docs/src/pages/components/slider/DiscreteSliderMarks.js
 create mode 100644 docs/src/pages/components/slider/DiscreteSliderMarks.tsx
 create mode 100644 docs/src/pages/components/slider/DiscreteSliderSteps.js
 create mode 100644 docs/src/pages/components/slider/DiscreteSliderSteps.tsx
 create mode 100644 docs/src/pages/components/slider/DiscreteSliderValues.js
 create mode 100644 docs/src/pages/components/slider/DiscreteSliderValues.tsx

diff --git a/docs/src/pages/components/buttons/UploadButtons.js b/docs/src/pages/components/buttons/UploadButtons.js
index 576f2cb3f14329..34af8b626a80d7 100644
--- a/docs/src/pages/components/buttons/UploadButtons.js
+++ b/docs/src/pages/components/buttons/UploadButtons.js
@@ -32,28 +32,6 @@ export default function UploadButtons() {
           Upload
         </Button>
       </label>
-      <input
-        accept="image/*"
-        className={classes.input}
-        id="text-button-file"
-        multiple
-        type="file"
-      />
-      <label htmlFor="text-button-file">
-        <Button component="span">Upload</Button>
-      </label>
-      <input
-        accept="image/*"
-        className={classes.input}
-        id="outlined-button-file"
-        multiple
-        type="file"
-      />
-      <label htmlFor="outlined-button-file">
-        <Button variant="outlined" component="span">
-          Upload
-        </Button>
-      </label>
       <input accept="image/*" className={classes.input} id="icon-button-file" type="file" />
       <label htmlFor="icon-button-file">
         <IconButton color="primary" aria-label="upload picture" component="span">
diff --git a/docs/src/pages/components/buttons/UploadButtons.tsx b/docs/src/pages/components/buttons/UploadButtons.tsx
index f35595ea03d5cc..44c29bae7b1fc6 100644
--- a/docs/src/pages/components/buttons/UploadButtons.tsx
+++ b/docs/src/pages/components/buttons/UploadButtons.tsx
@@ -34,28 +34,6 @@ export default function UploadButtons() {
           Upload
         </Button>
       </label>
-      <input
-        accept="image/*"
-        className={classes.input}
-        id="text-button-file"
-        multiple
-        type="file"
-      />
-      <label htmlFor="text-button-file">
-        <Button component="span">Upload</Button>
-      </label>
-      <input
-        accept="image/*"
-        className={classes.input}
-        id="outlined-button-file"
-        multiple
-        type="file"
-      />
-      <label htmlFor="outlined-button-file">
-        <Button variant="outlined" component="span">
-          Upload
-        </Button>
-      </label>
       <input accept="image/*" className={classes.input} id="icon-button-file" type="file" />
       <label htmlFor="icon-button-file">
         <IconButton color="primary" aria-label="upload picture" component="span">
diff --git a/docs/src/pages/components/checkboxes/checkboxes.md b/docs/src/pages/components/checkboxes/checkboxes.md
index 759abef386026d..037f1a2d6ce3fd 100644
--- a/docs/src/pages/components/checkboxes/checkboxes.md
+++ b/docs/src/pages/components/checkboxes/checkboxes.md
@@ -13,9 +13,13 @@ If you have multiple options appearing in a list,
 you can preserve space by using checkboxes instead of on/off switches.
 If you have a single option, avoid using a checkbox and use an on/off switch instead.
 
+## Basic checkboxes
+
 {{"demo": "pages/components/checkboxes/Checkboxes.js"}}
 
-`Checkbox` can also be used with a label description thanks to the `FormControlLabel` component.
+## Checkbox with FormControlLabel
+
+`Checkbox` can be provided with a label thanks to the `FormControlLabel` component.
 
 {{"demo": "pages/components/checkboxes/CheckboxLabels.js"}}
 
diff --git a/docs/src/pages/components/radio-buttons/FormControlLabelPosition.js b/docs/src/pages/components/radio-buttons/FormControlLabelPosition.js
index c27ee9a0705b80..76dfb333989799 100644
--- a/docs/src/pages/components/radio-buttons/FormControlLabelPosition.js
+++ b/docs/src/pages/components/radio-buttons/FormControlLabelPosition.js
@@ -6,7 +6,7 @@ import FormControl from '@material-ui/core/FormControl';
 import FormLabel from '@material-ui/core/FormLabel';
 
 export default function FormControlLabelPosition() {
-  const [value, setValue] = React.useState('female');
+  const [value, setValue] = React.useState('top');
 
   const handleChange = event => {
     setValue(event.target.value);
diff --git a/docs/src/pages/components/radio-buttons/FormControlLabelPosition.tsx b/docs/src/pages/components/radio-buttons/FormControlLabelPosition.tsx
index 4f170c4d20397d..b718cfa8502a66 100644
--- a/docs/src/pages/components/radio-buttons/FormControlLabelPosition.tsx
+++ b/docs/src/pages/components/radio-buttons/FormControlLabelPosition.tsx
@@ -6,7 +6,7 @@ import FormControl from '@material-ui/core/FormControl';
 import FormLabel from '@material-ui/core/FormLabel';
 
 export default function FormControlLabelPosition() {
-  const [value, setValue] = React.useState('female');
+  const [value, setValue] = React.useState('top');
 
   const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
     setValue((event.target as HTMLInputElement).value);
diff --git a/docs/src/pages/components/radio-buttons/RadioButtonsGroup.js b/docs/src/pages/components/radio-buttons/RadioButtonsGroup.js
index 4d32977e8e63b3..97cb58fb52e803 100644
--- a/docs/src/pages/components/radio-buttons/RadioButtonsGroup.js
+++ b/docs/src/pages/components/radio-buttons/RadioButtonsGroup.js
@@ -1,20 +1,11 @@
 import React from 'react';
-import { makeStyles } from '@material-ui/core/styles';
 import Radio from '@material-ui/core/Radio';
 import RadioGroup from '@material-ui/core/RadioGroup';
-import FormHelperText from '@material-ui/core/FormHelperText';
 import FormControlLabel from '@material-ui/core/FormControlLabel';
 import FormControl from '@material-ui/core/FormControl';
 import FormLabel from '@material-ui/core/FormLabel';
 
-const useStyles = makeStyles(theme => ({
-  formControl: {
-    margin: theme.spacing(3),
-  },
-}));
-
 export default function RadioButtonsGroup() {
-  const classes = useStyles();
   const [value, setValue] = React.useState('female');
 
   const handleChange = event => {
@@ -22,52 +13,14 @@ export default function RadioButtonsGroup() {
   };
 
   return (
-    <div>
-      <FormControl component="fieldset" className={classes.formControl}>
-        <FormLabel component="legend">Gender</FormLabel>
-        <RadioGroup aria-label="gender" name="gender1" value={value} onChange={handleChange}>
-          <FormControlLabel value="female" control={<Radio />} label="Female" />
-          <FormControlLabel value="male" control={<Radio />} label="Male" />
-          <FormControlLabel value="other" control={<Radio />} label="Other" />
-          <FormControlLabel
-            value="disabled"
-            disabled
-            control={<Radio />}
-            label="(Disabled option)"
-          />
-        </RadioGroup>
-      </FormControl>
-      <FormControl component="fieldset" className={classes.formControl}>
-        <FormLabel component="legend">Gender</FormLabel>
-        <RadioGroup aria-label="gender" name="gender2" value={value} onChange={handleChange}>
-          <FormControlLabel
-            value="female"
-            control={<Radio color="primary" />}
-            label="Female"
-            labelPlacement="start"
-          />
-          <FormControlLabel
-            value="male"
-            control={<Radio color="primary" />}
-            label="Male"
-            labelPlacement="start"
-          />
-          <FormControlLabel
-            value="other"
-            control={<Radio color="primary" />}
-            label="Other"
-            labelPlacement="start"
-          />
-          <FormControlLabel
-            value="disabled"
-            disabled
-            control={<Radio />}
-            label="(Disabled option)"
-            labelPlacement="start"
-          />
-        </RadioGroup>
-        <FormHelperText>labelPlacement start</FormHelperText>
-      </FormControl>
-    </div>
+    <FormControl component="fieldset">
+      <FormLabel component="legend">Gender</FormLabel>
+      <RadioGroup aria-label="gender" name="gender1" value={value} onChange={handleChange}>
+        <FormControlLabel value="female" control={<Radio />} label="Female" />
+        <FormControlLabel value="male" control={<Radio />} label="Male" />
+        <FormControlLabel value="other" control={<Radio />} label="Other" />
+        <FormControlLabel value="disabled" disabled control={<Radio />} label="(Disabled option)" />
+      </RadioGroup>
+    </FormControl>
   );
 }
diff --git a/docs/src/pages/components/radio-buttons/RadioButtonsGroup.tsx b/docs/src/pages/components/radio-buttons/RadioButtonsGroup.tsx
index 9c3ded75821b11..6243074cf41e8d 100644
--- a/docs/src/pages/components/radio-buttons/RadioButtonsGroup.tsx
+++ b/docs/src/pages/components/radio-buttons/RadioButtonsGroup.tsx
@@ -1,22 +1,11 @@
 import React from 'react';
-import { makeStyles, Theme, createStyles } from '@material-ui/core/styles';
 import Radio from '@material-ui/core/Radio';
 import RadioGroup from '@material-ui/core/RadioGroup';
-import FormHelperText from '@material-ui/core/FormHelperText';
 import FormControlLabel from '@material-ui/core/FormControlLabel';
 import FormControl from '@material-ui/core/FormControl';
 import FormLabel from '@material-ui/core/FormLabel';
 
-const useStyles = makeStyles((theme: Theme) =>
-  createStyles({
-    formControl: {
-      margin: theme.spacing(3),
-    },
-  }),
-);
-
 export default function RadioButtonsGroup() {
-  const classes = useStyles();
   const [value, setValue] = React.useState('female');
 
   const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
@@ -24,52 +13,14 @@ export default function RadioButtonsGroup() {
   };
 
   return (
-    <div>
-      <FormControl component="fieldset" className={classes.formControl}>
-        <FormLabel component="legend">Gender</FormLabel>
-        <RadioGroup aria-label="gender" name="gender1" value={value} onChange={handleChange}>
-          <FormControlLabel value="female" control={<Radio />} label="Female" />
-          <FormControlLabel value="male" control={<Radio />} label="Male" />
-          <FormControlLabel value="other" control={<Radio />} label="Other" />
-          <FormControlLabel
-            value="disabled"
-            disabled
-            control={<Radio />}
-            label="(Disabled option)"
-          />
-        </RadioGroup>
-      </FormControl>
-      <FormControl component="fieldset" className={classes.formControl}>
-        <FormLabel component="legend">Gender</FormLabel>
-        <RadioGroup aria-label="gender" name="gender2" value={value} onChange={handleChange}>
-          <FormControlLabel
-            value="female"
-            control={<Radio color="primary" />}
-            label="Female"
-            labelPlacement="start"
-          />
-          <FormControlLabel
-            value="male"
-            control={<Radio color="primary" />}
-            label="Male"
-            labelPlacement="start"
-          />
-          <FormControlLabel
-            value="other"
-            control={<Radio color="primary" />}
-            label="Other"
-            labelPlacement="start"
-          />
-          <FormControlLabel
-            value="disabled"
-            disabled
-            control={<Radio />}
-            label="(Disabled option)"
-            labelPlacement="start"
-          />
-        </RadioGroup>
-        <FormHelperText>labelPlacement start</FormHelperText>
-      </FormControl>
-    </div>
+    <FormControl component="fieldset">
+      <FormLabel component="legend">Gender</FormLabel>
+      <RadioGroup aria-label="gender" name="gender1" value={value} onChange={handleChange}>
+        <FormControlLabel value="female" control={<Radio />} label="Female" />
+        <FormControlLabel value="male" control={<Radio />} label="Male" />
+        <FormControlLabel value="other" control={<Radio />} label="Other" />
+        <FormControlLabel value="disabled" disabled control={<Radio />} label="(Disabled option)" />
+      </RadioGroup>
+    </FormControl>
   );
 }
diff --git a/docs/src/pages/components/radio-buttons/radio-buttons.md b/docs/src/pages/components/radio-buttons/radio-buttons.md
index c552249b1225e7..ee72f34ec69b0f 100644
--- a/docs/src/pages/components/radio-buttons/radio-buttons.md
+++ b/docs/src/pages/components/radio-buttons/radio-buttons.md
@@ -12,13 +12,15 @@ If available options can be collapsed, consider using a dropdown menu because it
 
 Radio buttons should have the most commonly used option selected by default.
 
+## RadioGroup
+
 `RadioGroup` is a helpful wrapper used to group `Radio` components that provides an easier API, and proper keyboard accessibility to the group.
 
 {{"demo": "pages/components/radio-buttons/RadioButtonsGroup.js"}}
 
-## Standalone Radio Buttons
+## Standalone radio buttons
 
-`Radio` can also be used standalone, without the wrapper.
+`Radio` can also be used standalone, without the RadioGroup wrapper.
 
 {{"demo": "pages/components/radio-buttons/RadioButtons.js"}}
 
diff --git a/docs/src/pages/components/slider/ContinuousSlider.js b/docs/src/pages/components/slider/ContinuousSlider.js
index eb20b018d6392d..cd8ecd9ed0b56f 100644
--- a/docs/src/pages/components/slider/ContinuousSlider.js
+++ b/docs/src/pages/components/slider/ContinuousSlider.js
@@ -36,7 +36,10 @@ export default function ContinuousSlider() {
           <VolumeUp />
         </Grid>
       </Grid>
-      <Slider disabled defaultValue={30} aria-labelledby="continuous-slider" />
+      <Typography id="disabled-slider" gutterBottom>
+        Disabled slider
+      </Typography>
+      <Slider disabled defaultValue={30} aria-labelledby="disabled-slider" />
     </div>
   );
 }
diff --git a/docs/src/pages/components/slider/ContinuousSlider.tsx b/docs/src/pages/components/slider/ContinuousSlider.tsx
index e76a4edbc8f190..ad56830a6ffca5 100644
--- a/docs/src/pages/components/slider/ContinuousSlider.tsx
+++ b/docs/src/pages/components/slider/ContinuousSlider.tsx
@@ -36,7 +36,10 @@ export default function ContinuousSlider() {
           <VolumeUp />
         </Grid>
       </Grid>
-      <Slider disabled defaultValue={30} aria-labelledby="continuous-slider" />
+      <Typography id="disabled-slider" gutterBottom>
+        Disabled slider
+      </Typography>
+      <Slider disabled defaultValue={30} aria-labelledby="disabled-slider" />
     </div>
   );
 }
diff --git a/docs/src/pages/components/slider/DiscreteSlider.js b/docs/src/pages/components/slider/DiscreteSlider.js
index ecc93cc9681922..f034e1e9c75afe 100644
--- a/docs/src/pages/components/slider/DiscreteSlider.js
+++ b/docs/src/pages/components/slider/DiscreteSlider.js
@@ -3,42 +3,16 @@ import { makeStyles } from '@material-ui/core/styles';
 import Typography from '@material-ui/core/Typography';
 import Slider from '@material-ui/core/Slider';
 
-const useStyles = makeStyles(theme => ({
+const useStyles = makeStyles({
   root: {
     width: 300,
   },
-  margin: {
-    height: theme.spacing(3),
-  },
-}));
-
-const marks = [
-  {
-    value: 0,
-    label: '0°C',
-  },
-  {
-    value: 20,
-    label: '20°C',
-  },
-  {
-    value: 37,
-    label: '37°C',
-  },
-  {
-    value: 100,
-    label: '100°C',
-  },
-];
+});
 
 function valuetext(value) {
   return `${value}°C`;
 }
 
-function valueLabelFormat(value) {
-  return marks.findIndex(mark => mark.value === value) + 1;
-}
-
 export default function DiscreteSlider() {
   const classes = useStyles();
 
@@ -57,56 +31,19 @@ export default function DiscreteSlider() {
         min={10}
         max={110}
       />
-      <div className={classes.margin} />
-      <Typography id="discrete-slider-small-steps" gutterBottom>
-        Small steps
-      </Typography>
-      <Slider
-        defaultValue={0.00000005}
-        getAriaValueText={valuetext}
-        aria-labelledby="discrete-slider-small-steps"
-        step={0.00000001}
-        marks
-        min={-0.00000005}
-        max={0.0000001}
-        valueLabelDisplay="auto"
-      />
-      <div className={classes.margin} />
-      <Typography id="discrete-slider-custom" gutterBottom>
-        Custom marks
-      </Typography>
-      <Slider
-        defaultValue={20}
-        getAriaValueText={valuetext}
-        aria-labelledby="discrete-slider-custom"
-        step={10}
-        valueLabelDisplay="auto"
-        marks={marks}
-      />
-      <div className={classes.margin} />
-      <Typography id="discrete-slider-restrict" gutterBottom>
-        Restricted values
+      <Typography id="discrete-slider" gutterBottom>
+        Disabled
       </Typography>
       <Slider
-        defaultValue={20}
-        valueLabelFormat={valueLabelFormat}
+        defaultValue={30}
         getAriaValueText={valuetext}
-        aria-labelledby="discrete-slider-restrict"
-        step={null}
+        aria-labelledby="discrete-slider"
         valueLabelDisplay="auto"
-        marks={marks}
-      />
-      <div className={classes.margin} />
-      <Typography id="discrete-slider-always" gutterBottom>
-        Always visible
-      </Typography>
-      <Slider
-        defaultValue={80}
-        getAriaValueText={valuetext}
-        aria-labelledby="discrete-slider-always"
         step={10}
-        marks={marks}
-        valueLabelDisplay="on"
+        marks
+        min={10}
+        max={110}
+        disabled
       />
     </div>
   );
diff --git a/docs/src/pages/components/slider/DiscreteSlider.tsx b/docs/src/pages/components/slider/DiscreteSlider.tsx
index e70ee5e5fd65f7..d720aa2fbd7811 100644
--- a/docs/src/pages/components/slider/DiscreteSlider.tsx
+++ b/docs/src/pages/components/slider/DiscreteSlider.tsx
@@ -1,46 +1,18 @@
 import React from 'react';
-import { makeStyles, Theme, createStyles } from '@material-ui/core/styles';
+import { makeStyles } from '@material-ui/core/styles';
 import Typography from '@material-ui/core/Typography';
 import Slider from '@material-ui/core/Slider';
 
-const useStyles = makeStyles((theme: Theme) =>
-  createStyles({
-    root: {
-      width: 300,
-    },
-    margin: {
-      height: theme.spacing(3),
-    },
-  }),
-);
-
-const marks = [
-  {
-    value: 0,
-    label: '0°C',
-  },
-  {
-    value: 20,
-    label: '20°C',
-  },
-  {
-    value: 37,
-    label: '37°C',
-  },
-  {
-    value: 100,
-    label: '100°C',
+const useStyles = makeStyles({
+  root: {
+    width: 300,
   },
-];
+});
 
 function valuetext(value: number) {
   return `${value}°C`;
 }
 
-function valueLabelFormat(value: number) {
-  return marks.findIndex(mark => mark.value === value) + 1;
-}
-
 export default function DiscreteSlider() {
   const classes = useStyles();
 
@@ -59,56 +31,19 @@ export default function DiscreteSlider() {
         min={10}
         max={110}
       />
-      <div className={classes.margin} />
-      <Typography id="discrete-slider-small-steps" gutterBottom>
-        Small steps
-      </Typography>
-      <Slider
-        defaultValue={0.00000005}
-        getAriaValueText={valuetext}
-        aria-labelledby="discrete-slider-small-steps"
-        step={0.00000001}
-        marks
-        min={-0.00000005}
-        max={0.0000001}
-        valueLabelDisplay="auto"
-      />
-      <div className={classes.margin} />
-      <Typography id="discrete-slider-custom" gutterBottom>
-        Custom marks
-      </Typography>
-      <Slider
-        defaultValue={20}
-        getAriaValueText={valuetext}
-        aria-labelledby="discrete-slider-custom"
-        step={10}
-        valueLabelDisplay="auto"
-        marks={marks}
-      />
-      <div className={classes.margin} />
-      <Typography id="discrete-slider-restrict" gutterBottom>
-        Restricted values
+      <Typography id="discrete-slider" gutterBottom>
+        Disabled
       </Typography>
       <Slider
-        defaultValue={20}
-        valueLabelFormat={valueLabelFormat}
+        defaultValue={30}
         getAriaValueText={valuetext}
-        aria-labelledby="discrete-slider-restrict"
-        step={null}
+        aria-labelledby="discrete-slider"
         valueLabelDisplay="auto"
-        marks={marks}
-      />
-      <div className={classes.margin} />
-      <Typography id="discrete-slider-always" gutterBottom>
-        Always visible
-      </Typography>
-      <Slider
-        defaultValue={80}
-        getAriaValueText={valuetext}
-        aria-labelledby="discrete-slider-always"
         step={10}
-        marks={marks}
-        valueLabelDisplay="on"
+        marks
+        min={10}
+        max={110}
+        disabled
       />
     </div>
   );
diff --git a/docs/src/pages/components/slider/DiscreteSliderLabel.js b/docs/src/pages/components/slider/DiscreteSliderLabel.js
new file mode 100644
index 00000000000000..a86412f46ef38b
--- /dev/null
+++ b/docs/src/pages/components/slider/DiscreteSliderLabel.js
@@ -0,0 +1,56 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import Typography from '@material-ui/core/Typography';
+import Slider from '@material-ui/core/Slider';
+
+const useStyles = makeStyles(theme => ({
+  root: {
+    width: 300,
+  },
+  margin: {
+    height: theme.spacing(3),
+  },
+}));
+
+const marks = [
+  {
+    value: 0,
+    label: '0°C',
+  },
+  {
+    value: 20,
+    label: '20°C',
+  },
+  {
+    value: 37,
+    label: '37°C',
+  },
+  {
+    value: 100,
+    label: '100°C',
+  },
+];
+
+function valuetext(value) {
+  return `${value}°C`;
+}
+
+export default function DiscreteSlider() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Typography id="discrete-slider-always" gutterBottom>
+        Always visible
+      </Typography>
+      <Slider
+        defaultValue={80}
+        getAriaValueText={valuetext}
+        aria-labelledby="discrete-slider-always"
+        step={10}
+        marks={marks}
+        valueLabelDisplay="on"
+      />
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/slider/DiscreteSliderLabel.tsx b/docs/src/pages/components/slider/DiscreteSliderLabel.tsx
new file mode 100644
index 00000000000000..6604a527cca363
--- /dev/null
+++ b/docs/src/pages/components/slider/DiscreteSliderLabel.tsx
@@ -0,0 +1,58 @@
+import React from 'react';
+import { makeStyles, Theme, createStyles } from '@material-ui/core/styles';
+import Typography from '@material-ui/core/Typography';
+import Slider from '@material-ui/core/Slider';
+
+const useStyles = makeStyles((theme: Theme) =>
+  createStyles({
+    root: {
+      width: 300,
+    },
+    margin: {
+      height: theme.spacing(3),
+    },
+  }),
+);
+
+const marks = [
+  {
+    value: 0,
+    label: '0°C',
+  },
+  {
+    value: 20,
+    label: '20°C',
+  },
+  {
+    value: 37,
+    label: '37°C',
+  },
+  {
+    value: 100,
+    label: '100°C',
+  },
+];
+
+function valuetext(value: number) {
+  return `${value}°C`;
+}
+
+export default function DiscreteSlider() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Typography id="discrete-slider-always" gutterBottom>
+        Always visible
+      </Typography>
+      <Slider
+        defaultValue={80}
+        getAriaValueText={valuetext}
+        aria-labelledby="discrete-slider-always"
+        step={10}
+        marks={marks}
+        valueLabelDisplay="on"
+      />
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/slider/DiscreteSliderMarks.js b/docs/src/pages/components/slider/DiscreteSliderMarks.js
new file mode 100644
index 00000000000000..5119b72c20ebea
--- /dev/null
+++ b/docs/src/pages/components/slider/DiscreteSliderMarks.js
@@ -0,0 +1,56 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import Typography from '@material-ui/core/Typography';
+import Slider from '@material-ui/core/Slider';
+
+const useStyles = makeStyles(theme => ({
+  root: {
+    width: 300,
+  },
+  margin: {
+    height: theme.spacing(3),
+  },
+}));
+
+const marks = [
+  {
+    value: 0,
+    label: '0°C',
+  },
+  {
+    value: 20,
+    label: '20°C',
+  },
+  {
+    value: 37,
+    label: '37°C',
+  },
+  {
+    value: 100,
+    label: '100°C',
+  },
+];
+
+function valuetext(value) {
+  return `${value}°C`;
+}
+
+export default function DiscreteSlider() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Typography id="discrete-slider-custom" gutterBottom>
+        Custom marks
+      </Typography>
+      <Slider
+        defaultValue={20}
+        getAriaValueText={valuetext}
+        aria-labelledby="discrete-slider-custom"
+        step={10}
+        valueLabelDisplay="auto"
+        marks={marks}
+      />
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/slider/DiscreteSliderMarks.tsx b/docs/src/pages/components/slider/DiscreteSliderMarks.tsx
new file mode 100644
index 00000000000000..b763933c7c383c
--- /dev/null
+++ b/docs/src/pages/components/slider/DiscreteSliderMarks.tsx
@@ -0,0 +1,58 @@
+import React from 'react';
+import { makeStyles, Theme, createStyles } from '@material-ui/core/styles';
+import Typography from '@material-ui/core/Typography';
+import Slider from '@material-ui/core/Slider';
+
+const useStyles = makeStyles((theme: Theme) =>
+  createStyles({
+    root: {
+      width: 300,
+    },
+    margin: {
+      height: theme.spacing(3),
+    },
+  }),
+);
+
+const marks = [
+  {
+    value: 0,
+    label: '0°C',
+  },
+  {
+    value: 20,
+    label: '20°C',
+  },
+  {
+    value: 37,
+    label: '37°C',
+  },
+  {
+    value: 100,
+    label: '100°C',
+  },
+];
+
+function valuetext(value: number) {
+  return `${value}°C`;
+}
+
+export default function DiscreteSlider() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Typography id="discrete-slider-custom" gutterBottom>
+        Custom marks
+      </Typography>
+      <Slider
+        defaultValue={20}
+        getAriaValueText={valuetext}
+        aria-labelledby="discrete-slider-custom"
+        step={10}
+        valueLabelDisplay="auto"
+        marks={marks}
+      />
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/slider/DiscreteSliderSteps.js b/docs/src/pages/components/slider/DiscreteSliderSteps.js
new file mode 100644
index 00000000000000..b597b6b98f9c22
--- /dev/null
+++ b/docs/src/pages/components/slider/DiscreteSliderSteps.js
@@ -0,0 +1,36 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import Typography from '@material-ui/core/Typography';
+import Slider from '@material-ui/core/Slider';
+
+const useStyles = makeStyles({
+  root: {
+    width: 300,
+  },
+});
+
+function valuetext(value) {
+  return `${value}°C`;
+}
+
+export default function DiscreteSlider() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Typography id="discrete-slider-small-steps" gutterBottom>
+        Small steps
+      </Typography>
+      <Slider
+        defaultValue={0.00000005}
+        getAriaValueText={valuetext}
+        aria-labelledby="discrete-slider-small-steps"
+        step={0.00000001}
+        marks
+        min={-0.00000005}
+        max={0.0000001}
+        valueLabelDisplay="auto"
+      />
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/slider/DiscreteSliderSteps.tsx b/docs/src/pages/components/slider/DiscreteSliderSteps.tsx
new file mode 100644
index 00000000000000..4ce83bf1a4caad
--- /dev/null
+++ b/docs/src/pages/components/slider/DiscreteSliderSteps.tsx
@@ -0,0 +1,36 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import Typography from '@material-ui/core/Typography';
+import Slider from '@material-ui/core/Slider';
+
+const useStyles = makeStyles({
+  root: {
+    width: 300,
+  },
+});
+
+function valuetext(value: number) {
+  return `${value}°C`;
+}
+
+export default function DiscreteSlider() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Typography id="discrete-slider-small-steps" gutterBottom>
+        Small steps
+      </Typography>
+      <Slider
+        defaultValue={0.00000005}
+        getAriaValueText={valuetext}
+        aria-labelledby="discrete-slider-small-steps"
+        step={0.00000001}
+        marks
+        min={-0.00000005}
+        max={0.0000001}
+        valueLabelDisplay="auto"
+      />
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/slider/DiscreteSliderValues.js b/docs/src/pages/components/slider/DiscreteSliderValues.js
new file mode 100644
index 00000000000000..493e0f6b14b337
--- /dev/null
+++ b/docs/src/pages/components/slider/DiscreteSliderValues.js
@@ -0,0 +1,58 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import Typography from '@material-ui/core/Typography';
+import Slider from '@material-ui/core/Slider';
+
+const useStyles = makeStyles({
+  root: {
+    width: 300,
+  },
+});
+
+const marks = [
+  {
+    value: 0,
+    label: '0°C',
+  },
+  {
+    value: 20,
+    label: '20°C',
+  },
+  {
+    value: 37,
+    label: '37°C',
+  },
+  {
+    value: 100,
+    label: '100°C',
+  },
+];
+
+function valuetext(value) {
+  return `${value}°C`;
+}
+
+function valueLabelFormat(value) {
+  return marks.findIndex(mark => mark.value === value) + 1;
+}
+
+export default function DiscreteSlider() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Typography id="discrete-slider-restrict" gutterBottom>
+        Restricted values
+      </Typography>
+      <Slider
+        defaultValue={20}
+        valueLabelFormat={valueLabelFormat}
+        getAriaValueText={valuetext}
+        aria-labelledby="discrete-slider-restrict"
+        step={null}
+        valueLabelDisplay="auto"
+        marks={marks}
+      />
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/slider/DiscreteSliderValues.tsx b/docs/src/pages/components/slider/DiscreteSliderValues.tsx
new file mode 100644
index 00000000000000..c4efab8b7ea96d
--- /dev/null
+++ b/docs/src/pages/components/slider/DiscreteSliderValues.tsx
@@ -0,0 +1,58 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import Typography from '@material-ui/core/Typography';
+import Slider from '@material-ui/core/Slider';
+
+const useStyles = makeStyles({
+  root: {
+    width: 300,
+  },
+});
+
+const marks = [
+  {
+    value: 0,
+    label: '0°C',
+  },
+  {
+    value: 20,
+    label: '20°C',
+  },
+  {
+    value: 37,
+    label: '37°C',
+  },
+  {
+    value: 100,
+    label: '100°C',
+  },
+];
+
+function valuetext(value: number) {
+  return `${value}°C`;
+}
+
+function valueLabelFormat(value: number) {
+  return marks.findIndex(mark => mark.value === value) + 1;
+}
+
+export default function DiscreteSlider() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Typography id="discrete-slider-restrict" gutterBottom>
+        Restricted values
+      </Typography>
+      <Slider
+        defaultValue={20}
+        valueLabelFormat={valueLabelFormat}
+        getAriaValueText={valuetext}
+        aria-labelledby="discrete-slider-restrict"
+        step={null}
+        valueLabelDisplay="auto"
+        marks={marks}
+      />
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/slider/slider.md b/docs/src/pages/components/slider/slider.md
index 2cf8ca0062a68d..17f5fb5d160c5d 100644
--- a/docs/src/pages/components/slider/slider.md
+++ b/docs/src/pages/components/slider/slider.md
@@ -9,41 +9,65 @@ components: Slider
 
 [Sliders](https://material.io/design/components/sliders.html) reflect a range of values along a bar, from which users may select a single value. They are ideal for adjusting settings such as volume, brightness, or applying image filters.
 
-- 📦 [22 kB gzipped](/size-snapshot) (but only 8 kB without @material-ui/styles).
+- 📦 [22 kB gzipped](/size-snapshot) (but only +8 kB when used together with other Material-UI components).
+
+## Continuous sliders
+
+Continuous sliders allow users to select a value along a subjective range.
+
+{{"demo": "pages/components/slider/ContinuousSlider.js"}}
 
 ## Discrete sliders
 
 Discrete sliders can be adjusted to a specific value by referencing its value indicator.
 By order of demos:
 
-1. You can generate a mark for each step with `marks={true}`.
-1. You can change the default step increment.
-1. You can have custom marks by providing a rich array to the `marks` prop.
-1. You can restrict the selectable values to those provided with the `marks` prop with `step={null}`.
-1. You can force the thumb label to be always visible with `valueLabelDisplay="on"`.
+You can generate a mark for each step with `marks={true}`.
 
 {{"demo": "pages/components/slider/DiscreteSlider.js"}}
 
-## Customized sliders
+### Small steps
 
-Here are some examples of customizing the component. You can learn more about this in the [overrides documentation page](/customization/components/).
+You can change the default step increment.
 
-{{"demo": "pages/components/slider/CustomizedSlider.js"}}
+{{"demo": "pages/components/slider/DiscreteSliderSteps.js"}}
 
-## Continuous sliders
+### Custom marks
 
-Continuous sliders allow users to select a value along a subjective range.
+You can have custom marks by providing a rich array to the `marks` prop.
 
-{{"demo": "pages/components/slider/ContinuousSlider.js"}}
+{{"demo": "pages/components/slider/DiscreteSliderMarks.js"}}
+
+### Restricted values
 
-## Range sliders
+You can restrict the selectable values to those provided with the `marks` prop with `step={null}`.
+
+{{"demo": "pages/components/slider/DiscreteSliderValues.js"}}
+
+### Label always visible
+
+You can force the thumb label to be always visible with `valueLabelDisplay="on"`.
+
+{{"demo": "pages/components/slider/DiscreteSliderLabel.js"}}
+
+## Range slider
+
+The slider can be used to set the start and end of a range by supplying an array of values to the `value` prop.
 
 {{"demo": "pages/components/slider/RangeSlider.js"}}
 
-## With input field
+## Slider with input field
+
+In this example an input allows a discrete value to be set.
 
 {{"demo": "pages/components/slider/InputSlider.js"}}
 
+## Customized sliders
+
+Here are some examples of customizing the component. You can learn more about this in the [overrides documentation page](/customization/components/).
+
+{{"demo": "pages/components/slider/CustomizedSlider.js"}}
+
 ## Vertical sliders
 
 {{"demo": "pages/components/slider/VerticalSlider.js"}}
diff --git a/docs/src/pages/components/switches/switches.md b/docs/src/pages/components/switches/switches.md
index 84cabb0a4533d9..edf36dfd8946df 100644
--- a/docs/src/pages/components/switches/switches.md
+++ b/docs/src/pages/components/switches/switches.md
@@ -11,18 +11,20 @@ components: Switch, FormControl, FormGroup, FormLabel, FormControlLabel
 The option that the switch controls, as well as the state it’s in,
 should be made clear from the corresponding inline label.
 
+## Basic switches
+
 {{"demo": "pages/components/switches/Switches.js"}}
 
-## Switches with FormControlLabel
+## Switch with FormControlLabel
 
-`Switch` can also be used with a label description thanks to the `FormControlLabel` component.
+`Switch` can be provided with a description thanks to the `FormControlLabel` component.
 
 {{"demo": "pages/components/switches/SwitchLabels.js"}}
 
 ## Switches with FormGroup
 
 `FormGroup` is a helpful wrapper used to group selection controls components that provides an easier API.
-However, we encourage you to use a [Checkbox](/components/checkboxes/) instead.
+However, you are encouraged you to use [Checkboxes](/components/checkboxes/) instead if multiple related controls are required. (See: [When to use](#when-to-use)).
 
 {{"demo": "pages/components/switches/SwitchesGroup.js"}}