doc: update README

Author: andreypopp

Makefile

@@ -22,6 +22,9 @@ test::
 ci::
 	@$(BIN)/mocha $(MOCHA_OPTS) --watch --watch-extensions json,md $(TESTS)
 
+doctoc:
+	@$(BIN)/doctoc --title '**Table of Contents**' ./README.md
+
 version-major version-minor version-patch:: lint check test build
 	@npm version $(@:version-%=%)
 

README.md

@@ -3,6 +3,22 @@
 [![Travis build status](https://img.shields.io/travis/andreypopp/react-css-components/master.svg)](https://travis-ci.org/andreypopp/react-css-components)
 [![npm](https://img.shields.io/npm/v/react-css-components.svg)](https://www.npmjs.com/package/react-css-components)
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Motivation](#motivation)
+- [Installation & Usage](#installation-&-usage)
+- [Base components](#base-components)
+  - [DOM components](#dom-components)
+  - [Composite components](#composite-components)
+- [Variants](#variants)
+  - [Named variants](#named-variants)
+  - [Variants controlled with JS expression](#variants-controlled-with-js-expression)
+- [TODO](#todo)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Motivation
 
 Define React presentational components with CSS.
@@ -53,8 +69,42 @@ import {Label} from './styles.react.css'
 
 <Label /> // => <div className="<autogenerated classname>">...</div>
 ```
+
+## Base components
+
+### DOM components
+
+By default React CSS Components produces styled `<div />` components. You can
+change that by defining `base:` property:
+
+```css
+FancyButton {
+  base: button;
+  color: red;
+}
+```
+
+### Composite components
+
+In fact any React components which accepts `className` props can be used as a
+base. That's means that React CSS Components can be used as theming tool for any
+UI library.
+
+Example:
+
+```css
+DangerButton {
+  base: react-ui-library/components/Button;
+  color: red;
+}
+```
+
 ## Variants
 
+Variants is a mechanism which allows to define styling variants for a component.
+
+### Named variants
+
 You can define additional styling variants for your components:
 ```css
 Label {
@@ -71,10 +121,13 @@ They are compiled as CSS classes which then can be controlled from JS via
 ```js
 <Label variant={{emphasis: true}} /> // sets both classes with `color` and `font-weight`
 ```
-## Prop variants
+### Variants controlled with JS expression
+
+You can define variants which are conditionally applied if JS expression against
+props evaluates to a truthy value.
+
+Example:
 
-You can define variants which are based on some JavaScript expression against
-props:
 ```css
 Label {
   color: red;
@@ -84,13 +137,20 @@ Label:prop(mode == "emphasis") {
   font-weight: bold;
 }
 ```
-They are compiled as CSS classes which then can be controlled from JS:
+
+Note that any free variable reference a member of `props`, thus in JS `mode`
+becomes `props.mode` in the example above.
+
+They are compiled as CSS classes as well. JS expressions within `prop(..)` are
+used to determine if corresponding CSS classes should be applied to DOM:
+
 ```js
 <Label mode="emphasis" /> // sets both classes with `color` and `font-weight`
 ```
 
 ## TODO
 
 * [ ] Document how to add PostCSS transform to build pipeline (think autoprefixer).
+* [ ] Document how to do CSS extraction.
 
 [CSS modules]: https://github.com/css-modules/css-modules

package.json

@@ -59,6 +59,7 @@
     "babel-core": "^6.7.6",
     "babel-generator": "^6.7.5",
     "babel-preset-prometheusresearch": "^0.1.0",
+    "doctoc": "^1.1.1",
     "eslint": "^2.7.0",
     "eslint-config-prometheusresearch": "^0.2.0",
     "eslint-plugin-react": "^4.3.0",