diff --git a/docs/assets/styles/docs.css b/docs/assets/styles/docs.css
index c9e65c567..77d3459e3 100644
--- a/docs/assets/styles/docs.css
+++ b/docs/assets/styles/docs.css
@@ -191,8 +191,8 @@
font-family: var(--base-font-family);
}
-.markdown-section table code {
- white-space: normal !important;
+.markdown-section table code:not([class*="lang-"]):not([class*="language-"]) {
+ white-space: normal;
}
html .repo-button {
@@ -245,3 +245,8 @@ html .repo-button--small {
html .repo-button--sponsor sl-icon {
color: #ea4aaa;
}
+
+body[data-page^="tokens/"] .table-wrapper td:first-child,
+body[data-page^="tokens/"] .table-wrapper td:first-child code {
+ white-space: nowrap;
+}
diff --git a/docs/tokens/border-radius.md b/docs/tokens/border-radius.md
index 276b6f51d..845e39452 100644
--- a/docs/tokens/border-radius.md
+++ b/docs/tokens/border-radius.md
@@ -1,5 +1,7 @@
# Border Radius Tokens
+Border radius tokens are used to give sharp edges a more subtle, rounded effect. They use rem units so they scale with the base font size. The pixel values displayed are based on a 16px font size.
+
| Token | Value | Example |
| ---------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- |
| `--sl-border-radius-small` | 0.125rem (2px) | |
diff --git a/docs/tokens/color.md b/docs/tokens/color.md
index a4e9bb242..7446c1c90 100644
--- a/docs/tokens/color.md
+++ b/docs/tokens/color.md
@@ -1,14 +1,28 @@
# Color Tokens
-TODO
+Color tokens are used to maintain consistent color use throughout your app.
-- Describe how color tokens are generated using HSL
-- Show hue + saturation tokens for each base color
+## Theme Colors
+
+Theme colors are based on HSL values rather than hex or RGB. This technique lets us generate more consistent palettes for every theme color, ranging from 5% to 95% lightness. There are no 0% nor 100% values for theme colors. Use `--sl-color-black` and `--sl-color-white` instead.
+
+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.
+
+```css
+--sl-color-primary-hue: 203;
+--sl-color-primary-saturation: 100%;
+--sl-color-primary-text: var(--sl-color-white);
+```
+
+?> Palettes are comprised of CSS custom properties ("CSS variables"), so you can update them live in your app and see the changes reflect instantly.
## Primary
| Token | Example |
| ----------------------- | ------------------------------------------------------------------------------------ |
+| `--sl-color-primary-5` | |
| `--sl-color-primary-10` | |
| `--sl-color-primary-15` | |
| `--sl-color-primary-20` | |
@@ -33,6 +47,7 @@ TODO
| Token | Example |
| -------------------- | --------------------------------------------------------------------------------- |
| `--sl-color-black` | |
+| `--sl-color-gray-5` | |
| `--sl-color-gray-10` | |
| `--sl-color-gray-15` | |
| `--sl-color-gray-20` | |
@@ -57,6 +72,7 @@ TODO
| Token | Example |
| ----------------------- | ------------------------------------------------------------------------------------ |
+| `--sl-color-success-5` | |
| `--sl-color-success-10` | |
| `--sl-color-success-15` | |
| `--sl-color-success-20` | |
@@ -80,6 +96,7 @@ TODO
| Token | Example |
| -------------------- | --------------------------------------------------------------------------------- |
+| `--sl-color-info-5` | |
| `--sl-color-info-10` | |
| `--sl-color-info-15` | |
| `--sl-color-info-20` | |
@@ -103,6 +120,7 @@ TODO
| Token | Example |
| ----------------------- | ------------------------------------------------------------------------------------ |
+| `--sl-color-warning-5` | |
| `--sl-color-warning-10` | |
| `--sl-color-warning-15` | |
| `--sl-color-warning-20` | |
@@ -126,6 +144,7 @@ TODO
| Token | Example |
| ---------------------- | ----------------------------------------------------------------------------------- |
+| `--sl-color-danger-5` | |
| `--sl-color-danger-10` | |
| `--sl-color-danger-15` | |
| `--sl-color-danger-20` | |
diff --git a/docs/tokens/spacing.md b/docs/tokens/spacing.md
index 259193d6a..4376cb618 100644
--- a/docs/tokens/spacing.md
+++ b/docs/tokens/spacing.md
@@ -1,5 +1,7 @@
# Spacing Tokens
+Spacing tokens are used to provide consistent spacing between components and content throughout your app.
+
| Token | Value | Example |
| ------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
| `--sl-spacing-xxx-small` | 0.125rem (2px) | |
diff --git a/docs/tokens/transition.md b/docs/tokens/transition.md
index 3c600763b..f45b2e031 100644
--- a/docs/tokens/transition.md
+++ b/docs/tokens/transition.md
@@ -1,5 +1,7 @@
# Transition Tokens
+Transition tokens are used to provide consistent transitions throughout your app.
+
| Token | Value | Example |
| ------------------------ | ------ | --------------------------------------------------------------------------------------------- |
| `--sl-transition-x-slow` | 1000ms | |
diff --git a/docs/tokens/typography.md b/docs/tokens/typography.md
index 7e5e52c11..dbd05ba9d 100644
--- a/docs/tokens/typography.md
+++ b/docs/tokens/typography.md
@@ -1,5 +1,7 @@
# Typography Tokens
+Typography tokens are used to maintain a consistent set of font styles throughout your app.
+
## Font Family
The default font stack is designed to be simple and highly available on as many devices as possible.
diff --git a/docs/tokens/z-index.md b/docs/tokens/z-index.md
index 7840437bf..1888b1cf0 100644
--- a/docs/tokens/z-index.md
+++ b/docs/tokens/z-index.md
@@ -1,6 +1,6 @@
# Z-Index Tokens
-Z-indexes are still very much a work in progress.
+Z-indexes are used to stack components in a logical manner.
| Token | Value |
| --------------------------- | ----- |