diff --git a/README.md b/README.md
index 3013485b..d2ae5cbe 100644
--- a/README.md
+++ b/README.md
@@ -2,93 +2,65 @@
[![Build Status][travis-image]][travis-url]
[![npm version][npm-image]][npm-url]
-
+
-[React Native][react-native-url] components and APIs for the Web.
-
-Try it out in the [React Native for Web
-Playground](http://codepen.io/necolas/pen/PZzwBR) on CodePen.
+[React Native][react-native-url] components and APIs for the Web. Flexbox
+layout and JavaScript styling.
* [Discord: #react-native-web on reactiflux][discord-url]
* [Gitter: react-native-web][gitter-url]
## Table of contents
-* [Install](#install)
+* [Quick start](#quick-start)
+* [Overview](#overview)
* [Example](#example)
* [APIs](#apis)
* [Components](#components)
-* [Styling](#styling)
-* [Accessibility](#accessibility)
* [Contributing](#contributing)
* [Thanks](#thanks)
* [License](#license)
-## Install
+## Quick start
+
+You can [try the latest version on CodePen](http://codepen.io/necolas/pen/PZzwBR).
+
+To install in your app:
```
-npm install --save react react-dom react-native-web
+npm install --save react@0.14 react-dom@0.14 react-native-web
```
-## Example
+## Overview
-React Native for Web exports its components, a reference to the `react`
-installation, and the `react-dom` methods (customized for Web). Styles are defined
-with, and used as JavaScript objects.
+### Importing
-Component:
+All API's, components, and a Web-specific `React` are provided by the
+`react-native-web` module:
```js
import React, { Image, StyleSheet, Text, View } from 'react-native-web'
-
-const Title = ({ children }) => {children}
-
-const Summary = ({ children }) => (
-
- {children}
-
-)
-
-class App extends React.Component {
- render() {
- return (
-
-
- React Native Web
- Build high quality web apps using React
-
- )
- },
-})
-
-const styles = StyleSheet.create({
- row: {
- flexDirection: 'row',
- margin: 40
- },
- image: {
- height: 40,
- marginRight: 10,
- width: 40,
- },
- text: {
- flexGrow: 1,
- justifyContent: 'center'
- },
- title: {
- fontSize: '1.25rem',
- fontWeight: 'bold'
- },
- subtitle: {
- fontSize: '1rem'
- }
-})
```
-Pre-rendering on the server automatically includes your app styles:
+### Client-side rendering
+
+Client-side rendering requires that you use the module's `React` export.
+`React.render` is a thin wrapper around `ReactDOM.render` that renders your
+application and the style sheet. Styles are updated if new bundles are loaded
+asynchronously.
+
+```js
+// client.js
+import App from './components/App'
+import React from 'react-native-web'
+
+React.render(, document.getElementById('react-root'))
+```
+
+### Server-side rendering
+
+Server-side rendering is done by calling `React.renderToString` or
+`React.renderToStaticMarkup`, the output of both includes the style sheet.
```js
// server.js
@@ -110,15 +82,49 @@ const Html = () => (
)
```
-Rendering on the client automatically includes your app styles and supports
-progressive app loading (i.e. code-splitting / lazy bundle loading):
+### Styling
+
+React Native for Web allows you to [define styles using
+JavaScript](docs/guides/style.md), either with inline styles or
+[`StyleSheet.create`](docs/apis/StyleSheet.md).
+
+The `View` component makes it easy to build common layouts with flexbox, such
+as stacked and nested boxes with margin and padding. See this [guide to
+flexbox][flexbox-guide-url].
+
+### Accessibility
+
+The most common and best supported [accessibility
+features](docs/guides/accessibility.md) of the Web are leveraged through 4
+props available on most components: `accessible`, `accessibilityLabel`,
+`accessibilityLiveRegion`, and `accessibilityRole`.
+
+## Example
+
+More examples can be found in the [`examples` directory](examples).
```js
-// client.js
-import App from './components/App'
-import React from 'react-native-web'
+import React, { Image, StyleSheet, Text, View } from 'react-native-web'
-React.render(, document.getElementById('react-root'))
+const Card = ({ children }) => {children}
+const Title = ({ children }) => {children}
+const Photo = ({ uri }) =>
+
+const styles = StyleSheet.create({
+ card: {
+ flexGrow: 1,
+ justifyContent: 'center'
+ },
+ title: {
+ fontSize: '1.25rem',
+ fontWeight: 'bold'
+ },
+ image: {
+ height: 40,
+ marginRight: 10,
+ width: 40
+ }
+})
```
## APIs
@@ -160,58 +166,6 @@ Touch bindings for press and long press.
The fundamental UI building block using flexbox for layout.
-## Styling
-
-React Native for Web relies on styles being defined in JavaScript. Styling
-components can be achieved with inline styles or the use of
-[StyleSheet](docs/apis/StyleSheet.md).
-
-The `View` component makes it easy to build common layouts with flexbox, such
-as stacked and nested boxes with margin and padding. See this [guide to
-flexbox][flexbox-guide-url].
-
-### Media Queries, pseudo-classes, and pseudo-elements
-
-Changing styles and/or the render tree in response to device adaptation can be
-controlled in JavaScript, e.g.,
-[react-media-queries](https://github.com/bloodyowl/react-media-queries),
-[media-query-fascade](https://github.com/tanem/media-query-facade), or
-[react-responsive](https://github.com/contra/react-responsive). This has the
-benefit of co-locating breakpoint-specific DOM and style changes.
-
-Pseudo-classes like `:hover` and `:focus` can be implemented with the `onHover`
-and `onFocus` events.
-
-Pseudo-elements are not supported; elements can be used instead.
-
-## Accessibility
-
-On the Web, assistive technologies derive useful information about the
-structure, purpose, and interactivity of apps from their [HTML
-elements][html-accessibility-url], attributes, and [ARIA in
-HTML][aria-in-html-url].
-
-The most common and best supported accessibility features of the Web are
-exposed as the props: `accessible`, `accessibilityLabel`,
-`accessibilityLiveRegion`, and `accessibilityRole`.
-
-React Native for Web does not provide a way to directly control the rendered
-HTML element. The `accessibilityRole` prop is used to infer an [analogous HTML
-element][html-aria-url] to use in addition, where possible. While this may
-contradict some ARIA recommendations, it also helps avoid certain HTML5
-conformance errors and accessibility anti-patterns (e.g., giving a `heading`
-role to a `button` element).
-
-For example:
-
-* `` => ``.
-* `` => ``.
-* `` => ``.
-* `` => ``.
-* `` => ``.
-
-See the component documentation for more details.
-
## Contributing
Please read the [contribution guidelines][contributing-url]. Contributions are
@@ -230,13 +184,10 @@ backing the current implementation of `Touchable`.
Copyright (c) 2015 Nicolas Gallagher. Released under the [MIT
license](http://www.opensource.org/licenses/mit-license.php).
-[aria-in-html-url]: https://w3c.github.io/aria-in-html/
[contributing-url]: https://github.com/necolas/react-native-web/blob/master/CONTRIBUTING.md
[discord-url]: http://join.reactiflux.com
[flexbox-guide-url]: https://css-tricks.com/snippets/css/a-guide-to-flexbox/
[gitter-url]: https://gitter.im/necolas/react-native-web
-[html-accessibility-url]: http://www.html5accessibility.com/
-[html-aria-url]: http://www.w3.org/TR/html-aria/
[npm-image]: https://badge.fury.io/js/react-native-web.svg
[npm-url]: https://npmjs.org/package/react-native-web
[react-native-url]: https://facebook.github.io/react-native/
diff --git a/docs/apis/StyleSheet.md b/docs/apis/StyleSheet.md
index b0b96c8e..7d1c042f 100644
--- a/docs/apis/StyleSheet.md
+++ b/docs/apis/StyleSheet.md
@@ -1,9 +1,9 @@
# StyleSheet
-React Native for Web will automatically vendor-prefix styles applied to the
-library's components. The `StyleSheet` abstraction converts predefined styles
-to CSS without a compile-time step. Some styles cannot be resolved outside of
-the render loop and are applied as inline styles.
+The `StyleSheet` abstraction converts predefined styles to (vendor-prefixed)
+CSS without requiring a compile-time step. Some styles cannot be resolved
+outside of the render loop and are applied as inline styles. Read more about to
+[how style your application](docs/guides/style).
Create a new StyleSheet:
@@ -40,119 +40,3 @@ Use styles:
## Methods
**create**(obj: {[key: string]: any})
-
-## About
-
-### Strategy
-
-React Native for Web uses a `style`-to-`className` conversion strategy that is
-designed to avoid issues arising from the [7 deadly sins of
-CSS](https://speakerdeck.com/vjeux/react-css-in-js):
-
-1. Global namespace
-2. Dependency hell
-3. Dead code elimination
-4. Code minification
-5. Sharing constants
-6. Non-deterministic resolution
-7. Breaking isolation
-
-The strategy minimizes the amount of generated CSS, making it viable to inline
-the style sheet when pre-rendering pages on the server. There is one unique
-selector per unique style _declaration_.
-
-```js
-// definition
-{
- heading: {
- color: 'gray',
- fontSize: '2rem'
- },
- text: {
- color: 'gray',
- fontSize: '1.25rem'
- }
-}
-
-// css output
-//
-// .a { color: gray; }
-// .b { font-size: 2rem; }
-// .c { font-size: 1.25rem; }
-```
-
-For example:
-
-```js
-...
-
-const styles = StyleSheet.create({
- root: {
- background: 'transparent',
- display: 'flex',
- flexGrow: 1,
- justifyContent: 'center'
- }
-})
-```
-
-Yields (in development):
-
-```html
-
...
-```
-
-And is backed by the following CSS:
-
-```css
-.background\:transparent {background:transparent;}
-.display\:flex {display:flex;}
-.flexGrow\:1 {flex-grow:1;}
-.justifyContext\:center {justify-content:center;}
-```
-
-In production the class names are obfuscated.
-
-(CSS libraries like [Atomic CSS](http://acss.io/),
-[Basscss](http://www.basscss.com/), [SUIT CSS](https://suitcss.github.io/), and
-[tachyons](http://tachyons.io/) are attempts to limit style scope and limit
-style sheet growth in a similar way. But they're CSS utility libraries, each
-with a particular set of classes and features to learn. And all of them require
-developers to manually connect CSS classes for given styles.)
-
-### Reset
-
-React Native for Web includes a very small CSS reset taken from
-[normalize.css](https://necolas.github.io/normalize.css/) – **you do not need
-to include normalize.css**. It removes unwanted User Agent styles from
-(pseudo-)elements beyond the reach of React (e.g., `html`, `body`) or inline
-styles (e.g., `::-moz-focus-inner`).
-
-```css
-html {
- font-family: sans-serif;
- -ms-text-size-adjust: 100%;
- -webkit-text-size-adjust: 100%;
-}
-
-body {
- margin: 0;
-}
-
-button::-moz-focus-inner,
-input::-moz-focus-inner {
- border: 0;
- padding: 0;
-}
-
-input[type="search"]::-webkit-search-cancel-button,
-input[type="search"]::-webkit-search-decoration {
- -webkit-appearance: none;
-}
-
-ol,
-ul,
-li {
- list-style:none
-}
-```
diff --git a/docs/guides/accessibility.md b/docs/guides/accessibility.md
new file mode 100644
index 00000000..ac45d4fd
--- /dev/null
+++ b/docs/guides/accessibility.md
@@ -0,0 +1,31 @@
+# Accessibility
+
+On the Web, assistive technologies derive useful information about the
+structure, purpose, and interactivity of apps from their [HTML
+elements][html-accessibility-url], attributes, and [ARIA in
+HTML][aria-in-html-url].
+
+The most common and best supported accessibility features of the Web are
+exposed as the props: `accessible`, `accessibilityLabel`,
+`accessibilityLiveRegion`, and `accessibilityRole`.
+
+React Native for Web does not provide a way to directly control the rendered
+HTML element. The `accessibilityRole` prop is used to infer an [analogous HTML
+element][html-aria-url] to use in addition, where possible. While this may
+contradict some ARIA recommendations, it also helps avoid certain HTML5
+conformance errors and accessibility anti-patterns (e.g., giving a `heading`
+role to a `button` element).
+
+For example:
+
+* `` => ``.
+* `` => ``.
+* `` => ``.
+* `` => ``.
+* `` => ``.
+
+See the component documentation for more details.
+
+[aria-in-html-url]: https://w3c.github.io/aria-in-html/
+[html-accessibility-url]: http://www.html5accessibility.com/
+[html-aria-url]: http://www.w3.org/TR/html-aria/
diff --git a/docs/guides/style.md b/docs/guides/style.md
new file mode 100644
index 00000000..bae3273e
--- /dev/null
+++ b/docs/guides/style.md
@@ -0,0 +1,220 @@
+# Style
+
+React Native for Web relies on JavaScript to let you style your application.
+Along with a novel JS-to-CSS conversion strategy, this allows you to avoid
+issues arising from the [7 deadly sins of
+CSS](https://speakerdeck.com/vjeux/react-css-in-js):
+
+1. Global namespace
+2. Dependency hell
+3. No dead code elimination
+4. No code minification
+5. No sharing of constants
+6. Non-deterministic resolution
+7. Lack of isolation
+
+## Defining styles
+
+Styles should be defined outside of the component:
+
+```js
+class Example extends React.Component {}
+
+const styles = StyleSheet.create({
+ heading: {
+ color: 'gray',
+ fontSize: '2rem'
+ },
+ text: {
+ color: 'gray',
+ fontSize: '1.25rem'
+ }
+})
+```
+
+Using `StyleSheet.create` is optional but provides some key advantages: styles
+are immutable in development, styles are converted to CSS rather than applied
+as inline styles, and styles are only created once for the application and not
+on every render.
+
+The attribute names and values are a subset of CSS. See the `style`
+documentation of individual components.
+
+## Using styles
+
+All the core components accept a `style` attribute.
+
+```js
+
+
+```
+
+A common pattern is to conditionally add style based on a condition:
+
+```js
+
+```
+
+## Composing styles
+
+In order to let a call site customize the style of your component children, you
+can pass styles around. Use `View.propTypes.style` and `Text.propTypes.style` in
+order to make sure only styles are being passed.
+
+```js
+export default class List extends React.Component {
+ static propTypes = {
+ style: View.propTypes.style,
+ elementStyle: View.propTypes.style,
+ }
+
+ render() {
+ return (
+
+ {elements.map((element) =>
+
+ )}
+
+ );
+ }
+}
+```
+
+In another file:
+
+```js
+
+```
+
+You also have much greater control over how styles are composed when compared
+to using class names. For example, you may choose to accept a limited subset
+of style props in the component's API, and control when they are applied:
+
+```js
+class List extends React.Component {
+ static propTypes = {
+ children: React.PropTypes.any,
+ // limit which styles are accepted
+ style: React.PropTypes.shape({
+ borderColor: View.propTypes.borderColor,
+ borderWidth: View.propTypes.borderWidth
+ })
+ }
+
+ render() {
+ return (
+
+ )
+ }
+}
+```
+
+## Media Queries
+
+`StyleSheet.create` is a way of defining the styles your application requires;
+it does not concern itself with _where_ or _when_ those styles are applied to
+elements.
+
+Changing styles in response to device adaptation can be controlled using
+JavaScript Media Query API's. There are several React libraries that provide a
+means to do this, e.g.,
+[react-media-queries](https://github.com/bloodyowl/react-media-queries),
+[media-query-fascade](https://github.com/tanem/media-query-facade), or
+[react-responsive](https://github.com/contra/react-responsive). This approach
+has the benefit of co-locating breakpoint-specific DOM and style changes.
+
+## Pseudo-classes and pseudo-elements
+
+Pseudo-classes like `:hover` and `:focus` can be implemented with the `onHover`
+and `onFocus` events. Pseudo-elements are not supported; elements should be
+used instead.
+
+## How it works
+
+Every call to `StyleSheet.create` extracts the unique _declarations_ and
+converts them to a unique CSS rule. This is sometimes referred to as "atomic
+CSS". All the core components map their `style` property-value pairs to the
+corresponding `className`'s.
+
+By doing this, the total size of the generated CSS is determined by the
+total number of unique declarations (rather than the total number of rules in
+the application), making it viable to inline the style sheet when pre-rendering
+on the server.
+
+JavaScript definition:
+
+```js
+const styles = StyleSheet.create({
+ heading: {
+ color: 'gray',
+ fontSize: '2rem'
+ },
+ text: {
+ color: 'gray',
+ fontSize: '1.25rem'
+ }
+})
+```
+
+CSS output:
+
+```css
+._s1 { color: gray; }
+._s2 { font-size: 2rem; }
+._s3 { font-size: 1.25rem; }
+```
+
+Rendered HTML:
+
+```html
+Heading
+Text
+```
+
+### Reset
+
+You **do not** need to include a CSS reset or
+[normalize.css](https://necolas.github.io/normalize.css/).
+
+React Native for Web includes a very small CSS reset taken from normalize.css.
+It removes unwanted User Agent styles from (pseudo-)elements beyond the reach
+of React (e.g., `html`, `body`) or inline styles (e.g., `::-moz-focus-inner`).
+
+```css
+html {
+ font-family: sans-serif;
+ -ms-text-size-adjust: 100%;
+ -webkit-text-size-adjust: 100%;
+}
+
+body {
+ margin: 0;
+}
+
+button::-moz-focus-inner,
+input::-moz-focus-inner {
+ border: 0;
+ padding: 0;
+}
+
+input[type="search"]::-webkit-search-cancel-button,
+input[type="search"]::-webkit-search-decoration {
+ -webkit-appearance: none;
+}
+
+ol,
+ul,
+li {
+ list-style:none
+}
+```