readme and doc consolidation updates

README.md

@@ -1,7 +1,6 @@
-### All documentation on master is for version 8. The documentation for version 7 is located under the [`v7.3.2` tag](/~https://github.com/emotion-js/emotion/tree/v7.3.2).
 
 <p align="center" style="color: #343a40">
-  <img src="https://cdn.rawgit.com/tkh44/emotion/master/emotion.png" alt="emotion" height="200" width="200">
+  <img src="https://cdn.rawgit.com/tkh44/emotion/master/emotion.png" alt="emotion" height="150" width="150">
   <h1 align="center">emotion</h1>
 </p>
 <p align="center" style="font-size: 1.2rem;">The Next Generation of CSS-in-JS</p>
@@ -15,27 +14,75 @@
 ![react size](http://img.badgesize.io/https://unpkg.com/react-emotion/dist/DO-NOT-USE.min.js?label=react%20size)
 [![slack](https://emotion.now.sh/badge.svg)](http://emotion.now.sh/)
 
-emotion is a high performance, lightweight css-in-js library. 
-The core idea comes from Sunil Pai’s [glam](/~https://github.com/threepointone/glam) library and its philosophy is laid out [here](https://gist.github.com/threepointone/0ef30b196682a69327c407124f33d69a). 
-The basic idea is simple.
-You shouldn’t have to sacrifice runtime performance for good developer experience when writing CSS. emotion 
-minimizes the runtime cost of css-in-js dramatically by parsing your styles with PostCSS during compilation instead of at runtime. 
-
--- [Introduction Article](https://medium.com/@tkh44/emotion-ad1c45c6d28b)
+emotion is a high performance, lightweight css-in-js library. emotion minimizes the runtime cost of css-in-js dramatically by parsing your styles at build time and utilizing [insertRule](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet/insertRule) on the client.
 
 ---
+### Quick Start
+Get up and running with a single import.
+```bash
+npm install --save emotion 
+```
 
-### [Install](/~https://github.com/tkh44/emotion/tree/master/docs/install.md)
+```javascript
+import { css } from 'emotion';
 
-### Demos
-
-  - [Code Sandbox](https://codesandbox.io/s/pk1qjqpw67)
-  - [emotion website](/~https://github.com/tkh44/emotion/tree/master/packages/site) [[Demo Here](https://emotion.sh)]
+const app = document.getElementById('root');
+const myStyle = css`
+  color: rebeccapurple;
+`
+app.classList.add(myStyle);
+```
+### React with [Optional Babel Plugin](docs/babel.md)
+```bash
+npm install --save emotion react-emotion babel-plugin-emotion
+```
+_Note: use `preact-emotion` in place of `react-emotion` if using [Preact](/~https://github.com/developit/preact)_
+
+```javascript
+import styled, { css } from 'react-emotion';
+
+const Container = styled('div')`
+  background: #333;
+`
+const myStyle = css`
+  color: rebeccapurple;
+`
+const app = () => (
+<Container>
+  <p className={myStyle}>Hello World</p>
+</Container>
+);
+```
+
+[Demo Code Sandbox](https://codesandbox.io/s/pk1qjqpw67)
+
+### Examples
+
+  - [emotion website](packages/site) [[Demo Here](https://emotion.sh)]
   - [next-hnpwa-guide-kit](/~https://github.com/tkh44/next-hnpwa-guide-kit) [[Demo Here](https://hnpwa.life)]
   - **open a PR and add yours!**
 
-### [Documentation](/~https://github.com/tkh44/emotion/tree/master/docs)
+### About
+
+The core idea comes from Sunil Pai’s [glam](/~https://github.com/threepointone/glam) library and its philosophy is laid out [here](https://gist.github.com/threepointone/0ef30b196682a69327c407124f33d69a). 
+
+-- [Introduction Article](https://medium.com/@tkh44/emotion-ad1c45c6d28b)
+
+### Documentation
+#### API
+- Styling components with [`styled`](docs/styled.md)
+
+- Create composable styles with [`css` classes and props](docs/css.md)
+
+  - [`composition`](docs/composition.md)
+
+- [`keyframes`](docs/keyframes.md)
+- [`fontFace`](docs/font-face.md)
+- [`injectGlobal`](docs/inject-global.md)
 
+#### Doc files
+- [All docs](docs/)
+- [Version 7 docs](/~https://github.com/emotion-js/emotion/tree/v7.3.2)
 ### Ecosystem
 
   - [emotion-vue](/~https://github.com/egoist/emotion-vue)

docs/README.md

@@ -7,15 +7,11 @@
 - [Configurable Imports](/~https://github.com/emotion-js/emotion/tree/master/docs/configurable-imports.md) Useful when migrating from another css-in-js library such as styled-components or styled-jsx
 - [Preact](/~https://github.com/emotion-js/emotion/tree/master/docs/preact.md)
 - [Nested Selectors](/~https://github.com/emotion-js/emotion/tree/master/docs/nested.md)
-- [Pseudo Selectors ](/~https://github.com/emotion-js/emotion/tree/master/docs/pseudo.md)
-- [Media Queries](/~https://github.com/emotion-js/emotion/tree/master/docs/media.md)
 - [Composition](/~https://github.com/emotion-js/emotion/tree/master/docs/composition.md)
-- [Styling Any Component](/~https://github.com/emotion-js/emotion/tree/master/docs/styling-any-component.md)
 - [`styled.withComponent`](/~https://github.com/emotion-js/emotion/tree/master/docs/styled-with-component.md)
-- [Dynamic Props For `styled` Components](/~https://github.com/emotion-js/emotion/tree/master/docs/props.md)
 - [Using Javascript Objects for Styles](/~https://github.com/emotion-js/emotion/tree/master/docs/objects.md)
 - [`styled` With Object Styles](/~https://github.com/emotion-js/emotion/tree/master/docs/styled-with-object.md) (glamorous api)
-- [Styling Elements Via `css` Prop in JSX](/~https://github.com/emotion-js/emotion/tree/master/docs/css-prop.md)
+- [Styling Elements Via `css` Prop in JSX](/~https://github.com/emotion-js/emotion/tree/master/docs/css#CSS-Prop.md)
 - [Injecting Global Styles](/~https://github.com/emotion-js/emotion/tree/master/docs/inject-global.md)
 - [Custom Fonts](/~https://github.com/emotion-js/emotion/tree/master/docs/font-face.md)
 - [Keyframe Animations](/~https://github.com/emotion-js/emotion/tree/master/docs/keyframes.md)
@@ -24,5 +20,5 @@
 - [Source Maps](/~https://github.com/emotion-js/emotion/tree/master/docs/source-maps.md)
 - [Extracting Static Styles](/~https://github.com/emotion-js/emotion/tree/master/docs/extract-static.md)
 - [Using `withProps` To Attach Props](/~https://github.com/emotion-js/emotion/tree/master/docs/with-props.md) (styled-components `.attrs` api)
-- [Usage with babel-macros](/~https://github.com/tkh44/emotion/tree/master/docs/babel-macros.md)
+- [Usage with babel-macros](/~https://github.com/emotion-js/emotion/tree/master/docs/babel.md#usage-with-babel-macros)
 - [TypeScript](/~https://github.com/emotion-js/emotion/tree/master/docs/typescript.md)

docs/babel.md

@@ -0,0 +1,36 @@
+## Usage with Babel
+
+The Babel Plugin is highly recommended, but not required in version 8 and above.
+
+See the [installation instructions](install.md).
+
+### Features which are enabled with the babel plugin
+
+### styled.element Syntax
+`styled('div')` will work without the plugin
+
+### Minification
+Any leading/trailing space between properties in your `css` and `styled` blocks is removed. This can reduce the size of your final bundle.
+
+### Dead Code Elimination
+Uglifyjs will use the injected `/*#__PURE__*/` flag comments to mark your `css` and `styled` blocks as candidates for dead code elimination.
+
+### Static Extraction
+Generated CSS that is eligible for extraction can be moved to an external css file.
+
+### Source Maps
+When enabled, navigate directly to the style declaration in your javascript file.
+
+### css as Prop
+Convenient helper for calling `css` and appending the generated className during compile time.
+
+## Babel Macros
+
+Instead of using emotion's babel plugin, you can use emotion with [`babel-macros`](/~https://github.com/kentcdodds/babel-macros). Add `babel-macros` to your babel config and import whatever you want from emotion but add `/macro` to the end. The macro is currently the same as inline mode. Currently every API except for the css prop is supported by the macro.
+
+```jsx
+import styled from 'react-emotion/macro'
+import { css, keyframes, fontFace, injectGlobal, flush, hydrate } from 'emotion/macro'
+```
+
+For some context, check out this [issue](/~https://github.com/facebookincubator/create-react-app/issues/2730).

docs/css.md

@@ -1,10 +1,12 @@
 ## CSS
 
-`css` takes in styles and returns a class name. It is the foundation of emotion.
+`css` accepts styles as a template literal, object, or array of objects and returns a class name. It is the foundation of emotion.
 
-```jsx
+```jsx harmony
 import { css } from 'emotion'
+import { lighten, modularScale } from 'polished'
 
+// Write your css as normal.
 const flex = css`
   display: flex;
 `
@@ -13,42 +15,54 @@ const justifyCenter = css`
   justifyContent: center;
 `
 
-<div className={justifyCenter}>
- Centered Content
-</div>
-```
-
-### Objects as Styles
-
-`css` can also take an object or array of objects as a parameter.
-This allows you to use your existing object styles in the emotion ecosystem.
-Another great benefit is that you can now use [polished](https://polished.js.org/) with emotion.
-
-```jsx harmony
-import { css } from 'emotion'
-import { lighten, modularScale } from 'polished'
-
+// As an object
 const cssA = {
+  // Easily use [polished](https://polished.js.org/)
   color: lighten(0.2, '#000'),
   "font-size": modularScale(1),
   [hiDPI(1.5)]: {
     "font-size": modularScale(1.25)
   }
 }
 
-const cssB = css`
-  ${cssA};
-  height: 64px;
-`
-
 const H1 = styled('h1')`
-  ${cssB};
+  ${cssA};
   font-size: ${modularScale(4)};
 `
 
 const H2 = styled(H1)`font-size:32px;`
+<div className={justifyCenter}>
+  <H2 scale={2} className={'legacy__class'}>
+    Centered Content
+  </H2>
+</div>
+```
+
+## CSS Prop 
+###### [requires babel plugin](babel.md)
+A shortcut for calling the css function and appending the result to the className prop. Done at compile time.
+_Note: CSS props are not compatible with babel's `"transform-react-inline-elements"` plugin. If you include it in your `.babelrc` no transformation will take place and your styles will silently fail._
 
-<H2 scale={2} className={'legacy__class'}>
-  hello world
-</H2>
-```
+```jsx
+function SomeComponent (props) {
+  // Create styles as if you're calling css and the class will be applied to the component
+  return (<div css={`
+    color: blue;
+    font-size: ${props.fontSize}px;
+
+    &:hover {
+      color: green;
+    }
+
+    & .some-class {
+      font-size: 20px;
+    }
+  `}>
+    This will be blue until hovered.
+    <div className="some-class">
+      This font size will be 20px
+    </div>
+  </div>)
+}
+
+```

docs/extract-static.md

@@ -1,7 +1,10 @@
 ## Extract Static
+###### [requires babel plugin](babel.md)
 
 Extract styles with no interpolations into external css files.
 
+While there are some beneficial use cases for `extractStatic`, emotion's inherent performance since version 8 makes the added complexity of this feature somewhat disadvantageous.
+
 
 **does NOT work with object styles**
 

docs/index.md

@@ -6,7 +6,7 @@
 </h1>
 <p align="center" style="font-size: 1.2rem;">high performance css-in-js</p>
 
-[github](/~https://github.com/tkh44/emotion)
+[github](/~https://github.com/emotion-js/emotion)
 [npm](https://npm.im/emotion)
 
 In order to learn more about emotion lets build this guide together. By following along below, we can get this markdown looking good.

docs/install.md

@@ -1,35 +1,53 @@
-[github](/~https://github.com/tkh44/emotion)
-[npm](https://npm.im/emotion)
-
 ## Install
 
 ```bash
 npm install --save emotion react-emotion babel-plugin-emotion
 ```
 
-**.babelrc**
+All `emotion` APIs are available from the `react-emotion` package.
+
+```javascript
+import styled, { css, injectGlobal } from 'react-emotion';
+```
+
+### .babelrc
+
+[More information on the babel plugin](babel.md)
+
+_`"emotion"` must be the **first plugin** in your babel config `plugins` list._
+
+Takes optional configs:
+- [extractStatic](babel.md#Static-Extraction) _{boolean}_
+- [sourceMap](babel.md#Static-Extraction) _{boolean}_
 ```json
 {
   "plugins": [
-    "emotion"
+    ["emotion"]
   ]
 }
 ```
-
-**Notes:**
-- Make sure `"emotion"` is the first plugin.
-- If you are using Babel's env option in your `.babelrc` file, ensure that emotion is first in every environment's list of plugins.
+If using Babel's env option emotion must also be first for each environment.
   ```json
   {
     "env": {
       "production": {
-        "plugins": ["emotion", "some-other-plugin"]
+        "plugins": [
+          "emotion", 
+          [...all other babel plugins...]
+        ]
       }
     },
     "plugins": ["emotion"]
   }
   ```
+###  Preact
 
-### Preact
+Import `preact-emotion` instead of `react-emotion` and use it the same way you would with React.
 
-If you're using [Preact](/~https://github.com/developit/preact) instead of [React](/~https://github.com/facebook/react), install [`preact-emotion`](./preact.md). The babel setup remains the same.
+```jsx
+import styled from 'preact-emotion'
+
+const SomeComponent = styled.div`
+  display: flex;
+`
+```