docs: improve interface docs

README.md

@@ -1,10 +1,10 @@
-![libreact logo](./docs/assets/freestyler.png)
+    ![libreact logo](./docs/assets/freestyler.png)
 
 # freestyler
 
 [![][npm-badge]][npm-url] [![][travis-badge]][travis-url]
 
-[**5<sup>th</sup> generation**](https://github.com/streamich/freestyler/blob/feat/universal-2/docs/en/terminology.md#5th-generation) [React styling library][npm-url] &mdash;
+[**5<sup>th</sup> generation**](./docs/en/generations.md) [React styling library][npm-url] &mdash;
 it is *lightning fast*, *lean*, and with *gazillion* [__*feat*ures__](#feat).
 
 ```
@@ -46,14 +46,14 @@ it is *lightning fast*, *lean*, and with *gazillion* [__*feat*ures__](#feat).
 - __Generic:__ [__3<sup>rd</sup> Generation Interfaces__](./docs/en/3rd-gen.md)
     - [`rule()` Interface](./docs/en/rule.md)
     - [`StyleSheet.create()` Interface](./docs/en/StyleSheet.md) with lazy rendering
+    - [`hyperstyle()` `styleName` Interface](./docs/en/hyperstyle.md)
 - __React.js:__ [__4<sup>th</sup> Generation Interfaces__](./docs/en/4th-gen.md)
     - [`styled()()` Component Interface](./docs/en/styled.md)
     - [`@css` Static Class Decorator Interface](./docs/en/css-static-class-decorator.md)
     - [`@css()` Class Decorator Interface](./docs/en/css-class-decorator.md)
     - [`@css()` `.render()` Decorator Interface](./docs/en/css-render-decorator.md)
     - [`hoc()` Generator Interface](./docs/en/hoc-generator.md)
     - [`Component` Class Interface](./docs/en/component-class.md)
-    - [`hyperstyle()` `styleName` Interface](./docs/en/hyperstyle.md)
 - __React.js:__ [__5<sup>th</sup> Generation Interfaces__](./docs/en/5th-gen.md)
     - [`styleit()` and `<Styleit>` Interfaces](./docs/en/styleit.md)
     - [`jsxstyle()`, `<Block>`, `<Inline>`, `<InlineBlock>`, `<Row>`, and `<Column>` Interfaces](./docs/en/jsxstyle.md)

docs/en/StyleSheet.md

@@ -9,18 +9,25 @@ __Example__
 import StyleSheet from 'freestyler/lib/StyleSheet';
 
 const styles = StyleSheet.create({
-    button: {
-      background: 'tomato',
-    },
-    link: {
-      border: '1px solid tomato'
-    }
+  container: {
+    border: '1px solid tomato',
+  }
+  button: {
+    background: 'red',
+    borderRadius: '5px',
+    color: '#fff',
+  }
 });
 
-<div>
-    <button className={styles.button}>Hello</button>
-    <a className={styles.link}>world!</a>
-</div>
+class Button extends Component {
+  render () {
+    return (
+      <div className={styles.container}>
+        <button className={styles.button}/>
+      </div>
+    );
+  }
+}
 ```
 
 This approach has a couple of advantages over the [`rule`](./rule.md) interface. Firstly, it returns

docs/en/css-render-decorator.md

@@ -21,11 +21,20 @@ Add styling to your component using a function that returns a CSS-like object.
 
 ```jsx
 class App extends Component {
-    @css(({props, state, context}) => ({
-        border: '1px solid tomato'
-    }))
-    render () {
-        return <div>Hello world!</div>;
+  @css(({props, state}) => ({
+    bd: '1px solid ' + (props.color || 'tomato'),
+    '& > button': {
+      bg: 'red',
+      bdrad: '5px',
+      col: '#fff',
     }
+  }))
+  render () {
+    return (
+      <div>
+        <button className='button' />
+      </div>
+    );
+  }
 }
 ```

docs/en/generations.md

@@ -6,32 +6,33 @@ to what scope of variables those templates have access to? Module scope? Compone
 `.render()` method scope?
 
 Below we define five generations of CSS-in-JS libraries based on their template dynamicity and whether they
-use inline styles or inject actual CSS; starting from generation 1 — for the most static libraries —
-going all the way up to generation 5. Although not strictly true, this is also how React styling libraries evolved over time.
+use inline styles or inject actual CSS; starting from generation one — for the most static libraries —
+and going all the way up to generation five. Although not strictly true, this also corresponds to how React
+styling libraries evolved over time.
 
 
 ## 1<sup>st</sup> Generation
 
 First generation React styling libraries don't allow you to write styling in JavaScript and use any of
-JavaScript variables, instead, you have to use *CSS pre-processors*. The CSS source file is usually
-located in a separate `.*css` file.
+JavaScript variables, instead, you have to use *CSS pre-processors*. The CSS source files are usually
+located in separate `.*css` files.
 
   - *Notable example*: [`css-modules`][lib-css-modules]
 
 
 ## 2<sup>nd</sup> Generation
 
-Second generation React styling libraries emit __inline styles__ in `style` property of your JSX
-elements and are very dynamic, because they can use even `.render()` method scope variables. However,
-they use inline styles, thus, you don't get all the power of CSS>
+Second generation React styling libraries emit __inline styles__ in `style` property of your React
+elements, but are very dynamic, because they can use even `.render()` method scope variables. However,
+they use inline styles, thus, you don't get all the benefits of CSS.
 
   - *Notable example*: [`Radium`][lib-radium]
 
 
 ## 3<sup>rd</sup> Generation
 
 Third generation React styling libraries allow you to write CSS templates in JavaScript and inject actual *CSS* into
-DOM in `<style>` tags and generate unique scoped `className` properties. However, the style templates are *static*,
+DOM `<style>` tags. However, the templates are *static*,
 in a sense that they are defined in __module scope__, and thus they can't use component `props`. The reason why they are "static" is
 because they have access only to module scope JavaScript variables, which evaluate only once when the module is imported for the first time.
 
@@ -41,7 +42,7 @@ because they have access only to module scope JavaScript variables, which evalua
 ## 4<sup>th</sup> Generation
 
 Just like 3<sup>rd</sup> generation libraries, fourth generation React styling libraries also emit CSS into DOM `<style>` tags,
-but their templates are more *dynamic* because they have access to __component scope__, such as `props` or `state`. Fourth generation
+but their templates are more *dynamic* because they have access to __component scope__ variables, such as `props` and `state`. Fourth generation
 templates normally also re-render on every component prop or state change.
 
 *Examples*: [`styled-components`][lib-styled-components], [`glamorous`][lib-glamorous]
@@ -57,8 +58,8 @@ can use JavaScript variables from component's __`.render()` function scope__.
 
 ## Summary
 
-|Generation|Supports CSS|Module scope variables|Component scope variables|Render method scope variables|
-|----------|------------|----------------------|-------------------------|-----------------------------|
+|Generation|Emits CSS|Module scope variables|Component scope variables|Render method scope variables|
+|----------|---------|----------------------|-------------------------|-----------------------------|
 |1<sup>st</sup> Genration|✅|❌|❌|❌|
 |2<sup>nd</sup> Genration|❌|✅|✅|✅|
 |3<sup>rd</sup> Genration|✅|✅|❌|❌|
@@ -69,34 +70,20 @@ can use JavaScript variables from component's __`.render()` function scope__.
 ## Survey
 
 
-Libraries grouped by generation:
+Libraries grouped by generation.
 
-  - First generation
-    - [`css-modules`][lib-css-modules]
-    - [`babel-plugin-css-in-js`][lib-babel-plugin-css-in-js]
-    - [`bloody-react-styled`][lib-bloody-react-styled]
-    - [`css-loader`][lib-css-loader]
-    - [lib-css-ns][lib-css-ns]
-  - Second generation
+  - 1<sup>st</sup> generation
+    - [`css-modules`][lib-css-modules], [`babel-plugin-css-in-js`][lib-babel-plugin-css-in-js], [`bloody-react-styled`][lib-bloody-react-styled],
+    [`css-loader`][lib-css-loader], and [`lib-css-ns`][lib-css-ns]
+  - 2<sup>nd</sup> generation
     - [`Radium`][lib-radium]
-  - Third generation
-    - [`aphrodite`][lib-aphrodite]
-    - [`glamor`][lib-glamor]
-    - [`jsxstyle`][lib-jsxstyle]
-    - [`styletron`][lib-styletron]
-    - [`Classy`][lib-classy]
-    - [`csjs`][lib-csjs]
-    - [`css-constructor`][lib-css-constructor]
-    - [`hyperstyles`][lib-hyperstyles]
-    - [`styletron`][lib-styletron]
-  - Fourth generation
-    - [`styled-components`][lib-styled-components]
-    - [`glamorous`][lib-glamorous]
-  - Fifth generation
-    - [`freestyler`][lib-freestyler]
-    - [`jsxstyle`][lib-jsxstyle]
-    - [`style-it`][lib-style-it]
-    - [`superstyle`][lib-superstyle]
+  - 3<sup>rd</sup> generation
+    - [`aphrodite`][lib-aphrodite], [`glamor`][lib-glamor], [`jsxstyle`][lib-jsxstyle], [`styletron`][lib-styletron], [`Classy`][lib-classy],
+    [`csjs`][lib-csjs], [`css-constructor`][lib-css-constructor], [`hyperstyles`][lib-hyperstyles], [`styletron`][lib-styletron]
+  - 4<sup>th</sup> generation
+    - [`styled-components`][lib-styled-components], [`glamorous`][lib-glamorous]
+  - 5<sup>th</sup> generation
+    - [`freestyler`][lib-freestyler], [`jsxstyle`][lib-jsxstyle], [`style-it`][lib-style-it], [`superstyle`][lib-superstyle]
 
 [lib-css-modules]: https://github.com/css-modules/css-modules
 [lib-babel-plugin-css-in-js]: https://github.com/martinandert/babel-plugin-css-in-js

docs/en/interfaces.md

@@ -4,24 +4,22 @@ Interfaces are patterns used to apply CSS styling to React components or element
 interface will also define [the generation](./generations.md) of the library as it will put
 restrictions on scope of JavaScript variables.
 
-  - First generation
+  - 1<sup>st</sup> generation
     - [Namespacer](./interfaces/1st-generation/namespacer.md)
     - [Webpack loader](./interfaces/1st-generation/webpack-loader.md)
     - [Babel plugin](./interfaces/1st-generation/babel-plugin.md)
-    - [Hyperstyles](./interfaces/1st-generation/hyperstyles.md)
-  - Second generation
+  - 2<sup>nd</sup> generation
     - [Inline styles](./interfaces/2nd-generation/inline-stylesheet.md)
-  - Third generation
+  - 3<sup>rd</sup> generation
     - [Rule](./interfaces/3rd-generation/rule.md)
     - [StyleSheet](./interfaces/3rd-generation/stylesheet.md)
-    - [Static class property](./interfaces/3rd-generation/static-class-property.md)
-    - [Render method decorator](./interfaces/3rd-generation/static-class-property.md)
-    - [Component](./interfaces/3rd-generation/component.md)
-  - Fourth generation
+    - [Hyperstyles](./interfaces/3rd-generation/hyperstyles.md)
+  - 4<sup>th</sup> generation
     - [Styled component](./interfaces/4th-generation/styled-component.md)
+    - [Static property](./interfaces/4th-generation/static-class-property.md)
     - [Class decorator](./interfaces/4th-generation/class-decorator.md)
-    - [Render method decorator](./interfaces/4th-generation/render-decorator.md)
+    - [Render decorator](./interfaces/4th-generation/render-decorator.md)
     - [Component](./interfaces/4th-generation/component.md)
-  - Fifth generation
+  - 5<sup>th</sup> generation
     - [Style-it](./interfaces/5th-generation/style-it.md)
     - [jsxstyle](./interfaces/5th-generation/jsxstyle.md)

docs/en/interfaces/1st-generation/babel-plugin.md

@@ -1,17 +1,19 @@
-# Babel plugin interface
+# Babel Plugin Interface
 
-In *Babel plugin interface* styles are defined in JavaScript, but they are statically
+In *Babel Plugin Interface* styles are defined in JavaScript, but they are statically
 extracted and saved as external style `.css` sheet by a Babel plugin.
 
-`freestyler` does not inplement such interface.
+> `freestyler` does not provide such interface.
 
-### Libraries that provide *rule interface*:
+
+## Libraries that provide *Babel Plugin Interface*:
 
   - [`babel-plugin-css-in-js`][lib-babel-plugin-css-in-js]
 
 [lib-babel-plugin-css-in-js]: https://github.com/martinandert/babel-plugin-css-in-js
 
-##### `babel-plugin-css-in-js` example
+
+### `babel-plugin-css-in-js` example
 
 ```jsx
 const styles = cssInJS({

docs/en/interfaces/1st-generation/namespacer.md

@@ -1,9 +1,12 @@
 # Namespacer interface
 
 In *namespacer interfaces* library simply namespaces class names so that they are unique.
-The way how CSS styles are written is usually left to the user.
+The way how CSS styles are written is usually left up to the user.
 
-### Libraries that provide *namespacer interface*:
+> `freestyler` does not provide such interface.
+
+
+## Libraries that provide *namespacer interface*:
 
   - [`css-ns`][lib-css-ns]
 

docs/en/interfaces/1st-generation/webpack-loader.md

@@ -1,20 +1,22 @@
-# Webpack loader interface
+# Webpack Loader Interface
 
-In *Webpack loader interface* styles are stored in an external file, usually `.css` or using
+In *Webpack Loader Interface* CSS templates are stored in an external file, usually `.css` or using
 some pre-processor file extension, like `.scss`. The styles can be inlined into the JavaScript
 bundle or serverd as an external style sheet.
 
-`freestyler` does not inplement such interface.
+> `freestyler` does not provide such interface.
 
-### Libraries that provide *rule interface*:
 
-  - [`bloody-react-styled`][lib-bloody-react-styleds]
+## Libraries that provide *Webpack Loader Interface*:
+
+  - [`bloody-react-styled`][lib-bloody-react-styled]
   - [`css-loader`][lib-css-loader]
 
 [lib-bloody-react-styled]: https://github.com/martinandert/babel-plugin-css-in-js
 [lib-css-loader]: https://github.com/webpack-contrib/css-loader
 
-##### `bloody-react-styled` example
+
+### `bloody-react-styled` example
 
 JavaScript:
 

docs/en/interfaces/2nd-generation/inline-stylesheet.md

@@ -1,11 +1,11 @@
-# Inline StyleSheet interface
+# Inline StyleSheet Interface
 
-*Inline Style interface* is when styles are defined at module level
+*Inline Style Interface* is when styles are defined at module level
 in a *"CSS stylesheet-like"* object and then applied as inline styles.
 
-```jsx
-import rule from 'freestyler/rule';
+__Example__
 
+```jsx
 const styles = {
   container: {
     border: '1px solid tomato',
@@ -28,4 +28,4 @@ class Button extends Component {
 }
 ```
 
-This interface can be used in any React project.
+> This interface can be used in any React project.

docs/en/interfaces/1st-generation/hyperstyles.md → docs/en/interfaces/3rd-generation/hyperstyles.md

@@ -1,9 +1,12 @@
-# Hyperstyles interface
+# Hyperstyle Interface
 
-In *hyperstyles interface* the Virtual HyperScript function `h` of React (`createElement`) is
-replaced by one that will also contain style information.
+In *Hyperstyle Interface* the hyperscript function `h` (or React's `createElement`) is
+replaced by one that will automatically style React elements.
 
-### Other libraries that provide *Component interface*
+> See [`freestyler` *Hyperstyle Interface* API](../../hyperstyle.md).
+
+
+## Other libraries that provide *Hyperstyle Interface*
 
   - [hyperstyles][lib-hyperstyles]