diff --git a/docs/_guide/styles.md b/docs/_guide/styles.md
index 0f19e0d9..d6057cb5 100644
--- a/docs/_guide/styles.md
+++ b/docs/_guide/styles.md
@@ -4,66 +4,317 @@ title: Styles
 slug: styles
 ---
 
-**This guide applies only if you use the default (shadow DOM) render root.** If you modify your element's render root to render into the main DOM tree instead of a shadow root, these instructions won't apply.
-
-**If you're using the Shady CSS polyfill, be aware that it has some limitations.** See the [Shady CSS README](https://github.com/webcomponents/shadycss/blob/master/README.md#limitations) for more information.
-
 {::options toc_levels="1..3" /}
 * ToC
 {:toc}
 
-## Use the :host and :host() CSS pseudo-classes
+This page is a guide to the styling options available for LitElement components. 
 
-When styling your custom element, you can use the `:host` and `:host()` CSS pseudo-classes in a `<style>` block to select the host element (the element hosting the root of your shadow DOM). The two pseudo-classes slightly differ in usage:
+* [Styling options for component developers](#styling-for-developers) describes how to apply styles internally to a component that you're building.
 
-* Use `:host(...)` when you need to apply a CSS selector (e.g. a class or attribute selector).
-* Use `:host` to refer to the host element, wihout further selection.
+* [Styling options for component consumers](#styling-for-consumers) describes how to style an element that you're importing and using. 
 
-Please note, that `:host` and `:host()` (with empty parentheses) do not behave the same. Here's a simple example:
+* [Theming](#theming) is relevant to both developers and consumers of a LitElement-based component. It describes how to create easily stylable LitElement components, and how to create a style theme that can easily be applied to imported LitElement components.
 
-_my-element.js_
+<div class="alert alert-info">
+
+**If you're using the Shady CSS polyfill, be aware that it has some limitations.** See the [Shady CSS README](https://github.com/webcomponents/shadycss/blob/master/README.md#limitations) for more information.
+
+</div>
+
+## Styling options for component developers {#styling-for-developers}
+
+The [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) API allows the creation of encapsulated DOM trees that are attached to a custom element. 
+
+The root node of a shadow DOM tree is called the **shadow root**. The element in the main document that has a shadow root attached to it is called the **host element**, or **host**.
+
+By default, LitElement creates a shadow root for your host element. LitElement renders the DOM structure described in your element template into this shadow root. 
+
+Shadow DOM scopes CSS so that styles defined in a shadow root only apply to DOM inside the shadow root, and do not "leak" to outside DOM. With the exception of inherited CSS properties, shadow roots are also isolated from styles defined outside the shadow root, whether in the main page or an outer shadow root.
+
+This section describes how to create styles in your shadow root to style your host element and its shadow DOM.
+
+### Where to define your styles {#where}
+
+There are three main places in which you can define styles for your host element and its shadow DOM:
+
+* [In the static `styles` property of a LitElement class (recomended)](#static).
+* [Inside a `<style>` element in the HTML template defined in your `render` function](#styleelement).
+* [In an external stylesheet, linked to from your LitElement template with `<link rel="stylesheet" href="...">`](#external).
+
+### Define styles in a static styles property {#static-styles}
+
+LitElement lets you define static styles that apply to all instances of a component.
+
+We recommend using static styles for optimal performance. LitElement uses [Constructable Stylesheets](https://wicg.github.io/construct-stylesheets/) in browsers that support it, with a fallback for browsers that don't. Constructable Stylesheets allow the browser to parse styles exactly once and reuse the resulting Stylesheet object for maximum efficiency.
+
+The styles in the static `styles` property are evaluated once only and applied to all instances of the element. You can modify styles per element instance by using [CSS custom properties](#cssprops):
+
+*   The element **developer** defines a style rule inside shadow DOM that uses CSS variables to apply a custom CSS property to a particular style property.
+*   The element **consumer** defines the value of the custom CSS property outside shadow DOM in a CSS rule that is inherited by the host element.
+
+If you don't want to use custom properties, you can define per-instance styles in a `<style>` element inside shadow DOM. See the section on [Defining your styles in a style element](#styleelement) for more information.
+
+</div>
+
+To define a static `styles` property:
+
+1.  Import the `css` helper function from the `lit-element` module:
+
+    ```js
+    import {LitElement, css} from 'lit-element';
+    ```
+
+2.  Create a static `styles` property and define your styles in plain CSS.
+
+    The value of the static `styles` property can be:
+    
+    *   A single tagged template literal:
+    
+        ```js
+        class MyElement extends LitElement {
+          static styles = css`
+            :host {
+              display: block;
+            }
+          `;
+        }
+        ```
+
+    *   Or an array of tagged template literals:
+
+        ```js
+        class MyElement extends LitElement {
+          static styles = [ css`:host { display: block; }`, ...];
+        }
+        ```
+
+        Using an array of tagged template literals lets you inherit the styles from a LitElement superclass, and add more:
+
+        ```js
+        class MySubElement extends MyElement {
+          static styles = [
+            super.styles,
+            css`
+              :host([.important]) {
+                color: red;
+              }
+            `
+          ];
+        }
+        ```
+
+#### Expressions in static styles
+
+Static styles apply to all instances of an element. Any expressions in your CSS are evaluated and included **once**, then reused for all instances. 
+
+For security reasons, expressions must be tagged with the `cssLiteral` template literal tag:
 
 ```js
-render() {
-  return html`
-    <style>
-      :host([hidden]) { display: none; }
-      :host {
-        display: block; 
-        border: 1px solid black;
-      }
-    </style>
-    <p>Hello world</p>
+import { LitElement, css, cssLiteral } from 'lit-element';
+
+const mainColor = cssLiteral`red`;
+
+class MyElement extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+      color: ${mainColor}
+    }
   `;
 }
 ```
 
-{% include project.html folder="docs/style/hostselector" openFile="my-element.js" %}
+### Define styles in a style element {#style-element} 
+
+We recommend using static styles to style LitElement components. However, in some cases you may want to evaluate and apply styles per instance, rather than to all instances of a LitElement component. One way to do this is to include inline styles in a `<style>` element in your template, and use your element's properties in your CSS rules to evaluate styles per instance.
+
+<div class="alert alert-warning">
 
-See the MDN documentation on [:host](https://developer.mozilla.org/en-US/docs/Web/CSS/:host), [:host()](https://developer.mozilla.org/en-US/docs/Web/CSS/:host()), and [pseudo-classes](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes) for more information.
+**Expressions inside a `<style>` element won't update per instance in ShadyCSS**. Due to limitations of the ShadyCSS polyfill, you can't use element properties in CSS rules as the expressions won't be evaluated.
 
-### Set host element display styles
+</div>
+
+```js
+import {LitElement, property} from 'lit-element';
+
+class MyElement extends LitElement {
+  @property() mainColor = 'blue';
+  render() {
+    return html`
+      <style>
+        :host {
+          color: ${this.mainColor};
+        }
+      </style>
+    `;
+  }
+}
+```
+
+### Define styles in an external stylesheet {#external-stylesheet}
+
+We strongly recommend static styles, CSS custom properties, or [lit-html's `classMap` or `styleMap` directives](TODO) if you're stying non-host shadow root contents.
+
+However, you can load an external stylesheet into a shadow root with a `<link>` element:
+
+```js
+import {LitElement} from 'lit-element';
+
+class MyElement extends LitElement {
+  render() {
+    return html`
+      <link rel="stylesheet" href="./styles.css">
+    `;
+  }
+}
+```
+
+This can be a good way to load CSS generated from tools like SASS/LESS.
+
+There are some important caveats though:
+
+* External styles can cause a flash-of-unstyled-content (FOUC) while they load.
+* The URL in the `href` attribute is relative to the _main document_, making this technique mostly useful for application elements where asset URLs are well known, and not for reusable elements published publicly.
+
+### Write CSS styles for a host element and its shadow DOM {#shadow-dom-styles}
+
+In this section: 
+
+* [Write CSS styles for a host element](#host-styles).
+* [Write CSS styles for elements in shadow DOM](#shadow-dom-styles).
+* [Write CSS styles for slotted children](#slotted-styles). Light DOM children of your host element can be rendered in shadow DOM via the `slot` element.
+
+#### Write CSS styles for a host element {#host-styles}
+
+An element can apply styles to itself with the `:host` and `:host()` CSS psuedo-classes used inside the element's ShadowRoot. The tern "host" is used because an element is the host of its own shadow root.
+
+* `:host` selects the host element of the shadow root:
+
+  ```css
+  :host {
+    display: block;
+    color: blue;
+  }
+  ```
+
+* `:host(...)` selects the host element, but only if the selector inside the parentheses matches the host element:
+
+  ```css
+  :host([.important]) {
+    color: red;
+    font-weight: bold;
+  }
+  ```
+
+{% include project.html folder="style/hostselector" openFile="my-element.js" %}
 
 Two best practices for working with custom elements are:
 
-* Set a `:host` display style such as `block` or `inline-block` so that your component's `width` and `height` can be set.
+* Add a `:host` display style (such as `block` or `inline-block`) unless you prefer the default of `inline`.
 
-* Set a `:host()` display style that respects the `hidden` attribute.
+  Inline elements are sized by their content and cannot have their dimensions set via CSS. They can also cause block element children to overflow its bounds.
+
+  ```css
+    :host {
+      display: block;
+    }
+  ```
+
+* Add a `:host()` display style that respects the `hidden` attribute.
+
+  ```css
+    :host([hidden]) {
+      display: none;
+    }
+  ```
+
+{% include project.html folder="style/bestpracs" openFile="my-element.js" %}
+
+See [Custom Element Best Practices](https://developers.google.com/web/fundamentals/web-components/best-practices) for more information.
+
+#### Write CSS styles for elements in shadow DOM {#shadow-dom-styles}
+
+To style elements in a shadow root, simply use standard CSS selectors.
+
+Since CSS selectors in a shadow root only apply to elements in the shadow root, you don't need to be defensive against accidentally styling other elements in the page. This means you can generally write much simpler selectors, that are easier to reason about, and faster, than without shadow DOM.
+
+Simple selectors, like `*`, tagname, id, and class selectors, are fine in a shadow root because they don't match outside the root:
+
+```css
+* {
+  color: black;
+}
+
+h1 {
+  font-size: 4rem;
+}
+
+#main {
+  padding: 16px;
+}
+
+.important {
+  color: red;
+}
+```
+
+#### Write CSS styles for slotted children {#slotted-styles}
+
+Use the `::slotted()` CSS pseudo-element to select light DOM children that have been included in shadow DOM via the `<slot>` element.
+
+* `::slotted(*)` matches all slotted elements.
+
+* `::slotted(p)` matches slotted paragraphs.
+
+* `p ::slotted(*)` matches slotted elements in a paragraph element.
+
+```js
+{% include projects/style/slotted/my-element.js %}
+```
+
+{% include project.html folder="style/slotted" openFile="my-element.js" %}
+
+## Styling options for component consumers {#styling-for-consumers}
+
+When you use a LitElement component, you can set styles from the main document by using its custom element tag as a selector. For example:
+
+_index.html_ 
 
 ```html
 <style>
-  :host([hidden]) { display: none; }
-  :host { display: block; }
+  my-element { 
+    font-family: Roboto;
+    font-size: 20;
+    color: blue;
+  }
 </style>
+...
+<my-element></my-element>
 ```
 
-{% include project.html folder="docs/style/bestpracs" openFile="my-element.js" %}
+<div class="alert alert-info">
 
-See [Custom Element Best Practices](https://developers.google.com/web/fundamentals/web-components/best-practices) for more information.
+An element type selector has higher specificity than the `:host` pseudo-class selector. 
+
+Styles set for a host element from outside its shadow DOM will override styles set with the `:host` or `:host()` pseudo-class selectors inside shadow DOM. See Inheritance. 
 
-### Style shadow DOM children via properties inherited via :host 
+</div>
 
-Child elements in your template will inherit CSS properties you assign to your host via the `:host` CSS pseudo-class:
+## Theming
+
+This section describes how to use CSS inheritance and custom CSS properties to:
+
+* Create easily stylable LitElement components.
+* Create a style theme that can easily be applied to imported LitElement components.
+
+### CSS Inheritance and shadow DOM {#inheritance}
+
+[Inherited CSS properties](https://developer.mozilla.org/en-US/docs/Web/CSS/inheritance) like `color`, `font-family`, and all CSS custom properties (`--*`) inherit through shadow root boundaries.
+
+This means that by default an element will share some important styles from its outside context.
+
+Component authors can take advantage of this to style all of a shadow root's contents by setting inherited properties on the host with the `:host` CSS pseudo-class:
 
 _my-element.js_
 
@@ -83,27 +334,22 @@ render() {
 }
 ```
 
-{% include project.html folder="docs/style/inherited" openFile="my-element.js" %}
+{% include project.html folder="style/inherited" openFile="my-element.js" %}
 
-If your host element itself inherits properties from another element, the host's shadow DOM children will inherit those properties in turn:
+If a host element itself inherits properties from another element, the host's shadow DOM children will inherit those properties in turn:
 
 ```html
   <style>
     div { font-family: Roboto; }
   </style>
-  ...
-  <div><my-element>Will use Roboto font</my-element></div>
+  <div>
+    <my-element>Will use Roboto font</my-element>
+  </div>
 ```
 
-{% include project.html folder="docs/style/inherited2" openFile="my-element.js" %}
+{% include project.html folder="style/inherited2" openFile="my-element.js" %}
 
-## Style the host from the main document
-
-You can also style the host from outside its own template.
-
-### Use the custom element tag as a selector
-
-You can set styles for the host from the main document by using its custom element tag as a selector. For example:
+A LitElement component can be styled by using its custom element tag as a selector. For example:
 
 _index.html_ 
 
@@ -119,12 +365,15 @@ _index.html_
 <my-element></my-element>
 ```
 
-**The :host CSS pseudo-class has higher specificity than the element's type selector.** Styles set for your host with the `:host` pseudo-class from inside its own template will override styles set in the main document. For example:
+An element type selector has higher specificity than the `:host` pseudo-class selector. 
+
+Styles set for a host element from outside its shadow DOM will override styles set with the `:host` or `:host()` pseudo-class selectors inside shadow DOM. For example:
 
 _index.html_ 
 
 ```html
 <style>
+  /* Overrides the `color` property of the `:host` styles in my-element.js */
   my-element { 
     color: blue;
   }
@@ -137,16 +386,16 @@ _my-element.js_
 
 ```html
 <style>
-  /* Overrides styles set for my-element in index.html */
   :host {
     color: red;
+    background-color: aliceblue;
   }
 </style>
 ```
 
-### Use custom properties
+### Custom CSS Properties {#css-properties}
 
-Custom properties inherit down the DOM tree. You can use this to let your users apply styles and themes to your elements.
+Custom properties inherit down the DOM tree, and through shadow root boundaries. You can use this to let your users apply styles and themes to your elements.
 
 For example, the following element sets its background color to a CSS variable that uses the value of the custom property `--myBackground` if it is available, and uses `yellow` otherwise:
 
@@ -187,105 +436,25 @@ If the user has an existing app theme, they can easily apply their theme propert
 ```
 
 ```js
-{% include projects/docs/style/customproperties/my-element.js %}
+{% include projects/style/customproperties/my-element.js %}
 ```
 
-{% include project.html folder="docs/style/customproperties" openFile="my-element.js" %}
+{% include project.html folder="style/customproperties" openFile="my-element.js" %}
 
 See [CSS Custom Properties on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) for more information.
 
-## Select slotted elements with the ::slotted() CSS pseudo-element
-
-Use the `::slotted()` CSS pseudo-element to select light DOM elements that have been included in shadow DOM via the `<slot>` element.
-
-* `::slotted(*)` matches all slotted elements.
-
-* `::slotted(p)` matches slotted paragraphs.
-
-* `p ::slotted(*)` matches slotted elements in a paragraph element.
-
-```js
-{% include projects/docs/style/slotted/my-element.js %}
-```
-
-{% include project.html folder="docs/style/slotted" openFile="my-element.js" %}
-
-## Use JavaScript expressions in LitElement style blocks
-
-You can include style information in a JavaScript expression inside a LitElement template:
-
-```js
-render() { 
-  return html`
-    <style>${this.myStyles}</style>
-    <p>hi world</p>
-  `; 
-}
-
-get myStyles() { 
-  return html`p { color: red }`; 
-} 
-```
-
-{% include project.html folder="docs/style/expressions" openFile="my-element.js" %}
-
-## Example: A small theme
+### A simple example theme {#example-theme}
 
 _index.html_
 
 ```html
-<style>
-  html {
-    --themeColor1: rgb(67, 156, 144);
-    --themeFont: Roboto;
-  }
-  my-element {
-    --myColor: var(--themeColor1);
-    --myFont: var(--themeFont);
-  }
-</style>
-...
-<my-element></my-element>
+{% include projects/style/theming/index.html %}
 ```
 
 _my-element.js_
 
 ```js
-render() {
-  return html`
-    <style>
-      :host([hidden]) { display: none; }
-      :host { display: block; 
-        color: var(--myColor, aliceblue);
-        font-family: var(--myFont, Verdana);
-      }
-      ${navStyles}
-    </style>
-
-    <ul class="navigation">
-      ${this.menuItems.map(item => html`<li class="item">${item}</li>`)}
-    </ul>
-  `;
-}
-```
-
-_my-styles.js_
-
-```js
-export const navStyles = html`
-  ul {
-    list-style-type: none; 
-    margin: 0;
-    padding: 0;
-  }
-  .navigation {
-    display: flex;
-    flex-direction: row;
-  }
-  .item {
-    padding: 8px;
-  }
-`;
+{% include projects/style/theming/my-element.js %}
 ```
 
-{% include project.html folder="docs/style/smalltheme" openFile="my-element.js" %}
+{% include project.html folder="style/theming" openFile="theme.css" %}
diff --git a/docs/_guide/templates.md b/docs/_guide/templates.md
index c400eb48..296a0f43 100644
--- a/docs/_guide/templates.md
+++ b/docs/_guide/templates.md
@@ -374,7 +374,7 @@ class MyPage extends LitElement {
 
 {% include project.html folder="docs/templates/composeimports" openFile="my-page.js" %}
 
-## Specify the render root
+## Specify the render root {#renderroot}
 
 The node into which your component's template will render is called its **render root**.
 
diff --git a/docs/_includes/projects/docs/style/before/my-element.js b/docs/_includes/projects/docs/style/before/my-element.js
deleted file mode 100644
index a83e3df4..00000000
--- a/docs/_includes/projects/docs/style/before/my-element.js
+++ /dev/null
@@ -1,46 +0,0 @@
-/**
- * Try LitElement https://lit-element.polymer-project.org/try
- * Starting code for 6. Style
- */
-
-import { LitElement, html } from 'lit-element';
-
-class MyElement extends LitElement {
-  static get properties() {
-    return {
-      message: { type: String },
-      myArray: { type: Array },
-      myBool: { type: Boolean }
-    };
-  }
-
-  constructor() {
-    super();
-    this.message='Hello world! From my-element';
-    this.myArray = ['an','array','of','test','data'];
-    this.myBool = true;
-  }
-
-  render() {
-    return html`
-      <!-- TODO: Add a style block. -->
-
-      <!-- TODO: Add a styled paragraph. -->
-
-      <p>${this.message}</p>
-      <ul>
-        ${this.myArray.map(i => html`<li>${i}</li>`)}
-      </ul>
-      ${this.myBool?
-        html`<p>Render some HTML if myBool is true</p>`:
-        html`<p>Render some other HTML if myBool is false</p>`}
-      <button @click="${(event) => this.clickHandler(event)}">Click</button>
-    `;
-  }
-
-  clickHandler(event) {
-    console.log(event.target);
-    this.myBool = !this.myBool;
-  }
-}
-customElements.define('my-element', MyElement);
diff --git a/docs/_includes/projects/docs/style/expressions/index.html b/docs/_includes/projects/docs/style/expressions/index.html
deleted file mode 100644
index abdf62ae..00000000
--- a/docs/_includes/projects/docs/style/expressions/index.html
+++ /dev/null
@@ -1,14 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <meta http-equiv="X-UA-Compatible" content="ie=edge">
-    <script src="/node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>
-    <script src="/node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js"></script>
-    <title>lit-element code sample</title>
-  </head>
-  <body>
-    <my-element></my-element>
-  </body>
-</html>
diff --git a/docs/_includes/projects/docs/style/expressions/my-element.js b/docs/_includes/projects/docs/style/expressions/my-element.js
deleted file mode 100644
index 0c20cbdf..00000000
--- a/docs/_includes/projects/docs/style/expressions/my-element.js
+++ /dev/null
@@ -1,15 +0,0 @@
-import { LitElement, html } from 'lit-element';
-
-class MyElement extends LitElement {
-  render() {
-    return html`
-      <style>${this.myStyles}</style>
-      <p>hi world</p>
-    `;
-  }
-  get myStyles() {
-    return html`p { color: red }`;
-  }
-}
-
-customElements.define('my-element', MyElement);
diff --git a/docs/_includes/projects/docs/style/host/my-element.js b/docs/_includes/projects/docs/style/host/my-element.js
deleted file mode 100644
index 2df59509..00000000
--- a/docs/_includes/projects/docs/style/host/my-element.js
+++ /dev/null
@@ -1,19 +0,0 @@
-import { LitElement, html } from 'lit-element';
-
-class MyElement extends LitElement {
-  render() {
-    return html`
-      <style>
-        :host([hidden]) { display: none; }
-        :host {
-          display: block;
-          font-family: Roboto;
-          font-size: 20;
-          color: blue;
-        }
-      </style>
-      <p>Demonstrating :host selector</p>
-    `;
-  }
-}
-customElements.define('my-element', MyElement);
diff --git a/docs/_includes/projects/docs/style/hostselector/index.html b/docs/_includes/projects/docs/style/hostselector/index.html
deleted file mode 100644
index 205b902b..00000000
--- a/docs/_includes/projects/docs/style/hostselector/index.html
+++ /dev/null
@@ -1,17 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta http-equiv="X-UA-Compatible" content="ie=edge">
-  <script src="/node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>
-  <script src="/node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js"></script>
-  <title>lit-element code sample</title>
-  
-</head>
-
-  <body>
-    <my-element></my-element>
-  </body>
-
-</html>
diff --git a/docs/_includes/projects/docs/style/inherited/index.html b/docs/_includes/projects/docs/style/inherited/index.html
deleted file mode 100644
index 205b902b..00000000
--- a/docs/_includes/projects/docs/style/inherited/index.html
+++ /dev/null
@@ -1,17 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta http-equiv="X-UA-Compatible" content="ie=edge">
-  <script src="/node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>
-  <script src="/node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js"></script>
-  <title>lit-element code sample</title>
-  
-</head>
-
-  <body>
-    <my-element></my-element>
-  </body>
-
-</html>
diff --git a/docs/_includes/projects/docs/style/inherited2/index.ts b/docs/_includes/projects/docs/style/inherited2/index.ts
deleted file mode 100644
index 735d0c5f..00000000
--- a/docs/_includes/projects/docs/style/inherited2/index.ts
+++ /dev/null
@@ -1 +0,0 @@
-import './my-element.js';
diff --git a/docs/_includes/projects/docs/style/inherited2/manifest.json b/docs/_includes/projects/docs/style/inherited2/manifest.json
deleted file mode 100644
index cc77695b..00000000
--- a/docs/_includes/projects/docs/style/inherited2/manifest.json
+++ /dev/null
@@ -1,14 +0,0 @@
-{
-  "title": "lit-element code sample",
-  "description": "lit-element code sample",
-  "files": [
-    "my-element.js",
-    "index.html",
-    "index.ts"
-  ],
-  "dependencies": {
-    "lit-element": "latest",
-    "@webcomponents/webcomponentsjs": "latest"
-  },
-  "template": "typescript"
-}
diff --git a/docs/_includes/projects/docs/style/maindocument/index.html b/docs/_includes/projects/docs/style/maindocument/index.html
deleted file mode 100644
index aba88c3e..00000000
--- a/docs/_includes/projects/docs/style/maindocument/index.html
+++ /dev/null
@@ -1,24 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta http-equiv="X-UA-Compatible" content="ie=edge">
-  <script src="/node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>
-  <script src="/node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js"></script>
-  <title>lit-element code sample</title>
-  <style>
-    my-element { 
-      display: block; 
-      font-family: Roboto;
-      font-size: 20;
-      color: blue;
-    }
-  </style>
-</head>
-
-  <body>
-    <my-element></my-element>
-  </body>
-
-</html>
diff --git a/docs/_includes/projects/docs/style/maindocument/index.ts b/docs/_includes/projects/docs/style/maindocument/index.ts
deleted file mode 100644
index 735d0c5f..00000000
--- a/docs/_includes/projects/docs/style/maindocument/index.ts
+++ /dev/null
@@ -1 +0,0 @@
-import './my-element.js';
diff --git a/docs/_includes/projects/docs/style/maindocument/manifest.json b/docs/_includes/projects/docs/style/maindocument/manifest.json
deleted file mode 100644
index cc77695b..00000000
--- a/docs/_includes/projects/docs/style/maindocument/manifest.json
+++ /dev/null
@@ -1,14 +0,0 @@
-{
-  "title": "lit-element code sample",
-  "description": "lit-element code sample",
-  "files": [
-    "my-element.js",
-    "index.html",
-    "index.ts"
-  ],
-  "dependencies": {
-    "lit-element": "latest",
-    "@webcomponents/webcomponentsjs": "latest"
-  },
-  "template": "typescript"
-}
diff --git a/docs/_includes/projects/docs/style/maindocument/my-element.js b/docs/_includes/projects/docs/style/maindocument/my-element.js
deleted file mode 100644
index 807b8162..00000000
--- a/docs/_includes/projects/docs/style/maindocument/my-element.js
+++ /dev/null
@@ -1,20 +0,0 @@
-import { LitElement, html } from 'lit-element';
-
-class MyElement extends LitElement {
-  render() {
-    return html`
-      <style>
-        :host([hidden]) { display: none; }
-        :host {
-          display: block;
-        }
-        div {
-          color: red;
-        }
-      </style>
-      <p>Paragraph</p>
-      <div>Div</div>
-    `;
-  }
-}
-customElements.define('my-element', MyElement);
diff --git a/docs/_includes/projects/docs/style/slotted/index.ts b/docs/_includes/projects/docs/style/slotted/index.ts
deleted file mode 100644
index 735d0c5f..00000000
--- a/docs/_includes/projects/docs/style/slotted/index.ts
+++ /dev/null
@@ -1 +0,0 @@
-import './my-element.js';
diff --git a/docs/_includes/projects/docs/style/slotted/manifest.json b/docs/_includes/projects/docs/style/slotted/manifest.json
deleted file mode 100644
index cc77695b..00000000
--- a/docs/_includes/projects/docs/style/slotted/manifest.json
+++ /dev/null
@@ -1,14 +0,0 @@
-{
-  "title": "lit-element code sample",
-  "description": "lit-element code sample",
-  "files": [
-    "my-element.js",
-    "index.html",
-    "index.ts"
-  ],
-  "dependencies": {
-    "lit-element": "latest",
-    "@webcomponents/webcomponentsjs": "latest"
-  },
-  "template": "typescript"
-}
diff --git a/docs/_includes/projects/docs/style/smalltheme/index.html b/docs/_includes/projects/docs/style/smalltheme/index.html
deleted file mode 100644
index 923bb676..00000000
--- a/docs/_includes/projects/docs/style/smalltheme/index.html
+++ /dev/null
@@ -1,25 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <meta http-equiv="X-UA-Compatible" content="ie=edge">
-    <script src="/node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>
-    <script src="/node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js"></script>
-    <title>lit-element code sample</title>
-    <style>
-      html {
-        --themeColor1: rgb(67, 156, 144);
-        --themeFont: Roboto;
-      }
-      my-element {
-        --myColor: var(--themeColor1);
-        --myFont: var(--themeFont);
-      }
-    </style>
-  </head>
-  <body>
-
-    <my-element></my-element>
-  </body>
-</html>
diff --git a/docs/_includes/projects/docs/style/smalltheme/index.ts b/docs/_includes/projects/docs/style/smalltheme/index.ts
deleted file mode 100644
index 735d0c5f..00000000
--- a/docs/_includes/projects/docs/style/smalltheme/index.ts
+++ /dev/null
@@ -1 +0,0 @@
-import './my-element.js';
diff --git a/docs/_includes/projects/docs/style/smalltheme/manifest.json b/docs/_includes/projects/docs/style/smalltheme/manifest.json
deleted file mode 100644
index 7ae02ae4..00000000
--- a/docs/_includes/projects/docs/style/smalltheme/manifest.json
+++ /dev/null
@@ -1,15 +0,0 @@
-{
-  "title": "lit-element code sample",
-  "description": "lit-element code sample",
-  "files": [
-    "my-element.js",
-    "my-styles.js",
-    "index.html",
-    "index.ts"
-  ],
-  "dependencies": {
-    "lit-element": "latest",
-    "@webcomponents/webcomponentsjs": "latest"
-  },
-  "template": "typescript"
-}
diff --git a/docs/_includes/projects/docs/style/smalltheme/my-element.js b/docs/_includes/projects/docs/style/smalltheme/my-element.js
deleted file mode 100644
index cf179431..00000000
--- a/docs/_includes/projects/docs/style/smalltheme/my-element.js
+++ /dev/null
@@ -1,28 +0,0 @@
-import { LitElement, html } from 'lit-element';
-import { navStyles } from './my-styles.js';
-
-class MyElement extends LitElement {
-  static get properties() {
-    return { menuItems: { } };
-  }
-  constructor() {
-    super();
-    this.menuItems = [ 'Option1', 'Option2', 'Option3'];
-  }
-  render() {
-    return html`
-      <style>
-        :host([hidden]) { display: none; }
-        :host { display: block;
-          color: var(--myColor);
-          font-family: var(--myFont);
-        }
-        ${navStyles}
-      </style>
-      <ul class="navigation">
-        ${this.menuItems.map(item => html`<li class="item">${item}</li>`)}
-      </ul>
-    `;
-  }
-}
-customElements.define('my-element', MyElement);
diff --git a/docs/_includes/projects/docs/style/smalltheme/my-styles.js b/docs/_includes/projects/docs/style/smalltheme/my-styles.js
deleted file mode 100644
index f99882a6..00000000
--- a/docs/_includes/projects/docs/style/smalltheme/my-styles.js
+++ /dev/null
@@ -1,16 +0,0 @@
-import { html } from 'lit-element';
-
-export const navStyles = html`
-  ul {
-    list-style-type: none;
-    margin: 0;
-    padding: 0;
-  }
-  .navigation {
-    display: flex;
-    flex-direction: row;
-  }
-  .item {
-    padding: 8px;
-  }
-`;
diff --git a/docs/_includes/projects/docs/style/before/index.html b/docs/_includes/projects/style/bestpracs/index.html
similarity index 100%
rename from docs/_includes/projects/docs/style/before/index.html
rename to docs/_includes/projects/style/bestpracs/index.html
diff --git a/docs/_includes/projects/docs/style/before/index.ts b/docs/_includes/projects/style/bestpracs/index.ts
similarity index 100%
rename from docs/_includes/projects/docs/style/before/index.ts
rename to docs/_includes/projects/style/bestpracs/index.ts
diff --git a/docs/_includes/projects/docs/style/before/manifest.json b/docs/_includes/projects/style/bestpracs/manifest.json
similarity index 100%
rename from docs/_includes/projects/docs/style/before/manifest.json
rename to docs/_includes/projects/style/bestpracs/manifest.json
diff --git a/docs/_includes/projects/docs/style/bestpracs/my-element.js b/docs/_includes/projects/style/bestpracs/my-element.js
similarity index 100%
rename from docs/_includes/projects/docs/style/bestpracs/my-element.js
rename to docs/_includes/projects/style/bestpracs/my-element.js
diff --git a/docs/_includes/projects/docs/style/customproperties/index.html b/docs/_includes/projects/style/customproperties/index.html
similarity index 100%
rename from docs/_includes/projects/docs/style/customproperties/index.html
rename to docs/_includes/projects/style/customproperties/index.html
diff --git a/docs/_includes/projects/docs/style/bestpracs/index.ts b/docs/_includes/projects/style/customproperties/index.ts
similarity index 100%
rename from docs/_includes/projects/docs/style/bestpracs/index.ts
rename to docs/_includes/projects/style/customproperties/index.ts
diff --git a/docs/_includes/projects/docs/style/bestpracs/manifest.json b/docs/_includes/projects/style/customproperties/manifest.json
similarity index 100%
rename from docs/_includes/projects/docs/style/bestpracs/manifest.json
rename to docs/_includes/projects/style/customproperties/manifest.json
diff --git a/docs/_includes/projects/docs/style/customproperties/my-element.js b/docs/_includes/projects/style/customproperties/my-element.js
similarity index 100%
rename from docs/_includes/projects/docs/style/customproperties/my-element.js
rename to docs/_includes/projects/style/customproperties/my-element.js
diff --git a/docs/_includes/projects/docs/style/bestpracs/index.html b/docs/_includes/projects/style/hostselector/index.html
similarity index 100%
rename from docs/_includes/projects/docs/style/bestpracs/index.html
rename to docs/_includes/projects/style/hostselector/index.html
diff --git a/docs/_includes/projects/docs/style/customproperties/index.ts b/docs/_includes/projects/style/hostselector/index.ts
similarity index 100%
rename from docs/_includes/projects/docs/style/customproperties/index.ts
rename to docs/_includes/projects/style/hostselector/index.ts
diff --git a/docs/_includes/projects/docs/style/customproperties/manifest.json b/docs/_includes/projects/style/hostselector/manifest.json
similarity index 100%
rename from docs/_includes/projects/docs/style/customproperties/manifest.json
rename to docs/_includes/projects/style/hostselector/manifest.json
diff --git a/docs/_includes/projects/docs/style/hostselector/my-element.js b/docs/_includes/projects/style/hostselector/my-element.js
similarity index 100%
rename from docs/_includes/projects/docs/style/hostselector/my-element.js
rename to docs/_includes/projects/style/hostselector/my-element.js
diff --git a/docs/_includes/projects/docs/style/host/index.html b/docs/_includes/projects/style/inherited/index.html
similarity index 100%
rename from docs/_includes/projects/docs/style/host/index.html
rename to docs/_includes/projects/style/inherited/index.html
diff --git a/docs/_includes/projects/docs/style/expressions/index.ts b/docs/_includes/projects/style/inherited/index.ts
similarity index 100%
rename from docs/_includes/projects/docs/style/expressions/index.ts
rename to docs/_includes/projects/style/inherited/index.ts
diff --git a/docs/_includes/projects/docs/style/expressions/manifest.json b/docs/_includes/projects/style/inherited/manifest.json
similarity index 100%
rename from docs/_includes/projects/docs/style/expressions/manifest.json
rename to docs/_includes/projects/style/inherited/manifest.json
diff --git a/docs/_includes/projects/docs/style/inherited/my-element.js b/docs/_includes/projects/style/inherited/my-element.js
similarity index 100%
rename from docs/_includes/projects/docs/style/inherited/my-element.js
rename to docs/_includes/projects/style/inherited/my-element.js
diff --git a/docs/_includes/projects/docs/style/inherited2/index.html b/docs/_includes/projects/style/inherited2/index.html
similarity index 100%
rename from docs/_includes/projects/docs/style/inherited2/index.html
rename to docs/_includes/projects/style/inherited2/index.html
diff --git a/docs/_includes/projects/docs/style/host/index.ts b/docs/_includes/projects/style/inherited2/index.ts
similarity index 100%
rename from docs/_includes/projects/docs/style/host/index.ts
rename to docs/_includes/projects/style/inherited2/index.ts
diff --git a/docs/_includes/projects/docs/style/host/manifest.json b/docs/_includes/projects/style/inherited2/manifest.json
similarity index 100%
rename from docs/_includes/projects/docs/style/host/manifest.json
rename to docs/_includes/projects/style/inherited2/manifest.json
diff --git a/docs/_includes/projects/docs/style/inherited2/my-element.js b/docs/_includes/projects/style/inherited2/my-element.js
similarity index 100%
rename from docs/_includes/projects/docs/style/inherited2/my-element.js
rename to docs/_includes/projects/style/inherited2/my-element.js
diff --git a/docs/_includes/projects/docs/style/slotted/index.html b/docs/_includes/projects/style/slotted/index.html
similarity index 100%
rename from docs/_includes/projects/docs/style/slotted/index.html
rename to docs/_includes/projects/style/slotted/index.html
diff --git a/docs/_includes/projects/docs/style/hostselector/index.ts b/docs/_includes/projects/style/slotted/index.ts
similarity index 100%
rename from docs/_includes/projects/docs/style/hostselector/index.ts
rename to docs/_includes/projects/style/slotted/index.ts
diff --git a/docs/_includes/projects/docs/style/hostselector/manifest.json b/docs/_includes/projects/style/slotted/manifest.json
similarity index 100%
rename from docs/_includes/projects/docs/style/hostselector/manifest.json
rename to docs/_includes/projects/style/slotted/manifest.json
diff --git a/docs/_includes/projects/docs/style/slotted/my-element.js b/docs/_includes/projects/style/slotted/my-element.js
similarity index 100%
rename from docs/_includes/projects/docs/style/slotted/my-element.js
rename to docs/_includes/projects/style/slotted/my-element.js
diff --git a/docs/_includes/projects/style/theming/index.html b/docs/_includes/projects/style/theming/index.html
new file mode 100644
index 00000000..97b75b04
--- /dev/null
+++ b/docs/_includes/projects/style/theming/index.html
@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <script src="/node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>
+    <script src="/node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js"></script>
+    <title>lit-element code sample</title>
+    <style>
+      body {
+        --theme-primary: green;
+        --theme-secondary: aliceblue;
+        --theme-warning: red;
+        --theme-font-family: Roboto;
+      }
+
+      my-element { 
+        --my-element-text-color: var(--theme-primary); 
+        --my-element-background-color: var(--theme-secondary); 
+        --my-element-font-family: var(--theme-font-family);
+      } 
+
+      my-element.warning {
+        --my-element-text-color: var(--theme-warning); 
+      }
+    </style>
+  </head>
+  <body>
+    <my-element></my-element>
+    <my-element class="warning"></my-element>
+  </body>
+</html>
diff --git a/docs/_includes/projects/docs/style/inherited/index.ts b/docs/_includes/projects/style/theming/index.ts
similarity index 100%
rename from docs/_includes/projects/docs/style/inherited/index.ts
rename to docs/_includes/projects/style/theming/index.ts
diff --git a/docs/_includes/projects/docs/style/inherited/manifest.json b/docs/_includes/projects/style/theming/manifest.json
similarity index 100%
rename from docs/_includes/projects/docs/style/inherited/manifest.json
rename to docs/_includes/projects/style/theming/manifest.json
diff --git a/docs/_includes/projects/style/theming/my-element.js b/docs/_includes/projects/style/theming/my-element.js
new file mode 100644
index 00000000..d6b4b5ec
--- /dev/null
+++ b/docs/_includes/projects/style/theming/my-element.js
@@ -0,0 +1,21 @@
+import { LitElement, html, css } from 'lit-element';
+
+class MyElement extends LitElement {
+  static styles = css`
+    :host { 
+      display: block;
+      color: var(--my-element-text-color); 
+      background: var(--my-element-background-color);  
+      font-family: var(--my-element-font-family);
+    }
+    :host([hidden]) {
+      display: none;
+    }
+  `;
+  render() {
+    return html`
+      <div>Hello from my-element</div>
+    `;
+  }
+}
+customElements.define('my-element', MyElement);
diff --git a/docs/package.json b/docs/package.json
index 78a27b39..15a380a9 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -4,7 +4,8 @@
     "build": "polymer build && jekyll build",
     "build-all": "(cd .. && npm run gen-docs) && npm run build",
     "serve": "dev_appserver.py _site/app.yaml",
-    "deploy": "npm run build && gcloud app deploy _site/app.yaml --project polymer-lit-element --no-promote"
+    "deploy": "npm run build && gcloud app deploy _site/app.yaml --project polymer-lit-element --no-promote",
+    "deploy-staging": "npm run build && gcloud app deploy _site/app.yaml --project polymer-lit-element-staging"
   },
   "dependencies": {
     "lit-element": "^2.0.0-rc.1",