diff --git a/lib/elements/custom-style.html b/lib/elements/custom-style.html
index 7c95822fd8..c0af8738d7 100644
--- a/lib/elements/custom-style.html
+++ b/lib/elements/custom-style.html
@@ -19,17 +19,44 @@
 
   /**
    * Custom element for defining styles in the main document that can take
-   * advantage of several special features of Polymer's styling system:
+   * advantage of [shady DOM](https://github.com/webcomponents/shadycss) shims
+   * for style encapsulation, custom properties, and custom mixins.
    *
-   * - Document styles defined in a custom-style are shimmed to ensure they
+   * - Document styles defined in a `<custom-style>` are shimmed to ensure they
    *   do not leak into local DOM when running on browsers without native
    *   Shadow DOM.
-   * - Custom properties used by Polymer's shim for cross-scope styling may
-   *   be defined in an custom-style. Use the :root selector to define custom
-   *   properties that apply to all custom elements.
+   * - Custom properties can be defined in a `<custom-style>`. Use the `html` selector 
+   *   to define custom properties that apply to all custom elements.
+   * - Custom mixins can be defined in a `<custom-style>`, if you import the optional 
+   *   [apply shim](https://github.com/webcomponents/shadycss#about-applyshim)
+   *   (`shadycss/apply-shim.html`).
    *
-   * To use, simply wrap an inline `<style>` tag in the main document whose
-   * CSS uses these features with a `<custom-style>` element.
+   * To use:
+   * 
+   * - Import `custom-style.html`.
+   * - Place a `<custom-style>` element in the main document, wrapping an inline `<style>` tag that
+   *   contains the CSS rules you want to shim.
+   * 
+   * For example:
+   *
+   * ```
+   * <!-- import apply shim--only required if using mixins -->
+   * <link rel="import href="bower_components/shadycss/apply-shim.html">
+   * <!-- import custom-style element -->
+   * <link rel="import" href="bower_components/polymer/lib/elements/custom-style.html">
+   * ...
+   * <custom-style>
+   *   <style>
+   *     html {
+   *       --custom-color: blue;
+   *       --custom-mixin: {
+   *         font-weight: bold;
+   *         color: red;
+   *       };
+   *     }
+   *   </style>
+   * </custom-style>
+   * ```
    *
    * @customElement
    * @extends HTMLElement