Document theming

[arthurevans]

We document custom properties, but don't really document how to create a theme or override/extend a theme.

It appears that there are several unexpected wrinkles here, see:

PolymerElements/paper-styles#93
Polymer/polymer#3348

I think the summary is that to use the paper elements and override the default theme, you should probably do something like this:

<!-- my-goth-theme.html -->
<link rel="import" href="bower_components/polymer/polymer.html">
<link rel="import" href="bower_components/paper-styles/default-theme.html">

<style is="custom-style">
  :root {
    --dark-theme-background-color: black;
    --dark-theme-base-color: black;
    --dark-theme-text-color: black;
   }
</style>

If you're writing a theme for your own elements, you should probably have a default theme import like paper-styles does:

<!-- goth-default-theme.html -->
<link rel="import" href="bower_components/polymer/polymer.html">

<style is="custom-style">
  :root {
    --goth-background-color: black;
    --goth-base-color: black;
    --goth-text-color: black;
   }
</style>

If you don't include the theme's dependencies, but depend on the ordering of your imports, stuff will probably work OK... most of the time. But you'll be prey to unexpected problems.