[docs] Add Emotion to style interoperability guide (#12966)

lukePeavey · oliviertassinari · commit 3204104bbe75 · 2018-09-23T11:20:48.000+02:00
* [docs] Add Emotion to style interoperability guide

* Add note on controlling priority to React Emotion section

* Remove extra spaces

* let's merge
diff --git a/docs/src/pages/guides/interoperability/interoperability.md b/docs/src/pages/guides/interoperability/interoperability.md
@@ -9,6 +9,8 @@ We have provided examples for the following styling solutions:
 
 - [Raw CSS](#raw-css)
 - [Styled Components](#styled-components)
+- [Emotion](#emotion)
+- [React Emotion](#react-emotion)
 - [CSS Modules](#css-modules)
 - [Global CSS](#global-css)
 - [React JSS](#react-jss)
@@ -141,6 +143,8 @@ export default StyledComponentsButton;
 
 [![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/xpp5oj9o0z)
 
+### Deeper elements
+
 In some cases, the approaches above will not work.
 For example, if you attempt to style a [Drawer](/demos/drawers) with variant `permanent`,
 you will likely need to affect the Drawer's underlying `paper` style.
@@ -184,6 +188,117 @@ export default StyledComponentsButton;
 
 [![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/j4n13yl1r9)
 
+
+## Emotion
+
+Emotion's **css()** method works seamlessly with Material-UI. The class names returned by **css()** can be directly passed to a component's `className` prop to override the root styles.
+
+```jsx
+import React from 'react';
+import { css } from 'emotion';
+import Button from '@material-ui/core/Button';
+
+const buttonStyles = css`
+  background: linear-gradient(45deg, #fe6b8b 30%, #ff8e53 90%);
+  border-radius: 3;
+  border: 0;
+  color: white;
+  height: 48px;
+  padding: 0 30px;
+  box-shadow: 0 3px 5px 2px rgba(255, 105, 135, 0.3);
+`;
+
+// We just assign them the Button's className attribute
+function EmotionButton() {
+  return (
+    <div>
+      <Button>Material-UI</Button>
+      <Button className={buttonStyles}>Emotion</Button>
+    </div>
+  );
+}
+
+export default EmotionButton
+```
+
+[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/yw93kl7y0j)
+
+### Deeper elements
+
+The styles created with **css()** can also be mapped to class names using the `classes` prop. This is useful when you want to customize the styles of deeper elements within a component.
+
+```jsx
+import React from 'react';
+import { css } from 'emotion';
+import Button from '@material-ui/core/Button';
+
+const styles = {
+  button: css({
+    background: 'linear-gradient(45deg, #fe6b8b 30%, #ff8e53 90%)',
+    borderRadius: 3,
+    border: 0,
+    height: 48,
+    padding: '0 30px',
+    boxShadow: '0 3px 5px 2px rgba(255, 105, 135, 0.3)',
+  }),
+  label: css({
+    color: 'papayawhip',
+  }),
+};
+
+function EmotionButton() {
+  return (
+    <div>
+      <Button>Material-UI</Button>
+      <Button className={styles.button} classes={{ label: styles.label }}>
+        Emotion
+      </Button>
+    </div>
+  );
+}
+
+export default EmotionButton
+```
+
+[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/4q8o1y975w)
+
+**Note:** By default Emotion and JSS both inject their styles at the bottom of the `<head>`. If you don't want to mark style attributes with **!important**, you need to change [the CSS injection order](/customization/css-in-js#css-injection-order), as in the examples.
+
+## React Emotion
+
+The **styled()** function can be used to customize the root styles of any Material-UI component.
+
+```jsx
+import React from 'react';
+import styled from 'react-emotion';
+import Button from '@material-ui/core/Button';
+
+const StyledButton = styled(Button)`
+  background: linear-gradient(45deg, #fe6b8b 30%, #ff8e53 90%);
+  border-radius: 3;
+  border: 0;
+  color: white;
+  height: 48px;
+  padding: 0 30px;
+  box-shadow: 0 3px 5px 2px rgba(255, 105, 135, 0.3);
+`;
+
+function ReactEmotionButton() {
+  return (
+    <div>
+      <Button>Material-UI</Button>
+      <StyledButton>React Emotion</StyledButton>
+    </div>
+  );
+}
+
+export default ReactEmotionButton;
+```
+
+[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/xj81yqx504)
+
+**Note:** By default Emotion and JSS both inject their styles at the bottom of the `<head>`. If you don't want to mark style attributes with **!important**, you need to change [the CSS injection order](/customization/css-in-js#css-injection-order), as in the examples.
+
 ## CSS Modules
 
 ![stars](https://img.shields.io/github/stars/css-modules/css-modules.svg?style=social&label=Star)
