From aaf0f9f69e6f9db7bb44e1dc30b98c1a32cbe14f Mon Sep 17 00:00:00 2001
From: Cory LaViska <cory@abeautifulsite.net>
Date: Sat, 18 Jul 2020 07:38:45 -0400
Subject: [PATCH] Update theming docs

---
 docs/getting-started/customizing.md |  2 +-
 docs/tokens/color.md                | 21 ++++++++++++++++-----
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/docs/getting-started/customizing.md b/docs/getting-started/customizing.md
index 3c6a5638..9866cb43 100644
--- a/docs/getting-started/customizing.md
+++ b/docs/getting-started/customizing.md
@@ -20,7 +20,7 @@ To customize a design token, simply override it in your stylesheet using a `:roo
 }
 ```
 
-Design tokens are described further along in this documentation. For a complete list, refer to `shoelace.scss` in the project's [source code](https://github.com/shoelace-style/shoelace/blob/master/src/styles/shoelace.scss).
+Many design tokens are described further along in this documentation. For a complete list, refer to `shoelace.scss` in the project's [source code](https://github.com/shoelace-style/shoelace/blob/master/src/styles/shoelace.scss).
 
 !> **Never modify variables directly in `shoelace.css`** because your changes will be overwritten when you upgrade the library. Even if you don't plan on upgrading, it's always better to override design tokens in your own stylesheet for better maintainability.
 
diff --git a/docs/tokens/color.md b/docs/tokens/color.md
index 1ec32d2f..47ffc10c 100644
--- a/docs/tokens/color.md
+++ b/docs/tokens/color.md
@@ -8,15 +8,26 @@ Theme colors are based on HSL values rather than hex or RGB. This technique lets
 
 Theme colors include primary, gray, success, info, warning, and danger. They are used extensively throughout the library to maintain a consistent appearance across components.
 
-To customize a theme color, change its respective hue, saturation, and text tokens. This will update all colors in the palette — there's no need to update individual palette colors. In fact, doing so is strongly discouraged.
+To customize a theme color, change its respective hue, saturation, and text tokens. Possible theme colors include `primary`, `gray`, `success`, `info`, `warning`, and `danger`.
+
+This will make all colors in the primary color palette various shades of purple.
 
 ```css
---sl-color-primary-hue: 203;
---sl-color-primary-saturation: 100%;
---sl-color-primary-text: var(--sl-color-white);
+:root {
+  --sl-color-primary-hue: 290;
+  --sl-color-primary-saturation: 87%;
+  --sl-color-primary-text: var(--sl-color-white);
+}
 ```
 
-?> Color palettes are comprised of CSS custom properties ("CSS variables"), so you can update them live in your app and see the changes reflect instantly.
+You can update these values on the client and the changes will reflect instantly. To update the primary color using JavaScript, try this.
+
+```js
+document.documentElement.style.setProperty('--sl-color-primary-hue', '290');
+document.documentElement.style.setProperty('--sl-color-primary-saturation', '87%');
+```
+
+?> Although CSS lets you override custom properties on specific elements, these values _must_ be scoped to the `:root` block for the entire palette to be recalculated. [See this page for details.](https://stackoverflow.com/questions/52015737/css-scoped-custom-property-ignored-when-used-to-calculate-variable-in-outer-scop)
 
 ## Primary