[docs] Add a note on the override of internal states (#11227)

docs/src/pages/customization/overrides/Classes.js → docs/src/pages/customization/overrides/ClassesNesting.js

@@ -18,22 +18,23 @@ const styles = {
   },
 };
 
-function Classes(props) {
+function ClassesNesting(props) {
+  const { classes } = props;
+
   return (
     <Button
       classes={{
-        root: props.classes.root, // class name, e.g. `classes-root-x`
-        label: props.classes.label, // class name, e.g. `classes-label-x`
+        root: classes.root, // class name, e.g. `classes-nesting-root-x`
+        label: classes.label, // class name, e.g. `classes-nesting-label-x`
       }}
     >
-      {props.children ? props.children : 'classes'}
+      classes nesting
     </Button>
   );
 }
 
-Classes.propTypes = {
-  children: PropTypes.node,
+ClassesNesting.propTypes = {
   classes: PropTypes.object.isRequired,
 };
 
-export default withStyles(styles)(Classes);
+export default withStyles(styles)(ClassesNesting);

docs/src/pages/customization/overrides/ClassesState.js

@@ -0,0 +1,46 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { withStyles } from 'material-ui/styles';
+import Button from 'material-ui/Button';
+
+const styles = {
+  root: {
+    background: 'linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%)',
+    borderRadius: 3,
+    border: 0,
+    color: 'white',
+    height: 48,
+    padding: '0 30px',
+    boxShadow: '0 3px 5px 2px rgba(255, 105, 135, .30)',
+    // $disabled is a reference to the local disabled
+    // rule within the same style sheet.
+    // By using &, we increase the specificity.
+    '&$disabled': {
+      background: 'rgba(0, 0, 0, 0.12)',
+      color: 'white',
+      boxShadow: 'none',
+    },
+  },
+  disabled: {},
+};
+
+function ClassesState(props) {
+  const { classes } = props;
+  return (
+    <Button
+      disabled
+      classes={{
+        root: classes.root, // class name, e.g. `classes-state-root-x`
+        disabled: classes.disabled, // class name, e.g. `classes-state-disabled-x`
+      }}
+    >
+      classes state
+    </Button>
+  );
+}
+
+ClassesState.propTypes = {
+  classes: PropTypes.object.isRequired,
+};
+
+export default withStyles(styles)(ClassesState);

docs/src/pages/customization/overrides/overrides.md

@@ -40,7 +40,23 @@ you wish to add or override.
 
 Notice that in addition to the button styling, the button label's capitalization has been changed:
 
-{{"demo": "pages/customization/overrides/Classes.js"}}
+{{"demo": "pages/customization/overrides/ClassesNesting.js"}}
+
+Aside from accessing nested elements, the `classes` property can be used to customize the internal states of Material-UI components.
+The components internal states, like `:hover`, `:focus`, `disabled` and `selected`, are styled with a higher CSS specificity.
+[Specificity is a weight](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) that is applied to a given CSS declaration.
+In order to override the components internal states, **you need to increase specificity too**.
+
+```css
+.classes-state-root {
+  /* ... */
+}
+.classes-state-root.disabled {
+  color: white;
+}
+```
+
+{{"demo": "pages/customization/overrides/ClassesState.js"}}
 
 ### Overriding with inline-style
 

pages/customization/overrides.js

@@ -15,11 +15,18 @@ module.exports = require('fs')
   .readFileSync(require.resolve('docs/src/pages/customization/overrides/ClassNames'), 'utf8')
 `,
         },
-        'pages/customization/overrides/Classes.js': {
-          js: require('docs/src/pages/customization/overrides/Classes').default,
+        'pages/customization/overrides/ClassesNesting.js': {
+          js: require('docs/src/pages/customization/overrides/ClassesNesting').default,
           raw: preval`
 module.exports = require('fs')
-  .readFileSync(require.resolve('docs/src/pages/customization/overrides/Classes'), 'utf8')
+  .readFileSync(require.resolve('docs/src/pages/customization/overrides/ClassesNesting'), 'utf8')
+`,
+        },
+        'pages/customization/overrides/ClassesState.js': {
+          js: require('docs/src/pages/customization/overrides/ClassesState').default,
+          raw: preval`
+module.exports = require('fs')
+  .readFileSync(require.resolve('docs/src/pages/customization/overrides/ClassesState'), 'utf8')
 `,
         },
         'pages/customization/overrides/InlineStyle.js': {