From 52a7328e0fb2845f2fb4aeb9f673ab5c17c54762 Mon Sep 17 00:00:00 2001
From: Arthur Evans <arthure@google.com>
Date: Mon, 24 Jul 2017 15:45:05 -0700
Subject: [PATCH] Update custom-style API doc

Fixes https://github.com/Polymer/docs/issues/2266.

I didn't test this through the docs generation. Handle with care.
---
 lib/elements/custom-style.html | 38 ++++++++++++++++++++++++++++------
 1 file changed, 32 insertions(+), 6 deletions(-)

diff --git a/lib/elements/custom-style.html b/lib/elements/custom-style.html
index 7c95822fd8..c4ceef3334 100644
--- a/lib/elements/custom-style.html
+++ b/lib/elements/custom-style.html
@@ -19,17 +19,43 @@
 
   /**
    * 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
    *   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 an 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 the custom-style element.
+   * - 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