Improve theme remixing UI

Use background-image for native select caret (#594 )
Use native events when possible (#590 )
2026-01-13 12:39:14 +00:00 · 2025-01-27 12:42:35 -05:00 · 2025-01-24 11:52:06 -05:00 · 2025-01-23 17:52:41 -05:00 · 2025-01-22 13:25:29 -05:00 · 2025-01-21 15:16:11 -05:00
214 changed files with 5090 additions and 4283 deletions
--- a/docs/_data/componentList.js
+++ b/docs/_data/componentList.js
@@ -31,25 +31,13 @@ const components = manifest.modules.flatMap(module => {
        return prop.kind === 'field' && prop.privacy !== 'private';
      });

-      let ret = {
+      return {
        ...declaration,
        slug: declaration.tagName.replace(/^wa-/, ''),
        methods,
        attributes,
        properties,
      };
-
-      // Add named keys to these arrays
-      for (let thing of ['methods', 'attributes', 'properties', 'cssProperties', 'cssParts', 'cssStates', 'events']) {
-        if (ret[thing]) {
-          ret[thing] = ret[thing].reduce((acc, item) => {
-            acc[item.name] = item;
-            return acc;
-          }, ret[thing]);
-        }
-      }
-
-      return ret;
    });
 });

--- a/docs/_data/hues.json
+++ b/docs/_data/hues.json
@@ -0,0 +1 @@
+["red", "yellow", "green", "teal", "blue", "indigo", "violet", "gray"]
--- a/docs/_data/palettes.js
+++ b/docs/_data/palettes.js
@@ -0,0 +1 @@
+export { default as default } from '../../src/styles/color/palettes.js';
--- a/docs/_includes/base.njk
+++ b/docs/_includes/base.njk
@@ -16,7 +16,7 @@
    {# Docs styles #}
    <link rel="stylesheet" href="/assets/styles/docs.css" />
  </head>
-  <body class="layout-{{ layout | stripExtension }}">
+  <body class="layout-{{ layout | stripExtension }}{{ ' page-wide' if wide }}">
    <!-- use view="desktop" as default to reduce layout jank on desktop site. -->
    <wa-page view="desktop" disable-navigation-toggle="">
      <header slot="header" class="wa-split">
@@ -83,8 +83,6 @@
          </details>
        </nav>

-
-
        {% block header %}
          {% include 'breadcrumbs.njk' %}
          <h1 class="title">{{ title }}</h1>
--- a/docs/_includes/contrast-table.njk
+++ b/docs/_includes/contrast-table.njk
@@ -0,0 +1,40 @@
+<table class="colors wa-palette-{{ paletteId }}">
+  <thead>
+    <tr>
+      <th></th>
+      {% for tint_bg in tints -%}
+        {% for tint_fg in tints | reverse -%}
+          {% if (tint_fg - tint_bg) | abs == difference %}
+          <th>{{ tint_fg }} on {{ tint_bg }}</th>
+          {% endif %}
+        {%- endfor -%}
+      {%- endfor %}
+    </tr>
+  </thead>
+{% for hue in hues -%}
+<tr>
+  <th>{{ hue | capitalize }}</th>
+  {% for tint_bg in tints -%}
+    {% set color_bg = palettes[paletteId][hue][tint_bg] %}
+    {% for tint_fg in tints | reverse -%}
+      {% set color_fg = palettes[paletteId][hue][tint_fg] %}
+      {% if (tint_fg - tint_bg) | abs == difference %}
+      <td>
+        <div class="color swatch" style="background-color: var(--wa-color-{{ hue }}-{{ tint_bg }}); color: var(--wa-color-{{ hue }}-{{ tint_fg }})">
+          {% set contrast_wcag = '' %}
+          {% if color_fg and color_bg %}
+            {% set contrast_wcag = color_bg.contrast(color_fg, 'WCAG21') %}
+          {% endif %}
+          {% if contrast_wcag %}
+          {{ contrast_wcag | number({maximumSignificantDigits: 2}) }}
+          {% else %}
+          {{ tint_fg }} on {{ tint_bg }}
+          {% endif %}
+        </div>
+      </td>
+      {% endif %}
+    {%- endfor -%}
+  {%- endfor -%}
+</tr>
+{%- endfor %}
+</table>
--- a/docs/_includes/head.njk
+++ b/docs/_includes/head.njk
@@ -30,19 +30,15 @@

 <script type="module" src="/assets/scripts/theme-picker.js"></script>
 {# Preset Theme #}
-<link id="theme-stylesheet" rel="stylesheet" id="theme-stylesheet" href="/dist/styles/themes/{{ forceTheme or 'default' }}.css" render="blocking" fetchpriority="high" />
-{% if not forceTheme %}
+{% if forceTheme %}
+<link id="theme-stylesheet" rel="stylesheet" id="theme-stylesheet" href="/dist/styles/themes/{{ forceTheme }}.css" render="blocking" fetchpriority="high" />
+{% else %}
+<noscript><link id="theme-stylesheet" rel="stylesheet" id="theme-stylesheet" href="/dist/styles/themes/default.css" render="blocking" fetchpriority="high" /></noscript>
 <script>
-if (localStorage.presetTheme) {
-	let preset = localStorage.presetTheme;
+{
+	let preset = localStorage.presetTheme ?? 'default';
 	let script = document.currentScript;
-	let link = script.previousElementSibling;
-	let newLink = link.cloneNode();
-	newLink.href = link.href.replace("/default.css", `/${preset}.css`);
-	newLink.addEventListener('load', () => {
-		link.remove();
-	});
-	link.after(newLink);
+	script.insertAdjacentHTML('beforebegin', `<link id="theme-stylesheet" rel="stylesheet" id="theme-stylesheet" href="/dist/styles/themes/${ preset }.css" render="blocking" fetchpriority="high" />`);
 }
 </script>
 <script type="module" src="/assets/scripts/preset-theme-picker.js"></script>
--- a/docs/_includes/import-stylesheet-code.md.njk
+++ b/docs/_includes/import-stylesheet-code.md.njk
@@ -0,0 +1,24 @@
+{%- if not stylesheets %}{% set stylesheets = [stylesheet] %}{% endif -%}
+
+<wa-tab-group>
+<wa-tab panel="html">In HTML</wa-tab>
+<wa-tab panel="css">In CSS</wa-tab>
+<wa-tab-panel name="html">
+
+Simply add the following code to the `<head>` of your page:
+```html
+{% for stylesheet in stylesheets -%}
+<link rel="stylesheet" href="{% cdnUrl stylesheet %}" />{% if not loop.last %}
+{% endif %}{% endfor %}
+```
+</wa-tab-panel>
+<wa-tab-panel name="css">
+
+Simply add the following code at the top of your CSS file:
+```css
+{% for stylesheet in stylesheets -%}
+@import url('{% cdnUrl stylesheet %}');{% if not loop.last %}
+{% endif %}{% endfor %}
+```
+</wa-tab-panel>
+</wa-tab-group>
--- a/docs/_includes/sidebar-group.njk
+++ b/docs/_includes/sidebar-group.njk
@@ -1,8 +1,8 @@
 {# Some collections (like "patterns") will not have any items in the alpha build for example. So this checks to make sure the collection exists. #}
 {% if collections[tag] -%}
-  <wa-details {{ (tag in (tags or [])) | attr('open') }}>
+  {% set groupUrl %}/docs/{{ tag }}/{% endset %}
+  <wa-details {{ ((tag in (tags or [])) or (groupUrl in page.url)) | attr('open') }}>
    <h2 slot="summary">
-      {% set groupUrl %}/docs/{{ tag }}/{% endset %}
      {% if groupUrl | getCollectionItemFromUrl %}
        <a href="{{ groupUrl }}" title="Overview">{{ title or (tag | capitalize) }}
          <wa-icon name="grid-2"></wa-icon>
--- a/docs/_includes/sidebar.njk
+++ b/docs/_includes/sidebar.njk
@@ -25,7 +25,8 @@
  'utilities': 'Style Utilities',
  'layout': 'Layout',
  'patterns': 'Patterns',
-  'theming': 'Theming'
+  'palettes': 'Color Palettes',
+  'tokens': 'Design Tokens'
 } %}
  {% include 'sidebar-group.njk' %}
 {% endfor %}
--- a/docs/_includes/svgs/palette.njk
+++ b/docs/_includes/svgs/palette.njk
@@ -0,0 +1,24 @@
+{% set paletteId = page.fileSlug %}
+{% set tints = [80, 60, 40, 20] %}
+{% set width = 20 %}
+{% set height = 13 %}
+{% set gap_x = 3 %}
+{% set gap_y = 3 %}
+
+<svg viewBox="0 0 {{ (width + gap_x) * hues|length }} {{ (height + gap_y) * tints|length }}" fill="none" xmlns="http://www.w3.org/2000/svg" class="wa-palette-{{ paletteId }} palette-icon">
+<style>
+	@import url('/dist/styles/color/{{ paletteId }}.css') layer(palette.{{ paletteId }});
+	.palette-icon {
+		height: 8ch;
+	}
+</style>
+
+{% for hue in hues -%}
+  {% set hueIndex = loop.index0 %}
+  {% for tint in tints -%}
+    <rect x="{{ hueIndex * (width + gap_x) }}" y="{{ loop.index0 * (height + gap_y) }}"
+	      width="{{ width }}" height="{{ height }}"
+	      fill="var(--wa-color-{{ hue }}-{{ tint }})" rx="4" />
+  {%- endfor %}
+{% endfor %}
+</svg>
--- a/docs/_includes/svgs/theming/borders.njk
+++ b/docs/_includes/svgs/theming/borders.njk
--- a/docs/_includes/svgs/theming/color.njk
+++ b/docs/_includes/svgs/theming/color.njk
--- a/docs/_includes/svgs/theming/component-groups.njk
+++ b/docs/_includes/svgs/theming/component-groups.njk
--- a/docs/_includes/svgs/theming/focus.njk
+++ b/docs/_includes/svgs/theming/focus.njk
--- a/docs/_includes/svgs/theming/shadows.njk
+++ b/docs/_includes/svgs/theming/shadows.njk
--- a/docs/_includes/svgs/theming/space.njk
+++ b/docs/_includes/svgs/theming/space.njk
--- a/docs/_includes/svgs/theming/transitions.njk
+++ b/docs/_includes/svgs/theming/transitions.njk
--- a/docs/_includes/svgs/theming/typography.njk
+++ b/docs/_includes/svgs/theming/typography.njk
--- a/docs/_layouts/palette.njk
+++ b/docs/_layouts/palette.njk
@@ -0,0 +1,119 @@
+{% set hasSidebar = true %}
+{% set hasOutline = true %}
+{# {% set forceTheme = page.fileSlug %} #}
+
+{% extends '../_layouts/block.njk' %}
+
+{% set paletteId = page.fileSlug %}
+
+{% block afterContent %}
+<style>@import url('/dist/styles/color/{{ paletteId }}.css') layer(palette.{{ paletteId }});</style>
+
+{% set tints = ["95", "90", "80", "70", "60", "50", "40", "30", "20", "10", "05"] %}
+
+<table class="colors wa-palette-{{ paletteId }}">
+  <thead>
+    <tr>
+      <th></th>
+      {% for tint in tints -%}
+      <th>{{ tint }}</th>
+      {%- endfor %}
+    </tr>
+  </thead>
+{% for hue in hues -%}
+<tr>
+  <th>{{ hue | capitalize }}</th>
+  {% for tint in tints -%}
+    <td>
+      <div class="color swatch" style="background-color: var(--wa-color-{{ hue }}-{{ tint }})">
+        <wa-copy-button value="--wa-color-{{ hue }}-{{ tint }}" copy-label="--wa-color-{{ hue }}-{{ tint }}"></wa-copy-button>
+      </div>
+    </td>
+  {%- endfor -%}
+</tr>
+{%- endfor %}
+</table>
+
+<h2>Used By</h2>
+
+<section class="index-grid">
+{% for page in collections.theme %}
+  {%- if page.data.palette == paletteId -%}
+    {% include "page-card.njk" %}
+  {%- endif -%}
+{% endfor %}
+</section>
+
+{% markdown %}
+## Color Contrast
+
+Web Awesome color scales are designed to guarantee certain contrast ratios,
+both per [WCAG 2.1 success criteria](https://www.w3.org/TR/WCAG21/#contrast-minimum)
+as well as the emergent APCA specification _(planned)_,
+so you can ensure that text is both legible to all users, and legally conformant.
+
+### Level 1
+
+A difference of `40` ensures a minimum **3:1** contrast ratio, suitable for large text and icons (AA).
+{% endmarkdown %}
+
+{% set difference = 40 %}
+{% include "contrast-table.njk" %}
+
+{% markdown %}
+
+This also goes for a difference of `45`:
+
+{% endmarkdown %}
+
+{% set difference = 45 %}
+{% include "contrast-table.njk" %}
+
+{% markdown %}
+
+### Level 2
+
+A difference of `50` ensures a minimum **4.5:1** contrast ratio, suitable for normal text (AA) and large text (AAA)
+{% endmarkdown %}
+
+{% set difference = 50 %}
+{% include "contrast-table.njk" %}
+
+{% markdown %}
+
+This also goes for a difference of `55`:
+
+{% endmarkdown %}
+
+{% set difference = 55 %}
+{% include "contrast-table.njk" %}
+
+{% markdown %}
+### Level 3
+
+A difference of `60` ensures a minimum **7:1** contrast ratio, suitable for all text (AAA)
+{% endmarkdown %}
+
+{% set difference = 60 %}
+{% include "contrast-table.njk" %}
+
+{% markdown %}
+
+This also goes for a difference of `65`:
+
+{% endmarkdown %}
+
+{% set difference = 65 %}
+{% include "contrast-table.njk" %}
+
+{% markdown %}
+## How to use this palette
+
+If you are using a Web Awesome theme that uses this palette, it will already be included.
+To use a different palette than a theme default, or to use it in a custom theme, you can import this palette directly from the Web Awesome CDN.
+
+{% set stylesheet = 'styles/color/' + page.fileSlug + '.css' %}
+{% include 'import-stylesheet-code.md.njk' %}
+
+{% endmarkdown %}
+{% endblock %}
--- a/docs/_layouts/theme.njk
+++ b/docs/_layouts/theme.njk
@@ -3,35 +3,37 @@
 {# {% set forceTheme = page.fileSlug %} #}

 {% extends '../_includes/base.njk' %}
+{% set themeId = page.fileSlug %}
+{% if themeId == 'remixed' -%}
+  {% set themeId = 'default' %}
+{% endif -%}

 {% block header %}
-<iframe src='{{ page.url }}demo.html'></iframe>
+<iframe src='/docs/themes/{{ themeId }}/demo.html' id="demo"></iframe>
+
+{% if palette -%}
+<h2>Default Color Palette</h2>
+{% set paletteURL = '/docs/palettes/' + palette + '/' %}
+{% set themePage = page %}
+{% set page = paletteURL | getCollectionItemFromUrl %}
+<div class="index-grid">
+{% include 'page-card.njk' %}
+</div>
+{% set page = themePage %}
+{% endif %}
+
 {% endblock %}

 {% block afterContent %}
 {% markdown %}
+{%- if page.fileSlug != 'remixed' %}
 ## How to use this theme

 You can import this theme from the Web Awesome CDN.

-<wa-tab-group>
-<wa-tab panel="html">In HTML</wa-tab>
-<wa-tab panel="css">In CSS</wa-tab>
-<wa-tab-panel name="html">
-
-Simply add the following code to the `<head>` of your page:
-```html
-<link rel="stylesheet" href="{% cdnUrl 'styles/themes/' + page.fileSlug + '.css' %}" />
-```
-</wa-tab-panel>
-<wa-tab-panel name="css">
-
-Simply add the following code at the top of your CSS file:
-```css
-@import url('{% cdnUrl 'styles/themes/' + page.fileSlug + '.css' %}');
-```
-</wa-tab-panel>
-</wa-tab-group>
+{% set stylesheet = 'styles/themes/' + themeId + '.css' %}
+{% include 'import-stylesheet-code.md.njk' %}
+{% endif %}

 ## Dark mode

--- a/docs/_utils/filters.js
+++ b/docs/_utils/filters.js
@@ -14,18 +14,6 @@ export function trimPipes(content) {
  return typeof content === 'string' ? content.replace(/^(\s|\|)/g, '').replace(/(\s|\|)$/g, '') : content;
 }

-export function stripQuotes(content) {
-  return content.replace(/^(['"])(.+)\1$/g, '$2');
-}
-
-export function getEnumValues(type) {
-  return type
-    .split('|')
-    .map(value => value.trim())
-    .filter(Boolean)
-    .map(stripQuotes);
-}
-
 export function keys(obj) {
  return Object.keys(obj);
 }
@@ -117,6 +105,23 @@ export function deepValue(obj, key) {
  return key.reduce((subObj, property) => subObj?.[property], obj);
 }

+export function number(value, options) {
+  if (typeof value !== 'number' && isNaN(value)) {
+    return value;
+  }
+
+  let lang = options?.lang ?? 'en';
+  if (options?.lang) {
+    delete options.lang;
+  }
+
+  if (!options || Object.keys(options).length === 0) {
+    options = { maximumSignificantDigits: 3 };
+  }
+
+  return Number(value).toLocaleString(lang, options);
+}
+
 export function isNumeric(value) {
  return typeof value === 'number' || (typeof value === 'string' && !isNaN(value));
 }
--- a/docs/assets/scripts/filter.js
+++ b/docs/assets/scripts/filter.js
@@ -18,7 +18,7 @@ function updateResults(input) {
  }
 }

-document.documentElement.addEventListener('wa-input', e => {
+document.documentElement.addEventListener('input', e => {
  if (e.target?.matches('#block-filter wa-input')) {
    updateResults(e.target);
  }
--- a/docs/assets/scripts/preset-theme-picker.js
+++ b/docs/assets/scripts/preset-theme-picker.js
@@ -5,7 +5,7 @@ const presetTheme = new ThemeAspect({
  key: 'presetTheme',
  picker: 'wa-select.preset-theme-selector',

-  applyChange() {
+  applyChange(options = {}) {
    const oldStylesheets = [...document.querySelectorAll('#theme-stylesheet')];
    const oldStylesheet = oldStylesheets.pop();

@@ -38,7 +38,7 @@ const presetTheme = new ThemeAspect({

              oldStylesheet.remove();
            },
-            { behavior: 'smooth' },
+            { behavior: 'smooth', ...options },
          );
        },
        { once: true },
@@ -47,18 +47,6 @@ const presetTheme = new ThemeAspect({
  },
 });

-/**
- * Without this, there's a flash of the incorrect preset theme.
- */
-function updateSelectionBeforeTurboLoad(e) {
-  const newElement = e.detail.newBody || e.detail.newFrame || e.detail.newStream;
-  if (newElement) {
-    presetTheme.syncUI(newElement);
-  }
-}
-
-['turbo:before-render', 'turbo:before-stream-render', 'turbo:before-frame-render'].forEach(eventName => {
-  document.addEventListener(eventName, updateSelectionBeforeTurboLoad);
+window.addEventListener('turbo:render', e => {
+  presetTheme.applyChange({ behavior: 'instant' });
 });
-
-window.presetTheme = presetTheme;
--- a/docs/assets/scripts/search.js
+++ b/docs/assets/scripts/search.js
@@ -9,6 +9,7 @@ const icons = {
  component: 'puzzle-piece',
  document: 'file',
  home: 'house',
+  native: 'code',
  theme: 'palette',
 };
 let searchTimeout;
@@ -166,6 +167,7 @@ async function updateResults(query = '') {
      li.setAttribute('data-selected', index === 0 ? 'true' : 'false');

      if (page.url === '/') icon = icons.home;
+      if (page.url.startsWith('/docs/native')) icon = icons.native;
      if (page.url.startsWith('/docs/components')) icon = icons.component;
      if (page.url.startsWith('/docs/theme') || page.url.startsWith('/docs/restyle')) icon = icons.theme;

--- a/docs/assets/scripts/theme-picker.js
+++ b/docs/assets/scripts/theme-picker.js
@@ -28,12 +28,21 @@ export class ThemeAspect {
    });

    // Listen for selections
-    document.addEventListener('wa-change', event => {
+    document.addEventListener('change', event => {
      const picker = event.target.closest(this.picker);
      if (picker) {
        this.set(picker.value);
      }
    });
+
+    ['turbo:before-render', 'turbo:before-stream-render', 'turbo:before-frame-render'].forEach(eventName => {
+      document.addEventListener(eventName, e => {
+        const newElement = e.detail.newBody || e.detail.newFrame || e.detail.newStream;
+        if (newElement) {
+          this.syncUI(newElement);
+        }
+      });
+    });
  }

  get() {
@@ -91,11 +100,6 @@ const colorScheme = new ThemeAspect({
    domChange(() => {
      let dark = this.computedValue === 'dark';
      document.documentElement.classList.toggle(`wa-dark`, dark);
-
-      for (let el of document.querySelectorAll('.wa-invert')) {
-        el.classList.toggle('wa-dark', !dark);
-        el.classList.toggle('wa-light', dark);
-      }
    });
  },
 });
--- a/docs/assets/styles/code-highlighter.css
+++ b/docs/assets/styles/code-highlighter.css
@@ -1,6 +1,12 @@
 pre {
  background-color: var(--wa-color-gray-20);
  color: white;
+
+  /* Ensures a discernible background color in dark mode
+   * Useful for themes that use gray-20 as --wa-color-surface-default  */
+  .wa-dark & {
+    background-color: var(--wa-color-surface-lowered);
+  }
 }
 .code-comment,
 .code-prolog,
--- a/docs/assets/styles/docs.css
+++ b/docs/assets/styles/docs.css
@@ -333,6 +333,7 @@ wa-page > main:has(> .index-grid) {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(22ch, 100%), 1fr));
  gap: var(--wa-space-2xl);
+  margin-block-end: var(--wa-space-3xl);

  a {
    border-radius: var(--wa-border-radius-l);
@@ -382,15 +383,79 @@ wa-page > main:has(> .index-grid) {

 /* Swatches */
 .swatch {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
  background-color: transparent;
  border-color: var(--wa-color-neutral-border-normal);
  border-style: var(--wa-border-style);
  border-width: var(--wa-border-width-s);
  border-radius: var(--wa-border-radius-m);
  box-sizing: border-box;
-  line-height: 2.5;
-  height: 2.5em;
-  padding-inline: var(--wa-space-xs);
+  min-height: 2.5em;
+  padding: var(--wa-space-xs);
+  font-weight: var(--wa-font-weight-semibold);
+  line-height: var(--wa-line-height-condensed);
+
+  &.color {
+    border-color: transparent;
+  }
+
+  wa-copy-button {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    display: block;
+    --background-color-hover: transparent;
+    font-family: var(--wa-font-family-code);
+
+    &::part(button) {
+      display: block;
+      height: 100%;
+      width: 100%;
+    }
+
+    &::part(button):hover {
+      cursor: copy;
+    }
+
+    &::part(copy-icon),
+    &::part(success-icon),
+    &::part(error-icon) {
+      opacity: 0 !important;
+    }
+  }
+}
+
+table.colors {
+  thead {
+    th {
+      text-align: center;
+      padding-block: 0;
+    }
+  }
+  tbody {
+    tr {
+      border: none;
+      &:hover {
+        background: transparent;
+      }
+    }
+
+    th {
+      width: 0;
+      vertical-align: middle;
+      text-align: right;
+    }
+
+    td {
+      padding-inline: var(--wa-space-3xs);
+      padding-block: var(--wa-space-s);
+    }
+  }
 }

 /* Layout Examples */
@@ -456,7 +521,7 @@ wa-page > main:has(> .index-grid) {
  }
 }

-.layout-theme {
+.page-wide {
  wa-page > main {
    max-width: 140ch;

@@ -464,7 +529,9 @@ wa-page > main:has(> .index-grid) {
      max-width: 80ch;
    }
  }
+}

+.layout-theme {
  iframe {
    width: 100%;
    min-height: 16lh;
--- a/docs/docs/components/animation.md
+++ b/docs/docs/components/animation.md
@@ -77,9 +77,9 @@ This example demonstrates all of the baked-in animations and easings. Animations
    easingName.appendChild(option);
  });

-  animationName.addEventListener('wa-change', () => (animation.name = animationName.value));
-  easingName.addEventListener('wa-change', () => (animation.easing = easingName.value));
-  playbackRate.addEventListener('wa-input', () => (animation.playbackRate = playbackRate.value));
+  animationName.addEventListener('change', () => (animation.name = animationName.value));
+  easingName.addEventListener('change', () => (animation.easing = easingName.value));
+  playbackRate.addEventListener('input', () => (animation.playbackRate = playbackRate.value));
 </script>

 <style>
--- a/docs/docs/components/callout.md
+++ b/docs/docs/components/callout.md
@@ -3,6 +3,7 @@ title: Callout
 description: Callouts are used to display important messages inline.
 tags: [feedback, content]
 icon: callout
+native: callout
 ---

 ```html {.example}
--- a/docs/docs/components/carousel.md
+++ b/docs/docs/components/carousel.md
@@ -249,7 +249,7 @@ This example is best demonstrated using a mouse. Try clicking and dragging the s
  const carousel = container.querySelector('wa-carousel');
  const toggle = container.querySelector('wa-switch');

-  toggle.addEventListener('wa-change', () => {
+  toggle.addEventListener('change', () => {
    carousel.toggleAttribute('mouse-dragging', toggle.checked);
  });
 </script>
@@ -450,7 +450,7 @@ Use the `--aspect-ratio` custom property to customize the size of the carousel's
    const carousel = document.querySelector('wa-carousel.aspect-ratio');
    const aspectRatio = document.querySelector('wa-select[name="aspect"]');

-    aspectRatio.addEventListener('wa-change', () => {
+    aspectRatio.addEventlistener('change', () => {
      carousel.style.setProperty('--aspect-ratio', aspectRatio.value);
    });
  })();
--- a/docs/docs/components/cheatsheet/cheatsheet.js
+++ b/docs/docs/components/cheatsheet/cheatsheet.js
@@ -73,4 +73,4 @@ if (name_search.value) {
  filterByName(name_search.value);
 }

-name_search_group.addEventListener('wa-input', e => filterByName(name_search.value));
+name_search_group.addEventListener('input', e => filterByName(name_search.value));
--- a/docs/docs/components/checkbox.md
+++ b/docs/docs/components/checkbox.md
@@ -82,7 +82,7 @@ Use the `setCustomValidity()` method to set a custom validation message. This wi
  });

  // Update validity on change
-  checkbox.addEventListener('wa-change', () => {
+  checkbox.addEventlistener('change', () => {
    checkbox.setCustomValidity(checkbox.checked ? '' : errorMessage);
  });

--- a/docs/docs/components/format-bytes.md
+++ b/docs/docs/components/format-bytes.md
@@ -16,7 +16,7 @@ icon: format-bytes
  const formatter = container.querySelector('wa-format-bytes');
  const input = container.querySelector('wa-input');

-  input.addEventListener('wa-input', () => (formatter.value = input.value || 0));
+  input.addEventListener('input', () => (formatter.value = input.value || 0));
 </script>
 ```

--- a/docs/docs/components/format-number.md
+++ b/docs/docs/components/format-number.md
@@ -19,7 +19,7 @@ Localization is handled by the browser's [`Intl.NumberFormat` API](https://devel
  const formatter = container.querySelector('wa-format-number');
  const input = container.querySelector('wa-input');

-  input.addEventListener('wa-input', () => (formatter.value = input.value || 0));
+  input.addEventListener('input', () => (formatter.value = input.value || 0));
 </script>
 ```

--- a/docs/docs/components/popup.md
+++ b/docs/docs/components/popup.md
@@ -54,11 +54,11 @@ Popup is a low-level utility built specifically for positioning elements. Do not
  const active = container.querySelector('wa-switch[name="active"]');
  const arrow = container.querySelector('wa-switch[name="arrow"]');

-  select.addEventListener('wa-change', () => (popup.placement = select.value));
-  distance.addEventListener('wa-input', () => (popup.distance = distance.value));
-  skidding.addEventListener('wa-input', () => (popup.skidding = skidding.value));
-  active.addEventListener('wa-change', () => (popup.active = active.checked));
-  arrow.addEventListener('wa-change', () => (popup.arrow = arrow.checked));
+  select.addEventListener('change', () => (popup.placement = select.value));
+  distance.addEventListener('input', () => (popup.distance = distance.value));
+  skidding.addEventListener('input', () => (popup.skidding = skidding.value));
+  active.addEventListener('change', () => (popup.active = active.checked));
+  arrow.addEventListener('change', () => (popup.arrow = arrow.checked));
 </script>

 <style>
@@ -145,7 +145,7 @@ Popups are inactive and hidden until the `active` attribute is applied. Removing
  const popup = container.querySelector('wa-popup');
  const active = container.querySelector('wa-switch');

-  active.addEventListener('wa-change', () => (popup.active = active.checked));
+  active.addEventListener('change', () => (popup.active = active.checked));
 </script>
 ```

@@ -233,7 +233,7 @@ Since placement is preferred when using `flip`, you can observe the popup's curr
  const popup = container.querySelector('wa-popup');
  const select = container.querySelector('wa-select');

-  select.addEventListener('wa-change', () => (popup.placement = select.value));
+  select.addEventListener('change', () => (popup.placement = select.value));
 </script>
 ```

@@ -277,7 +277,7 @@ Use the `distance` attribute to change the distance between the popup and its an
  const popup = container.querySelector('wa-popup');
  const distance = container.querySelector('wa-slider');

-  distance.addEventListener('wa-input', () => (popup.distance = distance.value));
+  distance.addEventListener('input', () => (popup.distance = distance.value));
 </script>
 ```

@@ -321,7 +321,7 @@ The `skidding` attribute is similar to `distance`, but instead allows you to off
  const popup = container.querySelector('wa-popup');
  const skidding = container.querySelector('wa-slider');

-  skidding.addEventListener('wa-input', () => (popup.skidding = skidding.value));
+  skidding.addEventListener('input', () => (popup.skidding = skidding.value));
 </script>
 ```

@@ -409,9 +409,9 @@ By default, the arrow will be aligned as close to the center of the _anchor_ as
    const arrowPlacement = container.querySelector('[name="arrow-placement"]');
    const arrow = container.querySelector('[name="arrow"]');

-    placement.addEventListener('wa-change', () => (popup.placement = placement.value));
-    arrowPlacement.addEventListener('wa-change', () => (popup.arrowPlacement = arrowPlacement.value));
-    arrow.addEventListener('wa-change', () => (popup.arrow = arrow.checked));
+    placement.addEventListener('change', () => (popup.placement = placement.value));
+    arrowPlacement.addEventListener('change', () => (popup.arrowPlacement = arrowPlacement.value));
+    arrow.addEventListener('change', () => (popup.arrow = arrow.checked));
  </script>
 </div>
 ```
@@ -464,7 +464,7 @@ Use the `sync` attribute to make the popup the same width or height as the ancho
  const fixed = container.querySelector('wa-switch');
  const sync = container.querySelector('wa-select');

-  sync.addEventListener('wa-change', () => (popup.sync = sync.value));
+  sync.addEventListener('change', () => (popup.sync = sync.value));
 </script>
 ```

@@ -523,7 +523,7 @@ Toggle the switch and scroll the container to see the difference.
  const popup = container.querySelector('wa-popup');
  const fixed = container.querySelector('wa-switch');

-  fixed.addEventListener('wa-change', () => (popup.strategy = fixed.checked ? 'fixed' : 'absolute'));
+  fixed.addEventListener('change', () => (popup.strategy = fixed.checked ? 'fixed' : 'absolute'));
 </script>
 ```

@@ -575,7 +575,7 @@ Scroll the container to see how the popup flips to prevent clipping.
  const popup = container.querySelector('wa-popup');
  const flip = container.querySelector('wa-switch');

-  flip.addEventListener('wa-change', () => (popup.flip = flip.checked));
+  flip.addEventListener('change', () => (popup.flip = flip.checked));
 </script>
 ```

@@ -670,7 +670,7 @@ Toggle the switch to see the difference.
  const popup = container.querySelector('wa-popup');
  const shift = container.querySelector('wa-switch');

-  shift.addEventListener('wa-change', () => (popup.shift = shift.checked));
+  shift.addEventListener('change', () => (popup.shift = shift.checked));
 </script>
 ```

@@ -731,7 +731,7 @@ Scroll the container to see the popup resize as its available space changes.
  const popup = container.querySelector('wa-popup');
  const autoSize = container.querySelector('wa-switch');

-  autoSize.addEventListener('wa-change', () => (popup.autoSize = autoSize.checked ? 'both' : ''));
+  autoSize.addEventListener('change', () => (popup.autoSize = autoSize.checked ? 'both' : ''));
 </script>
 ```

@@ -782,9 +782,9 @@ When a gap exists between the anchor and the popup element, this option will add
  const hoverBridge = container.querySelector('wa-switch');
  const distance = container.querySelector('wa-slider[label="Distance"]');
  const skidding = container.querySelector('wa-slider[label="Skidding"]');
-  distance.addEventListener('wa-input', () => (popup.distance = distance.value));
-  skidding.addEventListener('wa-input', () => (popup.skidding = skidding.value));
-  hoverBridge.addEventListener('wa-change', () => (popup.hoverBridge = hoverBridge.checked));
+  distance.addEventListener('input', () => (popup.distance = distance.value));
+  skidding.addEventListener('input', () => (popup.skidding = skidding.value));
+  hoverBridge.addEventListener('change', () => (popup.hoverBridge = hoverBridge.checked));
 </script>
 ```

@@ -837,7 +837,7 @@ This example anchors a popup to the mouse cursor using a virtual element. As suc
  };

  // Only activate the popup when the switch is checked
-  enabled.addEventListener('wa-change', () => {
+  enabled.addEventListener('change', () => {
    popup.active = enabled.checked;
  });

--- a/docs/docs/components/qr-code.md
+++ b/docs/docs/components/qr-code.md
@@ -24,7 +24,7 @@ QR codes are useful for providing small pieces of information to users who can q

  customElements.whenDefined('wa-qr-code').then(() => {
    input.value = qrCode.value;
-    input.addEventListener('wa-input', () => (qrCode.value = input.value));
+    input.addEventListener('input', () => (qrCode.value = input.value));
  });
 </script>

--- a/docs/docs/components/radio-group.md
+++ b/docs/docs/components/radio-group.md
@@ -65,7 +65,7 @@ The size of [Radios](/docs/components/radio) and [Radio Buttons](/docs/component
 <script>
  const radioGroup = document.querySelector('.radio-group-size');

-  radioGroup.addEventListener('wa-change', () => {
+  radioGroup.addEventlistener('change', () => {
    radioGroup.size = radioGroup.value;
  });
 </script>
@@ -127,7 +127,7 @@ Use the `setCustomValidity()` method to set a custom validation message. This wi
  });

  // Update validity when a selection is made
-  form.addEventListener('wa-change', () => {
+  form.addEventlistener('change', () => {
    const isValid = radioGroup.value === '3';
    radioGroup.setCustomValidity(isValid ? '' : errorMessage);
  });
--- a/docs/docs/components/select.md
+++ b/docs/docs/components/select.md
@@ -420,5 +420,7 @@ This can be hard to conceptualize, so heres a fairly large example showing how l
  //
  // TODO - remove once we switch to the Popover API
  //
-  document.querySelectorAll('wa-code-demo [slot="preview"] wa-select').forEach(select => select.hoist = true);
+  customElements.whenDefined('wa-select').then(() => {
+    document.querySelectorAll('wa-code-demo [slot="preview"] wa-select').forEach(select => select.hoist = true);
+  });
 </script>
--- a/docs/docs/components/split-panel.md
+++ b/docs/docs/components/split-panel.md
@@ -208,7 +208,7 @@ Try resizing the example below with each option and notice how the panels respon
  const splitPanel = container.querySelector('wa-split-panel');
  const select = container.querySelector('wa-select');

-  select.addEventListener('wa-change', () => (splitPanel.primary = select.value));
+  select.addEventlistener('change', () => (splitPanel.primary = select.value));
 </script>
 ```

--- a/docs/docs/components/tree.md
+++ b/docs/docs/components/tree.md
@@ -88,7 +88,7 @@ The `selection` attribute lets you change the selection behavior of the tree.
  const selectionMode = document.querySelector('#selection-mode');
  const tree = document.querySelector('.tree-selectable');

-  selectionMode.addEventListener('wa-change', () => {
+  selectionMode.addEventlistener('change', () => {
    tree.querySelectorAll('wa-tree-item').forEach(item => (item.selected = false));
    tree.selection = selectionMode.value;
  });
--- a/docs/docs/customizing.md
+++ b/docs/docs/customizing.md
@@ -12,7 +12,7 @@ Web Awesome uses numerous CSS custom properties that make up a high-level themin

 Because these custom properties live at the page level, they're prefixed with `--wa-` to avoid collisions with other libraries or your own custom properties.

-To customize a theme, simply override any of these custom properties in your own stylesheet by scoping your styles to `:root`, `:host`, and, if needed, the class for the specific theme you want to override. Here's an example that changes the default brand color (blue) to violet in the light theme using existing [literal colors](/docs/theming/color/#literal-colors).
+To customize a theme, simply override any of these custom properties in your own stylesheet by scoping your styles to `:root`, `:host`, and, if needed, the class for the specific theme you want to override. Here's an example that changes the default brand color (blue) to violet in the light theme using existing [literal colors](/docs/tokens/color/#literal-colors).

 ```css
 :where(:root),
--- a/docs/docs/experimental/themer.md
+++ b/docs/docs/experimental/themer.md
@@ -506,7 +506,7 @@ hasOutline: false
      <wa-option data-alpha="remove" value="playful">Playful</wa-option>
      <wa-option data-alpha="remove" value="brutalist">Brutalist</wa-option>
      <wa-option data-alpha="remove" value="tailspin">Tailspin</wa-option>
-      <wa-option data-alpha="remove" value="glassy">Glassy</wa-option>
+      <wa-option data-alpha="remove" value="glossy">Glossy</wa-option>
      <wa-option data-alpha="remove" value="active">Active</wa-option>
      <wa-option value="classic">Classic</wa-option>
    </wa-select>
@@ -803,7 +803,7 @@ hasOutline: false
  const queue = [];
  let inputTimeout;

-  variantInput.addEventListener('wa-change', () => {
+  variantInput.addEventlistener('change', () => {
    iconList.dataset.variant = variantInput.value;
  });

@@ -823,7 +823,7 @@ hasOutline: false
  });

  // Filter as the user types
-  input.addEventListener('wa-input', () => {
+  input.addEventListener('input', () => {
    clearTimeout(inputTimeout);
    inputTimeout = setTimeout(() => {
      [...iconList.children].map(item => {
@@ -886,7 +886,7 @@ hasOutline: false
      case 'active':
        colorPalette = 'rudimentary';
        break;
-      case 'glassy':
+      case 'glossy':
        colorPalette = 'elegant';
        break;
      case 'premium':
@@ -1049,7 +1049,7 @@ hasOutline: false
      case 'brutalist':
      case 'classic':
      case 'awesome':
-      case 'glassy':
+      case 'glossy':
      case 'active':
        assetFolder = themeSelect.value;
        break;
@@ -1084,10 +1084,10 @@ hasOutline: false
    el.classList.add(`wa-theme-${theme}-${colorMode}`);
  }

-  colorModeSelect.addEventListener('wa-change', setColorMode);
+  colorModeSelect.addEventlistener('change', setColorMode);

  // Theme Switcher
-  themeSelect.addEventListener('wa-change', event => {
+  themeSelect.addEventlistener('change', event => {
    const theme = event.target.value
    const newStylesheet = Object.assign(document.createElement("link"), {
      // This media: "print" allows us to lazy load the stylesheet then hot swap it on load.
@@ -1132,14 +1132,14 @@ hasOutline: false
  });

  // Color Palette
-  colorSelect.addEventListener('wa-change', event => {
+  colorSelect.addEventlistener('change', event => {
    const colorPalette = event.target.value;

    colorStylesheet.href = `/dist/styles/themes/color/${colorPalette}.css`;
  });

  // Brand Color
-  brandColor.addEventListener('wa-change', event => {
+  brandColor.addEventlistener('change', event => {
    const documentStyles = document.documentElement.style
    documentStyles.setProperty('--wa-color-primary-95', `var(--wa-color-${event.target.value}-95)`);
    documentStyles.setProperty('--wa-color-primary-90', `var(--wa-color-${event.target.value}-90)`);
@@ -1223,7 +1223,7 @@ hasOutline: false
  })

  // Pre-generated logos
-  logoSelector.addEventListener('wa-change', event => {
+  logoSelector.addEventlistener('change', event => {
    const value = event.currentTarget.value

    const projectLogo = previewContainer.querySelector("#project-logo");
@@ -1259,7 +1259,7 @@ hasOutline: false
      case 'tailspin':
        presetLogoIcons = ['wind', 'feather', 'lemon', 'wind-turbine'];
        break;
-      case 'glassy':
+      case 'glossy':
        presetLogoIcons = ['raindrops', 'citrus-slice', 'lighthouse', 'kiwi-bird'];
        break;
      case 'active':
@@ -1279,21 +1279,21 @@ hasOutline: false
    })
  }

-  themeSelect.addEventListener('wa-change', setLogoIcons);
+  themeSelect.addEventlistener('change', setLogoIcons);

  // Project Name
-  container.querySelector('[name="project-name"]').addEventListener('wa-input', event => {
+  container.querySelector('[name="project-name"]').addEventListener('input', event => {
    previewContainer.querySelector("#project-name").innerText = event.target.value || event.target.getAttribute("placeholder")
  })

  // Heading font weight
  resetHeadingFontWeightValue()
-  fontWeightHeading.addEventListener('wa-input', event => {
+  fontWeightHeading.addEventListener('input', event => {
    document.documentElement.style.setProperty('--wa-font-weight-heading', event.target.value);
  });

  // Heading text
-  fontFamilyHeading.addEventListener('wa-change', event => {
+  fontFamilyHeading.addEventlistener('change', event => {
    let fontFamily;
    switch (event.target.value) {
      case 'assistant':
@@ -1351,7 +1351,7 @@ hasOutline: false
  })

  // Body text
-  fontFamilyBody.addEventListener('wa-change', event => {
+  fontFamilyBody.addEventlistener('change', event => {
    let fontFamily;
    switch (event.target.value) {
      case 'assistant':
@@ -1404,7 +1404,7 @@ hasOutline: false

  // Body font weight
  resetBodyFontWeightValue()
-  fontWeightBody.addEventListener('wa-input', event => {
+  fontWeightBody.addEventListener('input', event => {
    document.documentElement.style.setProperty('--wa-font-weight-body', event.target.value);
  });

@@ -1580,7 +1580,7 @@ hasOutline: false
  }

  // Swaps icons to the preferred set for the selected theme
-  themeSelect.addEventListener('wa-change', event => {
+  themeSelect.addEventlistener('change', event => {
    setPreferredIcons();
    showIconStyleOptions();
    syncLogoIcon();
@@ -1599,32 +1599,32 @@ hasOutline: false
  });

  // Changes available Icon Styles and swaps icons based on the selected Icon Family
-  iconFamily.addEventListener('wa-change', event => {
+  iconFamily.addEventlistener('change', event => {
    useFaIcons();
    showIconStyleOptions();
  });

  // Swaps icons based on the selected Icon Style
-  iconStyle.addEventListener('wa-change', useFaIcons);
+  iconStyle.addEventlistener('change', useFaIcons);


  // Corners
-  container.querySelector('[name="corners"]').addEventListener('wa-input', event => {
+  container.querySelector('[name="corners"]').addEventListener('input', event => {
    document.documentElement.style.setProperty('--wa-border-radius-scale', `${event.target.value}`);
  });

  // Border width
-  container.querySelector('[name="border-width"]').addEventListener('wa-input', event => {
+  container.querySelector('[name="border-width"]').addEventListener('input', event => {
    document.documentElement.style.setProperty('--wa-border-width-scale', `${event.target.value / 16}`);
  });

  // Border style
-  borderStyle.addEventListener('wa-input', event => {
+  borderStyle.addEventListener('input', event => {
    document.documentElement.style.setProperty('--wa-border-style', event.target.value);
  });

  // Spacing style
-  spacing.addEventListener('wa-input', event => {
+  spacing.addEventListener('input', event => {
    document.documentElement.style.setProperty('--wa-space-scale', `${event.target.value}`);
  });

--- a/docs/docs/form-controls.md
+++ b/docs/docs/form-controls.md
@@ -146,7 +146,7 @@ To create a custom validation error, pass a non-empty string to the `setCustomVa
      alert('All fields are valid!');
    });

-    input.addEventListener('wa-input', () => {
+    input.addEventListener('input', () => {
      if (input.value === 'webawesome') {
        input.setCustomValidity('');
      } else {
--- a/docs/docs/native/button.md
+++ b/docs/docs/native/button.md
@@ -20,7 +20,7 @@ snippets:

 ### Variants

-Use the variant utility classes to set the button's semantic variant.
+Use the [variant utility classes](../utilities/color.md) to set the button's semantic variant.

 ```html {.example}
 <button class="wa-neutral">Neutral</button>
@@ -32,7 +32,7 @@ Use the variant utility classes to set the button's semantic variant.

 ### Appearance

-Use the appearance utility classes to change the button's visual appearance:
+Use the [appearance utility classes](../utilities/appearance.md) to change the button's visual appearance:

 ```html {.example}
 <div style="margin-block-end: 1rem;">
@@ -69,7 +69,7 @@ Use the appearance utility classes to change the button's visual appearance:

 ### Sizes

-Use `wa-size-*` classes to change a button's size.
+Use the [size utility classes](../utilities/size.md) to change a button's size.

 ```html {.example}
 <button class="wa-size-s">Small</button>
--- a/docs/docs/native/callout.md
+++ b/docs/docs/native/callout.md
@@ -0,0 +1,117 @@
+---
+title: Callout
+description: Callouts are used to display important messages inline.
+component: callout
+icon: callout
+snippets: '.wa-callout'
+noAlpha: true
+---
+
+```html {.example}
+<article class="wa-callout">
+  This is a callout style, applied to a standard article element.
+</article>
+```
+
+## Examples
+
+### Variants
+
+Use the [variant utility classes](../utilities/color.md) to set the callout's color variant.
+
+```html {.example}
+<article class="wa-callout wa-brand">
+  <strong>This is super informative</strong><br />
+  You can tell by how pretty the callout is.
+</article>
+
+<br />
+
+<article class="wa-callout wa-success">
+  <strong>Your changes have been saved</strong><br />
+  You can safely exit the app now.
+</article>
+
+<br />
+
+<article class="wa-callout wa-neutral">
+  <strong>Your settings have been updated</strong><br />
+  Settings will take effect on next login.
+</article>
+
+<br />
+
+<article class="wa-callout wa-warning">
+  <strong>Your session has ended</strong><br />
+  Please login again to continue.
+</article>
+
+<br />
+
+<article class="wa-callout wa-danger">
+  <strong>Your account has been deleted</strong><br />
+  We're very sorry to see you go!
+</article>
+```
+
+### Appearance
+
+Use the [appearance utility classes](../utilities/appearance.md) to change the callout's visual appearance (the default is `outlined filled`).
+
+```html {.example}
+<article class="wa-callout wa-brand wa-outlined wa-accent">
+  This <strong>accent</strong> callout is also <strong>outlined</strong>
+</article>
+
+<br />
+
+<article class="wa-callout wa-brand wa-accent">
+  This <strong>accent</strong> callout draws attention without an outline
+</article>
+
+<br />
+
+<article class="wa-callout wa-brand wa-outlined wa-filled">
+  This callout is both <strong>filled</strong> and <strong>outlined</strong>
+</article>
+
+<br />
+
+<article class="wa-callout wa-brand wa-filled">
+  This callout is only <strong>filled</strong>
+</article>
+
+<br />
+
+<article class="wa-callout wa-brand wa-outlined">
+  Here's an <strong>outlined</strong> callout
+</article>
+
+<br />
+
+<article class="wa-callout wa-brand wa-plain">
+  No bells and whistles on this <strong>plain</strong> callout
+</article>
+```
+
+### Sizes
+
+Use the [size utility classes](../utilities/size.md) to change a callout's size.
+
+```html {.example}
+<article class="wa-callout wa-brand wa-outlined wa-accent wa-size-l">
+  This is meant to be very emphasized.
+</article>
+
+<br />
+
+<article class="wa-callout">
+  Normal-sized callout.
+</article>
+
+<br />
+
+<article class="wa-callout wa-plain wa-plain wa-size-s">
+  Just a small tip!
+</article>
+```
--- a/docs/docs/native/select.md
+++ b/docs/docs/native/select.md
@@ -33,3 +33,39 @@ Use the [appearance utilities](/docs/utilities/appearance/) to change the select
  </select>
 </label>
 ```
+
+### Grouping options
+
+In [modern browsers](https://caniuse.com/mdn-html_elements_select_hr_in_select), you can use the `<hr>` element as a divider:
+
+```html {.example}
+<select>
+  <small>Section 1</small>
+  <option value="option-1">Option 1</option>
+  <option value="option-2">Option 2</option>
+  <option value="option-3">Option 3</option>
+  <hr />
+  <small>Section 2</small>
+  <option value="option-4">Option 4</option>
+  <option value="option-5">Option 5</option>
+  <option value="option-6">Option 6</option>
+</select>
+```
+
+To provide labels, you can use the `<optgroup>` element (with or without dividers):
+
+```html {.example}
+<select>
+  <optgroup label="Section 1">
+  <option value="option-1">Option 1</option>
+  <option value="option-2">Option 2</option>
+  <option value="option-3">Option 3</option>
+  </optgroup>
+  <optgroup label="Section 2">
+  <option value="option-4">Option 4</option>
+  <option value="option-5">Option 5</option>
+  <hr />
+  <option value="option-6">Option 6</option>
+  </optgroup>
+</select>
+```
--- a/docs/docs/palettes/anodized.md
+++ b/docs/docs/palettes/anodized.md
@@ -0,0 +1,5 @@
+---
+title: Anodized
+isPro: true
+tags: pro
+---
--- a/docs/docs/palettes/bright.md
+++ b/docs/docs/palettes/bright.md
@@ -0,0 +1,3 @@
+---
+title: Bright
+---
--- a/docs/docs/palettes/classic.md
+++ b/docs/docs/palettes/classic.md
@@ -0,0 +1,4 @@
+---
+title: Classic
+description: The original Shoelace color palette.
+---
--- a/docs/docs/palettes/default.md
+++ b/docs/docs/palettes/default.md
@@ -0,0 +1,4 @@
+---
+title: Default
+description: This is the palette used in the default theme.
+---
--- a/docs/docs/palettes/elegant.md
+++ b/docs/docs/palettes/elegant.md
@@ -0,0 +1,5 @@
+---
+title: Elegant
+isPro: true
+tags: pro
+---
--- a/docs/docs/palettes/index.njk
+++ b/docs/docs/palettes/index.njk
@@ -0,0 +1,10 @@
+---
+title: Color Palettes
+description: Palettes define [literal colors](/docs/tokens/colors) that are used in the design system.
+layout: overview
+override:tags: []
+forTag: palette
+categories:
+  other: Free
+  pro: Pro
+---
--- a/docs/docs/palettes/mild.md
+++ b/docs/docs/palettes/mild.md
@@ -0,0 +1,5 @@
+---
+title: Mild
+isPro: true
+tags: pro
+---
--- a/docs/docs/palettes/natural.md
+++ b/docs/docs/palettes/natural.md
@@ -0,0 +1,5 @@
+---
+title: Natural
+isPro: true
+tags: pro
+---
--- a/docs/docs/palettes/palettes.json
+++ b/docs/docs/palettes/palettes.json
@@ -0,0 +1,8 @@
+{
+  "layout": "palette.njk",
+  "tags": ["palettes", "palette"],
+  "eleventyComputed": {
+    "snippet": ".wa-palette-{{ page.fileSlug }}",
+    "icon": "palette"
+  }
+}
--- a/docs/docs/palettes/rudimentary.md
+++ b/docs/docs/palettes/rudimentary.md
@@ -0,0 +1,5 @@
+---
+title: Rudimentary
+isPro: true
+tags: pro
+---
--- a/docs/docs/palettes/vogue.md
+++ b/docs/docs/palettes/vogue.md
@@ -0,0 +1,5 @@
+---
+title: Vogue
+isPro: true
+tags: pro
+---
--- a/docs/docs/patterns/patterns.json
+++ b/docs/docs/patterns/patterns.json
@@ -1,5 +1,6 @@
 {
  "layout": "block.njk",
  "tags": ["patterns"],
+  "wide": true,
  "noAlpha": true
 }
--- a/docs/docs/resources/changelog.md
+++ b/docs/docs/resources/changelog.md
@@ -12,6 +12,30 @@ Components with the <wa-badge variant="warning" pill>Experimental</wa-badge> bad
 During the alpha period, things might break! We take breaking changes very seriously, but sometimes they're necessary to make the final product that much better. We appreciate your patience!
 :::

+## Next
+
+- 🚨 BREAKING: updated all components to use native events instead of `wa-` prefixed events. This will allow components to work more like native elements in your code, frameworks, third-party plugins, etc. To update your code, simply remove the prefix from your event listeners for the following events.
+  - `wa-input` => `input`
+  - `wa-change` => `change`
+  - `wa-blur` => `blur` (this event will no longer bubble, use `focusout` for a bubbling version)
+  - `wa-focus` => `focus` (this event will no longer bubble)
+- Added `.wa-callout` utility class
+- Fixed a bug in `<wa-tab-group>` that prevented nested tab groups from working properly
+- Fixed slot names for `show-password-icon` and `hide-password-icon` in `<wa-input>` to more intuitively represent their functions
+
+## 3.0.0-alpha.9
+
+- Added new themes:
+  - Glossy
+  - Matter
+  - Premium
+  - Playful
+- Added docs on themes and palettes
+- Separated colors and typography out from themes so they can be used independently
+- Added test suite to ensure all color palettes provide the color contrast they are supposed to
+- Added `.wa-invert` utility class to invert the current color scheme
+- Added `:state(blank)` to `<wa-input>`, `<wa-textarea>`, and `<wa-select>` to style form inputs differently when empty.
+
 ## 3.0.0-alpha.8

 - Simplified the internal structure and CSS properties of `<wa-card>`, removed `base` part.
@@ -30,7 +54,6 @@ During the alpha period, things might break! We take breaking changes very serio
  - Brutalist
  - Mellow
  - Tailspin
-  - Playful
 - Renamed `--wa-form-control-resting-color` to `--wa-form-control-border-color` for familiarity and accuracy
 - Removed size-based `--wa-form-control-height-*` tokens in favor of `--wa-form-control-height` (see [size utilities](/docs/utilities/size/))
 - Updated the `--wa-border-width-*` and `--wa-border-radius-*` scale for better DX
--- a/docs/docs/test/styling.njk
+++ b/docs/docs/test/styling.njk
@@ -1,36 +0,0 @@
---
-title: Styling Tests
---
-
-<h2>Appearance and variant tests</h2>
-
-{% for component in componentsBy.attribute.variant %}
-{%- if component.attributes.appearance -%}
-<h3><a href="../{{ component.url }}"><code>&lt;{{ component.tagName }}&gt;</code></a></h3>
-
-{% set variantValues = component.attributes.variant.type.text | getEnumValues %}
-{% set appearanceValues = component.attributes.appearance.type.text | getEnumValues %}
-
-<table>
-<thead>
-	<tr>
-		<th>Variant</th>
-		{% for appearance in appearanceValues %}
-			<th>{{ appearance }}</th>
-		{%- endfor %}
-	</tr>
-</thead>
-{% for variant in variantValues %}
-<tr>
-	<th>{{ variant }}</th>
-	{% for appearance in appearanceValues %}
-	<td>
-		<{{ component.tagName }} variant={{ variant }} appearance={{ appearance }}>{{ variant }} {{ appearance }}</{{ component.tagName }}>
-	</td>
-	{%- endfor %}
-</tr>
-{%- endfor %}
-</table>
-
-{% endif %}
-{%- endfor %}
--- a/docs/docs/themes/active.md
+++ b/docs/docs/themes/active.md
@@ -3,4 +3,5 @@ title: Active
 description: Energetic and tactile, always in motion.
 isPro: true
 tags: pro
+palette: rudimentary
 ---
--- a/docs/docs/themes/awesome.md
+++ b/docs/docs/themes/awesome.md
@@ -2,4 +2,5 @@
 title: Awesome
 description: Punchy and vibrant, the rockstar of themes.
 order: 0.2
+palette: bright
 ---
--- a/docs/docs/themes/brutalist.md
+++ b/docs/docs/themes/brutalist.md
@@ -3,4 +3,5 @@ title: Brutalist
 description: Sharp, square, and unapologetically bold.
 isPro: true
 tags: pro
+palette: default
 ---
--- a/docs/docs/themes/classic.md
+++ b/docs/docs/themes/classic.md
@@ -2,4 +2,5 @@
 title: Classic
 description: Timeless elegance that never goes out of style.
 order: 0.1
+palette: classic
 ---
--- a/docs/docs/themes/creating.md
+++ b/docs/docs/themes/creating.md
@@ -21,7 +21,8 @@ If you're customizing the default light styles, scope your styles to the followi
 :where(:root),
 :host,
 .wa-theme-default,
-.wa-light {
+.wa-light,
+.wa-dark .wa-invert {
  /* your custom styles here */
 }
 ```
@@ -30,6 +31,7 @@ If you're customizing the default dark styles, scope your styles to the followin

 ```css
 .wa-dark,
+.wa-invert,
 :is(:host-context(.wa-dark)) {
  /* your custom styles here */
 }
--- a/docs/docs/themes/default.md
+++ b/docs/docs/themes/default.md
@@ -2,4 +2,5 @@
 title: Default
 description: Your trusty companion, like a perfectly broken-in pair of jeans.
 order: 0
+palette: default
 ---
--- a/docs/docs/themes/demo.njk
+++ b/docs/docs/themes/demo.njk
@@ -10,12 +10,6 @@ override:tags: []
 eleventyComputed:
  forceTheme: "{{ theme.fileSlug }}"
 ---
-<script>
-  document.getElementById('theme-stylesheet').href = '/dist/styles/themes/{{ theme.fileSlug }}.css';
-</script>
-<script type=module>
-  document.getElementById('theme-stylesheet').href = '/dist/styles/themes/{{ theme.fileSlug }}.css';
-</script>

 <link rel="stylesheet" href="/dist/styles/themes/{{ theme.fileSlug }}.css" />
 <link rel="stylesheet" href="/docs/themes/showcase.css" />
@@ -24,6 +18,11 @@ eleventyComputed:
 <header>
  {% include 'breadcrumbs.njk' %}
  <h1 class="title">{{ theme.data.title }}</h1>
+  <p id="mix_and_match" hidden class="wa-size-s"></p>
+  <wa-button href="/docs/themes/remixed/?base={{ theme.fileSlug }}" class="remix-link" size="small" variant="brand" target="_parent">
+    <wa-icon name="merge"></wa-icon>
+    Remix
+  </wa-button>
  <p>{% include 'status.njk' %}</p>
  <p id="theme-showcase-description">{{ theme.data.description | inlineMarkdown | safe }}</p>
 </header>
@@ -38,3 +37,50 @@ eleventyComputed:
  {{ content | safe }}
 </div>
 </wa-image-comparer>
+
+<script>
+function updateTheme() {
+  let params = new URLSearchParams(window.location.search);
+  let script = document.currentScript;
+  const stylesheetURLs = {
+    color: id => `/dist/styles/themes/${ id }/color.css`,
+    palette: id => `/dist/styles/color/${ id }.css`,
+    typography: id => `/dist/styles/themes/${ id }/typography.css`
+  };
+  const icons = {
+    color: 'palette',
+    palette: 'swatchbook',
+    typography: 'font-case'
+  }
+
+  for (let link of document.querySelectorAll('link.mix-and-match')) {
+    link.remove();
+  }
+
+  let msgs = [];
+
+  for (let name in stylesheetURLs) {
+    if (params.get(name)) {
+      let url = stylesheetURLs[name](params.get(name));
+      script.insertAdjacentHTML('afterend', `<link rel="stylesheet" href="${ url }" class="mix-and-match" />`);
+      let docsURL = (name === 'palette' ? '/docs/palettes/' : '/docs/themes/') + params.get(name) + '/';
+      let title = params.get(name).replace(/^[a-z]/g, c => c.toUpperCase());
+      let icon = icons[name];
+      msgs.push(`<wa-icon name="${icon}" variant="regular"></wa-icon> <a href="${ docsURL }">${ title }</a>`);
+    }
+  }
+
+  let isRemixed = msgs.length > 0;
+  document.documentElement.classList.toggle("remixed", isRemixed);
+
+  for (let p of mix_and_match) {
+    p.hidden = !isRemixed;
+    if (isRemixed) {
+      let icon =
+      p.innerHTML = `<strong><wa-icon name="merge"></wa-icon> Remixed</strong><br> ` + msgs.map(msg => `<wa-badge appearance=outlined>
+        ${ msg }</wa-badge>`).join(' ');
+    }
+  }
+}
+updateTheme();
+</script>
--- a/docs/docs/themes/glassy.md
+++ b/docs/docs/themes/glassy.md
@@ -1,7 +0,0 @@
---
-title: Glassy
-description: Smooth, sleek, and reflective.
-isPro: true
-tags: pro
-noAlpha: true
---
--- a/docs/docs/themes/glossy.md
+++ b/docs/docs/themes/glossy.md
@@ -0,0 +1,7 @@
+---
+title: Glossy
+description: Bustling with plenty of luster and shine.
+isPro: true
+tags: pro
+palette: elegant
+---
--- a/docs/docs/themes/index.njk
+++ b/docs/docs/themes/index.njk
@@ -1,6 +1,6 @@
 ---
 title: Themes
-description: Themes are collections of pre-defined CSS custom properties that thread through every Web Awesome component and pattern.
+description: Themes are collections of predefined CSS custom properties that thread through every Web Awesome component and pattern.
 layout: overview
 override:tags: []
 forTag: theme
@@ -14,7 +14,7 @@ categories:

 ## What's a Theme?

-Themes are a collection of standardized [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) that cover a range of styles from colors to transitions. We use these custom properties throughout Web Awesome components for a cohesive look and feel. Our [Theming pages](/docs/theming/) document these styles so that you can use them freely throughout your project and customize them as needed.
+A theme is a collection of standardized [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*), also called "design tokens," that cover a range of styles from colors to transitions. We use these tokens throughout Web Awesome components for a cohesive look and feel. Our [Design Tokens pages](/docs/tokens/) document these styles so that you can use them freely throughout your project and customize them as needed.

 Themes are scoped to unique classes, such as `wa-theme-default` or `wa-theme-classic`.
 Scoping to unique classes allows you to import multiple themes and use them interchangeably without collisions.
@@ -22,6 +22,7 @@ Please note that if you import multiple themes, the last one will be the default

 Each theme may also include both light and dark color schemes with the classes `wa-light` and `wa-dark`.
 You can use these classes to apply a specific color scheme to an entire page or just a section.
+You can also use `wa-invert` which behaves like `wa-dark` in light mode, and like `wa-light` in dark mode.
 In pre-made themes, we use a light color scheme by default.


@@ -36,11 +37,13 @@ For example, the default theme is set up like this:
 :where(:root),
 :host,
 .wa-theme-default,
-.wa-light {
+.wa-light,
+.wa-dark .wa-invert {
  /* all CSS custom properties for color, typography, space, etc. */
 }

 .wa-dark,
+.wa-invert,
 :host-context(.wa-dark) {
  /* subset of CSS custom properties for a dark color scheme */
 }
--- a/docs/docs/themes/matter.md
+++ b/docs/docs/themes/matter.md
@@ -0,0 +1,85 @@
+---
+title: Matter
+description: Digital design inspired by the real world.
+isPro: true
+tags: pro
+palette: mild
+---
+
+Set the page theme to "{{ title }}" from the top right to preview the following examples.
+
+## Floating Labels
+
+This theme implements "floating labels" for `wa-input`, `wa-textarea`, `wa-select`,
+which makes labels look like placeholders when the input is empty, does not have an actual placeholder, and is not focused.
+
+```html {.example}
+<wa-input label="What is your name?"></wa-input>
+<br>
+<wa-input label="What is your name?" appearance="filled"></wa-input>
+```
+
+## Ripple Effect
+
+This theme implements a ripple effect for buttons, including native buttons.
+Click on the following buttons to observe it:
+
+```html {.example}
+<wa-button variant="brand">Button</wa-button>
+<button class="wa-brand">Button</button>
+```
+
+
+
+### Customization
+
+You can use several properties to customize the ripple effect.
+
+These properties can be set on any ancestor, including the root element:
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--wa-ripple-start-radius` | `<length>` | `0.1em` | The starting radius of the ripple effect. |
+| `--wa-ripple-start-opacity` | `<number>` | `0.1` | The starting opacity of the ripple effect. |
+| `--wa-ripple-duration` | `<time>` | `calc(2 * var(--wa-transition-slow))` | The duration of the ripple effect transition. |
+
+Any of these can be used to disable the ripple effect:
+
+```css
+--wa-ripple-start-radius: 0em;
+```
+```css
+--wa-ripple-start-opacity: 0;
+```
+```css
+--wa-ripple-duration: 0s;
+```
+
+These properties would only work on the button itself:
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--wa-ripple-center-x` | `<percentage>` | `50%` | The x-coordinate of the ripple center point as a percentage of the button width. |
+| `--wa-ripple-center-y` | `<percentage>` | `50%` | The y-coordinate of the ripple center point as a percentage of the button height. |
+
+### Ripple Center Point
+
+By default the ripple effect starts from the center of the button.
+If you want it to start from the position the button was clicked, you can use this JS snippet:
+
+```js
+document.addEventListener("mousedown", evt => {
+	let target = evt.target;
+
+	if (!target.matches?.('wa-button, button, .wa-button')) {
+		return;
+	}
+
+	let rect = target.getBoundingClientRect();
+	let x = (evt.clientX - rect.left) / rect.width;
+	let y = (evt.clientY - rect.top) / rect.height;
+
+	target.style.setProperty("--mouse-local-x", x);
+	target.style.setProperty("--mouse-local-y", y);
+});
+```
--- a/docs/docs/themes/mellow.md
+++ b/docs/docs/themes/mellow.md
@@ -3,4 +3,5 @@ title: Mellow
 description: Soft and soothing, like a lazy Sunday morning.
 isPro: true
 tags: pro
+palette: natural
 ---
--- a/docs/docs/themes/playful.md
+++ b/docs/docs/themes/playful.md
@@ -1,7 +1,7 @@
 ---
 title: Playful
-description: Fun, colorful, and full of personality.
+description: Cheerful and engaging, like a playground on screen.
 isPro: true
 tags: pro
-noAlpha: true
+palette: rudimentary
 ---
--- a/docs/docs/themes/premium.md
+++ b/docs/docs/themes/premium.md
@@ -3,5 +3,5 @@ title: Premium
 description: The ultimate in sophistication and style.
 isPro: true
 tags: pro
-noAlpha: true
+palette: anodized
 ---
--- a/docs/docs/themes/remixed/index.js
+++ b/docs/docs/themes/remixed/index.js
@@ -0,0 +1,138 @@
+let params = { base: 'default', palette: '', color: '', typography: '' };
+
+// Find usage code snippet and prepare it
+let snippets = document.querySelectorAll('#remixed-usage ~ wa-tab-group pre > code');
+let copyButtons = document.querySelectorAll('#remixed-usage ~ wa-tab-group pre > wa-copy-button');
+let codeExamples = [];
+
+for (let snippet of snippets) {
+  let tokens = [...snippet.children];
+  let base = tokens.shift();
+  let [palette, color, typography] = tokens;
+
+  codeExamples.push({ snippet, base, palette, color, typography });
+
+  // Remove non-base tokens
+  for (let token of tokens) {
+    let whitespace = token.previousSibling;
+
+    if (whitespace.nodeType === Node.TEXT_NODE) {
+      // Move whitespace to beginning of node
+      token.prepend(token.previousSibling);
+    }
+  }
+}
+
+// Read URL params and apply them. This facilitates permalinks.
+if (location.search) {
+  let urlParams = new URLSearchParams(location.search);
+
+  for (let aspect in params) {
+    if (urlParams.has(aspect)) {
+      params[aspect] = urlParams.get(aspect);
+    }
+  }
+}
+
+const selects = Object.fromEntries(
+  [...document.querySelectorAll('#mix_and_match wa-select')].map(select => [select.getAttribute('name'), select]),
+);
+
+document.querySelector('#mix_and_match').addEventListener(
+  'change',
+  function (event) {
+    for (let name in selects) {
+      params[name] = selects[name].value;
+    }
+
+    render();
+  },
+  { capture: true },
+);
+
+function hasOverride(name) {
+  if (!params[name]) {
+    return false;
+  }
+
+  if (name === 'palette') {
+    return params[name] !== defaultPalettes[params.base];
+  }
+
+  if (name !== 'base') {
+    return params[name] !== params.base;
+  }
+
+  return true;
+}
+
+function render() {
+  let demoUrl = new URL(`/docs/themes/${params.base}/demo.html`, location);
+  let pageParams = new URLSearchParams(params);
+
+  for (let aspect in params) {
+    if (aspect !== 'base' && params[aspect]) {
+      demoUrl.searchParams.set(aspect, params[aspect]);
+    }
+
+    if (!params[aspect] || (aspect === 'base' && params[aspect] === 'default') || !hasOverride(aspect)) {
+      pageParams.delete(aspect);
+    }
+
+    // Output code snippet
+    if (aspect !== 'base') {
+      for (let codeExample of codeExamples) {
+        let token = codeExample[aspect];
+        let value = params[aspect];
+
+        if (hasOverride(aspect)) {
+          // Update code example
+          let valueToken = [...token.querySelectorAll('.code-attr-value, .code-url')].pop();
+          valueToken.textContent = replaceStyleSheetURL(valueToken.textContent, aspect, value);
+
+          // Add code example to <pre>
+          codeExample.snippet.append(token);
+        } else {
+          token.remove();
+        }
+      }
+    }
+
+    // Update selects
+    if (selects[aspect].value === undefined) {
+      selects[aspect].setAttribute('value', params[aspect]);
+    } else {
+      selects[aspect].value = params[aspect];
+    }
+  }
+
+  // Update code snippet copy buttons
+  for (let copyButton of copyButtons) {
+    copyButton.value = copyButton.nextElementSibling.textContent;
+  }
+
+  // Update demo URL
+  demo.src = demoUrl;
+
+  // Update page URL. If there’s already a search, replace it.
+  // We don’t want to clog the user’s history while they iterate
+  let historyAction = location.search ? 'replaceState' : 'pushState';
+  history[historyAction](null, '', `?${pageParams}`);
+}
+
+const regexes = {
+  base: /\/themes\/([a-z-]+)\.css/,
+  palette: /\/color\/([a-z-]+)\.css/,
+  color: /\/themes\/([a-z-]+)\/color\.css/,
+  typography: /\/themes\/([a-z-]+)\/typography\.css/,
+};
+
+function replaceStyleSheetURL(url, name, value) {
+  let regex = regexes[name];
+  return url.replace(regex, (match, oldValue) => {
+    return match.replace(oldValue, value);
+  });
+}
+
+globalThis.params = params;
+render();
--- a/docs/docs/themes/remixed/index.njk
+++ b/docs/docs/themes/remixed/index.njk
@@ -0,0 +1,84 @@
+---
+title: Remixed
+description: TODO
+isPro: true
+tags: pro
+---
+<link rel="stylesheet" href="{{ page.url }}/style.css">
+{% block header %}
+<script>
+globalThis.defaultPalettes = {
+  {% for theme in collections.theme | sort -%}
+    "{{ theme.fileSlug }}": "{{ theme.data.palette }}",
+  {%- endfor %}
+};
+</script>
+<p id="mix_and_match" class="wa-gap-m">
+  {# <strong>
+    <wa-icon name="merge" slot="prefix"></wa-icon>
+    Remix
+    <wa-icon-button href="#remixing" name="circle-question" slot="suffix" variant="regular" label="How to use?"></wa-icon-button>
+  </strong> #}
+  <wa-select name="base" label="Base:" size="small" value="default">
+    <wa-icon name="brush" slot="prefix" variant="regular"></wa-icon>
+    {% for theme in collections.theme | sort %}
+      {% if theme.fileSlug !== page.fileSlug %}
+      <wa-option value="{{ theme.fileSlug }}" data-palette="{{ theme.data.palette }}">{{ theme.data.title }}</wa-option>
+      {% endif %}
+    {% endfor %}
+  </wa-select>
+
+  <wa-select name="palette" label="Palette" size="small">
+    <wa-icon name="swatchbook" slot="prefix" variant="regular"></wa-icon>
+    <wa-option value="">(Theme default)</wa-option>
+    <wa-divider></wa-divider>
+    {% for p in collections.palette | sort %}
+      <wa-option value="{{ p.fileSlug }}">{{ p.data.title }}</wa-option>
+    {% endfor %}
+  </wa-select>
+
+  <wa-select name="color" label="Colors from…" size="small" value="">
+    <wa-icon name="palette" slot="prefix" variant="regular"></wa-icon>
+    <wa-option value="">(Theme default)</wa-option>
+    <wa-divider></wa-divider>
+    {% for theme in collections.theme | sort %}
+      <wa-option value="{{ theme.fileSlug }}">{{ theme.data.title }}</wa-option>
+    {% endfor %}
+  </wa-select>
+
+  <wa-select name="typography" label="Typography from…" size="small" value="">
+    <wa-icon name="font-case" slot="prefix"></wa-icon>
+    <wa-option value="">(Theme default)</wa-option>
+    <wa-divider></wa-divider>
+    {% for theme in collections.theme | sort %}
+      <wa-option value="{{ theme.fileSlug }}">{{ theme.data.title }}</wa-option>
+    {% endfor %}
+  </wa-select>
+</p>
+<script src="{{ page.url }}index.js" type="module"></script>
+
+<wa-callout variant="warning">
+  <wa-icon slot="icon" name="triangle-exclamation" variant="regular"></wa-icon>
+  Please note that not all combinations will look good — once you’re mixing and matching, you’re on your own!
+</wa-callout>
+{% endblock %}
+
+{% block afterContent %}
+{% markdown %}
+
+## How to use your remixed theme { #remixed-usage }
+
+You can import your remixed theme by importing the individual theme files from the Web Awesome CDN.
+{# Note: If you change the order here, you need to update index.js too #}
+{% set stylesheets = [
+  'styles/themes/default.css',
+  'styles/color/default.css',
+  'styles/themes/default/color.css',
+  'styles/themes/default/typography.css'
+] %}
+{% set stylesheet = 'styles/themes/default/color.css' %}
+{% include 'import-stylesheet-code.md.njk' %}
+
+
+{% endmarkdown %}
+{% endblock %}
--- a/docs/docs/themes/remixed/style.css
+++ b/docs/docs/themes/remixed/style.css
@@ -0,0 +1,18 @@
+#mix_and_match {
+  strong {
+    display: flex;
+    align-items: center;
+    gap: var(--wa-space-2xs);
+    margin-top: 1.2em;
+  }
+
+  wa-select::part(label) {
+    margin-block-end: 0;
+  }
+
+  wa-select[value='']::part(display-input),
+  wa-option[value=''] {
+    font-style: italic;
+    color: var(--wa-color-text-quiet);
+  }
+}
--- a/docs/docs/themes/showcase.css
+++ b/docs/docs/themes/showcase.css
@@ -9,7 +9,29 @@ body,
  overflow: hidden;
 }

+html.remixed {
+  .remix-link {
+    display: none;
+  }
+}
+
+html:not(.remixed) {
+  #mix_and_match {
+    display: none;
+  }
+}
+
+#mix_and_match {
+  font-weight: var(--wa-font-weight-semibold);
+  color: var(--wa-color-text-quiet);
+
+  wa-icon {
+    vertical-align: middle;
+  }
+}
+
 .theme-showcase {
+  isolation: isolate;
  background-color: var(--wa-color-surface-lowered);
  border-radius: var(--wa-border-radius-l);
  padding: var(--wa-space-xl);
--- a/docs/docs/themes/tailspin.md
+++ b/docs/docs/themes/tailspin.md
@@ -3,4 +3,5 @@ title: Tailspin
 description: Like a bird in flight, guiding you from there to here.
 isPro: true
 tags: pro
+palette: vogue
 ---
--- a/docs/docs/themes/themes.json
+++ b/docs/docs/themes/themes.json
@@ -1,4 +1,5 @@
 {
  "layout": "theme.njk",
+  "wide": true,
  "tags": ["themes", "theme"]
 }
--- a/docs/docs/theming/color.md
+++ b/docs/docs/theming/color.md
@@ -1,599 +0,0 @@
---
-title: Color
-description: Ensure consistent use of color and readable contrast with Web Awesome's color properties.
---
-
-<style>
-  td { vertical-align: middle; }
-
-  .color-name {
-    font-weight: var(--wa-font-weight-semibold);
-    margin-block-end: var(--wa-space-2xs);
-  }
-  ul.color-group {
-    list-style: none;
-    margin: 0;
-    padding: 0;
-  }
-  .color-group {
-    align-items: start;
-    display: flex;
-    flex-wrap: nowrap;
-    gap: 0.25em;
-  }
-  .color-group + * {
-    margin-block-start: var(--wa-space-xl);
-  }
-  .color-preview {
-    flex: 1 1 auto;
-  }
-  .swatch {
-    border-color: transparent;
-  }
-  .color-mix-example {
-    background-image:
-      linear-gradient(to right,
-      color-mix(in oklab, transparent, var(--mix-color)) 25%,
-      color-mix(in oklab, var(--wa-color-brand-fill-loud), var(--mix-color)) 25%,
-      color-mix(in oklab, var(--wa-color-brand-fill-loud), var(--mix-color)) 75%,
-      var(--wa-color-brand-fill-loud) 75%,
-      var(--wa-color-brand-fill-loud))
-    ;
-    border: none;
-    color: var(--wa-color-brand-on-loud);
-    text-align: center;
-  }
-</style>
-
-Web Awesome's color system is made up of CSS custom properties to help with consistent color use throughout your project.
-
-Color is organized by three main categories:
-
- [Literal colors](/#literal-colors) that give familiar names to your starting color palette
- [Foundational colors](/#foundational-colors) that lay the groundwork for your theme
- [Semantic colors](/#semantic-colors) that draw attention and convey meaning
-
-
-## Literal Colors
-
-Literal colors are the lowest level color properties in your theme. Each color is identified by a name, like red or gray, and a number that roughly corresponds to the color's perceived lightness. On this scale, 100 is equal to pure white and 0 is equal to pure black.
-
-Lightness values on this scale have a strong correlation to [relative luminance](https://www.w3.org/WAI/GL/wiki/Relative_luminance), which is used to calculate color contrast. To meet [WCAG 2.1 success criteria for minimum or enhanced contrast](https://www.w3.org/TR/WCAG21/#contrast-minimum), even across hues, calculate the difference between the lightness values of any two colors:
-
- A difference of 40 ensures a minimum 3:1 contrast ratio, suitable for large text and icons (AA)
- A difference of 50 ensures a minimum 4.5:1 contrast ratio, suitable for normal text (AA) and large text (AAA)
- A difference of 60 ensures a minimum 7:1 contrast ratio, suitable for all text (AAA)
-
-Web Awesome defines seven literal colors each with 11 lightness values using the format `--wa-color-{hue}-{tint}`.
-
-<div class="color-name">Red</div>
-<ul class="color-group">
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-red-95)"></div>
-    <small>95</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-red-90)"></div>
-    <small>90</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-red-80)"></div>
-    <small>80</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-red-70)"></div>
-    <small>70</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-red-60)"></div>
-    <small>60</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-red-50)"></div>
-    <small>50</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-red-40)"></div>
-    <small>40</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-red-30)"></div>
-    <small>30</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-red-20)"></div>
-    <small>20</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-red-10)"></div>
-    <small>10</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-red-05)"></div>
-    <small>05</small>
-  </li>
-</ul>
-
-<div class="color-name">Yellow</div>
-<ul class="color-group">
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-yellow-95)"></div>
-    <small>95</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-yellow-90)"></div>
-    <small>90</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-yellow-80)"></div>
-    <small>80</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-yellow-70)"></div>
-    <small>70</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-yellow-60)"></div>
-    <small>60</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-yellow-50)"></div>
-    <small>50</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-yellow-40)"></div>
-    <small>40</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-yellow-30)"></div>
-    <small>30</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-yellow-20)"></div>
-    <small>20</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-yellow-10)"></div>
-    <small>10</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-yellow-05)"></div>
-    <small>05</small>
-  </li>
-</ul>
-
-<div class="color-name">Green</div>
-<ul class="color-group">
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-green-95)"></div>
-    <small>95</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-green-90)"></div>
-    <small>90</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-green-80)"></div>
-    <small>80</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-green-70)"></div>
-    <small>70</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-green-60)"></div>
-    <small>60</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-green-50)"></div>
-    <small>50</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-green-40)"></div>
-    <small>40</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-green-30)"></div>
-    <small>30</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-green-20)"></div>
-    <small>20</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-green-10)"></div>
-    <small>10</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-green-05)"></div>
-    <small>05</small>
-  </li>
-</ul>
-
-<div class="color-name">Teal</div>
-<ul class="color-group">
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-teal-95)"></div>
-    <small>95</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-teal-90)"></div>
-    <small>90</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-teal-80)"></div>
-    <small>80</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-teal-70)"></div>
-    <small>70</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-teal-60)"></div>
-    <small>60</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-teal-50)"></div>
-    <small>50</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-teal-40)"></div>
-    <small>40</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-teal-30)"></div>
-    <small>30</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-teal-20)"></div>
-    <small>20</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-teal-10)"></div>
-    <small>10</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-teal-05)"></div>
-    <small>05</small>
-  </li>
-</ul>
-
-<div class="color-name">Blue</div>
-<ul class="color-group">
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-blue-95)"></div>
-    <small>95</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-blue-90)"></div>
-    <small>90</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-blue-80)"></div>
-    <small>80</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-blue-70)"></div>
-    <small>70</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-blue-60)"></div>
-    <small>60</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-blue-50)"></div>
-    <small>50</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-blue-40)"></div>
-    <small>40</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-blue-30)"></div>
-    <small>30</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-blue-20)"></div>
-    <small>20</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-blue-10)"></div>
-    <small>10</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-blue-05)"></div>
-    <small>05</small>
-  </li>
-</ul>
-
-<div class="color-name">Indigo</div>
-<ul class="color-group">
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-indigo-95)"></div>
-    <small>95</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-indigo-90)"></div>
-    <small>90</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-indigo-80)"></div>
-    <small>80</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-indigo-70)"></div>
-    <small>70</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-indigo-60)"></div>
-    <small>60</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-indigo-50)"></div>
-    <small>50</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-indigo-40)"></div>
-    <small>40</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-indigo-30)"></div>
-    <small>30</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-indigo-20)"></div>
-    <small>20</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-indigo-10)"></div>
-    <small>10</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-indigo-05)"></div>
-    <small>05</small>
-  </li>
-</ul>
-
-<div class="color-name">Violet</div>
-<ul class="color-group">
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-violet-95)"></div>
-    <small>95</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-violet-90)"></div>
-    <small>90</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-violet-80)"></div>
-    <small>80</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-violet-70)"></div>
-    <small>70</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-violet-60)"></div>
-    <small>60</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-violet-50)"></div>
-    <small>50</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-violet-40)"></div>
-    <small>40</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-violet-30)"></div>
-    <small>30</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-violet-20)"></div>
-    <small>20</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-violet-10)"></div>
-    <small>10</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-violet-05)"></div>
-    <small>05</small>
-  </li>
-</ul>
-
-<div class="color-name">Gray</div>
-<ul class="color-group">
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-gray-95)"></div>
-    <small>95</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-gray-90)"></div>
-    <small>90</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-gray-80)"></div>
-    <small>80</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-gray-70)"></div>
-    <small>70</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-gray-60)"></div>
-    <small>60</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-gray-50)"></div>
-    <small>50</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-gray-40)"></div>
-    <small>40</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-gray-30)"></div>
-    <small>30</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-gray-20)"></div>
-    <small>20</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-gray-10)"></div>
-    <small>10</small>
-  </li>
-  <li class="color-preview">
-    <div class="swatch" style="background-color: var(--wa-color-gray-05)"></div>
-    <small>05</small>
-  </li>
-</ul>
-
-## Foundational Colors
-
-Foundational colors lay the groundwork for the content and structure of your project. These colors are named according to their role in your theme.
-
-### Surfaces
-
-Surfaces are background layers that other content rests on. Surface colors help convey hierarchy through a sense of elevation, where `--wa-color-surface-raised` is the closest to the user (e.g., dialogs and popup menus) and `--wa-color-surface-lowered` is the farthest away (e.g., wells).
-
-| Custom Property               | Preview                                                                                                                         |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `--wa-color-surface-raised`   | <div class="swatch" style="background-color: var(--wa-color-surface-raised); box-shadow:var(--wa-shadow-s)"></div>              |
-| `--wa-color-surface-default`  | <div class="swatch" style="background-color: var(--wa-color-surface-default)"></div>                                            |
-| `--wa-color-surface-lowered`  | <div class="swatch" style="background-color: var(--wa-color-surface-lowered); box-shadow: inset var(--wa-shadow-s)"></div>      |
-| `--wa-color-surface-border`   | <div class="swatch" style="border-color: var(--wa-color-surface-border)"></div>                                                 |
-
-### Text
-
-Text colors are used for standard text elements. We recommend a minimum 4.5:1 contrast ratio between text colors and surface colors.
-
-| Custom Property          | Preview                                                    |
-| ------------------------ | ---------------------------------------------------------- |
-| `--wa-color-text-normal` | <div class="swatch" value="--wa-color-text-normal" style="color: var(--wa-color-text-normal); display: inline-block;">AaBb</div> |
-| `--wa-color-text-quiet`  | <div class="swatch" value="--wa-color-text-normal" style="color: var(--wa-color-text-quiet); display: inline-block;">AaBb</div>  |
-| `--wa-color-text-link`   | <div class="swatch" value="--wa-color-text-normal" style="color: var(--wa-color-text-link); display: inline-block;">AaBb</div>   |
-
-### Overlays
-
-Overlays provide a backdrop to isolate content, often allowing background context to show through.
-
-| Custom Property             | Preview                                                                             |
-| --------------------------- | ----------------------------------------------------------------------------------- |
-| `--wa-color-overlay-modal`  | <div class="swatch" style="background-color: var(--wa-color-overlay-modal)"></div>  |
-| `--wa-color-overlay-inline` | <div class="swatch" style="background-color: var(--wa-color-overlay-inline)"></div> |
-
-### Shadow
-
-Web Awesome uses a single color for all shadows. This is used alongside other [shadow properties](/docs/theming/shadows) to construct your theme's shadows.
-
-| Custom Property     | Preview                                                                     |
-| ------------------- | --------------------------------------------------------------------------- |
-| `--wa-color-shadow` | <div class="swatch" style="background-color: var(--wa-color-shadow)"></div> |
-
-### Interactions
-
-#### Focus
-
-Web Awesome uses a single focus color for predictable keyboard navigation. This is used alongside other [focus properties](/docs/theming/focus) to construct `--wa-focus-ring`. We recommend a minimum 3:1 contrast ratio against surface colors and background colors wherever possible.
-
-| Custom Property    | Preview                                                                                                                 |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| `--wa-color-focus` | <div class="swatch" value="--wa-color-focus" style="outline: var(--wa-focus-ring-style) var(--wa-focus-ring-width) var(--wa-color-focus)"></div> |
-
-#### Hover and Active
-
-Web Awesome leverages `color-mix()` to achieve consistent hover and active states across components without the need for untold numbers of handpicked colors. Through `color-mix()`, these custom properties contextually generate hover and active colors based on the color of the component.
-
-| Custom Property         | Preview                                                                                                          |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `--wa-color-mix-hover`  | <div class="swatch color-mix-example" value="--wa-color-mix-hover" style="--mix-color: var(--wa-color-mix-hover)"><small>mixed</small></div>  |
-| `--wa-color-mix-active` | <div class="swatch color-mix-example" value="--wa-color-mix-active" style="--mix-color: var(--wa-color-mix-active)"><small>mixed</small></div> |
-
-
-## Semantic Colors
-
-Semantic colors reinforce a specific message, intended usage, or expected results through familiar, meaningful hues. Each color is identified by its semantic group, role, and attention using the format `--wa-color-{group}-{role}-{attention}`. There are five groups of semantic colors:
- **Brand** to emphasize your brand color
- **Success** for validity or confirmation
- **Neutral** for ordinary or inactive content
- **Warning** for caution or uncertainty
- **Danger** for errors or risk
-
-Each group defines colors for specific roles so that colors can be easily assembled with predictable results and readable contrast. There are three roles:
- **Fill** for background colors or areas larger than a few pixels
- **Border** for borders, dividers, and other stroke-width elements
- **On** for content displayed on a fill (e.g., pair `--wa-color-danger-on-loud` with `--wa-color-danger-fill-loud`)
-
-Finally, each color is named according to how much attention it draws. Here, we use noise as an analogy: a loud noise draws more attention than a quiet one. There are three levels of attention:
- **Quiet** draws the least attention
- **Normal** draws some attention
- **Loud** draws the most attention
-
-| Custom Property              |  <code>brand</code> |  <code>success</code> |  <code>neutral</code> |  <code>warning</code> | <code>danger</code> |
-| ---------------------------- | ------------------- | --------------------- | --------------------- | --------------------- | ------------------- |
-| `--wa-color-*-fill-quiet`    | <div class="swatch" style="background-color: var(--wa-color-brand-fill-quiet)"></div> |  <div class="swatch" style="background-color: var(--wa-color-success-fill-quiet)"></div> | <div class="swatch" style="background-color: var(--wa-color-neutral-fill-quiet)"></div> | <div class="swatch" style="background-color: var(--wa-color-warning-fill-quiet)"></div> | <div class="swatch" style="background-color: var(--wa-color-danger-fill-quiet)"></div> |
-| `--wa-color-*-fill-normal`   | <div class="swatch" style="background-color: var(--wa-color-brand-fill-normal)"></div> | <div class="swatch" style="background-color: var(--wa-color-success-fill-normal)"></div> |<div class="swatch" style="background-color: var(--wa-color-neutral-fill-normal)"></div> | <div class="swatch" style="background-color: var(--wa-color-warning-fill-normal)"></div> | <div class="swatch" style="background-color: var(--wa-color-danger-fill-normal)"></div> |
-| `--wa-color-*-fill-loud`     | <div class="swatch" style="background-color: var(--wa-color-brand-fill-loud)"></div> | <div class="swatch" style="background-color: var(--wa-color-success-fill-loud)"></div> | <div class="swatch" style="background-color: var(--wa-color-neutral-fill-loud)"></div> |  <div class="swatch" style="background-color: var(--wa-color-warning-fill-loud)"></div> |  <div class="swatch" style="background-color: var(--wa-color-danger-fill-loud)"></div> |
-| `--wa-color-*-border-quiet`  | <div class="swatch" value="--wa-color-brand-border-quiet" style="border-color: var(--wa-color-brand-border-quiet)"></div> | <div class="swatch" value="--wa-color-success-border-quiet" style="border-color: var(--wa-color-success-border-quiet)"></div> | <div class="swatch" value="--wa-color-success-border-quiet" style="border-color: var(--wa-color-neutral-border-quiet)"></div> | <div class="swatch" value="--wa-color-warning-border-quiet" style="border-color: var(--wa-color-warning-border-quiet)"></div> | <div class="swatch" value="--wa-color-danger-border-quiet" style="border-color: var(--wa-color-danger-border-quiet)"></div> |
-| `--wa-color-*-border-normal`  | <div class="swatch" value="--wa-color-brand-border-normal" style="border-color: var(--wa-color-brand-border-normal)"></div> | <div class="swatch" value="--wa-color-success-border-normal" style="border-color: var(--wa-color-success-border-normal)"></div> | <div class="swatch" value="--wa-color-success-border-normal" style="border-color: var(--wa-color-neutral-border-normal)"></div> | <div class="swatch" value="--wa-color-warning-border-normal" style="border-color: var(--wa-color-warning-border-normal)"></div> | <div class="swatch" value="--wa-color-danger-border-normal" style="border-color: var(--wa-color-danger-border-normal)"></div> |
-| `--wa-color-*-border-loud`  | <div class="swatch" value="--wa-color-brand-border-loud" style="border-color: var(--wa-color-brand-border-loud)"></div> | <div class="swatch" value="--wa-color-success-border-loud" style="border-color: var(--wa-color-success-border-loud)"></div> | <div class="swatch" value="--wa-color-success-border-loud" style="border-color: var(--wa-color-neutral-border-loud)"></div> | <div class="swatch" value="--wa-color-warning-border-loud" style="border-color: var(--wa-color-warning-border-loud)"></div> | <div class="swatch" value="--wa-color-danger-border-loud" style="border-color: var(--wa-color-danger-border-loud)"></div> |
-| `--wa-color-*-on-quiet`      | <div class="swatch" value="--wa-color-brand-on-quiet" style="background-color: var(--wa-color-brand-fill-quiet); color: var(--wa-color-brand-on-quiet)">AaBb</div> | <div class="swatch" value="--wa-color-success-on-quiet" style="background-color: var(--wa-color-success-fill-quiet); color: var(--wa-color-success-on-quiet)">AaBb</div> | <div class="swatch" value="--wa-color-neutral-on-quiet" style="background-color: var(--wa-color-neutral-fill-quiet); color: var(--wa-color-neutral-on-quiet)">AaBb</div> | <div class="swatch" value="--wa-color-warning-on-quiet" style="background-color: var(--wa-color-warning-fill-quiet); color: var(--wa-color-warning-on-quiet)">AaBb</div> | <div class="swatch" value="--wa-color-danger-on-quiet" style="background-color: var(--wa-color-danger-fill-quiet); color: var(--wa-color-danger-on-quiet)">AaBb</div> |
-| `--wa-color-*-on-normal`     | <div class="swatch" value="--wa-color-brand-on-normal" style="background-color: var(--wa-color-brand-fill-normal); color: var(--wa-color-brand-on-normal)">AaBb</div> | <div class="swatch" value="--wa-color-success-on-normal" style="background-color: var(--wa-color-success-fill-normal); color: var(--wa-color-success-on-normal)">AaBb</div> | <div class="swatch" value="--wa-color-neutral-on-normal" style="background-color: var(--wa-color-neutral-fill-normal); color: var(--wa-color-neutral-on-normal)">AaBb</div> | <div class="swatch" value="--wa-color-warning-on-normal" style="background-color: var(--wa-color-warning-fill-normal); color: var(--wa-color-warning-on-normal)">AaBb</div> | <div class="swatch" value="--wa-color-warning-on-normal" style="background-color: var(--wa-color-danger-fill-normal); color: var(--wa-color-danger-on-normal)">AaBb</div> |
-| `--wa-color-*-on-loud`       | <div class="swatch" value="--wa-color-brand-on-loud" style="background-color: var(--wa-color-brand-fill-loud); color: var(--wa-color-brand-on-loud)">AaBb</div> | <div class="swatch" value="--wa-color-success-on-loud" style="background-color: var(--wa-color-success-fill-loud); color: var(--wa-color-success-on-loud)">AaBb</div> | <div class="swatch" value="--wa-color-neutral-on-loud" style="background-color: var(--wa-color-neutral-fill-loud); color: var(--wa-color-neutral-on-loud)">AaBb</div> | <div class="swatch" value="--wa-color-warning-on-loud" style="background-color: var(--wa-color-warning-fill-loud); color: var(--wa-color-warning-on-loud)">AaBb</div> | <div class="swatch" value="--wa-color-danger-on-loud" style="background-color: var(--wa-color-danger-fill-loud); color: var(--wa-color-danger-on-loud)">AaBb</div> |
-
-<style>
-.swatch {
-  position: relative;
-}
-.swatch wa-copy-button {
-  position: absolute;
-  top: 0;
-  left: 0;
-  width: 100%;
-  height: 100%;
-  display: block;
-}
-
-.swatch wa-copy-button::part(button) {
-  display: block;
-  height: 100%;
-  width: 100%;
-}
-
-.swatch wa-copy-button {
-  --background-color-hover: transparent;
-  font-family: var(--wa-font-family-code);
-}
-
-.swatch wa-copy-button::part(button):hover {
-  cursor: copy;
-}
-
-.swatch wa-copy-button::part(copy-icon),
-.swatch wa-copy-button::part(success-icon),
-.swatch wa-copy-button::part(error-icon) {
-  opacity: 0 !important;
-}
-</style>
-
-<script type="module">
-  const computedStyle = getComputedStyle(document.body)
-  document.querySelectorAll(".swatch").forEach((swatch) => {
-    let varName = swatch.getAttribute("value")
-
-    if (!varName) {
-      const bgColor = swatch.style.backgroundColor
-      varName = bgColor.replace(/^var\((--.*)\)$/, "$1")
-    }
-
-    const copyButton = Object.assign(document.createElement("wa-copy-button"), {
-      value: varName,
-      copyLabel: varName,
-      errorLabel: "Whoops, your browser doesn't support this!",
-    })
-
-    swatch.appendChild(copyButton)
-  })
-</script>
--- a/docs/docs/theming/index.njk
+++ b/docs/docs/theming/index.njk
@@ -1,6 +0,0 @@
---
-title: Theming
-description: A theme is a collection of pre-defined CSS custom properties that control global styles from color to shadows. These custom properties thread through all Web Awesome components for a consistent look and feel.
-layout: overview
-override:tags: []
---
--- a/docs/docs/theming/theming.json
+++ b/docs/docs/theming/theming.json
@@ -1,7 +0,0 @@
-{
-  "layout": "page-outline.njk",
-  "tags": ["theming"],
-  "eleventyComputed": {
-    "icon": "theming/{{ page.fileSlug }}"
-  }
-}
--- a/docs/docs/theming/borders.md
+++ b/docs/docs/theming/borders.md
@@ -21,7 +21,7 @@ Border widths use `rem` units in order to scale proportionately with the root fo
 | `--wa-border-width-m` | `0.125rem` <small>(2px)</small>  | <div class="swatch" style="border-width: var(--wa-border-width-m)"></div> |
 | `--wa-border-width-l` | `0.1875rem` <small>(3px)</small> | <div class="swatch" style="border-width: var(--wa-border-width-l)"></div> |

-To scale all borders at once, you can use the  `--wa-border-width-scale` property which specifies a multiplier on `border-width`. 
+To scale all borders at once, you can use the  `--wa-border-width-scale` property which specifies a multiplier on `border-width`.
 Values < 1 make all borders uniformly thinner, while values > 1 make them thicker.

 ## Radius
@@ -44,5 +44,5 @@ Size-based border radius properties allow you to customize the overall roundness
 | `--wa-border-radius-m`  | `0.375rem` <small>(6px)</small>  | <div class="swatch" style="border-radius: var(--wa-border-radius-m)"></div> |
 | `--wa-border-radius-l`  | `0.75rem` <small>(12px)</small>  | <div class="swatch" style="border-radius: var(--wa-border-radius-l)"></div> |

-To scale all border radii at once, you can use the  `--wa-border-radius-scale` property which specifies a multiplier on `border-radius`. 
-Values < 1 make corners sharper, while values > 1 make them rounder.
+To scale all border radii at once, you can use the  `--wa-border-radius-scale` property which specifies a multiplier on `border-radius`.
+Values < 1 make corners sharper, while values > 1 make them rounder.
--- a/docs/docs/tokens/color.md
+++ b/docs/docs/tokens/color.md
@@ -0,0 +1,191 @@
+---
+title: Color
+description: Ensure consistent use of color and readable contrast with Web Awesome's color properties.
+---
+
+<style>
+  td { vertical-align: middle; }
+
+  .color-name {
+    font-weight: var(--wa-font-weight-semibold);
+    margin-block-end: var(--wa-space-2xs);
+  }
+  ul.color-group {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+  .color-group {
+    align-items: start;
+    display: flex;
+    flex-wrap: nowrap;
+    gap: 0.25em;
+  }
+  .color-group + * {
+    margin-block-start: var(--wa-space-xl);
+  }
+  .color-preview {
+    flex: 1 1 auto;
+  }
+  .swatch {
+    border-color: transparent;
+  }
+  .color-mix-example {
+    background-image:
+      linear-gradient(to right,
+      color-mix(in oklab, transparent, var(--mix-color)) 25%,
+      color-mix(in oklab, var(--wa-color-brand-fill-loud), var(--mix-color)) 25%,
+      color-mix(in oklab, var(--wa-color-brand-fill-loud), var(--mix-color)) 75%,
+      var(--wa-color-brand-fill-loud) 75%,
+      var(--wa-color-brand-fill-loud))
+    ;
+    border: none;
+    color: var(--wa-color-brand-on-loud);
+    text-align: center;
+  }
+</style>
+
+Web Awesome's color system is made up of CSS custom properties to help with consistent color use throughout your project.
+
+Color is organized by three main categories:
+
+- [Literal colors](/#literal-colors) that give familiar names to your starting [color palette](/docs/palettes/)
+- [Foundational colors](/#foundational-colors) that lay the groundwork for your theme
+- [Semantic colors](/#semantic-colors) that draw attention and convey meaning
+
+
+## Literal Colors
+
+Literal colors are defined by your theme's [color palette](/docs/palettes/) and are the lowest level color tokens in your theme. Each token is identified by a name, like red or gray, and a number based on the color's lightness. On this scale, 100 is equal to pure white and 0 is equal to pure black.
+
+You can use these numbers to ensure accessible color contrast per [WCAG 2.1 success criteria](https://www.w3.org/TR/WCAG21/#contrast-minimum):
+
+- A difference of 40 ensures a minimum 3:1 contrast ratio, suitable for large text and icons (AA)
+- A difference of 50 ensures a minimum 4.5:1 contrast ratio, suitable for normal text (AA) and large text (AAA)
+- A difference of 60 ensures a minimum 7:1 contrast ratio, suitable for all text (AAA)
+
+Each Web Awesome palette defines seven literal colors each with 11 lightness values using the format `--wa-color-{hue}-{tint}`.
+
+{% for hue in ["red", "yellow", "green", "teal", "blue", "indigo", "violet", "gray"] -%}
+<div class="color-name">{{ hue | capitalize }}</div>
+<ul class="color-group">
+  {% for tint in ["95", "90", "80", "70", "60", "50", "40", "30", "20", "10", "05"] -%}
+    <li class="color-preview">
+      <div class="color swatch" style="background-color: var(--wa-color-{{ hue }}-{{ tint }})">
+        <wa-copy-button value="--wa-color-{{ hue }}-{{ tint }}" copy-label="--wa-color-{{ hue }}-{{ tint }}"></wa-copy-button>
+      </div>
+      <small>{{ tint }}</small>
+    </li>
+  {%- endfor %}
+</ul>
+{%- endfor %}
+
+## Foundational Colors
+
+Foundational colors lay the groundwork for the content and structure of your project. These colors are named according to their role in your theme.
+
+### Surfaces
+
+Surfaces are background layers that other content rests on. Surface colors help convey hierarchy through a sense of elevation, where `--wa-color-surface-raised` is the closest to the user (e.g., dialogs and popup menus) and `--wa-color-surface-lowered` is the farthest away (e.g., wells).
+
+| Custom Property               | Preview                                                                                                                         |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `--wa-color-surface-raised`   | <div class="swatch" style="background-color: var(--wa-color-surface-raised); box-shadow:var(--wa-shadow-s)"></div>              |
+| `--wa-color-surface-default`  | <div class="swatch" style="background-color: var(--wa-color-surface-default)"></div>                                            |
+| `--wa-color-surface-lowered`  | <div class="swatch" style="background-color: var(--wa-color-surface-lowered); box-shadow: inset var(--wa-shadow-s)"></div>      |
+| `--wa-color-surface-border`   | <div class="swatch" style="border-color: var(--wa-color-surface-border)"></div>                                                 |
+
+### Text
+
+Text colors are used for standard text elements. We recommend a minimum 4.5:1 contrast ratio between text colors and surface colors.
+
+| Custom Property          | Preview                                                    |
+| ------------------------ | ---------------------------------------------------------- |
+| `--wa-color-text-normal` | <div class="swatch" value="--wa-color-text-normal" style="color: var(--wa-color-text-normal); display: inline-block;">AaBb</div> |
+| `--wa-color-text-quiet`  | <div class="swatch" value="--wa-color-text-normal" style="color: var(--wa-color-text-quiet); display: inline-block;">AaBb</div>  |
+| `--wa-color-text-link`   | <div class="swatch" value="--wa-color-text-normal" style="color: var(--wa-color-text-link); display: inline-block;">AaBb</div>   |
+
+### Overlays
+
+Overlays provide a backdrop to isolate content, often allowing background context to show through.
+
+| Custom Property             | Preview                                                                             |
+| --------------------------- | ----------------------------------------------------------------------------------- |
+| `--wa-color-overlay-modal`  | <div class="swatch" style="background-color: var(--wa-color-overlay-modal)"></div>  |
+| `--wa-color-overlay-inline` | <div class="swatch" style="background-color: var(--wa-color-overlay-inline)"></div> |
+
+### Shadow
+
+Web Awesome uses a single color for all shadows.
+This is used alongside other [shadow tokens](/docs/tokens/shadows) to construct your theme's shadows.
+
+| Custom Property     | Preview                                                                     |
+| ------------------- | --------------------------------------------------------------------------- |
+| `--wa-color-shadow` | <div class="swatch" style="background-color: var(--wa-color-shadow)"></div> |
+
+### Interactions
+
+#### Focus
+
+Web Awesome uses a single focus color for predictable keyboard navigation. This is used alongside other [focus tokens](/docs/tokens/focus) to construct `--wa-focus-ring`. We recommend a minimum 3:1 contrast ratio against surface colors and background colors wherever possible.
+
+| Custom Property    | Preview                                                                                                                 |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `--wa-color-focus` | <div class="swatch" value="--wa-color-focus" style="outline: var(--wa-focus-ring-style) var(--wa-focus-ring-width) var(--wa-color-focus)"></div> |
+
+#### Hover and Active
+
+Web Awesome leverages `color-mix()` to achieve consistent hover and active states across components without the need for untold numbers of handpicked colors. Through `color-mix()`, these custom properties contextually generate hover and active colors based on the color of the component.
+
+| Custom Property         | Preview                                                                                                          |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `--wa-color-mix-hover`  | <div class="swatch color-mix-example" value="--wa-color-mix-hover" style="--mix-color: var(--wa-color-mix-hover)"><small>mixed</small></div>  |
+| `--wa-color-mix-active` | <div class="swatch color-mix-example" value="--wa-color-mix-active" style="--mix-color: var(--wa-color-mix-active)"><small>mixed</small></div> |
+
+
+## Semantic Colors
+
+Semantic colors reinforce a specific message, intended usage, or expected results through familiar, meaningful hues. Each color is identified by its semantic group, role, and attention using the format `--wa-color-{group}-{role}-{attention}`. There are five groups of semantic colors:
+- **Brand** to emphasize your brand color
+- **Success** for validity or confirmation
+- **Neutral** for ordinary or inactive content
+- **Warning** for caution or uncertainty
+- **Danger** for errors or risk
+
+Each group defines colors for specific roles so that colors can be easily assembled with predictable results and readable contrast. There are three roles:
+- **Fill** for background colors or areas larger than a few pixels
+- **Border** for borders, dividers, and other stroke-width elements
+- **On** for content displayed on a fill (e.g., pair `--wa-color-danger-on-loud` with `--wa-color-danger-fill-loud`)
+
+Finally, each color is named according to how much attention it draws. Here, we use noise as an analogy: a loud noise draws more attention than a quiet one. There are three levels of attention:
+- **Quiet** draws the least attention
+- **Normal** draws some attention
+- **Loud** draws the most attention
+
+{% set variants = ['brand', 'success', 'neutral', 'warning', 'danger'] %}
+<table>
+  <thead>
+    <tr>
+      <th>Custom Property</th>
+      {% for variant in variants -%}
+        <th><code>{{ variant }}</code></th>
+      {%- endfor %}
+    </tr>
+  </thead>
+  {% for type in ['fill', 'border', 'on'] -%}
+    {% for attention in ['quiet', 'normal', 'loud'] -%}
+      <tr>
+        <td><code>--wa-color-*-{{ type }}-{{ attention }}</code></td>
+        {% for variant in variants -%}
+          <td>
+            {%- if type == 'border' -%}
+            <div class="swatch" style="border-color: var(--wa-color-{{ variant }}-{{ type }}-{{ attention }})"></div>
+            {%- else -%}
+            <div class="swatch" style="background-color: var(--wa-color-{{ variant }}-fill-{{ attention }}); color: var(--wa-color-{{ variant }}-on-{{ attention }})">{{ 'AaBb' if type == 'on' }}</div>
+            {%- endif %}
+          </td>
+        {%- endfor %}
+      </tr>
+    {%- endfor %}
+    {%- endfor %}
+</table>
--- a/docs/docs/theming/component-groups.md
+++ b/docs/docs/theming/component-groups.md
--- a/docs/docs/theming/focus.md
+++ b/docs/docs/theming/focus.md
@@ -3,7 +3,7 @@ title: Focus
 description: Configure recognizable focus states with Web Awesome's focus properties.
 ---

-A consistent focus ring helps with predictable keyboard navigation. Together with [`--wa-color-focus`](/docs/theming/color/#interactions), these custom properties create a uniform focus state for Web Awesome components.
+A consistent focus ring helps with predictable keyboard navigation. Together with [`--wa-color-focus`](/docs/tokens/color/#interactions), these tokens create a uniform focus state for Web Awesome components.


 | Custom Property          |  Default Value                                                                |
--- a/docs/docs/tokens/index.njk
+++ b/docs/docs/tokens/index.njk
@@ -0,0 +1,6 @@
+---
+title: Design Tokens
+description: A theme is a collection of predefined CSS custom properties that control global styles from color to shadows. These custom properties thread through all Web Awesome components for a consistent look and feel.
+layout: overview
+override:tags: []
+---
--- a/docs/docs/theming/shadows.md
+++ b/docs/docs/theming/shadows.md
@@ -3,7 +3,7 @@ title: Shadows
 description: Elevate your components with Web Awesome's shadow properties.
 ---

-Shadows indicate elevation and, often, interactivity. Web Awesome offers highly modular shadow properties to easily create custom shadow effects or transform elements based on specific shadow qualities. Together with [`--wa-color-shadow`](/docs/theming/color/#shadow), these custom properties create realistic shadows for Web Awesome components.
+Shadows indicate elevation and, often, interactivity. Web Awesome offers highly modular shadow properties to easily create custom shadow effects or transform elements based on specific shadow qualities. Together with [`--wa-color-shadow`](/docs/tokens/color/#shadow), these tokens create realistic shadows for Web Awesome components.

 Shadows are constructed using corresponding offset-x, offset-y, blur, and spread properties, detailed in the sections below. In Web Awesome, shadows use a size-based scale where larger shadows have greater offset and blur values to indicate greater distance from the surface below.

--- a/docs/docs/theming/space.md
+++ b/docs/docs/theming/space.md
--- a/docs/docs/tokens/tokens.json
+++ b/docs/docs/tokens/tokens.json
@@ -0,0 +1,7 @@
+{
+  "layout": "page-outline.njk",
+  "tags": ["tokens"],
+  "eleventyComputed": {
+    "icon": "tokens/{{ page.fileSlug }}"
+  }
+}
--- a/docs/docs/theming/transitions.md
+++ b/docs/docs/theming/transitions.md
--- a/docs/docs/theming/typography.md
+++ b/docs/docs/theming/typography.md
@@ -69,7 +69,7 @@ Line heights control the distance between lines of text and are unitless to scal

 ## Links

-Together with [`--wa-color-link`](/docs/theming/color/#text), these custom properties add text decoration to `<a>` elements to signal their role as hyperlinks.
+Together with [`--wa-color-link`](/docs/tokens/color/#text), these tokens add text decoration to `<a>` elements to signal their role as hyperlinks.

 | Custom Property                | Default Value                                                                      |
 | ------------------------------ | ---------------------------------------------------------------------------------- |
--- a/docs/docs/usage.md
+++ b/docs/docs/usage.md
@@ -24,22 +24,9 @@ Some properties are boolean, so they only have true/false values. To activate a

 ## Events

-You can listen for standard events such as `click`, `mouseover`, etc. as you normally would. However, it's important to note that many events emitted within a component's shadow root will be [retargeted](https://dom.spec.whatwg.org/#retarget) to the host element. This may result in, for example, multiple `click` handlers executing even if the user clicks just once. Furthermore, `event.target` will point to the host element, making things even more confusing.
+You can listen for standard events such as `click`, `mouseover`, etc. as you normally would. In addition, some components have their own custom events. For example, you might listen to `wa-after-show` to determine when a dialog has been shown.

-As a result, you should almost always listen for Web Awesome events instead. For example, instead of listening to `click` to determine when an `<wa-checkbox>` gets toggled, listen to `wa-change`.
-
-```html
-<wa-checkbox>Check me</wa-checkbox>
-
-<script>
-  const checkbox = document.querySelector('wa-checkbox');
-  checkbox.addEventListener('wa-change', event => {
-    console.log(event.target.checked ? 'checked' : 'not checked');
-  });
-</script>
-```
-
-All Web Awesome events are prefixed with `wa-` to prevent collisions with standard events and other libraries. Refer to a component's documentation for a complete list of its events.
+Custom Web Awesome events are prefixed with `wa-` to prevent collisions with standard events and other libraries. Refer to a component's documentation for a complete list of its events.

 ## Methods

--- a/docs/docs/utilities/color.md
+++ b/docs/docs/utilities/color.md
@@ -1,7 +1,7 @@
 ---
 title: Color Variants
 description: Color utilities allow you to apply the brand, neutral, success, warning, and danger colors from your theme to any element.
-icon: theming/color
+icon: tokens/color
 snippets:
  - .wa-brand
  - .wa-neutral
@@ -27,7 +27,7 @@ You can create the same effect on any element by using the color variant utility
 - `.wa-danger`

 Using these classes is a two-way handshake:
-they do not directly apply styles, but define generic color tokens modeled after our [Semantic Colors](/docs/theming/color/#semantic-colors) but *without* the group identifier (`neutral`, `brand`, `success`, `warning`, `danger`), defaulting to `neutral`.
+they do not directly apply styles, but define generic color tokens modeled after our [Semantic Colors](/docs/tokens/color/#semantic-colors) but *without* the group identifier (`neutral`, `brand`, `success`, `warning`, `danger`), defaulting to `neutral`.
 This means that styles can be written to respond to variants by using e.g. `--wa-color-fill-loud` instead of e.g. `--wa-color-brand-fill-loud`,
 and all of our [native styles](/docs/native/) do so (where it made sense).

--- a/docs/docs/utilities/gap.md
+++ b/docs/docs/utilities/gap.md
@@ -16,7 +16,7 @@ tags: ["utilities", "layout"]
 Web Awesome includes classes to set the `gap` property of flex and grid containers. They can be used alongside other Web Awesome layout utilities, like [cluster](/docs/layout/cluster) and [stack](/docs/layout/stack), to change the space between items.
 Or even by themselves — all gap properties also set `display: flex` with a specificity of 0 so that it can be trivially overridden.

-Besides `wa-gap-0`, which sets `gap` to zero, each class corresponds to one of the [`--wa-space-*`](/docs/theming/space) properties in your theme.
+Besides `wa-gap-0`, which sets `gap` to zero, each class corresponds to one of the [`--wa-space-*`](/docs/tokens/space) tokens in your theme.

 | Class Name   | `gap` Value      | Preview                                                                                                     |
 | ------------ | ---------------- | ----------------------------------------------------------------------------------------------------------- |
--- a/docs/docs/utilities/rounding.md
+++ b/docs/docs/utilities/rounding.md
@@ -14,7 +14,7 @@ status: wip

 Web Awesome includes classes to set an element's `border-radius` property. They can be used alongside Web Awesome layout utilities, like [frame](/docs/layout/frame), to round all corners of an element.

-Each class corresponds to one of the [`--wa-border-radius-*`](/docs/theming/borders/#radius) properties in your theme.
+Each class corresponds to one of the [`--wa-border-radius-*`](/docs/tokens/borders/#radius) tokens in your theme.

 | Class Name                | `border-radius` Value       | Preview                                                                                 |
 | ------------------------- | --------------------------- | --------------------------------------------------------------------------------------- |
--- a/docs/docs/utilities/size.md
+++ b/docs/docs/utilities/size.md
@@ -1,7 +1,7 @@
 ---
 title: Size
 description: Size utilities give elements one of three preset sizes (small, medium, or large).
-icon: theming/space
+icon: tokens/space
 status: experimental
 snippets:
  - .wa-size-s
@@ -22,7 +22,7 @@ You can create the same effect on any element by using the size utility classes:
 - `.wa-size-l`

 Using these classes does two things:
- It sets `font-size` to one of the [size tokens](/docs/theming/typography/#font-size).
+- It sets `font-size` to one of the [size tokens](/docs/tokens/typography/#font-size).
 You can use CSS `em` units to reference that size in other properties.
 - It calculates `--wa-form-control-height` based on the applied size, supporting consistent heights for elements like inputs and buttons.
 - It aliases a bunch of other properties that CSS can use:
--- a/docs/docs/utilities/text.md
+++ b/docs/docs/utilities/text.md
@@ -13,7 +13,7 @@ Use body classes to style the main content of your pages. Each `wa-body-*` class
 - `font-weight: var(--wa-font-weight-body);`
 - `line-height: var(--wa-line-height-normal);`

-Additionally, each class specifies a `font-size` that corresponds to a [`--wa-font-size-*`](/docs/theming/typography/#font-size) property from your theme.
+Additionally, each class specifies a `font-size` that corresponds to a [`--wa-font-size-*`](/docs/tokens/typography/#font-size) token from your theme.

 | Class Name         | `font-size` Value    |  Preview                                                                  |
 | ------------------ | -------------------- | ------------------------------------------------------------------------- |
@@ -31,7 +31,7 @@ Use heading classes to style section titles and headings in your content. Each `
 - `line-height: var(--wa-line-height-condensed);`
 - `text-wrap: balance;`

-Additionally, each class specifies a `font-size` using a [`--wa-font-size-*`](/docs/theming/typography/#font-size) property from your theme. Heading classes are one font size larger than the corresponding `wa-body-*` class.
+Additionally, each class specifies a `font-size` using a [`--wa-font-size-*`](/docs/tokens/typography/#font-size) token from your theme. Heading classes are one font size larger than the corresponding `wa-body-*` class.

 | Class Name       | `font-size` Value    | Preview                                               |
 | ---------------- | -------------------- | ----------------------------------------------------- |
@@ -51,7 +51,7 @@ Use caption classes to style descriptions or auxiliary text in your content. Eac
 - `font-weight: var(--wa-font-weight-body);`
 - `line-height: var(--wa-line-height-condensed);`

-Additionally, each class specifies a `font-size` using a [`--wa-font-size-*`](/docs/theming/typography/#font-size) property from your theme. Caption classes are one font size smaller than the corresponding `wa-body-*` class.
+Additionally, each class specifies a `font-size` using a [`--wa-font-size-*`](/docs/tokens/typography/#font-size) token from your theme. Caption classes are one font size smaller than the corresponding `wa-body-*` class.

 | Class Name       | `font-size` Value    | Preview                                                                        |
 | ---------------- | -------------------- | ------------------------------------------------------------------------------ |
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
  "name": "@shoelace-style/webawesome",
-  "version": "3.0.0-alpha.8",
+  "version": "3.0.0-alpha.9",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "@shoelace-style/webawesome",
-      "version": "3.0.0-alpha.8",
+      "version": "3.0.0-alpha.9",
      "license": "MIT",
      "dependencies": {
        "@ctrl/tinycolor": "^4.1.0",
@@ -34,6 +34,7 @@
        "chalk": "^5.3.0",
        "change-case": "^4.1.2",
        "chokidar": "^3.5.3",
+        "colorjs.io": "^0.6.0-alpha.1",
        "command-line-args": "^5.2.1",
        "comment-parser": "^1.4.1",
        "cspell": "^6.18.1",
@@ -5078,6 +5079,17 @@
      "integrity": "sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==",
      "dev": true
    },
+    "node_modules/colorjs.io": {
+      "version": "0.6.0-alpha.1",
+      "resolved": "https://registry.npmjs.org/colorjs.io/-/colorjs.io-0.6.0-alpha.1.tgz",
+      "integrity": "sha512-c/h/8uAmPydQcriRdX8UTAFHj6SpSHFHBA8LvMikvYWAVApPTwg/pyOXNsGmaCBd6L/EeDlRHSNhTtnIFp/qsg==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/color"
+      }
+    },
    "node_modules/command-line-args": {
      "version": "5.2.1",
      "resolved": "https://registry.npmjs.org/command-line-args/-/command-line-args-5.2.1.tgz",
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Lea Verou	4316c2670a	Improve theme remixing UI	2025-01-27 12:42:35 -05:00
Lindsay M	71c054d6e4	Use `background-image` for native select caret (#594 )	2025-01-24 11:52:06 -05:00
Cory LaViska	e1bf5471bf	Use native events when possible (#590 ) * fix filename * <wa-input> input + change (change not working) * compose that horribly misleading change event * use native blur/focus events * update checkbox * update color picker events * update color picker events * update radio group events * update button events * remove event options * update select events * update image comparer events * update icon button events * update slider events * update rating events * update radio events * update switch event * update textarea events * update radio button events * remove unused events * cleanup * fix react wrappers * fix react events for real this time * update changelog * add note * Update src/components/input/input.ts Co-authored-by: Lea Verou <lea@verou.me> * delete unused close event * use same event type * fix tests * remove wa- from events in docs and examples * fix comment * Update docs/docs/resources/changelog.md Co-authored-by: Lea Verou <lea@verou.me> --------- Co-authored-by: Lea Verou <lea@verou.me>	2025-01-23 17:52:41 -05:00
Lea Verou	099edc5186	Implement `wide` page-level data	2025-01-22 13:25:29 -05:00
Lea Verou	e3560dcf98	Do not reflect default values - Add `default` descriptor - Do not reflect attributes when equal to their default value - Patch getter return value to return default value when empty - Use it in button `appearance`	2025-01-21 15:16:11 -05:00
Cory LaViska	f2bb2c84a0	fix nested tab groups (#576 )	2025-01-21 12:54:38 -05:00
Cory LaViska	13b3342017	fix slot names (#577 )	2025-01-21 12:52:41 -05:00
Cory LaViska	d1c1d689ce	ensure fix works on backers website (#579 )	2025-01-21 12:36:54 -05:00
Cory LaViska	44e5e37a2b	3.0.0-alpha.9	2025-01-17 10:40:54 -05:00
Cory LaViska	566aae927d	fix typo	2025-01-17 10:39:18 -05:00
Lea Verou	7258c001a7	Demo for mixing and matching (#565 )	2025-01-17 10:38:03 -05:00
Lea Verou	7a70940c6a	Update changelog, remove `.wa-callout` from alpha	2025-01-16 18:27:47 -05:00
Lea Verou	45f4edc426	Fix #561	2025-01-16 16:50:28 -05:00
Lea Verou	da32015f27	Basic mixing and matching docs (#560 )	2025-01-16 16:31:24 -05:00
Lea Verou	03d8238edb	Add missing `:state(blank)` docs	2025-01-16 16:17:50 -05:00
Lindsay M	34f8744493	Fix missing mild palette doc and links (#557 )	2025-01-16 16:09:52 -05:00
Lindsay M	fa3fe5f753	Theme files housekeeping, closes #519 (#552 ) * Reorg Glossy theme * Reorg Playful theme * Remove redundant dark mode tokens	2025-01-16 16:09:28 -05:00
Lindsay M	fc6c7de1fd	Fix contrast issues with Bright teal (#556 )	2025-01-16 16:09:03 -05:00
Lea Verou	0037712549	Matter Ripple MVP (#558 ) Co-authored-by: lindsaym-fa <dev@lindsaym.design>	2025-01-16 16:05:50 -05:00
Lea Verou	5301945bfa	Filled inputs	2025-01-16 14:48:56 -05:00
Lea Verou	1298651dd8	Floating labels on select	2025-01-16 14:48:56 -05:00
Lea Verou	5f9695fde1	Floating labels on textarea	2025-01-16 14:48:56 -05:00
Lea Verou	2eb2597efe	Floating labels for input	2025-01-16 14:48:56 -05:00
lindsaym-fa	431e82261b	Initial floating label attempt	2025-01-16 14:48:56 -05:00
Lea Verou	df51149d0a	Show contrast ratios in contrast pair tables	2025-01-16 13:18:26 -05:00
Lindsay M	fba0b11343	Add Matter theme (#547 ) * Add Matter theme * Add Matter to alpha build * Add changelog * Fix incorrect palette name * Make loud fills darker in light mode	2025-01-16 12:08:51 -05:00
Lea Verou	3618e93490	Reintroduce `--border-width` and `--border-radius`, fixes #531	2025-01-16 10:36:03 -05:00
Lea Verou	cfa95307d1	Quick proof of concept contrast tests	2025-01-16 10:22:01 -05:00
Lea Verou	15344c2a2a	Appease Turbo for the color scheme picker too, fixes #520	2025-01-16 10:15:52 -05:00
lindsaym-fa	3974aa5130	Decrease line height on swatches	2025-01-16 10:15:16 -05:00
lindsaym-fa	a6702ad6d2	Revise Color tokens doc and link to palettes	2025-01-16 10:15:16 -05:00
lindsaym-fa	ecf21adddc	Fix punctuation	2025-01-16 10:15:16 -05:00
Lea Verou	52c24fc3b7	Add color palette to theme pages	2025-01-16 10:15:16 -05:00
Lea Verou	d464714d7b	Rudimentary palette icons	2025-01-16 10:15:16 -05:00
Lea Verou	7d089bbe2f	Palette Docs	2025-01-16 10:15:16 -05:00
Lea Verou	71914afc91	`defaultPalette` -> `palette`	2025-01-16 10:15:16 -05:00
Lindsay M	9d139e3fa0	Minor style update for checkboxes in `wa-tree-item` (#542 ) * Use theme value line height for tree item checkbox * Apply theme checkbox styles to selected tree items	2025-01-16 09:30:35 -05:00
Lindsay M	db3039e9fe	Fix `green-40` in classic color palette (#548 )	2025-01-16 09:26:06 -05:00
Lindsay M	9494b9bb67	Improve default tooltip styles (#543 ) * Use inverted colors for tooltips * Remove redundant tooltip overrides from themes	2025-01-16 04:35:08 -05:00
Lea Verou	7e1f4f0351	Separate meaningful theme parts out (#526 ) Co-authored-by: lindsaym-fa <dev@lindsaym.design>	2025-01-15 17:32:36 -05:00
Lindsay M	5ebe4f4d3e	Finalize playful theme, closes #490 (#527 ) * Finalize Playful theme * Add changelog, add to alpha * Add playful theme to alpha build * Touchup and tweaks * Tweak hover mix color in `wa-dark` * Avoid transforming buttons in button groups * Final touchup --------- Co-authored-by: Lea Verou <lea@verou.me>	2025-01-15 17:13:48 -05:00
Lea Verou	dfb9d53a25	Checkbox improvements - Added `part="control", fixes #529 - Removed wrapper div which is no longer needed - Removed `form-control--has-hint` class which is no longer used anywhere	2025-01-15 15:03:58 -05:00
Lindsay M	c2c1a2ff5b	Add missing Glossy and Premium themes to alpha build (#528 )	2025-01-15 10:45:43 -05:00
Lindsay M	ac86c037a1	Finalize Glossy theme, closes #491 (#525 ) * Initial glassy theme progress * Add fallback to slider thumb box shadow * Remove redundant `wa-dark` styles and refactor shadows * Rename to 'Glossy' since it fits the vibe better	2025-01-14 18:44:31 -05:00
Lea Verou	6b07c9a040	Native callout (#513 ) Co-authored-by: lindsaym-fa <dev@lindsaym.design>	2025-01-14 14:56:03 -05:00
Lea Verou	24a76f6a7c	Color palette housekeeping (#523 )	2025-01-14 14:54:34 -05:00
Lea Verou	89c0667e9c	Improve maintainability of color docs	2025-01-14 14:44:30 -05:00
Lea Verou	434084ea4e	Playful: refer to rudimentary palette	2025-01-14 14:32:39 -05:00
Lea Verou	1738c6345b	Fix #514 for reals this time	2025-01-14 13:02:37 -05:00
Lea Verou	0ac7916a1b	Attempt to fix #514	2025-01-14 13:02:37 -05:00
Lea Verou	e7979991e3	Update docs to lean into the "tokens" terminology in lieu of "properties" Co-Authored-By: Lindsay M <126139086+lindsaym-fa@users.noreply.github.com>	2025-01-14 12:31:24 -05:00
Lea Verou	07f70098f8	Theming -> Design Tokens	2025-01-14 12:31:24 -05:00
Lindsay M	17146698db	Finalize Premium theme, closes #489 (#510 ) * Finalize Premium theme * Improve theme compatibility of dark mode shadows * Improve theme compatibility of code examples * Add comments * Revert dark mode shadow color changes (to be addressed separately) * Revert dark mode shadow color change * Clean up redundant `wa-dark` properties	2025-01-14 11:56:30 -05:00
Lea Verou	bf852b1296	Fix #515	2025-01-14 11:29:36 -05:00
Lea Verou	e367c0ef29	Open sidebar group on overview pages, fixes #507	2025-01-14 10:20:04 -05:00
Lea Verou	01210ef364	Implement `.wa-invert`, closes #497 (#508 )	2025-01-14 10:04:27 -05:00
Lea Verou	40648e15fb	Refactor: `library.system.ts` to export supported icons (#505 )	2025-01-13 16:37:54 -05:00
Cory LaViska	ab67ecfad3	add native icon to search (#498 )	2025-01-13 14:48:51 -05:00
				`@@ -0,0 +1 @@`
				`["red", "yellow", "green", "teal", "blue", "indigo", "violet", "gray"]`
				`@@ -0,0 +1 @@`
				`export { default as default } from '../../src/styles/color/palettes.js';`