diff --git a/content/docs/context.md b/content/docs/context.md
index 1a648042..2b9ccfdd 100644
--- a/content/docs/context.md
+++ b/content/docs/context.md
@@ -4,220 +4,92 @@ title: Context
 permalink: docs/context.html
 ---
 
-> Note:
->
-> `React.PropTypes` has moved into a different package since React v15.5. Please use [the `prop-types` library instead](https://www.npmjs.com/package/prop-types) to define `contextTypes`.
->
->We provide [a codemod script](/blog/2017/04/07/react-v15.5.0.html#migrating-from-react.proptypes) to automate the conversion.
-
-With React, it's easy to track the flow of data through your React components. When you look at a component, you can see which props are being passed, which makes your apps easy to reason about.
-
-In some cases, you want to pass data through the component tree without having to pass the props down manually at every level.
-You can do this directly in React with the powerful "context" API.
-
-> Note:
->
-> A [new, safe version of context](https://github.com/reactjs/rfcs/blob/master/text/0002-new-version-of-context.md) is under development for the upcoming 16.3 release.
+Context provides a way to pass data through the component tree without having to pass props down manually at every level.
 
+In a typical React application, data is passed top-down (parent to child) via props, but this can be cumbersome for certain types of props (e.g. locale preference, UI theme) that are required by many components within an application. Context provides a way to share values like this between components without having to explicitly pass a prop through every level of the tree.
 
-## Why Not To Use Context
+- [Motivation](#motivation)
+- [API](#api)
+  - [React.createContext](#reactcreatecontext)
+  - [Provider](#provider)
+  - [Consumer](#consumer)
+- [Examples](#examples)
+  - [Static Context](#static-context)
+  - [Dynamic Context](#dynamic-context)
+- [Legacy API](#legacy-api)
 
-The vast majority of applications do not need to use context.
 
-If you want your application to be stable, don't use context. It is an experimental API and it is likely to break in future releases of React.
+## Motivation
 
-If you aren't familiar with state management libraries like [Redux](https://github.com/reactjs/redux) or [MobX](https://github.com/mobxjs/mobx), don't use context. For many practical applications, these libraries and their React bindings are a good choice for managing state that is relevant to many components. It is far more likely that Redux is the right solution to your problem than that context is the right solution.
+Context is designed to relieve the pain of passing props down through a deeply nested component tree. For example, in the code below we manually thread through a color prop in order to style the Button and Message components:
 
-If you're still learning React, don't use context. There is usually a better way to implement functionality just using props and state.
+`embed:context/motivation-problem.js`
 
-If you insist on using context despite these warnings, try to isolate your use of context to a small area and avoid using the context API directly when possible so that it's easier to upgrade when the API changes.
+Using context, we can avoid passing props through intermediate elements:
 
-## How To Use Context
+`embed:context/motivation-solution.js`
 
-Suppose you have a structure like:
+## API
 
-```javascript
-class Button extends React.Component {
-  render() {
-    return (
-      <button style={{background: this.props.color}}>
-        {this.props.children}
-      </button>
-    );
-  }
-}
+### `React.createContext`
 
-class Message extends React.Component {
-  render() {
-    return (
-      <div>
-        {this.props.text} <Button color={this.props.color}>Delete</Button>
-      </div>
-    );
-  }
-}
-
-class MessageList extends React.Component {
-  render() {
-    const color = "purple";
-    const children = this.props.messages.map((message) =>
-      <Message text={message.text} color={color} />
-    );
-    return <div>{children}</div>;
-  }
-}
-```
-
-In this example, we manually thread through a `color` prop in order to style the `Button` and `Message` components appropriately. Using context, we can pass this through the tree automatically:
-
-```javascript{6,13-15,21,28-30,40-42}
-import PropTypes from 'prop-types';
-
-class Button extends React.Component {
-  render() {
-    return (
-      <button style={{background: this.context.color}}>
-        {this.props.children}
-      </button>
-    );
-  }
-}
-
-Button.contextTypes = {
-  color: PropTypes.string
-};
-
-class Message extends React.Component {
-  render() {
-    return (
-      <div>
-        {this.props.text} <Button>Delete</Button>
-      </div>
-    );
-  }
-}
-
-class MessageList extends React.Component {
-  getChildContext() {
-    return {color: "purple"};
-  }
-
-  render() {
-    const children = this.props.messages.map((message) =>
-      <Message text={message.text} />
-    );
-    return <div>{children}</div>;
-  }
-}
-
-MessageList.childContextTypes = {
-  color: PropTypes.string
-};
+```js
+const {Provider, Consumer} = React.createContext(defaultValue);
 ```
 
-By adding `childContextTypes` and `getChildContext` to `MessageList` (the context provider), React passes the information down automatically and any component in the subtree (in this case, `Button`) can access it by defining `contextTypes`.
+Creates a `{ Provider, Consumer }` pair.
 
-If `contextTypes` is not defined, then `context` will be an empty object.
+Optionally accepts a default value to be passed to Consumers without a Provider ancestor.
 
-## Parent-Child Coupling
+### `Provider`
 
-Context can also let you build an API where parents and children communicate. For example, one library that works this way is [React Router V4](https://reacttraining.com/react-router):
+```js
+<Provider value={/* some value */}>
+```
 
-```javascript
-import { BrowserRouter as Router, Route, Link } from 'react-router-dom';
+A React component that allows Consumers to subscribe to context changes.
 
-const BasicExample = () => (
-  <Router>
-    <div>
-      <ul>
-        <li><Link to="/">Home</Link></li>
-        <li><Link to="/about">About</Link></li>
-        <li><Link to="/topics">Topics</Link></li>
-      </ul>
+Accepts a `value` prop to be passed to Consumers that are descendants of this Provider. One Provider can be connected to many Consumers. Providers can be nested to override values deeper within the tree.
 
-      <hr />
+### `Consumer`
 
-      <Route exact path="/" component={Home} />
-      <Route path="/about" component={About} />
-      <Route path="/topics" component={Topics} />
-    </div>
-  </Router>
-);
+```js
+<Consumer>
+ { value => { /* render something based on the context value */ } }
+</Consumer>
 ```
 
-By passing down some information from the `Router` component, each `Link` and `Route` can communicate back to the containing `Router`.
-
-Before you build components with an API similar to this, consider if there are cleaner alternatives. For example, you can pass entire React components as props if you'd like to.
+A React component that subscribes to context changes.
 
-## Referencing Context in Lifecycle Methods
-
-If `contextTypes` is defined within a component, the following [lifecycle methods](/docs/react-component.html#the-component-lifecycle) will receive an additional parameter, the `context` object:
-
-- [`constructor(props, context)`](/docs/react-component.html#constructor)
-- [`componentWillReceiveProps(nextProps, nextContext)`](/docs/react-component.html#componentwillreceiveprops)
-- [`shouldComponentUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#shouldcomponentupdate)
-- [`componentWillUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#componentwillupdate)
+Requires a [function as a child](/docs/render-props.html#using-props-other-than-render). This function receives the current context value and returns a React node. It will be called whenever the Provider's value is updated.
 
 > Note:
->
-> As of React 16, `componentDidUpdate` no longer receives `prevContext`.
-
-## Referencing Context in Stateless Functional Components
-
-Stateless functional components are also able to reference `context` if `contextTypes` is defined as a property of the function. The following code shows a `Button` component written as a stateless functional component.
-
-```javascript
-import PropTypes from 'prop-types';
+> 
+> For more information about this pattern, see [render props](/docs/render-props.html).
 
-const Button = ({children}, context) =>
-  <button style={{background: context.color}}>
-    {children}
-  </button>;
+## Examples
 
-Button.contextTypes = {color: PropTypes.string};
-```
-
-## Updating Context
-
-Don't do it.
+### Static Context
 
-React has an API to update context, but it is fundamentally broken and you should not use it.
+Here is an example illustrating how you might inject a "theme" using context:
 
-The `getChildContext` function will be called when the state or props changes. In order to update data in the context, trigger a local state update with `this.setState`. This will trigger a new context and changes will be received by the children.
+`embed:context/theme-example.js`
 
-```javascript
-import PropTypes from 'prop-types';
+### Dynamic Context
 
-class MediaQuery extends React.Component {
-  constructor(props) {
-    super(props);
-    this.state = {type:'desktop'};
-  }
+A more complex example with dynamic values for the theme:
 
-  getChildContext() {
-    return {type: this.state.type};
-  }
+**theme-context.js**
+`embed:context/theme-detailed-theme-context.js`
 
-  componentDidMount() {
-    const checkMediaQuery = () => {
-      const type = window.matchMedia("(min-width: 1025px)").matches ? 'desktop' : 'mobile';
-      if (type !== this.state.type) {
-        this.setState({type});
-      }
-    };
+**themed-button.js**
+`embed:context/theme-detailed-themed-button.js`
 
-    window.addEventListener('resize', checkMediaQuery);
-    checkMediaQuery();
-  }
+**app.js**
+`embed:context/theme-detailed-app.js`
 
-  render() {
-    return this.props.children;
-  }
-}
-
-MediaQuery.childContextTypes = {
-  type: PropTypes.string
-};
-```
+## Legacy API
 
-The problem is, if a context value provided by component changes, descendants that use that value won't update if an intermediate parent returns `false` from `shouldComponentUpdate`. This is totally out of control of the components using context, so there's basically no way to reliably update the context. [This blog post](https://medium.com/@mweststrate/how-to-safely-use-react-context-b7e343eff076) has a good explanation of why this is a problem and how you might get around it.
+> The legacy context API was deprecated in React 16.3 and will be removed in version 17.
+> 
+> React previously shipped with an experimental context API. The old API will be supported in all 16.x releases, but applications using it should migrate to the new version. Read the [legacy context docs here](/docs/legacy-context.html).
diff --git a/content/docs/legacy-context.md b/content/docs/legacy-context.md
new file mode 100644
index 00000000..8da900b6
--- /dev/null
+++ b/content/docs/legacy-context.md
@@ -0,0 +1,217 @@
+---
+id: legacy-context
+title: Legacy Context
+permalink: docs/legacy-context.html
+---
+
+> Deprecation Warning
+>
+> The legacy API has been deprecated and will be removed in version 17.
+> Use the [new context API](/docs/context.html) introduced with version 16.3.
+> The legacy API will continue working for all 16.x releases.
+
+## How To Use Context
+
+> This section documents a deprecated API. See the [new API](/docs/context.html).
+
+Suppose you have a structure like:
+
+```javascript
+class Button extends React.Component {
+  render() {
+    return (
+      <button style={{background: this.props.color}}>
+        {this.props.children}
+      </button>
+    );
+  }
+}
+
+class Message extends React.Component {
+  render() {
+    return (
+      <div>
+        {this.props.text} <Button color={this.props.color}>Delete</Button>
+      </div>
+    );
+  }
+}
+
+class MessageList extends React.Component {
+  render() {
+    const color = "purple";
+    const children = this.props.messages.map((message) =>
+      <Message text={message.text} color={color} />
+    );
+    return <div>{children}</div>;
+  }
+}
+```
+
+In this example, we manually thread through a `color` prop in order to style the `Button` and `Message` components appropriately. Using context, we can pass this through the tree automatically:
+
+```javascript{6,13-15,21,28-30,40-42}
+import PropTypes from 'prop-types';
+
+class Button extends React.Component {
+  render() {
+    return (
+      <button style={{background: this.context.color}}>
+        {this.props.children}
+      </button>
+    );
+  }
+}
+
+Button.contextTypes = {
+  color: PropTypes.string
+};
+
+class Message extends React.Component {
+  render() {
+    return (
+      <div>
+        {this.props.text} <Button>Delete</Button>
+      </div>
+    );
+  }
+}
+
+class MessageList extends React.Component {
+  getChildContext() {
+    return {color: "purple"};
+  }
+
+  render() {
+    const children = this.props.messages.map((message) =>
+      <Message text={message.text} />
+    );
+    return <div>{children}</div>;
+  }
+}
+
+MessageList.childContextTypes = {
+  color: PropTypes.string
+};
+```
+
+By adding `childContextTypes` and `getChildContext` to `MessageList` (the context provider), React passes the information down automatically and any component in the subtree (in this case, `Button`) can access it by defining `contextTypes`.
+
+If `contextTypes` is not defined, then `context` will be an empty object.
+
+> Note:
+>
+> `React.PropTypes` has moved into a different package since React v15.5. Please use [the `prop-types` library instead](https://www.npmjs.com/package/prop-types) to define `contextTypes`.
+>
+> We provide [a codemod script](/blog/2017/04/07/react-v15.5.0.html#migrating-from-react.proptypes) to automate the conversion.
+
+### Parent-Child Coupling
+
+> This section documents a deprecated API. See the [new API](/docs/context.html).
+
+Context can also let you build an API where parents and children communicate. For example, one library that works this way is [React Router V4](https://reacttraining.com/react-router):
+
+```javascript
+import { BrowserRouter as Router, Route, Link } from 'react-router-dom';
+
+const BasicExample = () => (
+  <Router>
+    <div>
+      <ul>
+        <li><Link to="/">Home</Link></li>
+        <li><Link to="/about">About</Link></li>
+        <li><Link to="/topics">Topics</Link></li>
+      </ul>
+
+      <hr />
+
+      <Route exact path="/" component={Home} />
+      <Route path="/about" component={About} />
+      <Route path="/topics" component={Topics} />
+    </div>
+  </Router>
+);
+```
+
+By passing down some information from the `Router` component, each `Link` and `Route` can communicate back to the containing `Router`.
+
+Before you build components with an API similar to this, consider if there are cleaner alternatives. For example, you can pass entire React components as props if you'd like to.
+
+### Referencing Context in Lifecycle Methods
+
+> This section documents a deprecated API. See the [new API](/docs/context.html).
+
+If `contextTypes` is defined within a component, the following [lifecycle methods](/docs/react-component.html#the-component-lifecycle) will receive an additional parameter, the `context` object:
+
+- [`constructor(props, context)`](/docs/react-component.html#constructor)
+- [`componentWillReceiveProps(nextProps, nextContext)`](/docs/react-component.html#componentwillreceiveprops)
+- [`shouldComponentUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#shouldcomponentupdate)
+- [`componentWillUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#componentwillupdate)
+
+> Note:
+>
+> As of React 16, `componentDidUpdate` no longer receives `prevContext`.
+
+### Referencing Context in Stateless Functional Components
+
+> This section documents a deprecated API. See the [new API](/docs/context.html).
+
+Stateless functional components are also able to reference `context` if `contextTypes` is defined as a property of the function. The following code shows a `Button` component written as a stateless functional component.
+
+```javascript
+import PropTypes from 'prop-types';
+
+const Button = ({children}, context) =>
+  <button style={{background: context.color}}>
+    {children}
+  </button>;
+
+Button.contextTypes = {color: PropTypes.string};
+```
+
+### Updating Context
+
+> This section documents a deprecated API. See the [new API](/docs/context.html).
+
+Don't do it.
+
+React has an API to update context, but it is fundamentally broken and you should not use it.
+
+The `getChildContext` function will be called when the state or props changes. In order to update data in the context, trigger a local state update with `this.setState`. This will trigger a new context and changes will be received by the children.
+
+```javascript
+import PropTypes from 'prop-types';
+
+class MediaQuery extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {type:'desktop'};
+  }
+
+  getChildContext() {
+    return {type: this.state.type};
+  }
+
+  componentDidMount() {
+    const checkMediaQuery = () => {
+      const type = window.matchMedia("(min-width: 1025px)").matches ? 'desktop' : 'mobile';
+      if (type !== this.state.type) {
+        this.setState({type});
+      }
+    };
+
+    window.addEventListener('resize', checkMediaQuery);
+    checkMediaQuery();
+  }
+
+  render() {
+    return this.props.children;
+  }
+}
+
+MediaQuery.childContextTypes = {
+  type: PropTypes.string
+};
+```
+
+The problem is, if a context value provided by component changes, descendants that use that value won't update if an intermediate parent returns `false` from `shouldComponentUpdate`. This is totally out of control of the components using context, so there's basically no way to reliably update the context. [This blog post](https://medium.com/@mweststrate/how-to-safely-use-react-context-b7e343eff076) has a good explanation of why this is a problem and how you might get around it.
\ No newline at end of file
diff --git a/examples/context/motivation-problem.js b/examples/context/motivation-problem.js
new file mode 100644
index 00000000..80c906ce
--- /dev/null
+++ b/examples/context/motivation-problem.js
@@ -0,0 +1,34 @@
+class Button extends React.Component {
+  render() {
+    return (
+      <button style={{background: this.props.color}}>
+        {this.props.children}
+      </button>
+    );
+  }
+}
+
+class Message extends React.Component {
+  render() {
+    // highlight-range{1-3}
+    // The Message component must take `color` as as prop to pass it
+    // to the Button. Using context, the Button could connect to the
+    // color context on its own.
+    return (
+      <div>
+        <p>{this.props.text}</p>
+        <Button color={this.props.color}>Delete</Button>
+      </div>
+    );
+  }
+}
+
+class MessageList extends React.Component {
+  render() {
+    const color = 'purple';
+    const children = this.props.messages.map(message => (
+      <Message text={message.text} color={color} />
+    ));
+    return <div>{children}</div>;
+  }
+}
diff --git a/examples/context/motivation-solution.js b/examples/context/motivation-solution.js
new file mode 100644
index 00000000..76bf72cc
--- /dev/null
+++ b/examples/context/motivation-solution.js
@@ -0,0 +1,43 @@
+// highlight-range{1}
+const ColorContext = React.createContext();
+
+class Button extends React.Component {
+  render() {
+    // highlight-range{2-8}
+    return (
+      <ColorContext.Consumer>
+        {color => (
+          <button style={{background: color}}>
+            {this.props.children}
+          </button>
+        )}
+      </ColorContext.Consumer>
+    );
+  }
+}
+
+class Message extends React.Component {
+  render() {
+    return (
+      <div>
+        <p>{this.props.text}</p>
+        <Button>Delete</Button>
+      </div>
+    );
+  }
+}
+
+class MessageList extends React.Component {
+  render() {
+    const color = 'purple';
+    const children = this.props.messages.map(message => (
+      <Message text={message.text} />
+    ));
+    // highlight-range{2-4}
+    return (
+      <ColorContext.Provider value={color}>
+        {children}
+      </ColorContext.Provider>
+    );
+  }
+}
diff --git a/examples/context/theme-detailed-app.js b/examples/context/theme-detailed-app.js
new file mode 100644
index 00000000..1b57e15d
--- /dev/null
+++ b/examples/context/theme-detailed-app.js
@@ -0,0 +1,30 @@
+import {ThemeContext, themes} from './theme-context';
+import ThemedButton from './button';
+
+class App extends React.Component {
+  state = {
+    theme: themes.light,
+  };
+
+  toggleTheme = () => {
+    this.setState(state => ({
+      theme:
+        state.theme === themes.dark
+          ? themes.light
+          : themes.dark,
+    }));
+  };
+
+  render() {
+    //highlight-range{2,6}
+    return (
+      <ThemeContext.Provider value={this.state.theme}>
+        <ThemedButton onClick={this.toggleTheme}>
+          Change Theme
+        </ThemedButton>
+      </ThemeContext.Provider>
+    );
+  }
+}
+
+ReactDOM.render(<App />, document.root);
diff --git a/examples/context/theme-detailed-theme-context.js b/examples/context/theme-detailed-theme-context.js
new file mode 100644
index 00000000..80dd489a
--- /dev/null
+++ b/examples/context/theme-detailed-theme-context.js
@@ -0,0 +1,15 @@
+export const themes = {
+  light: {
+    foreground: '#ffffff',
+    background: '#222222',
+  },
+  dark: {
+    foreground: '#000000',
+    background: '#eeeeee',
+  },
+};
+
+// highlight-range{1-3}
+export const ThemeContext = React.createContext(
+  themes.dark
+);
diff --git a/examples/context/theme-detailed-themed-button.js b/examples/context/theme-detailed-themed-button.js
new file mode 100644
index 00000000..aa36ee77
--- /dev/null
+++ b/examples/context/theme-detailed-themed-button.js
@@ -0,0 +1,19 @@
+import {ThemeContext} from './theme-context';
+
+class ThemedButton extends React.Component {
+  // highlight-range{3-10}
+  render() {
+    return (
+      <ThemeContext.Consumer>
+        {theme => (
+          <button
+            {...this.props}
+            style={{backgroundColor: theme.background}}
+          />
+        )}
+      </ThemeContext.Consumer>
+    );
+  }
+}
+
+export default ThemedButton;
diff --git a/examples/context/theme-example.js b/examples/context/theme-example.js
new file mode 100644
index 00000000..d96e4765
--- /dev/null
+++ b/examples/context/theme-example.js
@@ -0,0 +1,55 @@
+// Create a theme context, defaulting to light theme
+// highlight-next-line
+const ThemeContext = React.createContext('light');
+
+class ThemeProvider extends React.Component {
+  render() {
+    // highlight-range{2-4}
+    return (
+      <ThemeContext.Provider value={this.props.theme}>
+        {this.props.children}
+      </ThemeContext.Provider>
+    );
+  }
+}
+
+class ThemedButton extends React.Component {
+  render() {
+    //highlight-range{2-4}
+    return (
+      <ThemeContext.Consumer>
+        {theme => <Button theme={theme} />}
+      </ThemeContext.Consumer>
+    );
+  }
+}
+
+const SomeComponent = props => {
+  // The ThemedButton receives the theme from context;
+  // SomeComponent does not need to know about it
+  // highlight-range{3}
+  return (
+    <div>
+      <ThemedButton />
+    </div>
+  );
+};
+
+class App extends React.Component {
+  render() {
+    // The ThemedButton button inside the ThemeProvider
+    // uses the dark theme while the one outside uses the
+    // default light theme
+    // highlight-range{3-5,7}
+    return (
+      <div>
+        <ThemeProvider theme="dark">
+          <SomeComponent />
+        </ThemeProvider>
+        <div>
+          <ThemedButton />
+        </div>
+      </div>
+    );
+  }
+}
diff --git a/src/theme.js b/src/theme.js
index 9da7e3e4..5fba925d 100644
--- a/src/theme.js
+++ b/src/theme.js
@@ -336,7 +336,7 @@ const sharedStyles = {
       },
 
       '& li': {
-        marginTop: 20,
+        marginTop: 10,
       },
 
       '& li.button-newapp': {
@@ -345,6 +345,7 @@ const sharedStyles = {
 
       '& ol, & ul': {
         marginLeft: 20,
+        marginTop: 10,
       },
     },