fix timing issues with dropdown updating triggers

Add new button appearances

.gitpod.yml

@@ -1,28 +0,0 @@
-tasks:
-  - init: npm install && npm run build
-    command: npm run start
-
-ports:
-  - port: 3001
-    onOpen: ignore
-  - port: 4000-4999
-    onOpen: open-preview
-
-github:
-  prebuilds:
-    # enable for the master/default branch (defaults to true)
-    master: true
-    # enable for all branches in this repo (defaults to false)
-    branches: true
-    # enable for pull requests coming from this repo (defaults to true)
-    pullRequests: true
-    # enable for pull requests coming from forks (defaults to false)
-    pullRequestsFromForks: true
-    # add a check to pull requests (defaults to true)
-    addCheck: true
-    # add a "Review in Gitpod" button as a comment to pull requests (defaults to false)
-    addComment: false
-    # add a "Review in Gitpod" button to the pull request's description (defaults to false)
-    addBadge: true
-    # add a label once the prebuild is ready to pull requests (defaults to false)
-    addLabel: true

CONTRIBUTING.md

@@ -2,4 +2,4 @@
 
 Before contributing, please review the contributions guidelines at:
 
-[shoelace.style/resources/contributing](https://shoelace.style/resources/contributing)
+[webawesome.com/docs/resources/contributing](https://webawesome.com/docs/resources/contributing)

custom-elements-manifest.js

@@ -1,6 +1,6 @@
 import { customElementJetBrainsPlugin } from 'custom-element-jet-brains-integration';
 import { customElementVsCodePlugin } from 'custom-element-vs-code-integration';
-import { customElementVuejsPlugin } from 'custom-element-vuejs-integration';
+// import { customElementVuejsPlugin } from 'custom-element-vuejs-integration';
 import { parse } from 'comment-parser';
 import { pascalCase } from 'pascal-case';
 import fs from 'fs';
@@ -156,7 +156,7 @@ export default {
       referencesTemplate: (_, tag) => [
         {
           name: 'Documentation',
-          url: `https://shoelace.style/components/${tag.replace('wa-', '')}`
+          url: `https://webawesome.com/docs/components/${tag.replace('wa-', '')}`
         }
       ]
     }),
@@ -168,7 +168,7 @@ export default {
       referencesTemplate: (_, tag) => {
         return {
           name: 'Documentation',
-          url: `https://shoelace.style/components/${tag.replace('wa-', '')}`
+          url: `https://webawesome.com/docs/components/${tag.replace('wa-', '')}`
         };
       }
     })

docs/404.md

@@ -1,7 +1,7 @@
 ---
 title: Not Found
 description: Sorry, I couldn't find that.
-layout: page.njk
+layout: page
 permalink: 404.html
 noindex: true
 ---

docs/_includes/logo-simple.njk

@@ -1 +1,3 @@
-<svg class="logo" xmlns="http://www.w3.org/2000/svg" width="277" height="211" viewBox="0 0 277 211"><g fill="none" fill-rule="evenodd"><path fill="#F6894C" d="M159.275,20.7541243 C159.275,28.4927904 155.035053,35.2422161 148.749528,38.8106604 L193.9,72.6391714 L238.157213,58.6776414 C236.43401,55.6537326 235.45,52.1547058 235.45,48.42629 C235.45,36.96411 244.751396,27.6721657 256.225,27.6721657 C267.698604,27.6721657 277,36.96411 277,48.42629 C277,59.8883646 267.698604,69.1804143 256.225,69.1804143 C255.131246,69.1804143 254.057541,69.0960801 253.00969,68.9332096 L204.251886,193.411571 C200.096886,204.019762 189.858966,211 178.45659,211 L98.5434095,211 C87.1410343,211 76.9031143,204.019762 72.7481143,193.411571 L23.990205,68.9332096 C22.9423008,69.0960801 21.8685432,69.1804143 20.775,69.1804143 C9.30129067,69.1804143 0,59.8883646 0,48.42629 C0,36.96411 9.30129067,27.6721657 20.775,27.6721657 C32.2487093,27.6721657 41.55,36.96411 41.55,48.42629 C41.55,52.1547058 40.5658322,55.6537326 38.842945,58.6776414 L83.1,72.6391714 L128.250472,38.8106604 C121.964947,35.2422161 117.725,28.4927904 117.725,20.7541243 C117.725,9.29194428 127.026396,0 138.5,0 C149.973604,0 159.275,9.29194428 159.275,20.7541243 Z"/></g></svg>
+<svg width="20" height="15" viewBox="0 0 20 15" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M11.63 1.625C11.63 2.27911 11.2435 2.84296 10.6865 3.10064L14 6L17.2622 5.34755C17.0968 5.10642 17 4.81452 17 4.5C17 3.67157 17.6716 3 18.5 3C19.3284 3 20 3.67157 20 4.5C20 5.31157 19.3555 5.9726 18.5504 5.99917L15.0307 13.8207C14.7077 14.5384 13.9939 15 13.2068 15H6.79317C6.00615 15 5.29229 14.5384 4.96933 13.8207L1.44963 5.99917C0.64452 5.9726 0 5.31157 0 4.5C0 3.67157 0.671573 3 1.5 3C2.32843 3 3 3.67157 3 4.5C3 4.81452 2.9032 5.10642 2.73777 5.34755L6 6L9.31702 3.09761C8.76346 2.83855 8.38 2.27656 8.38 1.625C8.38 0.727537 9.10754 0 10.005 0C10.9025 0 11.63 0.727537 11.63 1.625Z" fill="var(--wa-brand-orange, #f36944)"/>
+</svg>

docs/_includes/search.njk

@@ -1,4 +1,4 @@
-<wa-dialog id="site-search" no-header>
+<wa-dialog id="site-search" no-header light-dismiss>
   <div id="site-search-container">
     {# Header #}
     <header>

docs/_includes/sidebar.njk

@@ -8,31 +8,10 @@
   <li><a href="/docs/localization">Localization</a></li>
 </ul>
 
-{# Experimental #}
-<h2>Experimental</h2>
-<ul>
-  <li><a href="/docs/experimental/themer">Theme Builder</a></li>
-  <li><a href="/docs/experimental/style-guide">Style Guide</a></li>
-  <li><a href="/docs/experimental/form-validation">Form Validation Styles</a></li>
-  <li><a href="/docs/experimental/sandbox">Sandbox</a></li>
-  <li style="margin-top: .5rem;"><wa-switch id="theme-toggle">Dark mode</wa-switch></li>
-  <script type="module">
-    // Temporary dark toggle
-    const toggle = document.getElementById('theme-toggle');
-    toggle.checked = document.documentElement.classList.contains('wa-theme-default-dark');
-
-    toggle.addEventListener('wa-change', () => {
-      document.documentElement.classList.toggle('wa-theme-default-dark');
-      localStorage.setItem('theme', toggle.checked ? 'dark' : 'light');
-    });
-  </script>
-</ul>
-
-
 {# Resources #}
 <h2>Resources</h2>
 <ul>
-  <li><a href="https://github.com/shoelace-style/shoelace/discussions">Help &amp; Support</a></li>
+  <li><a href="https://github.com/shoelace-style/webawesome-alpha/discussions" target="_blank">Help &amp; Support</a></li>
   <li><a href="/docs/resources/community">Community</a></li>
   <li><a href="/docs/resources/accessibility">Accessibility</a></li>
   <li><a href="/docs/resources/contributing">Contributing</a></li>
@@ -144,12 +123,6 @@
   <li>
     <a href="/docs/components/mutation-observer">Mutation Observer</a>
   </li>
-  <li>
-    <a href="/docs/components/option">Option</a>
-  </li>
-  <li>
-    <a href="/docs/components/page">Page</a>
-  </li>
   <li>
     <a href="/docs/components/popup">Popup</a>
   </li>
@@ -187,6 +160,11 @@
   </li>
   <li>
     <a href="/docs/components/select">Select</a>
+    <ul>
+      <li>
+        <a href="/docs/components/option">Option</a>
+      </li>
+    </ul>
   </li>
   <li>
     <a href="/docs/components/skeleton">Skeleton</a>
@@ -232,3 +210,32 @@
     <a href="/docs/components/visually-hidden">Visually Hidden</a>
   </li>
 </ul>
+
+{# Theming #}
+<h2>Theming</h2>
+<ul>
+  <li>
+    <a href="/docs/theming/color">Color</a>
+  </li>
+  <li>
+    <a href="/docs/theming/typography">Typography</a>
+  </li>
+  <li>
+    <a href="/docs/theming/space">Space</a>
+  </li>
+  <li>
+    <a href="/docs/theming/borders">Borders</a>
+  </li>
+  <li>
+    <a href="/docs/theming/focus">Focus</a>
+  </li>
+  <li>
+    <a href="/docs/theming/shadows">Shadows</a>
+  </li>
+  <li>
+    <a href="/docs/theming/transitions">Transitions</a>
+  </li>
+  <li>
+    <a href="/docs/theming/component-groups">Component Groups</a>
+  </li>
+</ul>

docs/_layouts/component.njk

@@ -274,7 +274,6 @@
 
   <wa-tab-group label="How would you like to import this component?">
     <wa-tab slot="nav" panel="cdn">CDN</wa-tab>
-    <wa-tab slot="nav" panel="npm">npm</wa-tab>
     <wa-tab slot="nav" panel="react">React</wa-tab>
     <wa-tab-panel name="cdn">
       <p>
@@ -282,12 +281,6 @@
       </p>
       <pre><code class="language-js">import '{% cdnUrl component.path %}';</code></pre>
     </wa-tab-panel>
-    <wa-tab-panel name="npm">
-      <p>
-        To manually import this component from npm, use the following code.
-      </p>
-      <pre><code class="language-js">import '@shoelace-style/webawesome/{{ component.path }}';</code></pre>
-    </wa-tab-panel>
     <wa-tab-panel name="react">
       <p>
         To manually import this component from React, use the following code.

docs/_layouts/page-outline.njk

@@ -0,0 +1,4 @@
+{% set hasSidebar = true %}
+{% set hasOutline = true %}
+
+{% extends "../_includes/base.njk" %}

docs/assets/images/logo-simple.svg

@@ -1 +1 @@
-<svg class="logo" xmlns="http://www.w3.org/2000/svg" width="277" height="211" viewBox="0 0 277 211"><g fill="none" fill-rule="evenodd"><path fill="#F6894C" d="M159.275,20.7541243 C159.275,28.4927904 155.035053,35.2422161 148.749528,38.8106604 L193.9,72.6391714 L238.157213,58.6776414 C236.43401,55.6537326 235.45,52.1547058 235.45,48.42629 C235.45,36.96411 244.751396,27.6721657 256.225,27.6721657 C267.698604,27.6721657 277,36.96411 277,48.42629 C277,59.8883646 267.698604,69.1804143 256.225,69.1804143 C255.131246,69.1804143 254.057541,69.0960801 253.00969,68.9332096 L204.251886,193.411571 C200.096886,204.019762 189.858966,211 178.45659,211 L98.5434095,211 C87.1410343,211 76.9031143,204.019762 72.7481143,193.411571 L23.990205,68.9332096 C22.9423008,69.0960801 21.8685432,69.1804143 20.775,69.1804143 C9.30129067,69.1804143 0,59.8883646 0,48.42629 C0,36.96411 9.30129067,27.6721657 20.775,27.6721657 C32.2487093,27.6721657 41.55,36.96411 41.55,48.42629 C41.55,52.1547058 40.5658322,55.6537326 38.842945,58.6776414 L83.1,72.6391714 L128.250472,38.8106604 C121.964947,35.2422161 117.725,28.4927904 117.725,20.7541243 C117.725,9.29194428 127.026396,0 138.5,0 C149.973604,0 159.275,9.29194428 159.275,20.7541243 Z"/></g></svg>
+<svg class="logo" xmlns="http://www.w3.org/2000/svg" width="277" height="211" viewBox="0 0 277 211"><g fill="none" fill-rule="evenodd"><path fill="#var(--wa-brand-orange, #F36944)" d="M159.275,20.7541243 C159.275,28.4927904 155.035053,35.2422161 148.749528,38.8106604 L193.9,72.6391714 L238.157213,58.6776414 C236.43401,55.6537326 235.45,52.1547058 235.45,48.42629 C235.45,36.96411 244.751396,27.6721657 256.225,27.6721657 C267.698604,27.6721657 277,36.96411 277,48.42629 C277,59.8883646 267.698604,69.1804143 256.225,69.1804143 C255.131246,69.1804143 254.057541,69.0960801 253.00969,68.9332096 L204.251886,193.411571 C200.096886,204.019762 189.858966,211 178.45659,211 L98.5434095,211 C87.1410343,211 76.9031143,204.019762 72.7481143,193.411571 L23.990205,68.9332096 C22.9423008,69.0960801 21.8685432,69.1804143 20.775,69.1804143 C9.30129067,69.1804143 0,59.8883646 0,48.42629 C0,36.96411 9.30129067,27.6721657 20.775,27.6721657 C32.2487093,27.6721657 41.55,36.96411 41.55,48.42629 C41.55,52.1547058 40.5658322,55.6537326 38.842945,58.6776414 L83.1,72.6391714 L128.250472,38.8106604 C121.964947,35.2422161 117.725,28.4927904 117.725,20.7541243 C117.725,9.29194428 127.026396,0 138.5,0 C149.973604,0 159.275,9.29194428 159.275,20.7541243 Z"/></g></svg>

docs/assets/scripts/color-scheme.js

@@ -0,0 +1,65 @@
+//
+// Color scheme selector
+//
+(() => {
+  function getColorScheme() {
+    return localStorage.getItem('colorScheme') || 'auto';
+  }
+
+  function isDark() {
+    if (colorScheme === 'auto') {
+      return window.matchMedia('(prefers-color-scheme: dark)').matches;
+    }
+    return colorScheme === 'dark';
+  }
+
+  function setColorScheme(newColorScheme) {
+    colorScheme = newColorScheme;
+    localStorage.setItem('colorScheme', colorScheme);
+
+    // Update the UI
+    updateSelection();
+
+    // Toggle the dark mode class
+    document.documentElement.classList.toggle('wa-theme-default-dark', isDark());
+  }
+
+  function updateSelection() {
+    const menu = document.querySelector('#color-scheme-selector wa-menu');
+    if (!menu) return;
+    [...menu.querySelectorAll('wa-menu-item')].map(item => (item.checked = item.getAttribute('value') === colorScheme));
+  }
+
+  let colorScheme = getColorScheme();
+
+  // Selection is not preserved when changing page, so update when opening dropdown
+  document.addEventListener('wa-show', event => {
+    const colorSchemeSelector = event.target.closest('#color-scheme-selector');
+    if (!colorSchemeSelector) return;
+    updateSelection();
+  });
+
+  // Listen for selections
+  document.addEventListener('wa-select', event => {
+    const menu = event.target.closest('#color-scheme-selector wa-menu');
+    if (!menu) return;
+    setColorScheme(event.detail.item.value);
+  });
+
+  // Update the color scheme when the preference changes
+  window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => setColorScheme(colorScheme));
+
+  // Toggle with backslash
+  document.addEventListener('keydown', event => {
+    if (
+      event.key === '\\' &&
+      !event.composedPath().some(el => ['input', 'textarea'].includes(el?.tagName?.toLowerCase()))
+    ) {
+      event.preventDefault();
+      setColorScheme(isDark() ? 'light' : 'dark');
+    }
+  });
+
+  // Set the initial color scheme and sync the UI
+  setColorScheme(colorScheme);
+})();

docs/assets/styles/code-examples.css

@@ -1,13 +1,13 @@
 .code-example {
-  border: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-subtle);
-  border-radius: var(--wa-corners-m);
+  border: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-quiet);
+  border-radius: var(--wa-border-radius-m);
   color: var(--wa-color-text-normal);
   margin-block-end: var(--wa-flow-spacing);
 }
 
 .code-example-preview {
   padding: 2rem;
-  border-bottom: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-subtle);
+  border-bottom: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-quiet);
 
   > :first-child {
     margin-block-start: 0;
@@ -19,7 +19,7 @@
 }
 
 .code-example-source {
-  border-bottom: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-subtle);
+  border-bottom: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-quiet);
 }
 
 .code-example:not(.open) .code-example-source {
@@ -41,8 +41,8 @@
   border-bottom: none;
 
   pre {
-    border-bottom-right-radius: var(--wa-corners-m);
-    border-bottom-left-radius: var(--wa-corners-m);
+    border-bottom-right-radius: var(--wa-border-radius-m);
+    border-bottom-left-radius: var(--wa-border-radius-m);
   }
 }
 
@@ -55,18 +55,18 @@
     flex: 1 0 auto;
     font-size: 0.875rem;
     color: var(--wa-color-text-quiet);
-    border-left: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-subtle);
+    border-left: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-quiet);
     text-align: center;
     padding: 0.5rem;
     cursor: pointer;
 
     &:first-of-type {
       border-left: none;
-      border-bottom-left-radius: var(--wa-corners-m);
+      border-bottom-left-radius: var(--wa-border-radius-m);
     }
 
     &:last-of-type {
-      border-bottom-right-radius: var(--wa-corners-m);
+      border-bottom-right-radius: var(--wa-border-radius-m);
     }
 
     &:focus-visible {

docs/assets/styles/code-highlighter.css

@@ -4,7 +4,7 @@
 .code-cdata,
 .code-operator,
 .code-punctuation {
-  color: var(--wa-color-base-50);
+  color: var(--wa-color-base-40);
 }
 
 .code-namespace {
@@ -15,7 +15,7 @@
 .code-keyword,
 .code-tag,
 .code-url {
-  color: #7c3aed; /* violet */
+  color: var(--wa-color-indigo-40);
 }
 
 .code-symbol,
@@ -42,7 +42,7 @@
 .code-function,
 .code-class-name,
 .code-regex {
-  color: var(--wa-color-yellow-40);
+  color: var(--wa-color-blue-40);
 }
 
 .code-important,

docs/assets/styles/copy-code.css

@@ -3,13 +3,13 @@
   top: 0.25rem;
   right: 0.25rem;
   font-family: var(--wa-font-family-body);
-  color: var(--wa-color-neutral-text-on-fill);
-  background-color: var(--wa-color-neutral-fill-subtle);
-  border-radius: var(--wa-corners-s);
+  color: var(--wa-color-neutral-on-normal);
+  background-color: var(--wa-color-neutral-fill-quiet);
+  border-radius: var(--wa-border-radius-s);
   padding: 0.25rem;
 
   &:hover {
-    background-color: var(--wa-color-neutral-fill-highlight);
+    background-color: var(--wa-color-neutral-fill-normal);
   }
 
   &:focus-visible {

docs/assets/styles/docs.css

@@ -3,46 +3,147 @@
 @import 'copy-code.css';
 @import 'outline.css';
 @import 'search.css';
+@import 'cera_typeface.css';
+
+:root {
+  --wa-brand-orange: #f36944;
+  --wa-brand-grey: #30323b;
+}
+
+html.wa-theme-default-dark .only-light,
+html:not(.wa-theme-default-dark) .only-dark {
+  display: none;
+}
+
+wa-page {
+  --wa-flow-spacing: var(--wa-space-xl);
+}
 
 wa-page[view='desktop'] [data-toggle-nav] {
   display: none;
 }
 
+wa-page[view='desktop'] .only-mobile,
+wa-page:not([view='desktop']) .only-desktop {
+  display: none;
+}
+
 /* Header */
 wa-page::part(header) {
   background-color: var(--wa-color-surface-default);
-  border-bottom: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-subtle);
+  border-bottom: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-quiet);
 }
 
 wa-page > header {
   flex: 1 1 auto;
   display: flex;
   align-items: center;
-  max-width: 1200px;
-  height: 60px;
-  padding-inline: 2rem;
+  justify-content: space-between;
+  height: 4rem;
+  padding-inline: var(--wa-space-xl);
+
+  a[href='/'] {
+    color: var(--wa-color-text-normal);
+    line-height: 1;
+  }
+
+  wa-button[data-toggle-nav] {
+    --label-color: currentColor;
+    margin-inline-start: -0.875rem;
+    margin-inline-end: 0;
+
+    &::part(base) {
+      padding: 0;
+      padding-inline: 0.875rem;
+    }
+  }
 
   svg {
     width: auto;
-    max-height: 26px;
+    height: 1.75rem;
+  }
+
+  #docs-branding,
+  #docs-toolbar {
+    display: flex;
+    align-items: center;
+    gap: var(--wa-space-xs);
+  }
+
+  #version-number {
+    color: var(--wa-color-text-quiet);
+    font-size: var(--wa-font-size-xs);
+    line-height: 1;
+    margin-block-start: var(--wa-space-2xs);
+  }
+  #version-number + wa-badge {
+    --background-color: var(--wa-color-warning-fill-quiet);
+    --content-color: var(--wa-color-warning-on-quiet);
+    font-size: var(--wa-font-size-2xs);
+    text-transform: uppercase;
+  }
+  wa-button#search-trigger {
+    --background-color: var(--wa-form-control-background-color);
+    --border-color: var(--wa-form-control-resting-color);
+  }
+  #search-trigger kbd {
+    font-size: var(--wa-font-size-2xs);
+    line-height: var(--wa-form-control-value-line-height);
   }
 }
 
 /* Navigation sidebar */
 wa-page[view='desktop']::part(navigation) {
-  border-right: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-subtle);
+  border-right: var(--wa-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-quiet);
 }
 
 wa-page[view='desktop'] > #sidebar {
-  min-width: 320px;
-  padding: 2rem;
+  min-width: 300px;
+  padding: var(--wa-space-xl);
 }
 
 #sidebar,
 #outline {
   h2 {
-    font-size: 1.125rem;
-    margin-block-end: 0.5rem;
+    font-size: var(--wa-font-size-m);
+    margin-block-end: var(--wa-space-m);
+  }
+  h2:not(:first-of-type) {
+    margin-block-start: var(--wa-space-xl);
+  }
+  ul {
+    border-inline-start: var(--wa-border-width-s) solid var(--wa-color-surface-border);
+    font-size: var(--wa-font-size-s);
+    line-height: var(--wa-line-height-condensed);
+    margin: 0;
+    padding-inline-start: var(--wa-space-m);
+  }
+  ul ul {
+    margin-block-start: var(--wa-space-m);
+  }
+  li {
+    list-style: none;
+    margin-block-end: var(--wa-space-m);
+  }
+  li a {
+    color: var(--wa-color-text-normal);
+    text-decoration: none;
+  }
+  li a:hover {
+    text-decoration: underline;
+  }
+}
+
+#sidebar-close-button {
+  display: none;
+}
+
+@media screen and (max-width: 768px) {
+  #sidebar-close-button {
+    display: inline-block;
+    position: absolute;
+    top: 1rem;
+    right: 1rem;
   }
 }
 
@@ -50,6 +151,10 @@ wa-page[view='desktop'] > #sidebar {
   padding-bottom: 1rem;
 }
 
+wa-page::part(menu) {
+  scrollbar-width: thin;
+}
+
 /* Main content */
 wa-page > main {
   max-width: 80ch;
@@ -61,7 +166,7 @@ wa-page > main {
 #sidebar,
 #outline {
   .current {
-    font-weight: var(--wa-font-weight-heavy);
+    font-weight: var(--wa-font-weight-bold);
     text-decoration-style: solid;
   }
 }
@@ -84,7 +189,7 @@ wa-page > main {
   display: flex;
   gap: 1rem;
   border: var(--wa-border-style) var(--wa-border-width-m);
-  border-radius: var(--wa-corners-m);
+  border-radius: var(--wa-border-radius-m);
   padding: 1rem;
   margin-block-end: var(--wa-flow-spacing);
 
@@ -107,27 +212,46 @@ wa-page > main {
 }
 
 .callout-info {
-  background-color: var(--wa-color-brand-fill-subtle);
-  border-color: var(--wa-color-brand-border-subtle);
+  background-color: var(--wa-color-brand-fill-quiet);
+  border-color: var(--wa-color-brand-border-quiet);
 
   .callout-icon {
-    color: var(--wa-color-brand-text-on-fill);
+    color: var(--wa-color-brand-on-normal);
   }
 
   code {
-    background-color: var(--wa-color-brand-fill-highlight);
+    background-color: var(--wa-color-brand-fill-normal);
   }
 }
 
 .callout-warning {
-  background-color: var(--wa-color-warning-fill-subtle);
-  border-color: var(--wa-color-warning-border-subtle);
+  background-color: var(--wa-color-warning-fill-quiet);
+  border-color: var(--wa-color-warning-border-quiet);
 
   .callout-icon {
-    color: var(--wa-color-warning-text-on-fill);
+    color: var(--wa-color-warning-on-normal);
   }
 
   code {
-    background-color: var(--wa-color-warning-fill-highlight);
+    background-color: var(--wa-color-warning-fill-normal);
   }
 }
+
+/* Swatches */
+.swatch {
+  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-s);
+  box-sizing: border-box;
+  line-height: 2.5;
+  height: 2.5em;
+  padding-inline: var(--wa-space-xs);
+}
+
+/* Utilities */
+.two-columns {
+  columns: 2;
+  gap: 1rem;
+}

docs/assets/styles/search.css

@@ -4,7 +4,7 @@
   &::part(dialog) {
     position: absolute;
     top: 0;
-    border-radius: var(--wa-corners-m);
+    border-radius: var(--wa-border-radius-m);
     padding: 0;
     margin: 10rem auto;
     overflow: hidden;
@@ -42,12 +42,12 @@ header {
   flex: 0 0 auto;
   align-items: middle;
   /* Fixes an iOS Safari 16.4 bug that draws the parent element's border radius incorrectly when showing/hiding results */
-  border-radius: var(--wa-corners-l);
+  border-radius: var(--wa-border-radius-l);
 }
 
 #site-search.has-results header {
-  border-start-start-radius: var(--wa-corners-l);
-  border-start-end-radius: var(--wa-corners-l);
+  border-start-start-radius: var(--wa-border-radius-l);
+  border-start-end-radius: var(--wa-border-radius-l);
   border-end-start-radius: 0;
   border-end-end-radius: 0;
 }
@@ -99,7 +99,7 @@ header {
 #site-search.has-results,
 #site-search.no-results {
   #site-search-body {
-    border-top: var(--wa-panel-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-subtle);
+    border-top: var(--wa-panel-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-quiet);
   }
 }
 
@@ -126,19 +126,19 @@ header {
   @media (hover: hover) {
     li a:hover,
     li a:hover small {
-      background-color: var(--wa-color-neutral-fill-highlight);
+      background-color: var(--wa-color-neutral-fill-normal);
     }
   }
 
   li[data-selected='true'] a,
   li[data-selected='true'] a * {
     outline: none;
-    background-color: var(--wa-color-brand-spot);
-    color: var(--wa-color-brand-text-on-spot);
+    background-color: var(--wa-color-brand-fill-loud);
+    color: var(--wa-color-brand-on-loud);
   }
 
   h3 {
-    font-weight: var(--wa-font-weight-medium);
+    font-weight: var(--wa-font-weight-semibold);
     margin: 0;
   }
 
@@ -165,7 +165,7 @@ header {
 
     wa-icon {
       font-size: 1.75rem;
-      color: var(--wa-color-neutral-spot);
+      color: var(--wa-color-neutral-fill-loud);
     }
   }
 
@@ -184,8 +184,8 @@ header {
 
   .site-search-result-title {
     font-size: 1.25rem;
-    font-weight: var(--wa-font-weight-medium);
-    color: var(--wa-color-brand-text-on-fill);
+    font-weight: var(--wa-font-weight-semibold);
+    color: var(--wa-color-brand-on-normal);
   }
 
   .site-search-result-description {
@@ -224,12 +224,13 @@ header {
 #site-search footer {
   flex: 0 0 auto;
   display: flex;
+  flex-direction: row;
   justify-content: center;
   gap: 2rem;
   color: var(--wa-color-text-quiet);
-  border-top: var(--wa-panel-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-subtle);
-  border-bottom-left-radius: var(--wa-corners-m);
-  border-bottom-right-radius: var(--wa-corners-m);
+  border-top: var(--wa-panel-border-style) var(--wa-panel-border-width) var(--wa-color-neutral-border-quiet);
+  border-bottom-left-radius: var(--wa-border-radius-m);
+  border-bottom-right-radius: var(--wa-border-radius-m);
   padding: 1rem;
 
   kbd {
@@ -237,7 +238,7 @@ header {
     height: 1.35rem;
     justify-content: center;
     align-items: center;
-    font-weight: var(--wa-font-weight-heavy);
+    font-weight: var(--wa-font-weight-bold);
 
     &:last-of-type {
       margin-inline-end: 0.25rem;

docs/assets/styles/theme-headers.css

@@ -0,0 +1,50 @@
+/* #region Custom Styles */
+@container preview (min-width: 0) {
+  .hero-background {
+    height: 47rem;
+    background-color: var(--wa-color-brand-fill-loud);
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    z-index: -1;
+  }
+
+  .hero-background::after {
+    background: url(/assets/images/themer/default/hero.png) 10rem bottom no-repeat;
+    background-size: 95%;
+    content: '';
+    position: absolute;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    left: 0;
+  }
+
+  .hero wa-button[variant='brand'] {
+    --background: var(--wa-color-neutral-fill-quiet);
+    --label-color: var(--wa-color-neutral-on-normal);
+  }
+
+  .project-header {
+    color: var(--wa-color-brand-on-loud);
+  }
+
+  .strata.hero {
+    height: 26rem;
+  }
+
+  .hero .title {
+    margin-inline-end: 40%;
+    color: var(--wa-color-brand-on-loud);
+  }
+}
+
+/* responsive */
+@container preview (min-width: 1040px) {
+  .hero-background::after {
+    background-position: right bottom;
+    background-size: 90%;
+  }
+}
+/* #endregion */

docs/docs/components/animated-image.md

@@ -1,7 +1,7 @@
 ---
 title: Animated Image
 description: A component for displaying animated GIFs and WEBPs that play and pause on interaction.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/animation.md

@@ -1,7 +1,7 @@
 ---
 title: Animation
 description: Animate elements declaratively with nearly 100 baked-in presets, or roll your own with custom keyframes.
-layout: component.njk
+layout: component
 ---
 
 To animate an element, wrap it in `<wa-animation>` and set an animation `name`. The animation will not start until you add the `play` attribute. Refer to the [properties table](#properties) for a list of all animation options.
@@ -19,7 +19,7 @@ To animate an element, wrap it in `<wa-animation>` and set an animation `name`.
     display: inline-block;
     width: 100px;
     height: 100px;
-    background-color: var(--wa-color-brand-spot);
+    background-color: var(--wa-color-brand-fill-loud);
     margin: 1.5rem;
   }
 </style>
@@ -85,7 +85,7 @@ This example demonstrates all of the baked-in animations and easings. Animations
   .animation-sandbox .box {
     width: 100px;
     height: 100px;
-    background-color: var(--wa-color-brand-spot);
+    background-color: var(--wa-color-brand-fill-loud);
   }
 
   .animation-sandbox .controls {
@@ -131,7 +131,7 @@ Use an [Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/
     display: inline-block;
     width: 100px;
     height: 100px;
-    background-color: var(--wa-color-brand-spot);
+    background-color: var(--wa-color-brand-fill-loud);
   }
 </style>
 ```
@@ -171,7 +171,7 @@ Supply your own [keyframe formats](https://developer.mozilla.org/en-US/docs/Web/
   .animation-keyframes .box {
     width: 100px;
     height: 100px;
-    background-color: var(--wa-color-brand-spot);
+    background-color: var(--wa-color-brand-fill-loud);
   }
 </style>
 ```

docs/docs/components/avatar.md

@@ -1,7 +1,7 @@
 ---
 title: Avatar
 description: Avatars are used to represent a person or object.
-layout: component.njk
+layout: component
 ---
 
 By default, a generic icon will be shown. You can personalize avatars by adding custom icons, initials, and images. You should always provide a `label` for assistive devices.

docs/docs/components/badge.md

@@ -1,7 +1,7 @@
 ---
 title: Badge
 description: Badges are used to draw attention and display statuses or counts.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/breadcrumb-item.md

@@ -1,7 +1,7 @@
 ---
 title: Breadcrumb Item
 description: Breadcrumb Items are used inside breadcrumbs to represent different links.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/breadcrumb.md

@@ -1,7 +1,7 @@
 ---
 title: Breadcrumb
 description: Breadcrumbs provide a group of links so users can easily navigate a website's hierarchy.
-layout: component.njk
+layout: component
 ---
 
 Breadcrumbs are usually placed before a page's main content with the current page shown last to indicate the user's position in the navigation.

docs/docs/components/button-group.md

@@ -1,7 +1,7 @@
 ---
 title: Button Group
 description: Button groups can be used to group related buttons into sections.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/button.md

@@ -1,7 +1,7 @@
 ---
 title: Button
 description: Buttons represent actions that are available to the user.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}
@@ -12,16 +12,53 @@ layout: component.njk
 
 ### Variants
 
-Use the `variant` attribute to set the button's variant.
+Use the `variant` attribute to set the button's semantic variant.
 
 ```html {.example}
+<wa-button variant="neutral">Neutral</wa-button>
 <wa-button variant="brand">Brand</wa-button>
 <wa-button variant="success">Success</wa-button>
-<wa-button variant="neutral">Neutral</wa-button>
 <wa-button variant="warning">Warning</wa-button>
 <wa-button variant="danger">Danger</wa-button>
 ```
 
+### Appearance
+
+Use the `appearance` attribute to change the button's visual appearance.
+
+```html {.example}
+<div style="margin-block-end: 1rem;">
+  <wa-button appearance="filled" variant="neutral">Filled</wa-button>
+  <wa-button appearance="tinted" variant="neutral">Tinted</wa-button>
+  <wa-button appearance="outline" variant="neutral">Outline</wa-button>
+  <wa-button appearance="text" variant="neutral">Text</wa-button>
+</div>
+<div style="margin-block-end: 1rem;">
+  <wa-button appearance="filled" variant="brand">Filled</wa-button>
+  <wa-button appearance="tinted" variant="brand">Tinted</wa-button>
+  <wa-button appearance="outline" variant="brand">Outline</wa-button>
+  <wa-button appearance="text" variant="brand">Text</wa-button>
+</div>
+<div style="margin-block-end: 1rem;">
+  <wa-button appearance="filled" variant="success">Filled</wa-button>
+  <wa-button appearance="tinted" variant="success">Tinted</wa-button>
+  <wa-button appearance="outline" variant="success">Outline</wa-button>
+  <wa-button appearance="text" variant="success">Text</wa-button>
+</div>
+<div style="margin-block-end: 1rem;">
+  <wa-button appearance="filled" variant="warning">Filled</wa-button>
+  <wa-button appearance="tinted" variant="warning">Tinted</wa-button>
+  <wa-button appearance="outline" variant="warning">Outline</wa-button>
+  <wa-button appearance="text" variant="warning">Text</wa-button>
+</div>
+<div>
+  <wa-button appearance="filled" variant="danger">Filled</wa-button>
+  <wa-button appearance="tinted" variant="danger">Tinted</wa-button>
+  <wa-button appearance="outline" variant="danger">Outline</wa-button>
+  <wa-button appearance="text" variant="danger">Text</wa-button>
+</div>
+```
+
 ### Sizes
 
 Use the `size` attribute to change a button's size.
@@ -32,18 +69,6 @@ Use the `size` attribute to change a button's size.
 <wa-button size="large">Large</wa-button>
 ```
 
-### Outline Buttons
-
-Use the `outline` attribute to draw outlined buttons with transparent backgrounds.
-
-```html {.example}
-<wa-button variant="brand" outline>Brand</wa-button>
-<wa-button variant="success" outline>Success</wa-button>
-<wa-button variant="neutral" outline>Neutral</wa-button>
-<wa-button variant="warning" outline>Warning</wa-button>
-<wa-button variant="danger" outline>Danger</wa-button>
-```
-
 ### Pill Buttons
 
 Use the `pill` attribute to give buttons rounded edges.
@@ -54,16 +79,6 @@ Use the `pill` attribute to give buttons rounded edges.
 <wa-button size="large" pill>Large</wa-button>
 ```
 
-### Text Buttons
-
-Use the `text` variant to create text buttons that share the same size as regular buttons but don't have backgrounds or borders.
-
-```html {.example}
-<wa-button variant="text" size="small">Text</wa-button>
-<wa-button variant="text" size="medium">Text</wa-button>
-<wa-button variant="text" size="large">Text</wa-button>
-```
-
 ### Link Buttons
 
 It's often helpful to have a button that works like a link. This is possible by setting the `href` attribute, which will make the component render an `<a>` under the hood. This gives you all the default link behavior the browser provides (e.g. [[CMD/CTRL/SHIFT]] + [[CLICK]]) and exposes the `target` and `download` attributes.
@@ -178,7 +193,6 @@ Use the `disabled` attribute to disable a button.
 <wa-button variant="success" disabled>Success</wa-button>
 <wa-button variant="neutral" disabled>Neutral</wa-button>
 <wa-button variant="warning" disabled>Warning</wa-button>
-<wa-button variant="danger" disabled>Danger</wa-button>
 ```
 
 ### Styling Buttons
@@ -200,7 +214,7 @@ This example demonstrates how to style buttons using a custom class. This is the
     color: white;
     font-size: 1.125rem;
     box-shadow: 0 2px 10px #0002;
-    transition: var(--wa-transition-normal) all;
+    transition: all var(--wa-transition-slow) var(--wa-transition-easing);
   }
 
   wa-button.pink::part(base):hover {

docs/docs/components/callout.md

@@ -1,7 +1,7 @@
 ---
 title: Callout
 description: Callouts are used to display important messages inline.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/card.md

@@ -1,7 +1,7 @@
 ---
 title: Card
 description: Cards can be used to group related subjects in a container.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/carousel-item.md

@@ -1,7 +1,7 @@
 ---
 title: Carousel Item
 description: A carousel item represent a slide within a carousel.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/carousel.md

@@ -1,7 +1,7 @@
 ---
 title: Carousel
 description: Carousels display an arbitrary number of content slides along a horizontal or vertical axis.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/checkbox.md

@@ -1,7 +1,7 @@
 ---
 title: Checkbox
 description: Checkboxes allow the user to toggle an option on or off.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/color-picker.md

@@ -1,7 +1,7 @@
 ---
 title: Color Picker
 description: Color pickers allow the user to select a color.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/copy-button.md

@@ -1,7 +1,7 @@
 ---
 title: Copy Button
 description: Copies data to the clipboard when the user clicks the button.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}
@@ -111,7 +111,7 @@ You can customize the button to your liking with CSS.
     border-right-color: #ad005c;
     border-bottom-color: #ad005c;
     border-radius: 6px;
-    transition: var(--wa-transition-normal) all;
+    transition: all var(--wa-transition-slow) var(--wa-transition-easing);
   }
 
   .custom-styles::part(button):hover {

docs/docs/components/details.md

@@ -1,7 +1,7 @@
 ---
 title: Details
 description: Details show a brief summary and expand to show additional content.
-layout: component.njk
+layout: component
 ---
 
 <!-- cspell:dictionaries lorem-ipsum -->

docs/docs/components/dialog.md

@@ -1,7 +1,7 @@
 ---
 title: Dialog
 description: 'Dialogs, sometimes called "modals", appear above the page and require the user''s immediate attention.'
-layout: component.njk
+layout: component
 ---
 
 <!-- cspell:dictionaries lorem-ipsum -->
@@ -9,7 +9,7 @@ layout: component.njk
 ```html {.example}
 <wa-dialog label="Dialog" with-header with-footer class="dialog-overview">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-  <wa-button slot="footer" variant="brand" data-dialog="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
 </wa-dialog>
 
 <wa-button>Open Dialog</wa-button>
@@ -50,7 +50,7 @@ Footers can be used to display titles and more. Use the `with-footer` attribute
 ```html {.example}
 <wa-dialog label="Dialog" with-footer class="dialog-footer">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-  <wa-button slot="footer" variant="brand" data-dialog="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
 </wa-dialog>
 
 <wa-button>Open Dialog</wa-button>
@@ -65,12 +65,12 @@ Footers can be used to display titles and more. Use the `with-footer` attribute
 
 ### Dismissing Dialogs
 
-You can add the special `data-dialog="dismiss"` attribute to a button inside the dialog to tell it to close without additional JavaScript. Alternatively, you can set the `open` property to `false` to close the dialog programmatically.
+You can add the special `data-dialog="close"` attribute to a button inside the dialog to tell it to close without additional JavaScript. Alternatively, you can set the `open` property to `false` to close the dialog programmatically.
 
 ```html {.example}
 <wa-dialog label="Dialog" with-header with-footer class="dialog-dismiss">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-  <wa-button slot="footer" variant="brand" data-dialog="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
 </wa-dialog>
 
 <wa-button>Open Dialog</wa-button>
@@ -90,7 +90,7 @@ Use the `--width` custom property to set the dialog's width.
 ```html {.example}
 <wa-dialog label="Dialog" with-header with-footer class="dialog-width" style="--width: 50vw;">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-  <wa-button slot="footer" variant="brand" data-dialog="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
 </wa-dialog>
 
 <wa-button>Open Dialog</wa-button>
@@ -112,7 +112,7 @@ By design, a dialog's height will never exceed that of the viewport. As such, di
   <div style="height: 150vh; border: dashed 2px var(--wa-color-surface-border); padding: 0 1rem;">
     <p>Scroll down and give it a try! 👇</p>
   </div>
-  <wa-button slot="footer" variant="brand" data-dialog="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
 </wa-dialog>
 
 <wa-button>Open Dialog</wa-button>
@@ -133,7 +133,7 @@ The header shows a functional close button by default. You can use the `header-a
 <wa-dialog label="Dialog" with-header with-footer class="dialog-header-actions">
   <wa-icon-button class="new-window" slot="header-actions" name="arrow-up-right-from-square" variant="solid"></wa-icon-button>
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-  <wa-button slot="footer" variant="brand" data-dialog="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
 </wa-dialog>
 
 <wa-button>Open Dialog</wa-button>
@@ -155,7 +155,7 @@ If you want the dialog to close when the user clicks on the overlay, add the `li
 ```html {.example}
 <wa-dialog label="Dialog" light-dismiss with-header with-footer class="dialog-light-dismiss">
   This dialog will close when you click on the overlay.
-  <wa-button slot="footer" variant="brand" data-dialog="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
 </wa-dialog>
 
 <wa-button>Open Dialog</wa-button>
@@ -179,7 +179,7 @@ You can use `event.detail.source` to determine which element triggered the reque
 ```html {.example}
 <wa-dialog label="Dialog" with-header with-footer class="dialog-deny-close">
   This dialog will only close when you click the button below.
-  <wa-button slot="footer" variant="brand" data-dialog="dismiss">Only this button will close it</wa-button>
+  <wa-button slot="footer" variant="brand" data-dialog="close">Only this button will close it</wa-button>
 </wa-dialog>
 
 <wa-button>Open Dialog</wa-button>
@@ -207,7 +207,7 @@ To give focus to a specific element when the dialog opens, use the `autofocus` a
 ```html {.example}
 <wa-dialog label="Dialog" with-header with-footer class="dialog-focus">
   <wa-input autofocus placeholder="I will have focus when the dialog is opened"></wa-input>
-  <wa-button slot="footer" variant="brand" data-dialog="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
 </wa-dialog>
 
 <wa-button>Open Dialog</wa-button>

docs/docs/components/divider.md

@@ -1,7 +1,7 @@
 ---
 title: Divider
 description: Dividers are used to visually separate or group elements.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/drawer.md

@@ -1,7 +1,7 @@
 ---
 title: Drawer
 description: Drawers slide in from a container to expose additional options and information.
-layout: component.njk
+layout: component
 ---
 
 <!-- cspell:dictionaries lorem-ipsum -->
@@ -9,7 +9,7 @@ layout: component.njk
 ```html {.example}
 <wa-drawer label="Drawer" with-header with-footer class="drawer-overview">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-  <wa-button slot="footer" variant="brand" data-drawer="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
 
 <wa-button>Open Drawer</wa-button>
@@ -50,7 +50,7 @@ Footers can be used to display titles and more. Use the `with-footer` attribute
 ```html {.example}
 <wa-drawer label="Drawer" with-footer class="drawer-footer">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-  <wa-button slot="footer" variant="brand" data-drawer="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
 
 <wa-button>Open Drawer</wa-button>
@@ -65,12 +65,12 @@ Footers can be used to display titles and more. Use the `with-footer` attribute
 
 ### Dismissing Drawers
 
-You can add the special `data-drawer="dismiss"` attribute to a button inside the drawer to tell it to close without additional JavaScript. Alternatively, you can set the `open` property to `false` to close the drawer programmatically.
+You can add the special `data-drawer="close"` attribute to a button inside the drawer to tell it to close without additional JavaScript. Alternatively, you can set the `open` property to `false` to close the drawer programmatically.
 
 ```html {.example}
 <wa-drawer label="Drawer" with-header with-footer class="drawer-dismiss">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-  <wa-button slot="footer" variant="brand" data-drawer="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
 
 <wa-button>Open Drawer</wa-button>
@@ -90,7 +90,7 @@ By default, drawers slide in from the end. To make the drawer slide in from the
 ```html {.example}
 <wa-drawer label="Drawer" with-header with-footer placement="start" class="drawer-placement-start">
   This drawer slides in from the start.
-  <wa-button slot="footer" variant="brand" data-drawer="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
 
 <wa-button>Open Drawer</wa-button>
@@ -110,7 +110,7 @@ To make the drawer slide in from the top, set the `placement` attribute to `top`
 ```html {.example}
 <wa-drawer label="Drawer" with-header with-footer placement="top" class="drawer-placement-top">
   This drawer slides in from the top.
-  <wa-button slot="footer" variant="brand" data-drawer="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
 
 <wa-button>Open Drawer</wa-button>
@@ -130,7 +130,7 @@ To make the drawer slide in from the bottom, set the `placement` attribute to `b
 ```html {.example}
 <wa-drawer label="Drawer" with-header with-footer placement="bottom" class="drawer-placement-bottom">
   This drawer slides in from the bottom.
-  <wa-button slot="footer" variant="brand" data-drawer="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
 
 <wa-button>Open Drawer</wa-button>
@@ -150,7 +150,7 @@ Use the `--size` custom property to set the drawer's size. This will be applied
 ```html {.example}
 <wa-drawer label="Drawer" with-header with-footer class="drawer-custom-size" style="--size: 50vw;">
   This drawer is always 50% of the viewport.
-  <wa-button slot="footer" variant="brand" data-drawer="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
 
 <wa-button>Open Drawer</wa-button>
@@ -172,7 +172,7 @@ By design, a drawer's height will never exceed 100% of its container. As such, d
   <div style="height: 150vh; border: dashed 2px var(--wa-color-surface-border); padding: 0 1rem;">
     <p>Scroll down and give it a try! 👇</p>
   </div>
-  <wa-button slot="footer" variant="brand" data-drawer="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
 
 <wa-button>Open Drawer</wa-button>
@@ -193,7 +193,7 @@ The header shows a functional close button by default. You can use the `header-a
 <wa-drawer label="Drawer" with-header with-footer class="drawer-header-actions">
   <wa-icon-button class="new-window" slot="header-actions" name="arrow-up-right-from-square" variant="solid"></wa-icon-button>
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-  <wa-button slot="footer" variant="brand" data-drawer="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
 
 <wa-button>Open Drawer</wa-button>
@@ -215,7 +215,7 @@ If you want the drawer to close when the user clicks on the overlay, add the `li
 ```html {.example}
 <wa-drawer label="Drawer" light-dismiss with-header with-footer class="drawer-light-dismiss">
   This drawer will close when you click on the overlay.
-  <wa-button slot="footer" variant="brand" data-drawer="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
 
 <wa-button>Open Drawer</wa-button>
@@ -239,7 +239,7 @@ You can use `event.detail.source` to determine what triggered the request to clo
 ```html {.example}
 <wa-drawer label="Drawer" with-header with-footer class="drawer-deny-close">
   This drawer will only close when you click the button below.
-  <wa-button slot="footer" variant="brand" data-drawer="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
 
 <wa-button>Open Drawer</wa-button>
@@ -267,7 +267,7 @@ By default, the drawer's panel will gain focus when opened. This allows a subseq
 ```html {.example}
 <wa-drawer label="Drawer" with-header with-footer class="drawer-focus">
   <wa-input autofocus placeholder="I will have focus when the drawer is opened"></wa-input>
-  <wa-button slot="footer" variant="brand" data-drawer="dismiss">Close</wa-button>
+  <wa-button slot="footer" variant="brand" data-drawer="close">Close</wa-button>
 </wa-drawer>
 
 <wa-button>Open Drawer</wa-button>

docs/docs/components/dropdown.md

@@ -1,7 +1,7 @@
 ---
 title: Dropdown
 description: 'Dropdowns expose additional content that "drops down" in a panel.'
-layout: component.njk
+layout: component
 ---
 
 Dropdowns consist of a trigger and a panel. By default, activating the trigger will expose the panel and interacting outside of the panel will close it.

docs/docs/components/format-bytes.md

@@ -1,7 +1,7 @@
 ---
 title: Format Bytes
 description: Formats a number as a human readable bytes value.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/format-date.md

@@ -1,7 +1,7 @@
 ---
 title: Format Date
 description: Formats a date/time using the specified locale and options.
-layout: component.njk
+layout: component
 ---
 
 Localization is handled by the browser's [`Intl.DateTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). No language packs are required.

docs/docs/components/format-number.md

@@ -1,7 +1,7 @@
 ---
 title: Format Number
 description: Formats a number using the specified locale and options.
-layout: component.njk
+layout: component
 ---
 
 Localization is handled by the browser's [`Intl.NumberFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat). No language packs are required.

docs/docs/components/icon-button.md

@@ -1,7 +1,7 @@
 ---
 title: Icon Button
 description: Icons buttons are simple, icon-only buttons that can be used for actions and in toolbars.
-layout: component.njk
+layout: component
 ---
 
 For a full list of icons that come bundled with Web Awesome, refer to the [icon component](/components/icon).

docs/docs/components/icon.md

@@ -1,7 +1,7 @@
 ---
 title: Icon
 description: Icons are symbols that can be used to represent various options within an application.
-layout: component.njk
+layout: component
 ---
 
 Web Awesome comes bundled with over 2,000 free icons courtesy of [Font Awesome](https://fontawesome.com/). These icons are part of the `default` icon library. Font Awesome Pro users can unlock additional icon families. Or, if you prefer, you can register your own [custom icon library](#icon-library).

docs/docs/components/image-comparer.md

@@ -1,7 +1,7 @@
 ---
 title: Image Comparer
 description: Compare visual differences between similar photos with a sliding panel.
-layout: component.njk
+layout: component
 ---
 
 For best results, use images that share the same dimensions. The slider can be controlled by dragging or pressing the left and right arrow keys. (Tip: press shift + arrows to move the slider in larger intervals, or home + end to jump to the beginning or end.)

docs/docs/components/include.md

@@ -1,7 +1,7 @@
 ---
 title: Include
 description: Includes give you the power to embed external HTML files into the page.
-layout: component.njk
+layout: component
 ---
 
 Included files are asynchronously requested using `window.fetch()`. Requests are cached, so the same file can be included multiple times, but only one request will be made.

docs/docs/components/input.md

@@ -1,7 +1,7 @@
 ---
 title: Input
 description: Inputs collect data from the user.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/menu-item.md

@@ -1,7 +1,7 @@
 ---
 title: Menu Item
 description: Menu items provide options for the user to pick from in a menu.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/menu-label.md

@@ -1,7 +1,7 @@
 ---
 title: Menu Label
 description: Menu labels are used to describe a group of menu items.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/menu.md

@@ -1,7 +1,7 @@
 ---
 title: Menu
 description: Menus provide a list of options for the user to choose from.
-layout: component.njk
+layout: component
 ---
 
 You can use [menu items](/components/menu-item), [menu labels](/components/menu-label), and [dividers](/components/divider) to compose a menu. Menus support keyboard interactions, including type-to-select an option.

docs/docs/components/mutation-observer.md

@@ -1,7 +1,7 @@
 ---
 title: Mutation Observer
 description: The Mutation Observer component offers a thin, declarative interface to the MutationObserver API.
-layout: component.njk
+layout: component
 ---
 
 The mutation observer will report changes to the content it wraps through the `wa-mutation` event. When emitted, a collection of [MutationRecord](https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord) objects will be attached to `event.detail` that contains information about how it changed.

docs/docs/components/option.md

@@ -1,7 +1,7 @@
 ---
 title: Option
 description: Options define the selectable items within various form controls such as select.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/page.md

@@ -1,7 +1,7 @@
 ---
 title: Page
 description: Layouts offer an easy way to scaffold pages using minimal markup.
-layout: 'component.njk'
+layout: component
 ---
 
 The layout component is designed to power full webpages. It is flexible enough to handle most modern designs and includes a simple mechanism for handling desktop and mobile navigation.

docs/docs/components/popup.md

@@ -1,7 +1,7 @@
 ---
 title: Popup
 description: 'Popup is a utility that lets you declaratively anchor "popup" containers to another element.'
-layout: component.njk
+layout: component
 ---
 
 This component's name is inspired by [`<popup>`](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/Popup/explainer.md). It uses [Floating UI](https://floating-ui.com/) under the hood to provide a well-tested, lightweight, and fully declarative positioning utility for tooltips, dropdowns, and more.
@@ -62,22 +62,22 @@ Popup is a low-level utility built specifically for positioning elements. Do not
 
 <style>
   .popup-overview wa-popup {
-    --arrow-color: var(--wa-color-brand-spot);
+    --arrow-color: var(--wa-color-brand-fill-loud);
   }
 
   .popup-overview span[slot='anchor'] {
     display: inline-block;
     width: 150px;
     height: 150px;
-    border: dashed 2px var(--wa-color-neutral-spot);
+    border: dashed 2px var(--wa-color-neutral-fill-loud);
     margin: 50px;
   }
 
   .popup-overview .box {
     width: 100px;
     height: 50px;
-    background: var(--wa-color-brand-spot);
-    border-radius: var(--wa-corners-s);
+    background: var(--wa-color-brand-fill-loud);
+    border-radius: var(--wa-border-radius-s);
   }
 
   .popup-overview-options {
@@ -127,15 +127,15 @@ Popups are inactive and hidden until the `active` attribute is applied. Removing
     display: inline-block;
     width: 150px;
     height: 150px;
-    border: dashed 2px var(--wa-color-neutral-spot);
+    border: dashed 2px var(--wa-color-neutral-fill-loud);
     margin: 50px;
   }
 
   .popup-active .box {
     width: 100px;
     height: 50px;
-    background: var(--wa-color-brand-spot);
-    border-radius: var(--wa-corners-s);
+    background: var(--wa-color-brand-fill-loud);
+    border-radius: var(--wa-border-radius-s);
   }
 </style>
 
@@ -164,15 +164,15 @@ By default, anchors are slotted into the popup using the `anchor` slot. If your
     display: inline-block;
     width: 150px;
     height: 150px;
-    border: dashed 2px var(--wa-color-neutral-spot);
+    border: dashed 2px var(--wa-color-neutral-fill-loud);
     margin: 50px 0 0 50px;
   }
 
   #external-anchor ~ wa-popup .box {
     width: 100px;
     height: 50px;
-    background: var(--wa-color-brand-spot);
-    border-radius: var(--wa-corners-s);
+    background: var(--wa-color-brand-fill-loud);
+    border-radius: var(--wa-border-radius-s);
   }
 </style>
 ```
@@ -211,15 +211,15 @@ Since placement is preferred when using `flip`, you can observe the popup's curr
     display: inline-block;
     width: 150px;
     height: 150px;
-    border: dashed 2px var(--wa-color-neutral-spot);
+    border: dashed 2px var(--wa-color-neutral-fill-loud);
     margin: 50px;
   }
 
   .popup-placement .box {
     width: 100px;
     height: 50px;
-    background: var(--wa-color-brand-spot);
-    border-radius: var(--wa-corners-s);
+    background: var(--wa-color-brand-fill-loud);
+    border-radius: var(--wa-border-radius-s);
   }
 
   .popup-placement wa-select {
@@ -255,15 +255,15 @@ Use the `distance` attribute to change the distance between the popup and its an
     display: inline-block;
     width: 150px;
     height: 150px;
-    border: dashed 2px var(--wa-color-neutral-spot);
+    border: dashed 2px var(--wa-color-neutral-fill-loud);
     margin: 50px;
   }
 
   .popup-distance .box {
     width: 100px;
     height: 50px;
-    background: var(--wa-color-brand-spot);
-    border-radius: var(--wa-corners-s);
+    background: var(--wa-color-brand-fill-loud);
+    border-radius: var(--wa-border-radius-s);
   }
 
   .popup-distance wa-range {
@@ -299,15 +299,15 @@ The `skidding` attribute is similar to `distance`, but instead allows you to off
     display: inline-block;
     width: 150px;
     height: 150px;
-    border: dashed 2px var(--wa-color-neutral-spot);
+    border: dashed 2px var(--wa-color-neutral-fill-loud);
     margin: 50px;
   }
 
   .popup-skidding .box {
     width: 100px;
     height: 50px;
-    background: var(--wa-color-brand-spot);
-    border-radius: var(--wa-corners-s);
+    background: var(--wa-color-brand-fill-loud);
+    border-radius: var(--wa-border-radius-s);
   }
 
   .popup-skidding wa-range {
@@ -367,22 +367,22 @@ By default, the arrow will be aligned as close to the center of the _anchor_ as
 
   <style>
     .popup-arrow wa-popup {
-      --arrow-color: var(--wa-color-brand-spot);
+      --arrow-color: var(--wa-color-brand-fill-loud);
     }
 
     .popup-arrow span[slot='anchor'] {
       display: inline-block;
       width: 150px;
       height: 150px;
-      border: dashed 2px var(--wa-color-neutral-spot);
+      border: dashed 2px var(--wa-color-neutral-fill-loud);
       margin: 50px;
     }
 
     .popup-arrow .box {
       width: 100px;
       height: 50px;
-      background: var(--wa-color-brand-spot);
-      border-radius: var(--wa-corners-s);
+      background: var(--wa-color-brand-fill-loud);
+      border-radius: var(--wa-border-radius-s);
     }
 
     .popup-arrow-options {
@@ -439,7 +439,7 @@ Use the `sync` attribute to make the popup the same width or height as the ancho
     display: inline-block;
     width: 150px;
     height: 150px;
-    border: dashed 2px var(--wa-color-neutral-spot);
+    border: dashed 2px var(--wa-color-neutral-fill-loud);
     margin: 50px;
   }
 
@@ -448,8 +448,8 @@ Use the `sync` attribute to make the popup the same width or height as the ancho
     height: 100%;
     min-width: 50px;
     min-height: 50px;
-    background: var(--wa-color-brand-spot);
-    border-radius: var(--wa-corners-s);
+    background: var(--wa-color-brand-fill-loud);
+    border-radius: var(--wa-border-radius-s);
   }
 
   .popup-sync wa-select {
@@ -501,15 +501,15 @@ Toggle the switch and scroll the container to see the difference.
     display: inline-block;
     width: 150px;
     height: 150px;
-    border: dashed 2px var(--wa-color-neutral-spot);
+    border: dashed 2px var(--wa-color-neutral-fill-loud);
     margin: 150px 50px;
   }
 
   .popup-strategy .box {
     width: 100px;
     height: 50px;
-    background: var(--wa-color-brand-spot);
-    border-radius: var(--wa-corners-s);
+    background: var(--wa-color-brand-fill-loud);
+    border-radius: var(--wa-border-radius-s);
   }
 
   .popup-strategy wa-switch {
@@ -557,15 +557,15 @@ Scroll the container to see how the popup flips to prevent clipping.
     display: inline-block;
     width: 150px;
     height: 150px;
-    border: dashed 2px var(--wa-color-neutral-spot);
+    border: dashed 2px var(--wa-color-neutral-fill-loud);
     margin: 150px 50px;
   }
 
   .popup-flip .box {
     width: 100px;
     height: 50px;
-    background: var(--wa-color-brand-spot);
-    border-radius: var(--wa-corners-s);
+    background: var(--wa-color-brand-fill-loud);
+    border-radius: var(--wa-border-radius-s);
   }
 </style>
 
@@ -610,15 +610,15 @@ Scroll the container to see how the popup changes it's fallback placement to pre
     display: inline-block;
     width: 150px;
     height: 150px;
-    border: dashed 2px var(--wa-color-neutral-spot);
+    border: dashed 2px var(--wa-color-neutral-fill-loud);
     margin: 250px 50px;
   }
 
   .popup-flip-fallbacks .box {
     width: 100px;
     height: 50px;
-    background: var(--wa-color-brand-spot);
-    border-radius: var(--wa-corners-s);
+    background: var(--wa-color-brand-fill-loud);
+    border-radius: var(--wa-border-radius-s);
   }
 </style>
 ```
@@ -652,15 +652,15 @@ Toggle the switch to see the difference.
     display: inline-block;
     width: 150px;
     height: 150px;
-    border: dashed 2px var(--wa-color-neutral-spot);
+    border: dashed 2px var(--wa-color-neutral-fill-loud);
     margin: 60px 0 0 10px;
   }
 
   .popup-shift .box {
     width: 300px;
     height: 50px;
-    background: var(--wa-color-brand-spot);
-    border-radius: var(--wa-corners-s);
+    background: var(--wa-color-brand-fill-loud);
+    border-radius: var(--wa-border-radius-s);
   }
 </style>
 
@@ -706,13 +706,13 @@ Scroll the container to see the popup resize as its available space changes.
     display: inline-block;
     width: 150px;
     height: 150px;
-    border: dashed 2px var(--wa-color-neutral-spot);
+    border: dashed 2px var(--wa-color-neutral-fill-loud);
     margin: 250px 50px 100px 50px;
   }
 
   .popup-auto-size .box {
-    background: var(--wa-color-brand-spot);
-    border-radius: var(--wa-corners-s);
+    background: var(--wa-color-brand-fill-loud);
+    border-radius: var(--wa-border-radius-s);
 
     /* This sets the preferred size of the popup's content */
     width: 100px;
@@ -754,15 +754,15 @@ When a gap exists between the anchor and the popup element, this option will add
     display: inline-block;
     width: 150px;
     height: 150px;
-    border: dashed 2px var(--wa-color-neutral-spot);
+    border: dashed 2px var(--wa-color-neutral-fill-loud);
     margin: 50px;
   }
 
   .popup-hover-bridge .box {
     width: 100px;
     height: 50px;
-    background: var(--wa-color-brand-spot);
-    border-radius: var(--wa-corners-s);
+    background: var(--wa-color-brand-fill-loud);
+    border-radius: var(--wa-border-radius-s);
   }
 
   .popup-hover-bridge wa-range {
@@ -865,7 +865,7 @@ This example anchors a popup to the mouse cursor using a virtual element. As suc
   .popup-virtual-element .circle {
     width: 100px;
     height: 100px;
-    border: solid 4px var(--wa-color-neutral-spot);
+    border: solid 4px var(--wa-color-neutral-fill-loud);
     border-radius: 50%;
     translate: -50px -50px;
     animation: 1s virtual-cursor infinite;

docs/docs/components/progress-bar.md

@@ -1,7 +1,7 @@
 ---
 title: Progress Bar
 description: Progress bars are used to show the status of an ongoing operation.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/progress-ring.md

@@ -1,7 +1,7 @@
 ---
 title: Progress Ring
 description: Progress rings are used to show the progress of a determinate operation in a circular fashion.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/qr-code.md

@@ -1,7 +1,7 @@
 ---
 title: QR Code
 description: Generates a QR code and renders it using the Canvas API.
-layout: component.njk
+layout: component
 ---
 
 QR codes are useful for providing small pieces of information to users who can quickly scan them with a smartphone. Most smartphones have built-in QR code scanners, so simply pointing the camera at a QR code will decode it and allow the user to visit a website, dial a phone number, read a message, etc.

docs/docs/components/radio-button.md

@@ -1,7 +1,7 @@
 ---
 title: Radio Button
 description: Radios buttons allow the user to select a single option from a group using a button-like control.
-layout: component.njk
+layout: component
 ---
 
 Radio buttons are designed to be used with [radio groups](/components/radio-group). When a radio button has focus, the arrow keys can be used to change the selected option just like standard radio controls.

docs/docs/components/radio-group.md

@@ -1,7 +1,7 @@
 ---
 title: Radio Group
 description: Radio groups are used to group multiple radios or radio buttons so they function as a single form control.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/radio.md

@@ -1,7 +1,7 @@
 ---
 title: Radio
 description: Radios allow the user to select a single option from a group.
-layout: component.njk
+layout: component
 ---
 
 Radios are designed to be used with [radio groups](/components/radio-group).

docs/docs/components/range.md

@@ -1,7 +1,7 @@
 ---
 title: Range
 description: Ranges allow the user to select a single value within a given range using a slider.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}
@@ -69,8 +69,8 @@ You can customize the active and inactive portions of the track using the `--tra
 ```html {.example}
 <wa-range
   style="
-  --track-color-active: var(--wa-color-brand-spot);
-  --track-color-inactive: var(--wa-color-brand-fill-highlight);
+  --track-color-active: var(--wa-color-brand-fill-loud);
+  --track-color-inactive: var(--wa-color-brand-fill-normal);
 "
 ></wa-range>
 ```
@@ -84,8 +84,8 @@ You can customize the initial offset of the active track using the `--track-acti
   min="-100"
   max="100"
   style="
-  --track-color-active: var(--wa-color-brand-spot);
-  --track-color-inactive: var(--wa-color-brand-fill-highlight);
+  --track-color-active: var(--wa-color-brand-fill-loud);
+  --track-color-inactive: var(--wa-color-brand-fill-normal);
   --track-active-offset: 50%;
 "
 ></wa-range>

docs/docs/components/rating.md

@@ -1,7 +1,7 @@
 ---
 title: Rating
 description: Ratings give users a way to quickly view and provide feedback.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}
@@ -90,9 +90,9 @@ The event has a payload with `phase` and `value` properties. The `phase` propert
     position: relative;
     top: -4px;
     left: 8px;
-    border-radius: var(--wa-corners-s);
-    background: var(--wa-color-neutral-spot);
-    color: var(--wa-color-neutral-text-on-spot);
+    border-radius: var(--wa-border-radius-s);
+    background: var(--wa-color-neutral-fill-loud);
+    color: var(--wa-color-neutral-on-loud);
     text-align: center;
     padding: 4px 6px;
   }

docs/docs/components/relative-time.md

@@ -1,7 +1,7 @@
 ---
 title: Relative Time
 description: Outputs a localized time phrase relative to the current date and time.
-layout: component.njk
+layout: component
 ---
 
 Localization is handled by the browser's [`Intl.RelativeTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat). No language packs are required.

docs/docs/components/resize-observer.md

@@ -1,7 +1,7 @@
 ---
 title: Resize Observer
 description: The Resize Observer component offers a thin, declarative interface to the ResizeObserver API.
-layout: component.njk
+layout: component
 ---
 
 The resize observer will report changes to the dimensions of the elements it wraps through the `wa-resize` event. When emitted, a collection of [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) objects will be attached to `event.detail` that contains the target element and information about its dimensions.

docs/docs/components/select.md

@@ -1,7 +1,7 @@
 ---
 title: Select
 description: Selects allow you to choose items from a menu of predefined options.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/skeleton.md

@@ -1,7 +1,7 @@
 ---
 title: Skeleton
 description: Skeletons are used to provide a visual representation of where content will eventually be drawn.
-layout: component.njk
+layout: component
 ---
 
 These are simple containers for scaffolding layouts that mimic what users will see when content has finished loading. This prevents large areas of empty space during asynchronous operations.
@@ -139,7 +139,7 @@ Set a matching width and height to make a circle, square, or rounded avatar skel
   }
 
   .skeleton-avatars wa-skeleton:nth-child(2) {
-    --border-radius: var(--wa-corners-s);
+    --border-radius: var(--wa-border-radius-s);
   }
 </style>
 ```
@@ -165,11 +165,11 @@ Use the `--border-radius` custom property to make circles, squares, and rectangl
   }
 
   .skeleton-shapes .square::part(indicator) {
-    --border-radius: var(--wa-corners-s);
+    --border-radius: var(--wa-border-radius-s);
   }
 
   .skeleton-shapes .circle::part(indicator) {
-    --border-radius: var(--wa-corners-circle);
+    --border-radius: var(--wa-border-radius-circle);
   }
 
   .skeleton-shapes .triangle::part(indicator) {

docs/docs/components/spinner.md

@@ -1,7 +1,7 @@
 ---
 title: Spinner
 description: Spinners are used to show the progress of an indeterminate operation.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/split-panel.md

@@ -1,7 +1,7 @@
 ---
 title: Split Panel
 description: Split panels display two adjacent panels, allowing the user to reposition them.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}
@@ -137,7 +137,7 @@ To snap panels at specific positions while dragging, add the `snap` attribute wi
     width: 6px;
     height: 6px;
     border-radius: 50%;
-    background: var(--wa-color-neutral-spot);
+    background: var(--wa-color-neutral-fill-loud);
     transform: translateX(-3px);
   }
 
@@ -347,7 +347,7 @@ Here's a more elaborate example that changes the divider's color and width and a
 
   .split-panel-divider wa-icon {
     position: absolute;
-    border-radius: var(--wa-corners-l);
+    border-radius: var(--wa-border-radius-l);
     background: var(--wa-color-red-50);
     color: white;
     padding: 0.5rem 0.25rem;

docs/docs/components/switch.md

@@ -1,7 +1,7 @@
 ---
 title: Switch
 description: Switches allow the user to toggle an option on or off.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/tab-group.md

@@ -1,7 +1,7 @@
 ---
 title: Tab Group
 description: Tab groups organize content into a container that shows one section at a time.
-layout: component.njk
+layout: component
 ---
 
 Tab groups make use of [tabs](/components/tab) and [tab panels](/components/tab-panel). Each tab must be slotted into the `nav` slot and its `panel` must refer to a tab panel of the same name.

docs/docs/components/tab-panel.md

@@ -1,7 +1,7 @@
 ---
 title: Tab Panel
 description: Tab panels are used inside tab groups to display tabbed content.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/tab.md

@@ -1,7 +1,7 @@
 ---
 title: Tab
 description: Tabs are used inside tab groups to represent and activate tab panels.
-layout: component.njk
+layout: component
 ---
 
 :::info

docs/docs/components/tag.md

@@ -1,7 +1,7 @@
 ---
 title: Tag
 description: Tags are used as labels to organize things or to indicate a selection.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}
@@ -57,7 +57,7 @@ Use the `removable` attribute to add a remove button to the tag.
 
 <style>
   .tags-removable wa-tag {
-    transition: var(--wa-transition-fast) opacity;
+    transition: opacity var(--wa-transition-normal);
   }
 </style>
 ```

docs/docs/components/textarea.md

@@ -1,7 +1,7 @@
 ---
 title: Textarea
 description: Textareas collect data from the user and allow multiple lines of text.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/tooltip.md

@@ -1,7 +1,7 @@
 ---
 title: Tooltip
 description: Tooltips display additional information based on a specific action.
-layout: component.njk
+layout: component
 ---
 
 

docs/docs/components/tree-item.md

@@ -1,7 +1,7 @@
 ---
 title: Tree Item
 description: A tree item serves as a hierarchical node that lives inside a tree.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/tree.md

@@ -1,7 +1,7 @@
 ---
 title: Tree
 description: Trees allow you to display a hierarchical list of selectable tree items. Items with children can be expanded and collapsed as desired by the user.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}

docs/docs/components/visually-hidden.md

@@ -1,7 +1,7 @@
 ---
 title: Visually Hidden
 description: The visually hidden utility makes content accessible to assistive devices without displaying it on the screen.
-layout: component.njk
+layout: component
 ---
 
 According to [The A11Y Project](https://www.a11yproject.com/posts/2013-01-11-how-to-hide-content/), "there are real world situations where visually hiding content may be appropriate, while the content should remain available to assistive technologies, such as screen readers. For instance, hiding a search field's label as a common magnifying glass icon is used in its stead."

docs/docs/customizing.md

@@ -1,7 +1,7 @@
 ---
 title: Customizing
 description: Learn how to customize Web Awesome through parts and custom properties.
-layout: page.njk
+layout: page
 ---
 
 Web Awesome components can be customized at a high level through design tokens. This gives you control over theme colors and general styling. For more advanced customizations, you can make use of CSS parts and custom properties to target individual components.

docs/docs/experimental/form-validation.md

@@ -1,7 +1,7 @@
 ---
 title: Form Control Validation
 description: TODO
-layout: page.njk
+layout: page
 ---
 
 Adding the `wa-valid` or `wa-invalid` class to a form control will change its appearance. This is useful for applying validation styles to server-rendered form controls.

docs/docs/experimental/sandbox.md

@@ -1,13 +1,13 @@
 ---
 title: Theming Sandbox
 description: TODO
-layout: page.njk
+layout: page
 ---
 
 ## Card
 
 ```html {.example}
-<wa-card with-image class="card-overview">
+<wa-card with-image with-footer class="card-overview">
   <img
     slot="image"
     src="https://images.unsplash.com/photo-1559209172-0ff8f6d49ff7?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=500&q=80"
@@ -100,13 +100,19 @@ layout: page.njk
 <wa-button variant="warning">Warning</wa-button>
 <wa-button variant="danger">Danger</wa-button>
 <br /><br />
-<wa-button variant="brand" outline>Brand</wa-button>
-<wa-button variant="success" outline>Success</wa-button>
-<wa-button variant="neutral" outline>Neutral</wa-button>
-<wa-button variant="warning" outline>Warning</wa-button>
-<wa-button variant="danger" outline>Danger</wa-button>
+<wa-button variant="brand" appearance="outline">Brand</wa-button>
+<wa-button variant="success" appearance="outline">Success</wa-button>
+<wa-button variant="neutral" appearance="outline">Neutral</wa-button>
+<wa-button variant="warning" appearance="outline">Warning</wa-button>
+<wa-button variant="danger" appearance="outline">Danger</wa-button>
 <br /><br />
-<wa-button variant="text">Brand</wa-button>
+<wa-button appearance="text">Text</wa-button>
+<br /><br />
+<wa-radio-group label="Radio button group" name="a" value="1">
+  <wa-radio-button value="1">Option 1</wa-radio-button>
+  <wa-radio-button value="2">Option 2</wa-radio-button>
+  <wa-radio-button value="3">Option 3</wa-radio-button>
+</wa-radio-group>
 ```
 
 ## Form controls
@@ -126,9 +132,11 @@ layout: page.njk
 <br />
 <wa-switch checked>Switch on</wa-switch>
 <br /><br />
+<wa-range label="Range" help-text="Here's a bit of handy content." min="0" max="100"></wa-range>
+<br /><br />
 <wa-input label="Label" help-text="Super helpful and/or contextual content" placeholder="Placeholder"></wa-input>
 <br />
-<wa-select label="Select">
+<wa-select label="Select" multiple value="option-1 option-2">
   <wa-option value="option-1">Option 1</wa-option>
   <wa-option value="option-2">Option 2</wa-option>
   <wa-option value="option-3">Option 3</wa-option>
@@ -151,16 +159,96 @@ layout: page.njk
 ```html {.example}
 <style>
   div.shadow {
-    border: 1px solid var(--wa-color-surface-border);
-    border-radius: var(--wa-corners-s);
+    border: var(--wa-border-width-s) solid var(--wa-color-surface-border);
+    border-radius: var(--wa-border-radius-s);
     display: inline-block;
     height: 4rem;
     margin-right: 2rem;
     width: 4rem;
   }
   </style>
-<div class="shadow" style="box-shadow: var(--wa-shadow-inset);"></div>
-<div class="shadow" style="box-shadow: var(--wa-shadow-level-1);"></div>
-<div class="shadow" style="box-shadow: var(--wa-shadow-level-2);"></div>
-<div class="shadow" style="box-shadow: var(--wa-shadow-level-3);"></div>
+<div class="shadow" style="box-shadow: var(--wa-shadow-xs);"></div>
+<div class="shadow" style="box-shadow: var(--wa-shadow-s);"></div>
+<div class="shadow" style="box-shadow: var(--wa-shadow-m);"></div>
+<div class="shadow" style="box-shadow: var(--wa-shadow-l);"></div>
 ```
+
+## Tests
+
+```html {.example}
+<wa-button size="medium" style="width: 100%;" caret>Medium</wa-button>
+<br /><br />
+<wa-select>
+  <wa-option value="option-1">Option 1</wa-option>
+  <wa-option value="option-2">Option 2</wa-option>
+</wa-select>
+<br /><br />
+<wa-input placeholder="Small" size="small">
+  <wa-icon name="house" variant="solid" slot="prefix"></wa-icon>
+  <wa-icon name="comment" variant="solid" slot="suffix"></wa-icon>
+</wa-input>
+<wa-button size="small">
+  <wa-icon slot="prefix" name="gear" variant="solid"></wa-icon>
+  Settings
+</wa-button>
+<br /><br />
+<wa-input placeholder="Medium" size="medium">
+  <wa-icon name="house" variant="solid" slot="prefix"></wa-icon>
+  <wa-icon name="comment" variant="solid" slot="suffix"></wa-icon>
+</wa-input>
+<wa-button size="medium">
+  <wa-icon slot="prefix" name="gear" variant="solid"></wa-icon>
+  Settings
+</wa-button>
+<br /><br />
+<wa-input placeholder="Large" size="large">
+  <wa-icon name="house" variant="solid" slot="prefix"></wa-icon>
+  <wa-icon name="comment" variant="solid" slot="suffix"></wa-icon>
+</wa-input>
+<wa-button size="large">
+  <wa-icon slot="prefix" name="gear" variant="solid"></wa-icon>
+  Settings
+</wa-button>
+<br /><br />
+<wa-button size="medium">
+  <wa-icon slot="prefix" name="gear" variant="solid"></wa-icon>
+</wa-button>
+<br /><br />
+<wa-button-group label="Alignment">
+  <wa-button appearance="outline" variant="brand">Left</wa-button>
+  <wa-button appearance="outline" variant="brand">Center</wa-button>
+  <wa-button appearance="outline" variant="brand">Right</wa-button>
+</wa-button-group>
+
+<br /><br />
+
+<wa-button-group label="Alignment">
+  <wa-button appearance="outline" variant="success">Left</wa-button>
+  <wa-button appearance="outline" variant="success">Center</wa-button>
+  <wa-button appearance="outline" variant="success">Right</wa-button>
+</wa-button-group>
+
+<br /><br />
+
+<wa-button-group label="Alignment">
+  <wa-button appearance="outline">Left</wa-button>
+  <wa-button appearance="outline">Center</wa-button>
+  <wa-button appearance="outline">Right</wa-button>
+</wa-button-group>
+
+<br /><br />
+
+<wa-button-group label="Alignment">
+  <wa-button appearance="outline" variant="warning">Left</wa-button>
+  <wa-button appearance="outline" variant="warning">Center</wa-button>
+  <wa-button appearance="outline" variant="warning">Right</wa-button>
+</wa-button-group>
+
+<br /><br />
+
+<wa-button-group label="Alignment">
+  <wa-button appearance="outline" variant="danger">Left</wa-button>
+  <wa-button appearance="outline" variant="danger">Center</wa-button>
+  <wa-button appearance="outline" variant="danger">Right</wa-button>
+</wa-button-group>
+```

docs/docs/experimental/style-guide.md

@@ -1,7 +1,7 @@
 ---
 title: Style Guide
 description: TODO
-layout: page.njk
+layout: page
 ---
 
 The styles shown below can be all yours by adding Web Awesome's applied stylesheet to your project.
@@ -21,11 +21,10 @@ Cras pulvinar mattis nunc sed blandit libero. Facilisis magna etiam tempor orci.
 ## Inline Text
 
 ```html
-
 Feugiat nisl pretium fusce id. Ipsum dolor sit amet consectetur adipiscing elit. Eget nunc lobortis mattis aliquam faucibus purus. Metus dictum at tempor commodo ullamcorper a lacus vestibulum. Urna condimentum mattis pellentesque id nibh tortor id.
 ```
 
-<div class="docs-grid">
+<div class="two-columns">
   <p><strong>Bold</strong></p>
   <p><em>Italics</em></p>
   <p><u>Underline</u></p>
@@ -85,17 +84,17 @@ Individual details look like this.
 
 Grouping them provides accordion-style functionality.
 
-<details>
+<details name="details-accordion">
   <summary>Enim diam</summary>
   <p>Nunc faucibus a pellentesque sit amet porttitor. Adipiscing tristique risus nec feugiat in fermentum. Leo duis ut diam quam nulla porttitor massa id. Mauris nunc congue nisi vitae.</p>
 </details>
 
-<details>
+<details name="details-accordion">
   <summary>Arcu non odio</summary>
   <p>Sed libero enim sed faucibus turpis in eu mi bibendum. Nunc mi ipsum faucibus vitae aliquet nec. Ultricies tristique nulla aliquet enim tortor. Tellus at urna condimentum mattis pellentesque.</p>
 </details>
 
-<details>
+<details name="details-accordion">
   <summary>Ut porttitor</summary>
   <p>Eu facilisis sed odio morbi quis commodo odio aenean sed. Sit amet purus gravida quis blandit turpis cursus. Eu consequat ac felis donec et odio pellentesque diam volutpat.</p>
 </details>

docs/docs/experimental/themer.md

@@ -1,7 +1,7 @@
 ---
 meta:
 title: Themer
-layout: page.njk
+layout: page
 hasOutline: false
 ---
 
@@ -35,7 +35,7 @@ hasOutline: false
 
   :root,
   #knobs {
-    scrollbar-color: var(--wa-color-neutral-border-highlight) var(--wa-color-surface-raised);
+    scrollbar-color: var(--wa-color-neutral-border-normal) var(--wa-color-surface-raised);
   }
 
   /* #region Lock theme styles */
@@ -48,25 +48,23 @@ hasOutline: false
 
     --wa-color-shadow: rgb(0 0 0 / 0.1);
 
-    --wa-color-neutral-spot: color-mix(in oklab, var(--wa-color-surface-default), var(--wa-color-text-normal) 75%);
-    --wa-color-neutral-spot-darker: color-mix(in oklab, var(--wa-color-neutral-spot), black 5%);
-    --wa-color-neutral-fill-subtle: color-mix(in oklab, var(--wa-color-surface-default), var(--wa-color-text-normal) 10%);
-    --wa-color-neutral-fill-highlight: color-mix(in oklab, var(--wa-color-surface-default), var(--wa-color-text-normal) 20%);
-    --wa-color-neutral-border-subtle: color-mix(in oklab, var(--wa-color-text-normal), var(--wa-color-surface-default) 90%);
-    --wa-color-neutral-border-highlight: color-mix(in oklab, var(--wa-color-text-normal), var(--wa-color-surface-default) 70%);
-    --wa-color-neutral-text-on-spot: color-mix(in oklab, var(--wa-color-surface-default) 90%, var(--wa-color-text-normal));
-    --wa-color-neutral-text-on-fill: color-mix(in oklab, var(--wa-color-surface-raised) 10%, var(--wa-color-text-normal));
-    --wa-color-neutral-text-on-surface: var(--wa-color-neutral-spot);
+    --wa-color-neutral-fill-loud: color-mix(in oklab, var(--wa-color-surface-default), var(--wa-color-text-normal) 75%);
+    --wa-color-neutral-fill-quiet: color-mix(in oklab, var(--wa-color-surface-default), var(--wa-color-text-normal) 10%);
+    --wa-color-neutral-fill-normal: color-mix(in oklab, var(--wa-color-surface-default), var(--wa-color-text-normal) 20%);
+    --wa-color-neutral-border-quiet: color-mix(in oklab, var(--wa-color-text-normal), var(--wa-color-surface-default) 90%);
+    --wa-color-neutral-border-normal: color-mix(in oklab, var(--wa-color-text-normal), var(--wa-color-surface-default) 70%);
+    --wa-color-neutral-on-loud: color-mix(in oklab, var(--wa-color-surface-default) 90%, var(--wa-color-text-normal));
+    --wa-color-neutral-on-normal: color-mix(in oklab, var(--wa-color-surface-raised) 10%, var(--wa-color-text-normal));
+    --wa-color-neutral-on-quiet: var(--wa-color-neutral-fill-loud);
 
-    --wa-color-brand-spot: var(--wa-color-neutral-spot);
-    --wa-color-brand-spot-darker: var(--wa-color-neutral-spot-darker);
-    --wa-color-brand-fill-subtle: var(--wa-color-neutral-fill-subtle);
-    --wa-color-brand-fill-highlight: var(--wa-color-neutral-fill-highlight);
-    --wa-color-brand-border-subtle: var(--wa-color-neutral-border-subtle);
-    --wa-color-brand-border-highlight: var(--wa-color-neutral-border-highlight);
-    --wa-color-brand-text-on-spot: var(--wa-color-neutral-text-on-spot);
-    --wa-color-brand-text-on-fill: var(--wa-color-neutral-text-on-fill);
-    --wa-color-brand-text-on-surface: var(--wa-color-neutral-text-on-surface);
+    --wa-color-brand-fill-loud: var(--wa-color-neutral-fill-loud);
+    --wa-color-brand-fill-quiet: var(--wa-color-neutral-fill-quiet);
+    --wa-color-brand-fill-normal: var(--wa-color-neutral-fill-normal);
+    --wa-color-brand-border-quiet: var(--wa-color-neutral-border-quiet);
+    --wa-color-brand-border-normal: var(--wa-color-neutral-border-normal);
+    --wa-color-brand-on-loud: var(--wa-color-neutral-on-loud);
+    --wa-color-brand-on-normal: var(--wa-color-neutral-on-normal);
+    --wa-color-brand-on-quiet: var(--wa-color-neutral-on-quiet);
 
     --wa-font-family-heading: Inconsolata, monospace;
     --wa-font-family-body: Inconsolata, monospace;
@@ -75,123 +73,122 @@ hasOutline: false
 
     --wa-font-weight-light: 300;
     --wa-font-weight-normal: 400;
-    --wa-font-weight-medium: 600;
-    --wa-font-weight-heavy: 800;
+    --wa-font-weight-semibold: 600;
+    --wa-font-weight-bold: 800;
 
-    --wa-font-weight-heading: var(--wa-font-weight-heavy);
+    --wa-font-weight-heading: var(--wa-font-weight-bold);
     --wa-font-weight-body: var(--wa-font-weight-normal);
-    --wa-font-weight-action: var(--wa-font-weight-medium);
+    --wa-font-weight-action: var(--wa-font-weight-semibold);
 
     --wa-font-size-root: 16px;
-    --wa-font-size-2xs: var(--wa-font-size-root) * 0.6875;
-    --wa-font-size-xs: var(--wa-font-size-root) * 0.75;
-    --wa-font-size-s: var(--wa-font-size-root) * 0.875;
-    --wa-font-size-m: var(--wa-font-size-root) * 1;
-    --wa-font-size-l: var(--wa-font-size-root) * 1.25;
-    --wa-font-size-xl: var(--wa-font-size-root) * 1.625;
-    --wa-font-size-2xl: var(--wa-font-size-root) * 2;
-    --wa-font-size-3xl: var(--wa-font-size-root) * 2.5625;
-    --wa-font-size-4xl: var(--wa-font-size-root) * 3.25;
+    --wa-font-size-2xs: 1rem * 0.6875;
+    --wa-font-size-xs: 1rem * 0.75;
+    --wa-font-size-s: 1rem * 0.875;
+    --wa-font-size-m: 1rem * 1;
+    --wa-font-size-l: 1rem * 1.25;
+    --wa-font-size-xl: 1rem * 1.625;
+    --wa-font-size-2xl: 1rem * 2;
+    --wa-font-size-3xl: 1rem * 2.5625;
+    --wa-font-size-4xl: 1rem * 3.25;
 
-    --wa-font-line-height-compact: 1.25;
-    --wa-font-line-height-regular: 1.6;
-    --wa-font-line-height-comfortable: 2;
+    --wa-line-height-condensed: 1.25;
+    --wa-line-height-normal: 1.6;
+    --wa-line-height-expanded: 2;
 
-    --wa-space-base: 1;
-    --wa-space-3xs: calc(var(--wa-space-base) * var(--wa-font-size-root) * 0.125);
-    --wa-space-2xs: calc(var(--wa-space-base) * var(--wa-font-size-root) * 0.25);
-    --wa-space-xs: calc(var(--wa-space-base) * var(--wa-font-size-root) * 0.5);
-    --wa-space-s: calc(var(--wa-space-base) * var(--wa-font-size-root) * 0.75);
-    --wa-space-m: calc(var(--wa-space-base) * var(--wa-font-size-root) * 1);
-    --wa-space-l: calc(var(--wa-space-base) * var(--wa-font-size-root) * 1.25);
-    --wa-space-xl: calc(var(--wa-space-base) * var(--wa-font-size-root) * 1.5);
-    --wa-space-2xl: calc(var(--wa-space-base) * var(--wa-font-size-root) * 2);
-    --wa-space-3xl: calc(var(--wa-space-base) * var(--wa-font-size-root) * 3);
+    --wa-space-multiplier: 1;
+    --wa-space-3xs: calc(var(--wa-space-multiplier) * 1rem * 0.125);
+    --wa-space-2xs: calc(var(--wa-space-multiplier) * 1rem * 0.25);
+    --wa-space-xs: calc(var(--wa-space-multiplier) * 1rem * 0.5);
+    --wa-space-s: calc(var(--wa-space-multiplier) * 1rem * 0.75);
+    --wa-space-m: calc(var(--wa-space-multiplier) * 1rem * 1);
+    --wa-space-l: calc(var(--wa-space-multiplier) * 1rem * 1.25);
+    --wa-space-xl: calc(var(--wa-space-multiplier) * 1rem * 1.5);
+    --wa-space-2xl: calc(var(--wa-space-multiplier) * 1rem * 2);
+    --wa-space-3xl: calc(var(--wa-space-multiplier) * 1rem * 3);
 
     --wa-border-style: solid;
 
-    --wa-border-width-base: 0.0625;
-    --wa-border-width-s: calc(var(--wa-border-width-base) * var(--wa-font-size-root) * 1);
-    --wa-border-width-m: calc(var(--wa-border-width-base) * var(--wa-font-size-root) * 2);
-    --wa-border-width-l: calc(var(--wa-border-width-base) * var(--wa-font-size-root) * 3);
+    --wa-border-width-multiplier: 0.0625;
+    --wa-border-width-s: calc(var(--wa-border-width-multiplier) * 1rem * 1);
+    --wa-border-width-m: calc(var(--wa-border-width-multiplier) * 1rem * 2);
+    --wa-border-width-l: calc(var(--wa-border-width-multiplier) * 1rem * 3);
 
-    --wa-form-controls-border-style: var(--wa-border-style);
-    --wa-form-controls-border-width: var(--wa-border-width-s);
+    --wa-form-control-border-style: var(--wa-border-style);
+    --wa-form-control-border-width: var(--wa-border-width-s);
 
     --wa-panel-border-style: var(--wa-border-style);
     --wa-panel-border-width: var(--wa-border-width-s);
 
-    --wa-corners-base: 0.375;
-    --wa-corners-xs: calc(var(--wa-corners-base) * var(--wa-font-size-root) * 0.75);
-    --wa-corners-s: calc(var(--wa-corners-base) * var(--wa-font-size-root) * 1);
-    --wa-corners-m: calc(var(--wa-corners-base) * var(--wa-font-size-root) * 2);
-    --wa-corners-l: calc(var(--wa-corners-base) * var(--wa-font-size-root) * 3);
+    --wa-border-radius-multiplier: 0.375;
+    --wa-border-radius-xs: calc(var(--wa-border-radius-multiplier) * 1rem * 0.75);
+    --wa-border-radius-s: calc(var(--wa-border-radius-multiplier) * 1rem * 1);
+    --wa-border-radius-m: calc(var(--wa-border-radius-multiplier) * 1rem * 2);
+    --wa-border-radius-l: calc(var(--wa-border-radius-multiplier) * 1rem * 3);
 
-    --wa-shadow-blur-base: 0.125;
-    --wa-shadow-blur-inset: calc(var(--wa-shadow-blur-base) * 0.75rem);
-    --wa-shadow-blur-level-1: calc(var(--wa-shadow-blur-base) * 1rem);
-    --wa-shadow-blur-level-2: calc(var(--wa-shadow-blur-base) * 1.5rem);
-    --wa-shadow-blur-level-3: calc(var(--wa-shadow-blur-base) * 2rem);
+    --wa-shadow-blur-multiplier: 0.125;
+    --wa-shadow-blur-xs: calc(var(--wa-shadow-blur-multiplier) * 0.75rem);
+    --wa-shadow-blur-s: calc(var(--wa-shadow-blur-multiplier) * 1rem);
+    --wa-shadow-blur-m: calc(var(--wa-shadow-blur-multiplier) * 1.5rem);
+    --wa-shadow-blur-l: calc(var(--wa-shadow-blur-multiplier) * 2rem);
 
-    --wa-shadow-offset-y-base: 0.1;
-    --wa-shadow-offset-y-inset: calc(var(--wa-shadow-offset-y-base) * 0.75rem);
-    --wa-shadow-offset-y-level-1: calc(var(--wa-shadow-offset-y-base) * 1rem);
-    --wa-shadow-offset-y-level-2: calc(var(--wa-shadow-offset-y-base) * 1.5rem);
-    --wa-shadow-offset-y-level-3: calc(var(--wa-shadow-offset-y-base) * 2rem);
+    --wa-shadow-offset-y-multiplier: 0.1;
+    --wa-shadow-offset-y-xs: calc(var(--wa-shadow-offset-y-multiplier) * 0.75rem);
+    --wa-shadow-offset-y-s: calc(var(--wa-shadow-offset-y-multiplier) * 1rem);
+    --wa-shadow-offset-y-m: calc(var(--wa-shadow-offset-y-multiplier) * 1.5rem);
+    --wa-shadow-offset-y-l: calc(var(--wa-shadow-offset-y-multiplier) * 2rem);
 
-    --wa-shadow-offset-x-base: 0;
-    --wa-shadow-offset-x-inset: calc(var(--wa-shadow-offset-x-base) * 0.75rem);
-    --wa-shadow-offset-x-level-1: calc(var(--wa-shadow-offset-x-base) * 1rem);
-    --wa-shadow-offset-x-level-2: calc(var(--wa-shadow-offset-x-base) * 1.5rem);
-    --wa-shadow-offset-x-level-3: calc(var(--wa-shadow-offset-x-base) * 2rem);
+    --wa-shadow-offset-x-multiplier: 0;
+    --wa-shadow-offset-x-xs: calc(var(--wa-shadow-offset-x-multiplier) * 0.75rem);
+    --wa-shadow-offset-x-s: calc(var(--wa-shadow-offset-x-multiplier) * 1rem);
+    --wa-shadow-offset-x-m: calc(var(--wa-shadow-offset-x-multiplier) * 1.5rem);
+    --wa-shadow-offset-x-l: calc(var(--wa-shadow-offset-x-multiplier) * 2rem);
 
-    --wa-shadow-inset: inset var(--wa-shadow-offset-x-inset) var(--wa-shadow-offset-y-inset) var(--wa-shadow-blur-inset)
-      calc(var(--wa-shadow-offset-x-inset) * -1) var(--wa-color-shadow);
-    --wa-shadow-level-0: none;
-    --wa-shadow-level-1: var(--wa-shadow-offset-x-level-1) var(--wa-shadow-offset-y-level-1) var(--wa-shadow-blur-level-1)
-      calc(var(--wa-shadow-offset-x-level-1) * -1) var(--wa-color-shadow);
-    --wa-shadow-level-2: var(--wa-shadow-offset-x-level-2) var(--wa-shadow-offset-y-level-2) var(--wa-shadow-blur-level-2)
-      calc(var(--wa-shadow-offset-x-level-2) * -1) var(--wa-color-shadow);
-    --wa-shadow-level-3: var(--wa-shadow-offset-x-level-3) var(--wa-shadow-offset-y-level-3) var(--wa-shadow-blur-level-3)
-      calc(var(--wa-shadow-offset-x-level-3) * -1) var(--wa-color-shadow);
+    --wa-shadow-xs: inset var(--wa-shadow-offset-x-xs) var(--wa-shadow-offset-y-xs) var(--wa-shadow-blur-xs)
+      calc(var(--wa-shadow-offset-x-xs) * -1) var(--wa-color-shadow);
+    --wa-shadow-s: var(--wa-shadow-offset-x-s) var(--wa-shadow-offset-y-s) var(--wa-shadow-blur-s)
+      calc(var(--wa-shadow-offset-x-s) * -1) var(--wa-color-shadow);
+    --wa-shadow-m: var(--wa-shadow-offset-x-m) var(--wa-shadow-offset-y-m) var(--wa-shadow-blur-m)
+      calc(var(--wa-shadow-offset-x-m) * -1) var(--wa-color-shadow);
+    --wa-shadow-l: var(--wa-shadow-offset-x-l) var(--wa-shadow-offset-y-l) var(--wa-shadow-blur-l)
+      calc(var(--wa-shadow-offset-x-l) * -1) var(--wa-color-shadow);
 
-    --wa-form-controls-background: var(--wa-color-surface-default);
+    --wa-form-control-background-color: var(--wa-color-surface-default);
 
-    --wa-form-controls-corners: var(--wa-corners-s);
+    --wa-form-control-border-radius: var(--wa-border-radius-s);
 
-    --wa-form-controls-activated-color: var(--wa-color-brand-spot);
-    --wa-form-controls-resting-color: var(--wa-color-neutral-border-highlight);
+    --wa-form-control-activated-color: var(--wa-color-brand-fill-loud);
+    --wa-form-control-resting-color: var(--wa-color-neutral-border-normal);
 
-    --wa-form-controls-label-color: var(--wa-color-text-normal);
-    --wa-form-controls-label-font-weight: var(--wa-font-weight-normal);
-    --wa-form-controls-label-line-height: var(--wa-font-line-height-regular);
+    --wa-form-control-label-color: var(--wa-color-text-normal);
+    --wa-form-control-label-font-weight: var(--wa-font-weight-normal);
+    --wa-form-control-label-line-height: var(--wa-line-height-normal);
 
-    --wa-form-controls-value-color: var(--wa-color-text-normal);
-    --wa-form-controls-value-font-weight: var(--wa-font-weight-body);
-    --wa-form-controls-value-line-height: var(--wa-font-line-height-compact);
+    --wa-form-control-value-color: var(--wa-color-text-normal);
+    --wa-form-control-value-font-weight: var(--wa-font-weight-body);
+    --wa-form-control-value-line-height: var(--wa-line-height-condensed);
 
-    --wa-form-controls-placeholder-color: color-mix(in oklab, var(--wa-color-text-normal), transparent);
+    --wa-form-control-placeholder-color: color-mix(in oklab, var(--wa-color-text-normal), transparent);
 
-    --wa-form-controls-height-s: calc(
-      var(--wa-space-xs) * 2 + var(--wa-font-size-s) * var(--wa-form-controls-value-line-height)
+    --wa-form-control-height-s: calc(
+      var(--wa-space-xs) * 2 + var(--wa-font-size-s) * var(--wa-form-control-value-line-height)
     );
-    --wa-form-controls-height-m: calc(
-      var(--wa-space-s) * 2 + var(--wa-font-size-m) * var(--wa-form-controls-value-line-height)
+    --wa-form-control-height-m: calc(
+      var(--wa-space-s) * 2 + var(--wa-font-size-m) * var(--wa-form-control-value-line-height)
     );
-    --wa-form-controls-height-l: calc(
-      var(--wa-space-m) * 2 + var(--wa-font-size-l) * var(--wa-form-controls-value-line-height)
+    --wa-form-control-height-l: calc(
+      var(--wa-space-m) * 2 + var(--wa-font-size-l) * var(--wa-form-control-value-line-height)
     );
 
-    --wa-form-controls-required-content: '*';
-    --wa-form-controls-required-content-color: inherit;
-    --wa-form-controls-required-content-offset: -0.1em;
+    --wa-form-control-required-content: '*';
+    --wa-form-control-required-content-color: inherit;
+    --wa-form-control-required-content-offset: -0.1em;
 
-    --wa-panel-corners: var(--wa-corners-m);
+    --wa-panel-border-radius: var(--wa-border-radius-m);
 
     font-family: var(--wa-font-family-code);
-    font-size: var(--wa-font-size-root);
+    font-size: 1rem;
     font-weight: var(--wa-font-weight-normal);
-    line-height: var(--wa-font-line-height-regular);
+    line-height: var(--wa-line-height-normal);
 
     & wa-button,
     & wa-input,
@@ -232,7 +229,7 @@ hasOutline: false
       position: relative;
 
       &::part(summary) {
-        font-weight: var(--wa-font-weight-medium);
+        font-weight: var(--wa-font-weight-semibold);
       }
       &::part(summary-icon) {
         rotate: 0deg;
@@ -260,9 +257,9 @@ hasOutline: false
         padding-block-end: 0;
 
         & legend {
-          color: var(--wa-form-controls-label-color);
-          font-weight: var(--wa-form-controls-label-font-weight);
-          line-height: var(--wa-form-controls-label-line-height);
+          color: var(--wa-form-control-label-color);
+          font-weight: var(--wa-form-control-label-font-weight);
+          line-height: var(--wa-form-control-label-line-height);
           margin-bottom: var(--wa-space-3xs);
           padding-inline: 0;
         }
@@ -290,15 +287,15 @@ hasOutline: false
 
 
   #knobs wa-radio-group[name="color"] wa-radio {
-    border: 0.0625em solid var(--wa-color-neutral-border-subtle);
-    border-radius: var(--wa-corners-m);
+    border: 0.0625em solid var(--wa-color-neutral-border-quiet);
+    border-radius: var(--wa-border-radius-m);
     box-shadow: inset 0 0 0 0 transparent;
     padding: 1em;
-    transition: box-shadow var(--wa-transition-fast);
+    transition: box-shadow var(--wa-transition-normal) var(--wa-transition-easing);
 
     &[aria-checked="true"] {
       border-color: transparent;
-      box-shadow: inset 0 0 0 0.125em var(--wa-form-controls-activated-color);
+      box-shadow: inset 0 0 0 0.125em var(--wa-form-control-activated-color);
     }
 
     & + * {
@@ -329,13 +326,13 @@ hasOutline: false
   #knobs wa-radio-group[name="brand-color"] wa-radio {
     display: inline-block;
     border: 0.125em solid transparent;
-    border-radius: var(--wa-corners-circle);
+    border-radius: var(--wa-border-radius-circle);
     block-size: 2.375em;
     inline-size: 2.375em;
     padding: 0.0625em;
 
     &[aria-checked="true"] {
-      border: 0.125em solid var(--wa-form-controls-activated-color);
+      border: 0.125em solid var(--wa-form-control-activated-color);
     }
 
     &::part(base) {
@@ -354,7 +351,7 @@ hasOutline: false
       display: inline-block;
       block-size: 2em;
       inline-size: 2em;
-      border-radius: var(--wa-corners-circle);
+      border-radius: var(--wa-border-radius-circle);
     }
   }
 
@@ -368,18 +365,18 @@ hasOutline: false
   /* file uploader styles */
   .file-uploader {
     position: relative;
-    border: var(--wa-form-controls-border-width) dashed var(--wa-form-controls-resting-color);
-    border-radius: var(--wa-form-controls-corners);
-    background: var(--wa-form-controls-background);
+    border: var(--wa-form-control-border-width) dashed var(--wa-form-control-resting-color);
+    border-radius: var(--wa-form-control-border-radius);
+    background: var(--wa-form-control-background-color);
     cursor: pointer;
     font-weight: var(--wa-font-weight-action);
-    height: calc(var(--wa-form-controls-height-m) + var(--wa-border-width-s) * 2);
-    line-height: var(--wa-form-controls-height-m);
+    height: calc(var(--wa-form-control-height-m) + var(--wa-border-width-s) * 2);
+    line-height: var(--wa-form-control-height-m);
     text-align: center;
   }
 
   .file-uploader:is(:hover) {
-    background-color: var(--wa-color-neutral-fill-subtle);
+    background-color: var(--wa-color-neutral-fill-quiet);
   }
 
   /**
@@ -406,7 +403,7 @@ hasOutline: false
 
   #file-uploader-description {
     display: block;
-    line-height: var(--wa-font-line-height-compact);
+    line-height: var(--wa-line-height-condensed);
     color: var(--wa-color-text-quiet);
     margin-top: var(--wa-space-2xs);
   }
@@ -422,7 +419,7 @@ hasOutline: false
   }
 
   wa-radio-group[name="project-logo-selector"] wa-radio-button:last-of-type::part(button) {
-    border-radius: 0 var(--wa-corners-s) var(--wa-corners-s) 0;
+    border-radius: 0 var(--wa-border-radius-s) var(--wa-border-radius-s) 0;
   }
 
   wa-radio-group[name="project-logo-selector"] wa-tooltip {
@@ -432,8 +429,8 @@ hasOutline: false
 
   #icon-chooser-trigger {
     --button-group-separator-border: none;
-    --label-color: var(--wa-color-neutral-text-on-surface);
-    --label-color-hover: color-mix(in oklab, var(--wa-color-neutral-text-on-surface), var(--wa-color-mix-hover));
+    --label-color: var(--wa-color-neutral-on-quiet);
+    --label-color-hover: color-mix(in oklab, var(--wa-color-neutral-on-quiet), var(--wa-color-mix-hover));
     --label-color-active: var(--label-color-hover);
   }
 
@@ -450,7 +447,7 @@ hasOutline: false
 
   .icon-search {
     border: solid 1px var(--wa-color-surface-border);
-    border-radius: var(--wa-corners-s);
+    border-radius: var(--wa-border-radius-s);
     padding: var(--wa-space-m);
   }
 
@@ -537,12 +534,12 @@ hasOutline: false
         <wa-radio-button value="meteor"><wa-icon name="meteor"></wa-icon></wa-radio-button>
         <wa-radio-button value="cat-space"><wa-icon name="cat-space"></wa-icon></wa-radio-button>
         <wa-radio-button value="puzzle-piece"><wa-icon name="puzzle-piece"></wa-icon></wa-radio-button>
-          <wa-button value="[choose]" variant="text" id="icon-chooser-trigger" class="logo-chooser">
+          <wa-button value="[choose]" appearance="text" id="icon-chooser-trigger" class="logo-chooser">
             <wa-tooltip for="icon-chooser-trigger" distance="-3" hoist>Browse Icons</wa-tooltip>
             <wa-icon name="ellipsis" library="fa-classic-regular"></wa-icon>
             <wa-visually-hidden>Browse icons</wa-visually-hidden>
           </wa-button>
-          <small slot="help-text" style="display: inline-block; line-height: var(--wa-font-line-height-compact);">It's dangerous to go alone. Take these!</small>
+          <small slot="help-text" style="display: inline-block; line-height: var(--wa-line-height-condensed);">It's dangerous to go alone. Take these!</small>
       </wa-radio-group>
     </div>
   </wa-details>
@@ -712,17 +709,17 @@ hasOutline: false
     & wa-radio-group {
       &::part(button-group) {
         background: var(--wa-color-surface-raised);
-        border-radius: var(--wa-corners-pill);
+        border-radius: var(--wa-border-radius-pill);
         box-shadow: 0 0.25em 0.25em -0.25em rgb(0 0 0 / 0.8);
         padding: 4px;
       }
       & wa-radio-button {
         &::part(button) {
           border: none;
-          border-radius: var(--wa-corners-circle);
+          border-radius: var(--wa-border-radius-circle);
         }
         &::part(button--checked) {
-          background: var(--wa-color-brand-spot);
+          background: var(--wa-color-brand-fill-loud);
         }
       }
     }
@@ -931,8 +928,8 @@ hasOutline: false
   }
 
   function resetBorderWidthValue() {
-    document.documentElement.style.removeProperty('--wa-border-width-base')
-    borderWidth.value = getComputedStyle(previewContainer).getPropertyValue("--wa-border-width-base")
+    document.documentElement.style.removeProperty('--wa-border-width-multiplier')
+    borderWidth.value = getComputedStyle(previewContainer).getPropertyValue("--wa-border-width-multiplier")
   }
 
   function resetBorderStyleValue() {
@@ -941,13 +938,13 @@ hasOutline: false
   }
 
   function resetSpacingValue() {
-    document.documentElement.style.removeProperty('--wa-space-base')
-    spacing.value = getComputedStyle(previewContainer).getPropertyValue("--wa-space-base")
+    document.documentElement.style.removeProperty('--wa-space-multiplier')
+    spacing.value = getComputedStyle(previewContainer).getPropertyValue("--wa-space-multiplier")
   }
 
   function resetCornersValue() {
-    document.documentElement.style.removeProperty('--wa-corners-base')
-    corners.value = getComputedStyle(previewContainer).getPropertyValue("--wa-corners-base")
+    document.documentElement.style.removeProperty('--wa-border-radius-multiplier')
+    corners.value = getComputedStyle(previewContainer).getPropertyValue("--wa-border-radius-multiplier")
   }
 
 
@@ -1619,12 +1616,12 @@ hasOutline: false
 
   // Corners
   container.querySelector('[name="corners"]').addEventListener('wa-input', event => {
-    document.documentElement.style.setProperty('--wa-corners-base', `${event.target.value}`);
+    document.documentElement.style.setProperty('--wa-border-radius-multiplier', `${event.target.value}`);
   });
 
   // Border width
   container.querySelector('[name="border-width"]').addEventListener('wa-input', event => {
-    document.documentElement.style.setProperty('--wa-border-width-base', `${event.target.value / 16}`);
+    document.documentElement.style.setProperty('--wa-border-width-multiplier', `${event.target.value / 16}`);
   });
 
   // Border style
@@ -1634,7 +1631,7 @@ hasOutline: false
 
   // Spacing style
   spacing.addEventListener('wa-input', event => {
-    document.documentElement.style.setProperty('--wa-space-base', `${event.target.value}`);
+    document.documentElement.style.setProperty('--wa-space-multiplier', `${event.target.value}`);
   });
 
   // Form validation
@@ -1676,7 +1673,7 @@ hasOutline: false
     padding: 0;
     max-inline-size: 1400px;
     margin-inline: auto;
-    border: var(--wa-border-width-s) var(--wa-color-neutral-border-subtle) var(--wa-border-style);
+    border: var(--wa-border-width-s) var(--wa-color-neutral-border-quiet) var(--wa-border-style);
     overflow: clip;
   }
 
@@ -1711,7 +1708,7 @@ hasOutline: false
     overflow: hidden;
 
     &:not(wa-card *) {
-      border-radius: calc(var(--wa-corners-m) - var(--wa-panel-border-width));
+      border-radius: calc(var(--wa-border-radius-m) - var(--wa-panel-border-width));
     }
 
     & > img {
@@ -1845,7 +1842,7 @@ hasOutline: false
 
   .message-composer .grouped-buttons:not(:last-of-type) {
     padding-inline-end: var(--wa-space-m);
-    border-right: var(--wa-border-width-s) var(--wa-border-style) var(--wa-color-neutral-border-subtle);
+    border-right: var(--wa-border-width-s) var(--wa-border-style) var(--wa-color-neutral-border-quiet);
   }
 
   .message-composer wa-card::part(header) {
@@ -1890,11 +1887,6 @@ hasOutline: false
     margin-inline-end: var(--wa-space-m);
   }
 
-  .product-detail wa-radio-button[checked] {
-    --background: var(--wa-color-neutral-text-on-surface);
-    --label-color: var(--wa-color-surface-lowered);
-  }
-
   /* strata - support table */
   .support-table {
     font-size: var(--wa-font-size-s);
@@ -2048,7 +2040,7 @@ hasOutline: false
             <wa-icon slot="prefix" name="plus" variant="regular"></wa-icon>
             Add to Cart
           </wa-button>
-          <wa-button size="small" outline>
+          <wa-button size="small" appearance="outline">
             <wa-icon slot="prefix" name="bookmark" variant="regular"></wa-icon>
             Save
           </wa-button>
@@ -2071,7 +2063,7 @@ hasOutline: false
             <wa-icon slot="prefix" name="plus" variant="regular"></wa-icon>
             Add to Cart
           </wa-button>
-          <wa-button size="small" outline>
+          <wa-button size="small" appearance="outline">
             <wa-icon slot="prefix" name="bookmark" variant="regular"></wa-icon>
             Save
           </wa-button>
@@ -2093,7 +2085,7 @@ hasOutline: false
             <wa-icon slot="prefix" name="plus" variant="regular"></wa-icon>
             Add to Cart
           </wa-button>
-          <wa-button size="small" outline>
+          <wa-button size="small" appearance="outline">
             <wa-icon slot="prefix" name="bookmark" variant="regular"></wa-icon>
             Save
           </wa-button>

docs/docs/installation.md

@@ -1,98 +1,31 @@
 ---
 title: Installation
 description: Choose the installation method that works best for you.
-layout: page.njk
+layout: page
 ---
 
 You can load Web Awesome via CDN or by installing it locally. If you're using a framework, make sure to check out the pages for [React](/frameworks/react), [Vue](/frameworks/vue), and [Angular](/frameworks/angular) for additional information.
 
-## CDN Installation (Easiest)
+## Autoloading via CDN (Easiest)
 
-<wa-tab-group>
-<wa-tab slot="nav" panel="autoloader" active>Autoloader</wa-tab>
-<wa-tab slot="nav" panel="traditional">Traditional Loader</wa-tab>
-
-<wa-tab-panel name="autoloader">
-
-The experimental autoloader is the easiest and most efficient way to use Web Awesome. A lightweight script watches the DOM for unregistered Web Awesome elements and lazy loads them for you — even if they're added dynamically.
-
-While convenient, autoloading may lead to a [Flash of Undefined Custom Elements](https://www.abeautifulsite.net/posts/flash-of-undefined-custom-elements/). The linked article describes some ways to alleviate it.
+The autoloader is the easiest way to use Web Awesome. A lightweight script watches the DOM for unregistered Web Awesome elements and lazy loads them for you — even if they're added dynamically.
 
 ```html
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/themes/default.css" />
 <script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/autoloader.js"></script>
 ```
 
-</wa-tab-panel>
-
-<wa-tab-panel name="traditional">
-
-The traditional CDN loader registers all Web Awesome elements up front. Note that, if you're only using a handful of components, it will be much more efficient to stick with the autoloader. However, you can also [cherry pick](#cherry-picking) components if you want to load specific ones up front.
-
-```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/themes/default.css" />
-<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/autoloader.js" ></script>
-```
-
-</wa-tab-panel>
-</wa-tab-group>
-
-### Dark Theme
-
-The code above will load the light theme. If you want to use the [dark theme](/getting-started/themes#dark-theme) instead, update the stylesheet as shown below and add `<html class="wa-theme-default-dark">` to your page.
-
-```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/themes/dark.css" />
-```
-
-### Light & Dark Theme
-
-If you want to load the light or dark theme based on the user's `prefers-color-scheme` setting, use the stylesheets below. The `media` attributes ensure that only the user's preferred theme stylesheet loads and the `onload` attribute sets the appropriate [theme class](/getting-started/themes) on the `<html>` element.
-
-```html
-<link
-  rel="stylesheet"
-  media="(prefers-color-scheme:light)"
-  href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/themes/default.css"
-/>
-<link
-  rel="stylesheet"
-  media="(prefers-color-scheme:dark)"
-  href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/themes/dark.css"
-  onload="document.documentElement.classList.add('wa-theme-default-dark');"
-/>
-```
-
 Now you can [start using Web Awesome!](/getting-started/usage)
 
-## npm installation
-
-If you don't want to use the CDN, you can install Web Awesome from npm with the following command.
-
-```bash
-npm install @shoelace-style/shoelace
-```
-
-It's up to you to make the source files available to your app. One way to do this is to create a route in your app called `/shoelace` that serves static files from `node_modules/@shoelace-style/shoelace`.
-
-Once you've done that, add the following tags to your page. Make sure to update `href` and `src` so they point to the route you created.
-
-```html
-<link rel="stylesheet" href="/shoelace/%NPMDIR%/themes/default.css" />
-<script type="module" src="/shoelace/%NPMDIR%/autoloader.js"></script>
-```
-
-Alternatively, [you can use a bundler](#bundling).
-
 :::info
-For clarity, the docs will usually show imports from `@shoelace-style/shoelace`. If you're not using a module resolver or bundler, you'll need to adjust these paths to point to the folder Web Awesome is in.
+While convenient, autoloading may lead to a [Flash of Undefined Custom Elements](https://www.abeautifulsite.net/posts/flash-of-undefined-custom-elements/). The linked article describes some ways to alleviate it.
 :::
 
 ## Setting the Base Path
 
 Some components rely on assets (icons, images, etc.) and Web Awesome needs to know where they're located. For convenience, Web Awesome will try to auto-detect the correct location based on the script you've loaded it from. This assumes assets are colocated with `autoloader.js` and will "just work" for most users.
 
-However, if you're [cherry picking](#cherry-picking) or [bundling](#bundling) Web Awesome, you'll need to set the base path. You can do this one of two ways.
+If you're using the CDN, you can skip this section. However, if you're [cherry picking](#cherry-picking) or bundling Web Awesome, you'll need to set the base path. You can do this one of two ways.
 
 ```html
 <!-- Option 1: the data-webawesome attribute -->
@@ -105,10 +38,6 @@ However, if you're [cherry picking](#cherry-picking) or [bundling](#bundling) We
 </script>
 ```
 
-:::info
-An easy way to make sure the base path is configured properly is to check if [icons](/components/icon) are loading.
-:::
-
 ### Referencing Assets
 
 Most of the magic behind assets is handled internally by Web Awesome, but if you need to reference the base path for any reason, the same module exports a function called `getBasePath()`. An optional string argument can be passed, allowing you to get the full path to any asset.
@@ -129,7 +58,7 @@ Most of the magic behind assets is handled internally by Web Awesome, but if you
 </script>
 ```
 
-## Setting a Kit Code
+## Using Font Awesome Kit Codes
 
 Font Awesome users can set their kit code to unlock Font Awesome Pro icons. You can provide it through the `data-fa-kit-code` attribute or by calling the `setKitCode()` method.
 
@@ -146,9 +75,9 @@ Font Awesome users can set their kit code to unlock Font Awesome Pro icons. You
 
 ## Cherry Picking
 
-Cherry picking can be done from [the CDN](#cdn-installation-easiest) or from [npm](#npm-installation). This approach will load only the components you need up front, while limiting the number of files the browser has to download. The disadvantage is that you need to import each individual component.
+Cherry picking will only the components you need up front, while limiting the number of files the browser has to download. The disadvantage is that you need to import each individual component on each page it's used.
 
-Here's an example that loads only the button component. Again, if you're not using a module resolver, you'll need to adjust the path to point to the folder Web Awesome is in.
+Here's an example that loads only the button component.
 
 ```html
 <link rel="stylesheet" href="/path/to/web-awesome/%NPMDIR%/themes/default.css" />
@@ -166,44 +95,6 @@ You can copy and paste the code to import a component from the "Importing" secti
 You will see files named `chunk.[hash].js` in the `chunks` directory. Never import these files directly, as they are generated and change from version to version.
 :::
 
-## Bundling
+## Using Web Awesome with npm
 
-Web Awesome is distributed as a collection of standard ES modules that [all modern browsers can understand](https://caniuse.com/es6-module). However, importing a lot of modules can result in a lot of HTTP requests and potentially longer load times. Using a CDN can alleviate this, but some users may wish to further optimize their imports with a bundler.
-
-To use Web Awesome with a bundler, first install Web Awesome along with your bundler of choice.
-
-```bash
-npm install @shoelace-style/webawesome
-```
-
-Now it's time to configure your bundler. Configurations vary for each tool, but here are some examples to help you get started.
-
-- [Example webpack config](https://github.com/shoelace-style/webpack-example/blob/master/webpack.config.js)
-- [Example Rollup config](https://github.com/shoelace-style/rollup-example/blob/master/rollup.config.js)
-
-Once your bundler is configured, you'll be able to import Web Awesome components and utilities.
-
-```js
-import '/path/to/web-awesome/%NPMDIR%/themes/default.css';
-import '/path/to/web-awesome/%NPMDIR%/components/button/button.js';
-import '/path/to/web-awesome/%NPMDIR%/components/icon/icon.js';
-import '/path/to/web-awesome/%NPMDIR%/components/input/input.js';
-import '/path/to/web-awesome/%NPMDIR%/components/rating/rating.js';
-import { setBasePath } from '/path/to/web-awesome/%NPMDIR%/webawesome.js';
-
-// Set the base path to the folder you copied Web Awesome's assets to
-setBasePath('/path/to/web-awesome/%NPMDIR%');
-
-// <wa-button>, <wa-icon>, <wa-input>, and <wa-rating> are ready to use!
-```
-
-## The difference between CDN and npm
-
-You'll notice that the CDN links all start with `/%CDNDIR%/<path>` and npm imports use `/%NPMDIR%/<path>`. The `/%CDNDIR%` files are bundled separately from the `/%NPMDIR%` files. The `/%CDNDIR%` files come pre-bundled, which means all dependencies are inlined so you do not need to worry about loading additional libraries. The `/%NPMDIR%` files **DO NOT** come pre-bundled, allowing your bundler of choice to more efficiently deduplicate dependencies, resulting in smaller bundles and optimal code sharing.
-
-TL;DR:
-
-- `/path/to/web-awesome/%CDNDIR%` is for CDN users
-- `/path/to/web-awesome/%NPMDIR%` is for npm users
-
-This change was introduced in `v2.5.0` to address issues around installations from npm loading multiple versions of libraries (such as the Lit) that Web Awesome uses internally.
+An npm package isn't available in the early backer alpha release, but we'll have one soon! For now, please enjoy Web Awesome from the CDN as described above.

docs/docs/localization.md

@@ -1,10 +1,10 @@
 ---
 title: Localization
 description: Discover how to localize Web Awesome with minimal effort.
-layout: page.njk
+layout: page
 ---
 
-Components can be localized by importing the appropriate translation file and setting the desired [`lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) and/or [`dir` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir) on the `<html>` element. Here's an example that renders Web Awesome components in Spanish.
+Components can be localized by importing the appropriate translation file and setting the desired [`lang`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) and/or [`dir`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir) attributes on the `<html>` element. Here's an example that renders Web Awesome components in Spanish.
 
 ```html
 <html lang="es">

docs/docs/patterns/ecommerce.md

@@ -1,7 +1,7 @@
 ---
 title: E-commerce
 description: TODO
-layout: page.njk
+layout: page
 ---
 
 TODO Page Description
@@ -26,7 +26,7 @@ TODO Page Description
       <div style="font-size: small;">Off-white Jordan One</div>
       <div style="display:flex; justify-content: space-between; align-items: center;">
         <span>Qty: 1</span>
-        <wa-button variant="text" size="small">Remove</wa-button>
+        <wa-button appearance="text" size="small">Remove</wa-button>
       </div>
     </div>
   </section>
@@ -40,7 +40,7 @@ TODO Page Description
       <div style="font-size: small;">50/50 Cotton Poly Blend</div>
       <div style="display:flex; justify-content: space-between; align-items: center;">
         <span>Qty: 1</span>
-        <wa-button variant="text" size="small">Remove</wa-button>
+        <wa-button appearance="text" size="small">Remove</wa-button>
       </div>
     </div>
   </section>
@@ -54,7 +54,7 @@ TODO Page Description
       <div style="font-size: small;">100% Cotton</div>
       <div style="display:flex; justify-content: space-between; align-items: center;">
         <span>Qty: 1</span>
-        <wa-button variant="text" size="small">Remove</wa-button>
+        <wa-button appearance="text" size="small">Remove</wa-button>
       </div>
     </div>
   </section>
@@ -284,7 +284,7 @@ TODO Page Description
 
        <div style="display: flex;justify-content: space-between;align-items: baseline;">
         <span><wa-icon name="check" style="color: green; margin-right: 0.5rem;"></wa-icon> In Stock</span>
-        <wa-button variant="text" size="small">Remove</wa-button>
+        <wa-button appearance="text" size="small">Remove</wa-button>
         </div>
     </div>
 
@@ -301,7 +301,7 @@ TODO Page Description
 
        <div style="display: flex;justify-content: space-between;align-items: baseline;">
         <span><wa-icon name="check" style="color: green; margin-right: 0.5rem;"></wa-icon> In Stock</span>
-        <wa-button variant="text" size="small">Remove</wa-button>
+        <wa-button appearance="text" size="small">Remove</wa-button>
         </div>
     </div>
 
@@ -318,7 +318,7 @@ TODO Page Description
 
        <div style="display: flex;justify-content: space-between;align-items: baseline;">
         <span><wa-icon name="check" style="color: green; margin-right: 0.5rem;"></wa-icon> In Stock</span>
-        <wa-button variant="text" size="small">Remove</wa-button>
+        <wa-button appearance="text" size="small">Remove</wa-button>
         </div>
     </div>
 
@@ -469,8 +469,8 @@ TODO Page Description
       <span>$95.00</span>
     </span>
       <span style="display: grid;grid-template-columns: 1fr 1fr;column-gap: 1rem;">
-        <wa-button variant="neutral" outline>View Order</wa-button>
-        <wa-button variant="neutral" outline>View Invoice</wa-button>
+        <wa-button variant="neutral" appearance="outline">View Order</wa-button>
+        <wa-button variant="neutral" appearance="outline">View Invoice</wa-button>
       </span>
   </div>
   <div>

docs/docs/resources/accessibility.md

@@ -1,7 +1,7 @@
 ---
 title: Accessibility Commitment
 description: Web Awesome recognizes the need for all users to have undeterred access to the websites and applications that are created with it.
-layout: page.njk
+layout: page
 ---
 
 Web Awesome recognizes the need for all users, regardless of ability and device, to have undeterred access to the websites and applications that are created with it. This is an important goal of the project.

docs/docs/resources/community.md

@@ -1,7 +1,7 @@
 ---
 title: Community
 description: Web Awesome has a growing community of designers and developers that are building amazing things with web components.
-layout: page.njk
+layout: page
 ---
 
 Web Awesome has a growing community of designers and developers that are building amazing things with web components. We'd love for you to become a part of it!

docs/docs/resources/contributing.md

@@ -1,10 +1,10 @@
 ---
 title: Contributing
 description: Web Awesome is an open source project, meaning everyone can use it and contribute to its development.
-layout: page.njk
+layout: page
 ---
 
-Web Awesome is an open source project, meaning everyone can use it and contribute to its development. When you join our community, you'll find a friendly group of enthusiasts at all experience levels who are willing to chat about anything and everything related to Web Awesome.
+Many Web Awesome components are open source, meaning everyone can use them and contribute to their development. When you join our community, you'll find a friendly group of enthusiasts at all experience levels who are willing to chat about anything and everything related to Web Awesome.
 
 The easiest way to get started contributing is to join the [community chat](https://discord.gg/mg8f26C). This is where we hang out, discuss new ideas, ask for feedback, and more!
 
@@ -31,10 +31,10 @@ I realize that one cannot reasonably enforce this any more than one can enforce
 
 ## Using the Issue Tracker
 
-The [issue tracker](https://github.com/shoelace-style/shoelace/issues) is for bug reports, feature requests, and pull requests.
+The [issue tracker](https://github.com/shoelace-style/webawesome-alpha/issues) is for bug reports, feature requests, and pull requests.
 
-- Please **do not** use the issue tracker for personal support requests. Use [the discussion forum](https://github.com/shoelace-style/shoelace/discussions/categories/help) instead.
-- Please **do not** use the issue tracker for feature requests. Use [the discussion forum](https://github.com/shoelace-style/shoelace/discussions/categories/ideas) instead.
+- Please **do not** use the issue tracker for personal support requests. Use [the discussion forum](https://github.com/shoelace-style/webawesome-alpha/discussions/categories/help-support) instead.
+- Please **do not** use the issue tracker for feature requests. Use [the discussion forum](https://github.com/shoelace-style/webawesome-alpha/discussions/categories/ideas) instead.
 - Please **do not** derail, hijack, or troll issues. Keep the discussion on topic and be respectful of others.
 - Please **do not** post comments with "+1" or "👍". Use [reactions](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) instead.
 - Please **do** use the issue tracker for feature requests, bug reports, and pull requests.
@@ -43,7 +43,7 @@ Issues that do not follow these guidelines are subject to closure. There simply
 
 ### Feature Requests
 
-Feature requests can be added using [the discussion forum](https://github.com/shoelace-style/shoelace/discussions/categories/ideas).
+Feature requests can be added using [the discussion forum](https://github.com/shoelace-style/webawesome-alpha/discussions/categories/ideas).
 
 - Please **do** search for an existing request before suggesting a new feature.
 - Please **do** use the voting buttons to vote for a feature.
@@ -75,79 +75,9 @@ The author reserves the right to reject any PR that's outside the scope of the p
 
 ### Branches
 
-`current` - This branch reflects the latest release and powers [shoelace.style](https://shoelace.style/).
+`current` - This branch reflects the latest release.
 
-`next` - This is the branch you should submit pull requests against. It reflects what's coming in the _next_ release, which can be previewed at [next.shoelace.style](https://next.shoelace.style/).
-
-## Developing
-
-To set up a local dev environment, [fork the repo](https://github.com/shoelace-style/shoelace/fork) on GitHub, clone it locally, and install its dependencies.
-
-```bash
-git clone https://github.com/YOUR_GITHUB_USERNAME/webawesome
-cd webawesome
-npm install
-```
-
-Once you've cloned the repo, run the following command to spin up the dev server.
-
-```bash
-npm start
-```
-
-After the initial build, a browser will open automatically to a local version of the docs. The documentation is powered by Eleventy and a number of custom plugins.
-
-### Cloud-based Development
-
-Alternatively, you can use [Gitpod](https://www.gitpod.io/) to setup a dev environment in the cloud using only your browser.
-
-[![Open in Gitpod](/assets/images/gitpod.svg)](https://gitpod.io/#https://github.com/shoelace-style/shoelace)
-
-### Creating New Components
-
-To scaffold a new component, run the following command, replacing `wa-tag-name` with the desired tag name.
-
-```bash
-npm run create wa-tag-name
-```
-
-This will generate a source file, a stylesheet, and a docs page for you. When you start the dev server, you'll find the new component in the "Components" section of the sidebar.
-
-### Dev Sandbox
-
-Component development occurs _within_ the local docs site. I've found that offering common variations _in the docs_ is more beneficial for users than segmenting demos and code examples into separate tools such as Storybook. This encourages more thorough documentation, streamlines development for maintainers, and simplifies how the project is built. It also reduces installation and startup times significantly.
-
-There is currently no hot module reloading (HMR), as browsers don't provide a way to unregister custom elements. However, most changes to the source will reload the browser automatically.
-
-For more information about running and building the project locally, refer to `README.md` in the project's root.
-
-### Testing
-
-Web Awesome uses [Web Test Runner](https://modern-web.dev/guides/test-runner/getting-started/) for testing. To launch the test runner during development, open a terminal and launch the dev server.
-
-```bash
-npm start
-```
-
-In a second terminal window, launch the test runner.
-
-```bash
-npm run test:watch
-```
-
-Follow the on-screen instructions to work with the test runner. Tests will automatically re-run as you make changes.
-
-To run all tests only once:
-
-```bash
-npm run test
-```
-
-To test a single component, use the component's basename as shown in the following example.
-
-```bash
-npm run test:component breadcrumb-item
-```
+`next` - This is the branch you should submit pull requests against. It reflects what's coming in the _next_ release.
 
 ## Documentation
 
@@ -225,7 +155,7 @@ This section can be a lot to digest in one sitting, so don't feel like you need
 
 Web Awesome is built with accessibility in mind. Creating generic components that are fully accessible to users with varying capabilities across a multitude of circumstances is a daunting challenge. Oftentimes, the solution to an a11y problem is not written in black and white and, therefore, we may not get it right the first time around. There are, however, guidelines we can follow in our effort to make Web Awesome an accessible foundation from which applications and websites can be built.
 
-We take this commitment seriously, so please ensure your contributions have this goal in mind. If you need help with anything a11y-related, please [reach out to the community](/resources/community) for assistance. If you discover an accessibility concern within the library, please file a bug on the [issue tracker](https://github.com/shoelace-style/shoelace/issues).
+We take this commitment seriously, so please ensure your contributions have this goal in mind. If you need help with anything a11y-related, please [reach out to the community](/resources/community) for assistance. If you discover an accessibility concern within the library, please file a bug on the [issue tracker](https://github.com/shoelace-style/webawesome-alpha/issues).
 
 It's important to remember that, although accessibility starts with foundational components, it doesn't end with them. It everyone's responsibility to encourage best practices and ensure we're providing an optimal experience for all of our users.
 
@@ -328,8 +258,8 @@ To expose custom properties as part of a component's API, scope them to the `:ho
 
 ```css
 :host {
-  --color: var(--wa-color-brand-text-on-spot);
-  --background-color: var(--wa-color-brand-spot);
+  --color: var(--wa-color-brand-on-loud);
+  --background-color: var(--wa-color-brand-fill-loud);
 }
 ```
 

docs/docs/themes.md

@@ -1,12 +1,12 @@
 ---
 title: Themes
 description: Everything you need to know about theming Web Awesome.
-layout: page.njk
+layout: page
 ---
 
-Web Awesome is designed to be highly customizable through pure CSS. Out of the box, you can choose from a light or dark theme. Alternatively, you can design your own theme.
+Web Awesome is designed to be highly customizable through pure CSS. Out of the box, the default theme includes both light and dark styles. Alternatively, you can design your own theme.
 
-A theme is nothing more than a stylesheet that uses the Web Awesome API to define design tokens and apply custom styles to components. To create a theme, you will need a decent understanding of CSS, including [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) and the [`::part` selector](https://developer.mozilla.org/en-US/docs/Web/CSS/::part).
+In essence, a theme is a stylesheet that uses the Web Awesome API to define custom properties and apply custom styles to components. To create a theme, you will need a decent understanding of CSS, including [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) and the [`::part` selector](https://developer.mozilla.org/en-US/docs/Web/CSS/::part).
 
 :::info
 For component developers, built-in themes are also available as JavaScript modules that export [Lit CSSResult](https://lit.dev/docs/api/styles/#CSSResult) objects. You can find them in `/%NPMDIR%/themes/*.styles.js`.
@@ -14,7 +14,7 @@ For component developers, built-in themes are also available as JavaScript modul
 
 ## Theme Basics
 
-All themes are scoped to classes using the `wa-theme-{name}` convention, where `{name}` is a lowercase, hyphen-delimited value representing the name of the theme. The included light and dark themes use `wa-theme-default-light` and `wa-theme-default-dark`, respectively. A custom theme called "Purple Power", for example, would use a class called `wa-theme-purple-power`
+All themes are scoped to classes using the format `wa-theme-{name}`, where `{name}` is a lowercase, hyphen-delimited value representing the name of the theme. The included theme uses `wa-theme-default-light` and `wa-theme-default-dark` for light and dark styles, respectively. A custom theme called "Purple Power", for example, would use a class called `wa-theme-purple-power`.
 
 All selectors must be scoped to the theme's class to ensure interoperability with other themes. You should also scope them to `:host` so they can be imported and applied to custom element shadow roots.
 
@@ -25,14 +25,16 @@ All selectors must be scoped to the theme's class to ensure interoperability wit
 }
 ```
 
+In the default theme, all CSS custom properties that make up Web Awesome's theming API, from colors to transitions, are scoped to both `:root` and `wa-theme-default-light`. `wa-theme-default-dark`, on the other hand, only defines a subset of custom properties for colors. This ensures that non-color styles only need to be defined once for the theme, regardless of whether the color scheme is light or dark.
+
 ### Activating Themes
 
-To activate a theme, import it and apply the theme's class to the `<html>` element. This example imports and activates the built-in dark theme.
+To activate a theme, import it and apply the theme's class to the `<html>` element. This example imports and activates the default theme with dark styles.
 
 ```html
 <html class="wa-theme-default-dark">
   <head>
-    <link rel="stylesheet" href="path/to/shoelace/%NPMDIR%/themes/dark.css" />
+    <link rel="stylesheet" href="path/to/webawesome/%NPMDIR%/themes/default.css" />
   </head>
 
   <body>
@@ -42,18 +44,17 @@ To activate a theme, import it and apply the theme's class to the `<html>` eleme
 ```
 
 :::info
-There is one exception to this rule — the light theme _does not_ need to be activated. For convenience, the light theme is scoped to `:root` and will be activated by default when imported.
+There is one exception to this rule — the default light styles _do not_ need to be activated. For convenience, these styles are scoped to `:root` and will be activated by default when imported.
 :::
 
 ### Using Multiple Themes
 
-You can activate themes on various containers throughout the page. This example uses the light theme with a dark-themed sidebar.
+You can activate different themes and styles on various containers throughout the page. This example uses the default theme with a dark sidebar.
 
 ```html
 <html>
   <head>
     <link rel="stylesheet" href="path/to/shoelace/%NPMDIR%/themes/default.css" />
-    <link rel="stylesheet" href="path/to/shoelace/%NPMDIR%/themes/dark.css" />
   </head>
 
   <body>
@@ -70,13 +71,13 @@ It's for this reason that themes must be scoped to specific classes.
 
 ## Creating Themes
 
-There are two ways to create themes. The easiest way is to customize a built-in theme. The advanced way is to create a new theme from scratch. Which method you choose depends on your project's requirements and the amount of effort you're willing to commit to.
+There are two ways to create themes. The easiest way is to customize the default theme. The advanced way is to create a new theme from scratch. Which method you choose depends on your project's requirements and the amount of effort you're willing to invest.
 
 ### Customizing a Built-in Theme
 
-The easiest way to customize Web Awesome is to override one of the built-in themes. You can do this by importing the light or dark theme as-is, then creating a separate stylesheet that overrides [design tokens](/getting-started/customizing#design-tokens) and adds [component styles](/getting-started/customizing#component-parts) to your liking. You must import your theme _after_ the built-in theme.
+Overriding the default theme is the easiest way to customize Web Awesome. You can do this by importing the default theme as-is, then creating a separate stylesheet that overrides [the theming API](/getting-started/customizing#design-tokens) and adds [component styles](/getting-started/customizing#component-parts) to your liking. You must import your theme _after_ the default theme.
 
-If you're customizing the light theme, you should scope your styles to the following selectors.
+If you're customizing the default light styles, scope your styles to the following selectors.
 
 ```css
 :root,
@@ -86,7 +87,7 @@ If you're customizing the light theme, you should scope your styles to the follo
 }
 ```
 
-If you're customizing the dark theme, you should scope your styles to the following selectors.
+If you're customizing the default dark styles, scope your styles to the following selectors.
 
 ```css
 :host,
@@ -95,13 +96,13 @@ If you're customizing the dark theme, you should scope your styles to the follow
 }
 ```
 
-By customizing a built-in theme, you'll maintain a smaller stylesheet containing only the changes you've made. Contrast this to [creating a new theme](#creating-a-new-theme), where you need to explicitly define every design token required by the library. This approach is more "future-proof," as new design tokens that emerge in subsequent versions of Web Awesome will be accounted for by the built-in theme.
+By customizing a built-in theme, you'll maintain a smaller stylesheet containing only the changes you've made. Contrast this to [creating a new theme](#creating-a-new-theme), where you need to explicitly define every custom property required by the library. This approach is more "future-proof," as new design tokens that emerge in subsequent versions of Web Awesome will be accounted for by built-in themes.
 
 While this approach is easier to maintain, the drawback is that your theme can't be activated independently — it's tied to the built-in theme you're extending.
 
 ### Creating a New Theme
 
-Creating a new theme is more of an undertaking than [customizing an existing one](#customizing-a-built-in-theme). At a minimum, you must implement all of the required design tokens. The easiest way to do this is by "forking" one of the built-in themes and modifying it from there.
+Creating a new theme is more of an undertaking than [customizing an existing one](#customizing-a-built-in-theme). At a minimum, you must implement all of the required custom properties. The easiest way to do this is by "forking" a built-in theme and modifying it from there.
 
 Start by changing the selector to match your theme's name. Assuming your new theme is called "Purple Power", your theme should be scoped like this.
 
@@ -112,36 +113,13 @@ Start by changing the selector to match your theme's name. Assuming your new the
 }
 ```
 
-By creating a new theme, you won't be relying on a built-in theme as a foundation. Because the theme is decoupled from the built-ins, you can activate it independently as an alternative to the built-ins. This is the recommended approach if you're looking to open source your theme for others to use.
+By creating a new theme, you won't be relying on a built-in theme as a foundation. Because of this, you can activate it independently as an alternative to the default theme. This is the recommended approach if you're looking to open source your theme for others to use.
 
-You will, however, need to maintain your theme more carefully, as new versions of Web Awesome may introduce new design tokens that your theme won't have accounted for. Because of this, it's recommended that you clearly specify which version(s) of Web Awesome your theme is designed to work with and keep it up to date as new versions of Web Awesome are released.
+You will, however, need to maintain your theme more carefully, as new versions of Web Awesome change the theming API in ways that your theme won't have accounted for. It's recommended that you clearly specify which version(s) of Web Awesome your theme is designed to work with and keep it up to date as new versions of Web Awesome are released.
 
-## Dark Theme
+## Detecting Color Scheme Preference
 
-The built-in dark theme uses an inverted color scale so, if you're using design tokens as intended, you'll get dark mode for free. While this isn't the same as a professionally curated dark theme, it provides an excellent baseline for one and you're encouraged to customize it depending on your needs.
-
-The dark theme works by taking the light theme's [color tokens](/tokens/color) and "flipping" the scale so 100 becomes 900, 200 becomes 800, 300 becomes 700, etc. Next, the luminance of each primitive was fine-tuned to avoid true black, which is often undesirable in dark themes, and provide a richer experience. The result is a custom dark palette that complements the light theme and makes it easy to offer light and dark modes with minimal effort.
-
-To install the dark theme, add the following to the `<head>` section of your page.
-
-```html
-<link
-  rel="stylesheet"
-  href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/themes/dark.css"
-/>
-```
-
-To activate the theme, apply the `wa-theme-default-dark` class to the `<html>` element.
-
-```html
-<html class="wa-theme-default-dark">
-  ...
-</html>
-```
-
-### Detecting the User's Color Scheme Preference
-
-Web Awesome doesn't try to auto-detect the user's light/dark mode preference. This should be done at the application level. As a best practice, to provide a dark theme in your app, you should:
+Web Awesome's default theme has both light and dark styles built in. However, Web Awesome doesn't try to auto-detect the user's light/dark mode preference. This should be done at the application level. As a best practice, to provide a dark theme in your app, you should:
 
 - Check for [`prefers-color-scheme`](https://stackoverflow.com/a/57795495/567486) and use its value by default
 - Allow the user to override the setting in your app

docs/docs/theming/borders.md

@@ -0,0 +1,48 @@
+---
+title: Borders
+description: Change the edges and corners of your components with Web Awesome's border properties.
+layout: page
+---
+
+## Style
+
+Border style controls the standard line shape of borders throughout Web Awesome.
+
+| Custom Property     | Default Value | Preview                                                                 |
+| ------------------- | ------------- | ----------------------------------------------------------------------- |
+| `--wa-border-style` | `solid`       | <div class="swatch" style="border-style: var(--wa-border-style)"></div> |
+
+## Width
+
+Border widths use `rem` units in order to scale proportionately with the root font size. 
+
+Each border width value uses a `calc()` function with `--wa-border-width-multiplier` to scale all border widths at once. By default, this multiplier is `0.0625`. The table below lists the result of the calculation.
+
+| Custom Property       | Default Value                    | Preview                                                                   |
+| --------------------- | -------------------------------- | ------------------------------------------------------------------------- |
+| `--wa-border-width-s` | `0.0625rem` <small>(1px)</small> | <div class="swatch" style="border-width: var(--wa-border-width-s)"></div> |
+| `--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> |
+
+## Radius
+
+Border radius controls the corners of Web Awesome components.
+
+Common border radius properties allow you to achieve specific shapes beyond your theme's preferred corner styles.
+
+| Custom Property             | Default Value | Preview                                                                                               |
+| --------------------------- | ------------- | ----------------------------------------------------------------------------------------------------- |
+| `--wa-border-radius-pill`   | `9999px`      | <div class="swatch" style="border-radius: var(--wa-border-radius-pill)"></div>                        |
+| `--wa-border-radius-circle` | `50%`         | <div class="swatch" style="aspect-ratio: 1 / 1; border-radius: var(--wa-border-radius-circle)"></div> |
+| `--wa-border-radius-square` | `0px`         | <div class="swatch" style="border-radius: var(--wa-border-radius-square)"></div>                      |
+
+Size-based border radius properties allow you to customize the overall roundness of Web Awesome components. These use `rem` units in order to scale proportionately with the root font size. 
+
+Each property uses a `calc()` function with `--wa-border-radius-multiplier` to scale all border radii at once. By default, this multiplier is `0.375`. The table below lists the result of the calculation.
+
+| Custom Property         | Default Value                    |  Preview                                                                     |
+| ----------------------- | -------------------------------- | ---------------------------------------------------------------------------- |
+| `--wa-border-radius-xs` | `0.1875rem` <small>(3px)</small> | <div class="swatch" style="border-radius: var(--wa-border-radius-xs)"></div> |
+| `--wa-border-radius-s`  | `0.375rem` <small>(6px)</small>  | <div class="swatch" style="border-radius: var(--wa-border-radius-s)"></div>  |
+| `--wa-border-radius-m`  | `0.75rem` <small>(12px)</small>  | <div class="swatch" style="border-radius: var(--wa-border-radius-m)"></div>  |
+| `--wa-border-radius-l`  | `1.125rem` <small>(18px)</small> | <div class="swatch" style="border-radius: var(--wa-border-radius-l)"></div>  |

docs/docs/theming/color.md

@@ -0,0 +1,495 @@
+---
+title: Color
+description: Ensure consistent use of color and readable contrast with Web Awesome's color properties.
+layout: page
+---
+
+<style>
+  .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-{name}-{#}`.
+
+<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">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 style="color: var(--wa-color-text-normal)">AaBb</div> |
+| `--wa-color-text-quiet`  | <div style="color: var(--wa-color-text-quiet)">AaBb</div>  |
+| `--wa-color-text-link`   | <div style="color: var(--wa-color-text-link)">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" 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" style="--mix-color: var(--wa-color-mix-hover)"><small>mixed</small></div>  |
+| `--wa-color-mix-active` | <div class="swatch color-mix-example" 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" style="border-color: var(--wa-color-brand-border-quiet)"></div> | <div class="swatch" style="border-color: var(--wa-color-success-border-quiet)"></div> | <div class="swatch" style="border-color: var(--wa-color-neutral-border-quiet)"></div> | <div class="swatch" style="border-color: var(--wa-color-warning-border-quiet)"></div> | <div class="swatch" style="border-color: var(--wa-color-danger-border-quiet)"></div> |
+| `--wa-color-*-border-normal` | <div class="swatch" style="border-color: var(--wa-color-brand-border-normal)"></div> | <div class="swatch" style="border-color: var(--wa-color-success-border-normal)"></div> | <div class="swatch" style="border-color: var(--wa-color-neutral-border-normal)"></div> | <div class="swatch" style="border-color: var(--wa-color-warning-border-normal)"></div> | <div class="swatch" style="border-color: var(--wa-color-danger-border-normal)"></div> |
+| `--wa-color-*-border-loud`   | <div class="swatch" style="border-color: var(--wa-color-brand-border-loud)"></div> | <div class="swatch" style="border-color: var(--wa-color-success-border-loud)"></div> | <div class="swatch" style="border-color: var(--wa-color-neutral-border-loud)"></div> | <div class="swatch" style="border-color: var(--wa-color-warning-border-loud)"></div> | <div class="swatch" style="border-color: var(--wa-color-danger-border-loud)"></div> |
+| `--wa-color-*-on-quiet`      | <div class="swatch" style="background-color: var(--wa-color-brand-fill-quiet); color: var(--wa-color-brand-on-quiet)">AaBb</div> | <div class="swatch" style="background-color: var(--wa-color-success-fill-quiet); color: var(--wa-color-success-on-quiet)">AaBb</div> | <div class="swatch" style="background-color: var(--wa-color-neutral-fill-quiet); color: var(--wa-color-neutral-on-quiet)">AaBb</div> | <div class="swatch" style="background-color: var(--wa-color-warning-fill-quiet); color: var(--wa-color-warning-on-quiet)">AaBb</div> | <div class="swatch" 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" style="background-color: var(--wa-color-brand-fill-normal); color: var(--wa-color-brand-on-normal)">AaBb</div> | <div class="swatch" style="background-color: var(--wa-color-success-fill-normal); color: var(--wa-color-success-on-normal)">AaBb</div> | <div class="swatch" style="background-color: var(--wa-color-neutral-fill-normal); color: var(--wa-color-neutral-on-normal)">AaBb</div> | <div class="swatch" style="background-color: var(--wa-color-warning-fill-normal); color: var(--wa-color-warning-on-normal)">AaBb</div> | <div class="swatch" 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" style="background-color: var(--wa-color-brand-fill-loud); color: var(--wa-color-brand-on-loud)">AaBb</div> | <div class="swatch" style="background-color: var(--wa-color-success-fill-loud); color: var(--wa-color-success-on-loud)">AaBb</div> | <div class="swatch" style="background-color: var(--wa-color-neutral-fill-loud); color: var(--wa-color-neutral-on-loud)">AaBb</div> | <div class="swatch" style="background-color: var(--wa-color-warning-fill-loud); color: var(--wa-color-warning-on-loud)">AaBb</div> | <div class="swatch" style="background-color: var(--wa-color-danger-fill-loud); color: var(--wa-color-danger-on-loud)">AaBb</div> |

docs/docs/theming/component-groups.md

@@ -0,0 +1,117 @@
+---
+title: Component Groups
+description: Style groups of components that share similar qualities with these Web Awesome custom properties.
+layout: page
+---
+
+For components that share similar qualities, Web Awesome includes custom properties to change the appearance of these related components all at once.
+
+## Form Controls
+
+Components such as [input](/docs/components/input), [select](/docs/components/select), [textarea](/docs/components/textarea), [checkbox](/docs/components/checkbox), etc. share a number of styles to give your forms a cohesive appearance. Web Awesome defines custom properties for these styles using the format `--wa-form-control-{style}`.
+
+Not every form control uses all of these custom properties. For example, `<wa-radio>` defines its own height and border radius to achieve its familiar shape but shares many other styles with other components for a cohesive look and feel. Similarly, `<wa-button>` defines many of its own styles but matches the height and border width of other form controls.
+
+| Custom Property                             | Default Value                                                                                     |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `--wa-form-control-background-color`              | `var(--wa-color-surface-default)`                                                                 |
+| `--wa-form-control-border-style`            | `var(--wa-border-style)`                                                                          |
+| `--wa-form-control-border-width`            | `var(--wa-border-width-s)`                                                                        |
+| `--wa-form-control-border-radius`           | `var(--wa-border-radius-s)`                                                                       |
+| `--wa-form-control-activated-color`         | `var(--wa-color-brand-fill-loud)`                                                                 |
+| `--wa-form-control-resting-color`           | `var(--wa-color-neutral-border-loud)`                                                             |
+| `--wa-form-control-label-color`             | `var(--wa-color-neutral-border-loud)`                                                             |
+| `--wa-form-control-label-font-weight`       | `var(--wa-font-weight-normal)`                                                                    |
+| `--wa-form-control-label-line-height`       | `var(--wa-line-height-normal)`                                                                    |
+| `--wa-form-control-value-color`             | `var(--wa-color-text-normal)`                                                                     |
+| `--wa-form-control-value-font-weight`       | `var(--wa-font-weight-body)`                                                                      |
+| `--wa-form-control-value-line-height`       | `var(--wa-line-height-condensed)`                                                                 |
+| `--wa-form-control-placeholder-color`       | `var(--wa-color-base-60)`                                                                         |
+| `--wa-form-control-height-s`                | `calc(var(--wa-space-xs) * 2 + var(--wa-font-size-s) * var(--wa-form-control-value-line-height))` |
+| `--wa-form-control-height-m`                | `calc(var(--wa-space-s) * 2 + var(--wa-font-size-m) * var(--wa-form-control-value-line-height))`  |
+| `--wa-form-control-height-l`                | `calc(var(--wa-space-m) * 2 + var(--wa-font-size-l) * var(--wa-form-control-value-line-height))`  |
+| `--wa-form-control-required-content`        | `'*'`                                                                                             |
+| `--wa-form-control-required-content-color`  | `inherit`                                                                                         |
+| `--wa-form-control-required-content-offset` | `-0.1em`                                                                                          |
+
+```html {.example}
+<form class="wa-block-spacing-l">
+  <wa-input label="Input" placeholder="Placeholder"></wa-input>
+  <wa-select label="Select" value="option-1">
+    <wa-option value="option-1">Option 1</wa-option>
+    <wa-option value="option-2">Option 2</wa-option>
+    <wa-option value="option-3">Option 3</wa-option>
+  </wa-select>
+  <wa-textarea label="Textarea" placeholder="Placeholder"></wa-textarea>
+  <wa-radio-group label="Radio group" name="a" value="1">
+    <wa-radio value="1">Option 1</wa-radio>
+    <wa-radio value="2">Option 2</wa-radio>
+    <wa-radio value="3">Option 3</wa-radio>
+  </wa-radio-group>
+  <wa-checkbox>Checkbox</wa-checkbox>
+  <wa-switch>Switch</wa-switch>
+  <wa-range label="Range"></wa-range>
+  <wa-button>Button</wa-button>
+</form>
+
+<style>
+  .wa-block-spacing-l > * + *, wa-radio {
+    display: block;
+    margin-block-start: var(--wa-space-l);
+  }
+  wa-radio {
+    margin-block-start: var(--wa-space-2xs);
+  }
+  wa-radio, wa-checkbox, wa-switch, wa-button {
+    width: fit-content;
+  }
+</style>
+```
+
+## Panels
+
+Panels consist of components with larger, contained surface areas like [callout](/docs/components/callout), [card](/docs/components/card), [details](/docs/components/details), and [dialog](/docs/components/dialog).
+
+| Custom Property            | Default Value               |
+| -------------------------- | --------------------------- |
+| `--wa-panel-border-style`  | `var(--wa-border-style)`    |
+| `--wa-panel-border-width`  | `var(--wa-border-width-s)`  |
+| `--wa-panel-border-radius` | `var(--wa-border-radius-m)` |
+
+```html {.example}
+<div class="wa-block-spacing-l">
+  <wa-callout>
+    <wa-icon slot="icon" name="circle-info" variant="regular"></wa-icon>
+    This is a simple callout with an icon.
+  </wa-callout>
+  <wa-card>Here's a basic, no-nonsense card.</wa-card>
+  <wa-details summary="Details">
+    <code>wa-details</code>, at your service.
+  </wa-details>
+</div>
+
+<style>
+  .wa-block-spacing-l > * + * {
+    display: block;
+    margin-block-start: var(--wa-space-l);
+  }
+</style>
+```
+
+## Tooltips
+
+Tooltip styles are shared between the [tooltip](/docs/components/tooltip) component and the tooltip implementation in [range](/docs/components/range).
+
+| Custom Property              | Default Value                       |
+| ---------------------------- | ----------------------------------- |
+| `--wa-tooltip-arrow-size`    | `0.375rem` <small>(6px)</small>     |
+| `--wa-tooltip-background-color`    | `var(--wa-color-neutral-fill-loud)` |
+| `--wa-tooltip-border-radius` | `var(--wa-border-radius-s)`         |
+| `--wa-tooltip-content-color` | `var(--wa-color-neutral-on-loud)`   |
+| `--wa-tooltip-font-size`     | `var(--wa-font-size-s)`             |
+| `--wa-tooltip-line-height`   | `var(--wa-line-height-normal)`      |
+
+```html {.example}
+<wa-icon-button id="bullseye-example" label="Button" name="bullseye"></wa-icon-button>
+<wa-tooltip for="bullseye-example" open trigger="manual">This is a tooltip</wa-tooltip>
+```

docs/docs/theming/focus.md

@@ -0,0 +1,35 @@
+---
+title: Focus
+description: Configure recognizable focus states with Web Awesome's focus properties.
+layout: page
+---
+
+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.
+
+
+| Custom Property          |  Default Value                                                                |
+| ------------------------ | ----------------------------------------------------------------------------- |
+| `--wa-focus-ring-style`  | `solid`                                                                       |
+| `--wa-focus-ring-width`  | `0.1875rem` <small>(3px)</small>                                              |
+| `--wa-focus-ring`        | `var(--wa-focus-ring-style) var(--wa-focus-ring-width) var(--wa-color-focus)` |
+| `--wa-focus-ring-offset` | `0.0625rem` <small>(1px)</small>                                              |
+
+See your theme's focus ring in action by navigating this form example with your keyboard.
+
+```html {.example}
+<form class="wa-block-spacing-m">
+  <wa-input label="Text Input">
+    <span slot="help-text">Press <kbd>Tab</kbd> to move focus to other interactive elements.</span>
+  </wa-input>
+  <wa-checkbox>Checkbox</wa-checkbox>
+  <wa-button>Button</wa-button>
+</form>
+
+<style>
+  form > * + * {
+    display: block;
+    width: fit-content;
+    margin-block-start: var(--wa-space-m);
+  }
+</style>
+```

docs/docs/theming/shadows.md

@@ -0,0 +1,62 @@
+---
+title: Shadows
+description: Elevate your components with Web Awesome's shadow properties.
+layout: page
+---
+
+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 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. 
+
+| Custom Property  |  Default Value                                                      |
+| ---------------- | ------------------------------------------------------------------- |
+| `--wa-shadow-xs` | <div class="swatch" style="box-shadow: var(--wa-shadow-xs);"></div> |
+| `--wa-shadow-s`  | <div class="swatch" style="box-shadow: var(--wa-shadow-s);"></div>  |
+| `--wa-shadow-m`  | <div class="swatch" style="box-shadow: var(--wa-shadow-m);"></div>  |
+| `--wa-shadow-l`  | <div class="swatch" style="box-shadow: var(--wa-shadow-l);"></div>  |
+
+Any shadow may be implemented as an inner box shadow using the `inset` keyword, e.g. `box-shadow: inset var(--wa-shadow-xs);`.
+
+## Horizontal Offset (X)
+
+Each offset-x property uses a `calc()` function with `--wa-shadow-offset-x-multiplier` to uniformly scale horizontal offset values. By default, this multiplier is `0`. The table below lists the result of the calculation.
+
+| Custom Property           |  Default Value |
+| ------------------------- | -------------- |
+| `--wa-shadow-offset-x-xs` | `0rem`         |
+| `--wa-shadow-offset-x-s`  | `0rem`         |
+| `--wa-shadow-offset-x-m`  | `0rem`         |
+| `--wa-shadow-offset-x-l`  | `0rem`         |
+
+## Vertical Offset (Y)
+
+Each offset-y property uses a `calc()` function with `--wa-shadow-offset-y-multiplier` to uniformly scale vertical offset values. By default, this multiplier is `0.125`. The table below lists the result of the calculation.
+
+| Custom Property           |  Default Value                   |
+| ------------------------- | -------------------------------- |
+| `--wa-shadow-offset-y-xs` | `0.0625rem` <small>(1px)</small> |
+| `--wa-shadow-offset-y-s`  | `0.125rem` <small>(2px)</small>  |
+| `--wa-shadow-offset-y-m`  | `0.25rem` <small>(4px)</small>   |
+| `--wa-shadow-offset-y-l`  | `0.5rem` <small>(8px)</small>    |
+
+## Blur
+
+Each blur property uses a `calc()` function with `--wa-shadow-blur-multiplier` to uniformly scale blur values. By default, this multiplier is `0.125`. The table below lists the result of the calculation.
+
+| Custom Property       |  Default Value                   |
+| --------------------- | -------------------------------- |
+| `--wa-shadow-blur-xs` | `0.0625rem` <small>(1px)</small> |
+| `--wa-shadow-blur-s`  | `0.125rem` <small>(2px)</small>  |
+| `--wa-shadow-blur-m`  | `0.25rem` <small>(4px)</small>   |
+| `--wa-shadow-blur-l`  | `0.5rem` <small>(8px)</small>    |
+
+## Spread
+
+Each spread property uses a `calc()` function with `--wa-shadow-spread-multiplier` to uniformly scale spread values. By default, this multiplier is `-0.0625`. The table below lists the result of the calculation.
+
+| Custom Property         |  Default Value                        |
+| ----------------------- | ------------------------------------- |
+| `--wa-shadow-spread-xs` | `-0.03125rem` <small>(-0.5px)</small> |
+| `--wa-shadow-spread-s`  | `-0.0625rem` <small>(-1px)</small>    |
+| `--wa-shadow-spread-m`  | `-0.125rem` <small>(-2px)</small>     |
+| `--wa-shadow-spread-l`  | `-0.25rem` <small>(-4px)</small>      |

docs/docs/theming/space.md

@@ -0,0 +1,56 @@
+---
+title: Space
+description: Lock down consistent spacing Web Awesome's space properties.
+layout: page
+---
+
+<style>
+  .spacing-example {
+    --dot-size: 0.5em;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    background-color: var(--wa-color-neutral-fill-normal);
+    height: 2em;
+    margin-inline:var(--dot-size);
+  }
+
+  .spacing-example::before {
+    content: '';
+    aspect-ratio: 1 / 1;
+    width: var(--dot-size);
+    background-color: var(--wa-color-neutral-fill-loud);
+    border-radius: 50%;
+    margin-inline-start: calc(var(--dot-size) * -1);
+  }
+
+  .spacing-example::after {
+    content: '';
+    aspect-ratio: 1 / 1;
+    width: var(--dot-size);
+    background-color: var(--wa-color-neutral-fill-loud);
+    border-radius: 50%;
+    margin-inline-end: calc(var(--dot-size) * -1);
+  }
+</style>
+
+Space properties are used intentionally throughout Web Awesome to create predictable rhythm and meaningful proximity. These properties use `rem` units in order to scale proportionately with the root font size. 
+
+Each space property uses a `calc()` function with `--wa-space-multiplier` to scale all spacing at once. By default, this multiplier is `1`. The table below lists the result of the calculation.
+
+| Custom Property  | Default Value                   | Preview                                                               |
+| ---------------- | ------------------------------- | --------------------------------------------------------------------- |
+| `--wa-space-3xs` | `0.125rem` <small>(2px)</small> | <div class="spacing-example" style="width: var(--wa-space-3xs)"></div> |
+| `--wa-space-2xs` | `0.25rem` <small>(4px)</small>  | <div class="spacing-example" style="width: var(--wa-space-2xs)"></div> |
+| `--wa-space-xs`  | `0.5rem` <small>(8px)</small>   | <div class="spacing-example" style="width: var(--wa-space-xs)"></div>  |
+| `--wa-space-s`   | `0.75rem` <small>(12px)</small> | <div class="spacing-example" style="width: var(--wa-space-s)"></div>   |
+| `--wa-space-m`   | `1rem` <small>(16px)</small>    | <div class="spacing-example" style="width: var(--wa-space-m)"></div>   |
+| `--wa-space-l`   | `1.25rem` <small>(20px)</small> | <div class="spacing-example" style="width: var(--wa-space-l)"></div>   |
+| `--wa-space-xl`  | `1.5rem` <small>(24px)</small>  | <div class="spacing-example" style="width: var(--wa-space-xl)"></div>  |
+| `--wa-space-2xl` | `2rem` <small>(32px)</small>    | <div class="spacing-example" style="width: var(--wa-space-2xl)"></div> |
+| `--wa-space-3xl` | `3rem` <small>(48px)</small>    | <div class="spacing-example" style="width: var(--wa-space-3xl)"></div> |
+
+When using space properties, it may be helpful to consider three distinct groups:
+- Small-scale space (`3xs`, `2xs`, and `xs`) can be used for gaps between cooperating elements, such as a dropdown button and its menu, and padding within small components, such as badges and tooltips
+- Normal space (`s`, `m`, and `l`) can be used for gaps between related elements with distinct touch targets and padding within typical interface elements, such as buttons and inputs
+- Large-scale space (`xl`, `2xl`, and `3xl`) can be used for gaps between unrelated elements and padding within larger components, such as cards and dialogs