From e53f36e5ef5a103d55dab932704bab3d1e5fe5a0 Mon Sep 17 00:00:00 2001
From: Cory LaViska <cory@abeautifulsite.net>
Date: Thu, 5 Aug 2021 09:39:58 -0400
Subject: [PATCH] update docs and changelog

---
 docs/resources/changelog.md | 23 ++++++++++++++++++++++-
 docs/tokens/color.md        | 30 ++++++++++++++++++++++++++++--
 2 files changed, 50 insertions(+), 3 deletions(-)

diff --git a/docs/resources/changelog.md b/docs/resources/changelog.md
index 58748b1e7..e0dee942b 100644
--- a/docs/resources/changelog.md
+++ b/docs/resources/changelog.md
@@ -8,9 +8,30 @@ _During the beta period, these restrictions may be relaxed in the event of a mis
 
 ## Next
 
-- Added a console error that appears when menu items have duplicate values in `sl-select`
+This release adds a variety of new color primitives and changes the way color tokens are consumed. Previously, color tokens were in hexidecimal format. Shoelace now uses an `R G B` format that requires you to use the `rgb()` function in your CSS.
+
+```css
+.example {
+  /* rgb() is required now */
+  color: rgb(var(--sl-color-gray-500));
+}
+```
+
+This is more verbose than before, but it has the advantage of letting you set the alpha channel of any color token.
+
+```css
+.example-with-alpha {
+  /* easily adjust opacity for any color token */
+  color: rgb(var(--sl-color-gray-500) / 50%);
+}
+```
+
+This change applies to all design tokens that implement a color. Refer to the [color tokens](/tokens/color) page for more details.
+
+- 🚨 BREAKING: all design tokens that implement colors have been converted to `R G B` and must be used with the `rgb()` function
 - Added new color primitives to the base set of design tokens
 - Added `--sl-color-*-1000` swatches to all color palettes
+- Added a console error that appears when menu items have duplicate values in `sl-select`
 - Exposed base and dark stylesheets so they can be imported via JavaScript [#438](https://github.com/shoelace-style/shoelace/issues/438)
 - Fixed a bug in `sl-menu` where pressing <kbd>Enter</kbd> after using type to select would result in the wrong value
 - Refactored thumb position logic in `sl-switch` [#490](https://github.com/shoelace-style/shoelace/pull/490)
diff --git a/docs/tokens/color.md b/docs/tokens/color.md
index 81d169a8e..ab39c6eb0 100644
--- a/docs/tokens/color.md
+++ b/docs/tokens/color.md
@@ -1,8 +1,34 @@
 # Color Tokens
 
-Color tokens help maintain consistent use of color throughout your app. Shoelace provides palettes for theme colors and primitives.
+Color tokens help maintain consistent use of color throughout your app. Shoelace provides palettes for theme colors and primitives that you can use as a foundation for your design system.
 
-To reference a color token in your stylesheet, use the `--sl-color-{name}-{n}` CSS custom property, where `{name}` is the name of the palette and `{n}` is the numeric value of the desired swatch.
+## Usage
+
+Color tokens are referenced using the `--sl-color-{name}-{n}` CSS custom property, where `{name}` is the name of the palette and `{n}` is the numeric value of the desired swatch.
+
+All color tokens are defined as a set of RGB integers, eg. `113 113 122`. CSS doesn't understand this format, however, so you need wrap them in the `rgb()` function.
+
+```css
+.example {
+  color: rgb(var(--sl-color-gray-500));
+}
+```
+
+This may seem a bit verbose, but it gives us a super power — we can adjust the alpha channel of any color token!
+
+## Adjusting the Alpha Channel
+
+By default, color tokens produce an opaque color. With this syntax, you can easily change the alpha channel.
+
+```css
+.example-with-alpha {
+  color: rgb(var(--sl-color-gray-500) / 50%);
+}
+```
+
+The browser evaluates this to `rgb(113 113 122 / 50%)`, where 50% is the alpha value. Note the required `/` delimiter after the color token. Alternatively, you can use a decimal such as 0.5 in lieu of a percentage.
+
+This syntax may not look familiar, but it's perfectly valid per the [CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/#typedef-color) and [well-supported](https://caniuse.com/mdn-css_types_color_space_separated_functional_notation) by modern browsers.
 
 ## Theme Tokens