updated usage example

fix color picker label, remove inline color picker

.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)

README.md

@@ -11,11 +11,11 @@ Built by the folks behind [Font Awesome](https://fontawesome.com/).
 
 ---
 
-Documentation: [shoelace.style](https://shoelace.style)
+Documentation: [webawesome.com](https://webawesome.com)
 
-Source: [github.com/shoelace-style/shoelace](https://github.com/shoelace-style/shoelace)
+Source: [github.com/shoelace-style/webawesome](https://github.com/shoelace-style/webawesome)
 
-Twitter: [@shoelace_style](https://twitter.com/shoelace_style)
+Twitter: [@webawesomer](https://twitter.com/webawesomer)
 
 ---
 
@@ -25,7 +25,7 @@ Developers can use this documentation to learn how to build Web Awesome from sou
 
 **You don't need to do any of this to use Web Awesome!** This page is for people who want to contribute to the project, tinker with the source, or create a custom build of Web Awesome.
 
-If that's not what you're trying to do, the [documentation website](https://shoelace.style) is where you want to be.
+If that's not what you're trying to do, the [documentation website](https://webawesome.com) is where you want to be.
 
 ### What are you using to build Web Awesome?
 
@@ -33,7 +33,7 @@ Components are built with [LitElement](https://lit-element.polymer-project.org/)
 
 ### Forking the Repo
 
-Start by [forking the repo](https://github.com/shoelace-style/shoelace/fork) on GitHub, then clone it locally and install dependencies.
+Start by [forking the repo](https://github.com/shoelace-style/webawesome/fork) on GitHub, then clone it locally and install dependencies.
 
 ```bash
 git clone https://github.com/YOUR_GITHUB_USERNAME/webawesome

cspell.json

@@ -18,7 +18,6 @@
     "CACHEABLE",
     "callout",
     "callouts",
-    "cdndir",
     "chatbubble",
     "checkmark",
     "Clippy",
@@ -55,6 +54,7 @@
     "exportmaps",
     "exportparts",
     "fieldsets",
+    "fontawesome",
     "formaction",
     "formdata",
     "formenctype",
@@ -109,7 +109,6 @@
     "noopener",
     "noreferrer",
     "novalidate",
-    "npmdir",
     "Numberish",
     "oklab",
     "oklch",
@@ -178,6 +177,7 @@
     "Vuejs",
     "WCAG",
     "webawesome",
+    "webawesomer",
     "WEBP",
     "Webpacker",
     "xmark"

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/.eleventy.js

@@ -14,9 +14,16 @@ import { getComponents } from './_utils/manifest.js';
 import process from 'process';
 
 const packageData = JSON.parse(await readFile('./package.json', 'utf-8'));
+const isAlpha = process.argv.includes('--alpha');
 const isDeveloping = process.argv.includes('--develop');
 
 export default function (eleventyConfig) {
+  // NOTE - alpha setting removes certain pages
+  if (isAlpha) {
+    eleventyConfig.ignores.add('**/components/page.md');
+    eleventyConfig.ignores.add('**/experimental/**');
+  }
+
   // Add template data
   eleventyConfig.addGlobalData('package', packageData);
 
@@ -33,9 +40,7 @@ export default function (eleventyConfig) {
 
   // Shortcodes - {% shortCode arg1, arg2 %}
   eleventyConfig.addShortcode('cdnUrl', location => {
-    return (
-      `https://cdn.jsdelivr.net/npm/@shoelace-style/webawesome@${packageData.version}/` + location.replace(/^\//, '')
-    );
+    return `https://early.webawesome.com/webawesome@${packageData.version}/dist/` + location.replace(/^\//, '');
   });
 
   // Helpers

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

@@ -5,34 +5,14 @@
   <li><a href="/docs/usage">Usage</a></li>
   <li><a href="/docs/themes">Themes</a></li>
   <li><a href="/docs/customizing">Customizing</a></li>
+  <li><a href="/docs/form-controls">Form Controls</a></li>
   <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 +124,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 +161,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 +211,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

@@ -19,7 +19,7 @@
     </wa-badge>
   </div>
   <p class="component-summary">
-    {{ component.summary }}
+    {{ component.summary | inlineMarkdown | safe }}
   </p>
 {% endblock %}
 
@@ -69,41 +69,35 @@
         <thead>
           <tr>
             <th class="table-name">Name</th>
-            <th class="table-attribute">Attribute</th>
             <th class="table-description">Description</th>
             <th class="table-reflects">Reflects</th>
-            <th class="table-type">Type</th>
-            <th class="table-default">Default</th>
           </tr>
         </thead>
         <tbody>
           {% for prop in component.properties %}
             <tr>
               <td class="table-name">
-                <code>{{ prop.name }}</code>
-              </td>
-              <td class="table-attribute">
+                <code>{{ prop.name }}</code><br>
                 {% if prop.attribute %}
-                  <code>{{ prop.attribute }}</code>
+                  <div><small><code>{{ prop.attribute }}</code></small></div>
                 {% endif %}
               </td>
               <td class="table-description">
-                {{ prop.description | inlineMarkdown | safe }}
+                <div>{{ prop.description | inlineMarkdown | safe }}</div>
+                {% if prop.type.text %}
+                  <div><small><strong>Type</strong>&nbsp;<code>{{ prop.type.text | trimPipes | inlineMarkdown | safe }}</code></small></div>
+                {% endif %}
+                {% if prop.default %}
+                  <div><small><strong>Default</strong>&nbsp;<code>{{ prop.default | inlineMarkdown | safe }}</code></small></div>
+                {% endif %}
               </td>
               <td class="table-checkmark">
                 {% if prop.reflects %}
                   <wa-icon name="check"></wa-icon>
                 {% endif %}
               </td>
-              <td class="table-type">
-                {% if prop.type.text %}
-                  <code>{{ prop.type.text | trimPipes | inlineMarkdown | safe }}</code>
-                {% endif %}
-              </td>
               <td class="table-default">
-                {% if prop.default %}
-                  <code>{{ prop.default | inlineMarkdown | safe }}</code>
-                {% endif %}
+
               </td>
             </tr>
           {% endfor %}
@@ -206,17 +200,18 @@
           <tr>
             <th class="table-name">Name</th>
             <th class="table-description">Description</th>
-            <th>Default</th>
           </tr>
         </thead>
         <tbody>
           {% for cssProperty in component.cssProperties %}
             <tr>
               <td class="table-name"><code>{{ cssProperty.name }}</code></td>
-              <td class="table-description">{{ cssProperty.description | inlineMarkdown | safe }}</td>
-              <td class="table-default">
+              <td class="table-description">
+                <div>{{ cssProperty.description | inlineMarkdown | safe }}</div>
                 {% if cssProperty.default %}
-                  <code>{{ cssProperty.default }}</code>
+                  <div>
+                    <small><strong>Default</strong>&nbsp;<code>{{ cssProperty.default }}</code></small>
+                    </div>
                 {% endif %}
               </td>
             </tr>
@@ -236,7 +231,6 @@
           <tr>
             <th class="table-name">Name</th>
             <th class="table-description">Description</th>
-            <th class="table-selector">CSS selector</th>
           </tr>
         </thead>
         <tbody>
@@ -244,7 +238,6 @@
             <tr>
               <td class="table-name"><code>{{ cssPart.name }}</code></td>
               <td class="table-description">{{ cssPart.description | inlineMarkdown | safe }}</td>
-              <td class="table-selector"><code>::part({{ cssPart.name }})</code></td>
             </tr>
           {% endfor %}
         </tbody>
@@ -283,16 +276,16 @@
       <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>
+      Coming soon!
     </wa-tab-panel>
     <wa-tab-panel name="react">
+      Coming soon!
+      {# NOTE - disabled for alpha
       <p>
         To manually import this component from React, use the following code.
       </p>
       <pre><code class="language-js">import '@shoelace-style/webawesome/react/{{ component.tagName | stripPrefix }}';</code></pre>
+      #}
     </wa-tab-panel>
   </wa-tab-group>
 {% endblock %}

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/code-examples.js

@@ -15,12 +15,12 @@ document.addEventListener('click', event => {
   if (pen) {
     const codeExample = pen.closest('.code-example');
     const code = codeExample.querySelector('code');
-    const version = document.documentElement.dataset.version;
+    const cdnUrl = document.documentElement.dataset.cdnUrl;
     const html =
-      `<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/webawesome@${version}/dist/webawesome.loader.js"></script>` +
-      `\n\n` +
+      `<script type="module" src="${cdnUrl}webawesome.loader.js"></script>\n` +
+      `<link rel="stylesheet" href="${cdnUrl}themes/default.css">\n\n` +
       `${code.textContent}`;
-    const css = 'body {\n  font: 16px sans-serif;\n  padding: 1rem;\n}\n';
+    const css = 'body {\n  font: 16px sans-serif;\n  padding: 1rem;\n}';
     const js = '';
 
     const form = document.createElement('form');

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

@@ -1,10 +1,14 @@
+pre {
+  background-color: var(--wa-color-gray-20);
+  color: white;
+}
 .code-comment,
 .code-prolog,
 .code-doctype,
 .code-cdata,
 .code-operator,
 .code-punctuation {
-  color: var(--wa-color-base-50);
+  color: var(--wa-color-gray-70);
 }
 
 .code-namespace {
@@ -15,13 +19,13 @@
 .code-keyword,
 .code-tag,
 .code-url {
-  color: #7c3aed; /* violet */
+  color: var(--wa-color-indigo-70);
 }
 
 .code-symbol,
 .code-deleted,
 .code-important {
-  color: var(--wa-color-red-40);
+  color: var(--wa-color-red-70);
 }
 
 .code-boolean,
@@ -32,7 +36,7 @@
 .code-char,
 .code-builtin,
 .code-inserted {
-  color: var(--wa-color-green-40);
+  color: var(--wa-color-green-70);
 }
 
 .code-atrule,
@@ -42,7 +46,7 @@
 .code-function,
 .code-class-name,
 .code-regex {
-  color: var(--wa-color-yellow-40);
+  color: var(--wa-color-blue-70);
 }
 
 .code-important,

docs/assets/styles/copy-code.css

@@ -1,15 +1,16 @@
-.copy-button {
+wa-copy-button.copy-button {
+  --background-color: var(--wa-color-gray-20);
+  --background-color-hover: color-mix(in oklab, var(--background-color), white 5%);
   position: absolute;
   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-gray-80);
+  border-radius: var(--wa-border-radius-s);
   padding: 0.25rem;
 
   &:hover {
-    background-color: var(--wa-color-neutral-fill-highlight);
+    color: white;
   }
 
   &:focus-visible {

docs/assets/styles/docs.css

@@ -3,46 +3,150 @@
 @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);
+  max-width: 300px;
+  overflow: auto;
+  max-height: 100%;
 }
 
 #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,18 +154,30 @@ wa-page[view='desktop'] > #sidebar {
   padding-bottom: 1rem;
 }
 
+wa-page::part(menu) {
+  scrollbar-width: thin;
+}
+
 /* Main content */
 wa-page > main {
   max-width: 80ch;
-  padding: 2rem;
+  padding: var(--wa-space-xl);
   margin-inline: auto;
 }
 
+wa-page[view='desktop'] > main {
+  padding: var(--wa-space-3xl);
+}
+
+.component-info {
+  margin-block-end: var(--wa-flow-spacing);
+}
+
 /* Current link */
 #sidebar,
 #outline {
   .current {
-    font-weight: var(--wa-font-weight-heavy);
+    font-weight: var(--wa-font-weight-bold);
     text-decoration-style: solid;
   }
 }
@@ -83,8 +199,8 @@ wa-page > main {
 .callout {
   display: flex;
   gap: 1rem;
-  border: var(--wa-border-style) var(--wa-border-width-m);
-  border-radius: var(--wa-corners-m);
+  border: var(--wa-border-style) var(--wa-border-width-s);
+  border-radius: var(--wa-border-radius-m);
   padding: 1rem;
   margin-block-end: var(--wa-flow-spacing);
 
@@ -107,27 +223,54 @@ 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;
+}
+
+.component-table td > * + * {
+  margin-block-start: var(--wa-space-s);
+}
+
+.table-scroll {
+  overflow-x: auto;
+}

docs/assets/styles/outline.css

@@ -1,6 +1,5 @@
 #outline {
   order: 2;
-  padding-inline-end: 2rem;
   margin-block: 2rem;
 }
 
@@ -12,6 +11,9 @@
 #outline > nav {
   position: sticky;
   top: calc(var(--docs-header-height) + 3.5rem);
+  padding-inline-end: 2rem;
+  max-width: 240px;
+  min-width: 240px;
 }
 
 #outline-expandable {
@@ -28,7 +30,7 @@
   margin-inline-start: 1rem;
 }
 
-@media screen and (max-width: 1299px) {
+@media screen and (max-width: 1199px) {
   #outline {
     padding-block: 0.25rem;
     margin-block-end: -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;
@@ -249,12 +250,3 @@ header {
     }
   }
 }
-
-@keyframes show-search-backdrop {
-  from {
-    opacity: 0;
-  }
-  to {
-    opacity: 1;
-  }
-}

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>
@@ -50,7 +50,7 @@ This example demonstrates all of the baked-in animations and easings. Animations
 </div>
 
 <script type="module">
-  import { getAnimationNames, getEasingNames } from '/dist/utilities/animation.js';
+  import { getAnimationNames, getEasingNames } from '/dist/webawesome.js';
 
   const container = document.querySelector('.animation-sandbox');
   const animation = container.querySelector('wa-animation');
@@ -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}
@@ -16,5 +16,5 @@ layout: component.njk
 ```
 
 :::info
-Additional demonstrations can be found in the [breadcrumb examples](/components/breadcrumb).
+Additional demonstrations can be found in the [breadcrumb examples](/docs/components/breadcrumb).
 :::

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.
@@ -108,7 +108,7 @@ Dropdown menus can be placed in a prefix or suffix slot to provide additional op
   <wa-breadcrumb-item>
     Web Design
     <wa-dropdown slot="suffix">
-      <wa-button slot="trigger" size="small" pill>
+      <wa-button slot="trigger" size="small" appearance="tinted" pill>
         <wa-icon label="More options" name="ellipsis" variant="solid"></wa-icon>
       </wa-button>
       <wa-menu>

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}
@@ -135,7 +135,7 @@ Dropdowns can be placed inside button groups as long as the trigger is an `<wa-b
 
 ### Split Buttons
 
-Create a split button using a button and a dropdown. Use a [visually hidden](/components/visually-hidden) label to ensure the dropdown is accessible to users with assistive devices.
+Create a split button using a button and a dropdown. Use a [visually hidden](/docs/components/visually-hidden) label to ensure the dropdown is accessible to users with assistive devices.
 
 ```html {.example}
 <wa-button-group label="Example Button Group">

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="outlined" variant="neutral">Outlined</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="outlined" variant="brand">Outlined</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="outlined" variant="success">Outlined</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="outlined" variant="warning">Outlined</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="outlined" variant="danger">Outlined</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.
@@ -72,7 +87,6 @@ It's often helpful to have a button that works like a link. This is possible by
 <wa-button href="https://example.com/">Link</wa-button>
 <wa-button href="https://example.com/" target="_blank">New Window</wa-button>
 <wa-button href="/assets/images/logo.svg" download="shoelace.svg">Download</wa-button>
-<wa-button href="https://example.com/" disabled>Disabled</wa-button>
 ```
 
 :::info
@@ -178,7 +192,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 +213,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}
@@ -40,5 +40,5 @@ layout: component.njk
 ```
 
 :::info
-Additional demonstrations can be found in the [carousel examples](/components/carousel).
+Additional demonstrations can be found in the [carousel examples](/docs/components/carousel).
 :::

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}
@@ -9,31 +9,31 @@ layout: component.njk
   <wa-carousel-item>
     <img
       alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)"
-      src="/assets/examples/carousel/mountains.jpg"
+      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
-      alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)"
-      src="/assets/examples/carousel/waterfall.jpg"
+      alt="A river winding through an evergreen forest (by Luca Bravo on Unsplash)"
+      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)"
-      src="/assets/examples/carousel/sunset.jpg"
+      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)"
-      src="/assets/examples/carousel/field.jpg"
+      src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)"
-      src="/assets/examples/carousel/valley.jpg"
+      src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?q=10"
     />
   </wa-carousel-item>
 </wa-carousel>
@@ -50,31 +50,31 @@ Use the `pagination` attribute to show the total number of slides and the curren
   <wa-carousel-item>
     <img
       alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)"
-      src="/assets/examples/carousel/mountains.jpg"
+      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
-      alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)"
-      src="/assets/examples/carousel/waterfall.jpg"
+      alt="A river winding through an evergreen forest (by Luca Bravo on Unsplash)"
+      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)"
-      src="/assets/examples/carousel/sunset.jpg"
+      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)"
-      src="/assets/examples/carousel/field.jpg"
+      src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)"
-      src="/assets/examples/carousel/valley.jpg"
+      src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?q=10"
     />
   </wa-carousel-item>
 </wa-carousel>
@@ -89,31 +89,31 @@ Use the `navigation` attribute to show previous and next buttons.
   <wa-carousel-item>
     <img
       alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)"
-      src="/assets/examples/carousel/mountains.jpg"
+      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
-      alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)"
-      src="/assets/examples/carousel/waterfall.jpg"
+      alt="A river winding through an evergreen forest (by Luca Bravo on Unsplash)"
+      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)"
-      src="/assets/examples/carousel/sunset.jpg"
+      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)"
-      src="/assets/examples/carousel/field.jpg"
+      src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)"
-      src="/assets/examples/carousel/valley.jpg"
+      src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?q=10"
     />
   </wa-carousel-item>
 </wa-carousel>
@@ -128,31 +128,31 @@ By default, the carousel will not advanced beyond the first and last slides. You
   <wa-carousel-item>
     <img
       alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)"
-      src="/assets/examples/carousel/mountains.jpg"
+      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
-      alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)"
-      src="/assets/examples/carousel/waterfall.jpg"
+      alt="A river winding through an evergreen forest (by Luca Bravo on Unsplash)"
+      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)"
-      src="/assets/examples/carousel/sunset.jpg"
+      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)"
-      src="/assets/examples/carousel/field.jpg"
+      src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)"
-      src="/assets/examples/carousel/valley.jpg"
+      src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?q=10"
     />
   </wa-carousel-item>
 </wa-carousel>
@@ -167,31 +167,31 @@ The carousel will automatically advance when the `autoplay` attribute is used. T
   <wa-carousel-item>
     <img
       alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)"
-      src="/assets/examples/carousel/mountains.jpg"
+      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
-      alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)"
-      src="/assets/examples/carousel/waterfall.jpg"
+      alt="A river winding through an evergreen forest (by Luca Bravo on Unsplash)"
+      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)"
-      src="/assets/examples/carousel/sunset.jpg"
+      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)"
-      src="/assets/examples/carousel/field.jpg"
+      src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)"
-      src="/assets/examples/carousel/valley.jpg"
+      src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?q=10"
     />
   </wa-carousel-item>
 </wa-carousel>
@@ -209,31 +209,31 @@ This example is best demonstrated using a mouse. Try clicking and dragging the s
     <wa-carousel-item>
       <img
         alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)"
-        src="/assets/examples/carousel/mountains.jpg"
+        src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?q=10"
       />
     </wa-carousel-item>
     <wa-carousel-item>
       <img
-        alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)"
-        src="/assets/examples/carousel/waterfall.jpg"
+        alt="A river winding through an evergreen forest (by Luca Bravo on Unsplash)"
+        src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?q=10"
       />
     </wa-carousel-item>
     <wa-carousel-item>
       <img
         alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)"
-        src="/assets/examples/carousel/sunset.jpg"
+        src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?q=10"
       />
     </wa-carousel-item>
     <wa-carousel-item>
       <img
         alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)"
-        src="/assets/examples/carousel/field.jpg"
+        src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?q=10"
       />
     </wa-carousel-item>
     <wa-carousel-item>
       <img
         alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)"
-        src="/assets/examples/carousel/valley.jpg"
+        src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?q=10"
       />
     </wa-carousel-item>
   </wa-carousel>
@@ -350,31 +350,31 @@ Setting the `orientation` attribute to `vertical` will render the carousel in a
   <wa-carousel-item>
     <img
       alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)"
-      src="/assets/examples/carousel/mountains.jpg"
+      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
-      alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)"
-      src="/assets/examples/carousel/waterfall.jpg"
+      alt="A river winding through an evergreen forest (by Luca Bravo on Unsplash)"
+      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)"
-      src="/assets/examples/carousel/sunset.jpg"
+      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)"
-      src="/assets/examples/carousel/field.jpg"
+      src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)"
-      src="/assets/examples/carousel/valley.jpg"
+      src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?q=10"
     />
   </wa-carousel-item>
 </wa-carousel>
@@ -407,31 +407,31 @@ Use the `--aspect-ratio` custom property to customize the size of the carousel's
   <wa-carousel-item>
     <img
       alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)"
-      src="/assets/examples/carousel/mountains.jpg"
+      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
-      alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)"
-      src="/assets/examples/carousel/waterfall.jpg"
+      alt="A river winding through an evergreen forest (by Luca Bravo on Unsplash)"
+      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)"
-      src="/assets/examples/carousel/sunset.jpg"
+      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)"
-      src="/assets/examples/carousel/field.jpg"
+      src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)"
-      src="/assets/examples/carousel/valley.jpg"
+      src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?q=10"
     />
   </wa-carousel-item>
 </wa-carousel>
@@ -465,31 +465,31 @@ Use the `--scroll-hint` custom property to add inline padding in horizontal caro
   <wa-carousel-item>
     <img
       alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)"
-      src="/assets/examples/carousel/mountains.jpg"
+      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
-      alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)"
-      src="/assets/examples/carousel/waterfall.jpg"
+      alt="A river winding through an evergreen forest (by Luca Bravo on Unsplash)"
+      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)"
-      src="/assets/examples/carousel/sunset.jpg"
+      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)"
-      src="/assets/examples/carousel/field.jpg"
+      src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)"
-      src="/assets/examples/carousel/valley.jpg"
+      src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?q=10"
     />
   </wa-carousel-item>
 </wa-carousel>
@@ -504,42 +504,42 @@ The carousel has a robust API that makes it possible to extend and customize. Th
   <wa-carousel-item>
     <img
       alt="The sun shines on the mountains and trees (by Adam Kool on Unsplash)"
-      src="/assets/examples/carousel/mountains.jpg"
+      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
-      alt="A waterfall in the middle of a forest (by Thomas Kelly on Unsplash)"
-      src="/assets/examples/carousel/waterfall.jpg"
+      alt="A river winding through an evergreen forest (by Luca Bravo on Unsplash)"
+      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="The sun is setting over a lavender field (by Leonard Cotte on Unsplash)"
-      src="/assets/examples/carousel/sunset.jpg"
+      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A field of grass with the sun setting in the background (by Sapan Patel on Unsplash)"
-      src="/assets/examples/carousel/field.jpg"
+      src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?q=10"
     />
   </wa-carousel-item>
   <wa-carousel-item>
     <img
       alt="A scenic view of a mountain with clouds rolling in (by V2osk on Unsplash)"
-      src="/assets/examples/carousel/valley.jpg"
+      src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?q=10"
     />
   </wa-carousel-item>
 </wa-carousel>
 
 <div class="thumbnails">
   <div class="thumbnails__scroller">
-    <img alt="Thumbnail by 1" class="thumbnails__image active" src="/assets/examples/carousel/mountains.jpg" />
-    <img alt="Thumbnail by 2" class="thumbnails__image" src="/assets/examples/carousel/waterfall.jpg" />
-    <img alt="Thumbnail by 3" class="thumbnails__image" src="/assets/examples/carousel/sunset.jpg" />
-    <img alt="Thumbnail by 4" class="thumbnails__image" src="/assets/examples/carousel/field.jpg" />
-    <img alt="Thumbnail by 5" class="thumbnails__image" src="/assets/examples/carousel/valley.jpg" />
+    <img alt="Thumbnail by 1" class="thumbnails__image active" src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?q=10" />
+    <img alt="Thumbnail by 2" class="thumbnails__image" src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?q=10" />
+    <img alt="Thumbnail by 3" class="thumbnails__image" src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?q=10" />
+    <img alt="Thumbnail by 4" class="thumbnails__image" src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?q=10" />
+    <img alt="Thumbnail by 5" class="thumbnails__image" src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?q=10" />
   </div>
 </div>
 

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}
@@ -9,7 +9,7 @@ layout: component.njk
 ```
 
 :::info
-This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
+This component works with standard `<form>` elements. Please refer to the section on [form controls](/docs/form-controls) to learn more about form submission and client-side validation.
 :::
 
 ## Examples

docs/docs/components/color-picker.md

@@ -1,18 +1,15 @@
 ---
 title: Color Picker
 description: Color pickers allow the user to select a color.
-layout: component.njk
+layout: component
 ---
 
 ```html {.example}
-<form>
-<wa-color-picker required label="Select a color"></wa-color-picker>
-<wa-button type="submit">Submit</wa-button>
-</form>
+<wa-color-picker label="Select a color"></wa-color-picker>
 ```
 
 :::info
-This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
+This component works with standard `<form>` elements. Please refer to the section on [form controls](/docs/form-controls) to learn more about form submission and client-side validation.
 :::
 
 ## Examples
@@ -48,7 +45,7 @@ To prevent users from toggling the format themselves, add the `no-format-toggle`
 
 ### Swatches
 
-Use the `swatches` attribute to add convenient presets to the color picker. Any format the color picker can parse is acceptable (including CSS color names), but each value must be separated by a semicolon (`;`). Alternatively, you can pass an array of color values to this property using JavaScript.
+Use the `swatches` attribute to add convenient presets to the color picker. Any format the color picker can parse is acceptable (including [CSS color names](https://www.w3schools.com/colors/colors_names.asp)), but each value must be separated by a semicolon (`;`). Alternatively, you can pass an array of color values to this property using JavaScript.
 
 ```html {.example}
 <wa-color-picker
@@ -70,10 +67,18 @@ Use the `size` attribute to change the color picker's trigger size.
 <wa-color-picker size="large" label="Select a color"></wa-color-picker>
 ```
 
-### Inline
+### Disabled
 
-The color picker can be rendered inline instead of in a dropdown using the `inline` attribute.
+The color picker can be rendered as disabled.
 
 ```html {.example}
-<wa-color-picker inline label="Select a color"></wa-color-picker>
+<wa-color-picker disabled label="Select a color"></wa-color-picker>
 ```
+
+### Help Text
+
+The color picker can be rendered as disabled.
+
+```html {.example}
+<wa-color-picker label="Select a color" help-text="Choose a color with appropate contrast!"></wa-color-picker>
+```

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}
@@ -25,7 +25,7 @@ Copy Buttons display feedback in a tooltip. You can customize the labels using t
 
 ### Custom Icons
 
-Use the `copy-icon`, `success-icon`, and `error-icon` slots to customize the icons that get displayed for each state. You can use [`<wa-icon>`](/components/icon) or your own images.
+Use the `copy-icon`, `success-icon`, and `error-icon` slots to customize the icons that get displayed for each state. You can use [`<wa-icon>`](/docs/components/icon) or your own images.
 
 ```html {.example}
 <wa-copy-button value="Copied from a custom button">
@@ -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>
@@ -127,13 +127,13 @@ By design, a dialog's height will never exceed that of the viewport. As such, di
 
 ### Header Actions
 
-The header shows a functional close button by default. You can use the `header-actions` slot to add additional [icon buttons](/components/icon-button) if needed.
+The header shows a functional close button by default. You can use the `header-actions` slot to add additional [icon buttons](/docs/components/icon-button) if needed.
 
 ```html {.example}
 <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}
@@ -54,7 +54,7 @@ Add the `vertical` attribute to draw the divider in a vertical orientation. The
 
 ### Menu Dividers
 
-Use dividers in [menus](/components/menu) to visually group menu items.
+Use dividers in [menus](/docs/components/menu) to visually group menu items.
 
 ```html {.example}
 <wa-menu style="max-width: 200px;">

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>
@@ -187,13 +187,13 @@ By design, a drawer's height will never exceed 100% of its container. As such, d
 
 ### Header Actions
 
-The header shows a functional close button by default. You can use the `header-actions` slot to add additional [icon buttons](/components/icon-button) if needed.
+The header shows a functional close button by default. You can use the `header-actions` slot to add additional [icon buttons](/docs/components/icon-button) if needed.
 
 ```html {.example}
 <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,12 +1,12 @@
 ---
 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.
 
-Dropdowns are designed to work well with [menus](/components/menu) to provide a list of options the user can select from. However, dropdowns can also be used in lower-level applications (e.g. [color picker](/components/color-picker)). The API gives you complete control over showing, hiding, and positioning the panel.
+Dropdowns are designed to work well with [menus](/docs/components/menu) to provide a list of options the user can select from. However, dropdowns can also be used in lower-level applications (e.g. [color picker](/docs/components/color-picker)). The API gives you complete control over showing, hiding, and positioning the panel.
 
 ```html {.example}
 <wa-dropdown>
@@ -35,7 +35,7 @@ Dropdowns are designed to work well with [menus](/components/menu) to provide a
 
 ### Getting the Selected Item
 
-When dropdowns are used with [menus](/components/menu), you can listen for the [`wa-select`](/components/menu#events) event to determine which menu item was selected. The menu item element will be exposed in `event.detail.item`. You can set `value` props to make it easier to identify commands.
+When dropdowns are used with [menus](/docs/components/menu), you can listen for the [`wa-select`](/docs/components/menu#events) event to determine which menu item was selected. The menu item element will be exposed in `event.detail.item`. You can set `value` props to make it easier to identify commands.
 
 ```html {.example}
 <div class="dropdown-selection">
@@ -142,7 +142,7 @@ The offset of the panel along the trigger can be customized using the `skidding`
 
 ### Submenus
 
-To create a submenu, nest an `<wa-menu slot="submenu">` element in a [menu item](/components/menu-item).
+To create a submenu, nest an `<wa-menu slot="submenu">` element in a [menu item](/docs/components/menu-item).
 
 ```html {.example}
 <wa-dropdown>

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,10 +1,10 @@
 ---
 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).
+For a full list of icons that come bundled with Web Awesome, refer to the [icon component](/docs/components/icon).
 
 ```html {.example}
 <wa-icon-button name="gear" label="Settings"></wa-icon-button>

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).
@@ -16,7 +16,7 @@ Not sure which icon to use? [Find the perfect icon over at Font Awesome!](https:
 
 The default icon library is Font Awesome Free, which comes with two icon families: `classic` and `brands`. Use the `family` attribute to set the icon family.
 
-Many Font Awesome Pro icon families have variants such as `thin`, `light`, `regular`, and `solid`. Font Awesome Pro users can [provide their kit code](/docs/installation) to unlock additional families, including `sharp` and `duotone`. For these icon families, use the `variant` attribute to set the variant.
+Many Font Awesome Pro icon families have variants such as `thin`, `light`, `regular`, and `solid`. Font Awesome Pro users can [provide their kit code](/docs/installation/#using-font-awesome-kit-codes) to unlock additional families, including `sharp` and `duotone`. For these icon families, use the `variant` attribute to set the variant.
 
 ```html {.example}
 <wa-icon family="brands" name="font-awesome"></wa-icon>

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}
@@ -9,7 +9,7 @@ layout: component.njk
 ```
 
 :::info
-This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
+This component works with standard `<form>` elements. Please refer to the section on [form controls](/docs/form-controls) to learn more about form submission and client-side validation.
 :::
 
 ## Examples

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,10 +1,10 @@
 ---
 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.
+You can use [menu items](/docs/components/menu-item), [menu labels](/docs/components/menu-label), and [dividers](/docs/components/divider) to compose a menu. Menus support keyboard interactions, including type-to-select an option.
 
 ```html {.example}
 <wa-menu style="max-width: 200px;">
@@ -26,7 +26,7 @@ Menus are intended for system menus (dropdown menus, select menus, context menus
 
 ### In Dropdowns
 
-Menus work really well when used inside [dropdowns](/components/dropdown).
+Menus work really well when used inside [dropdowns](/docs/components/dropdown).
 
 ```html {.example}
 <wa-dropdown>
@@ -41,7 +41,7 @@ Menus work really well when used inside [dropdowns](/components/dropdown).
 
 ### Submenus
 
-To create a submenu, nest an `<wa-menu slot="submenu">` in any [menu item](/components/menu-item).
+To create a submenu, nest an `<wa-menu slot="submenu">` in any [menu item](/docs/components/menu-item).
 
 ```html {.example}
 <wa-menu style="max-width: 200px;">

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,12 +1,12 @@
 ---
 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.
 
-A number of sections are available as part of the layout, most of which are optional. Content is added by [slotting elements](/getting-started/usage/#slots) into various locations.
+A number of sections are available as part of the layout, most of which are optional. Content is added by [slotting elements](/docs/usage/#slots) into various locations.
 
 This component _does not_ implement any [content sectioning](https://developer.mozilla.org/en-US/docs/Web/HTML/Element#content_sectioning) or "semantic elements" internally (such as `<main>`, `<header>`, `<footer>`, etc.). Instead, it is recommended that you slot in content sectioning elements wherever you feel they're appropriate.
 
@@ -19,7 +19,7 @@ Most slots are optional. Slots that have no content will not be shown, allowing
 ![Screenshot of Layout Anatomy showing various slots](/assets/images/layout-anatomy.svg)
 
 :::info
-If you're not familiar with how slots work in HTML, you might want to [learn more about slots](/getting-started/usage/#slots) before using this component.
+If you're not familiar with how slots work in HTML, you might want to [learn more about slots](/docs/usage/#slots) before using this component.
 :::
 
 ## Sticky Sections

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.
@@ -9,7 +9,7 @@ This component's name is inspired by [`<popup>`](https://github.com/MicrosoftEdg
 Popup doesn't provide any styles — just positioning! The popup's preferred placement, distance, and skidding (offset) can be configured using attributes. An arrow that points to the anchor can be shown and customized to your liking. Additional positioning options are available and described in more detail below.
 
 :::warning
-Popup is a low-level utility built specifically for positioning elements. Do not mistake it for a [tooltip](/components/tooltip) or similar because _it does not facilitate an accessible experience!_ Almost every correct usage of `<wa-popup>` will involve building other components. It should rarely, if ever, occur directly in your HTML.
+Popup is a low-level utility built specifically for positioning elements. Do not mistake it for a [tooltip](/docs/components/tooltip) or similar because _it does not facilitate an accessible experience!_ Almost every correct usage of `<wa-popup>` will involve building other components. It should rarely, if ever, occur directly in your HTML.
 :::
 
 ```html {.example}
@@ -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,10 +1,10 @@
 ---
 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.
+Radio buttons are designed to be used with [radio groups](/docs/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.
 
 ```html {.example}
 <wa-radio-group label="Select an option" name="a" value="1">

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}
@@ -28,7 +28,7 @@ Add descriptive help text to a radio group with the `help-text` attribute. For h
 
 ### Radio Buttons
 
-[Radio buttons](/components/radio-button) offer an alternate way to display radio controls. In this case, an internal [button group](/components/button-group) is used to group the buttons into a single, cohesive control.
+[Radio buttons](/docs/components/radio-button) offer an alternate way to display radio controls. In this case, an internal [button group](/docs/components/button-group) is used to group the buttons into a single, cohesive control.
 
 ```html {.example}
 <wa-radio-group label="Select an option" help-text="Select an option that makes you proud." name="a" value="1">
@@ -52,7 +52,7 @@ Radios and radio buttons can be disabled by adding the `disabled` attribute to t
 
 ### Sizing Options
 
-The size of [Radios](/components/radio) and [Radio Buttons](/components/radio-buttons) will be determined by the Radio Group's `size` attribute.
+The size of [Radios](/docs/components/radio) and [Radio Buttons](/docs/components/radio-buttons) will be determined by the Radio Group's `size` attribute.
 
 ```html preview
 <wa-radio-group label="Select an option" size="medium" value="medium" class="radio-group-size">
@@ -71,7 +71,7 @@ The size of [Radios](/components/radio) and [Radio Buttons](/components/radio-bu
 ```
 
 :::info
-[Radios](/components/radio) and [Radio Buttons](/components/radio-button) also have a `size` attribute. This can be useful in certain compositions, but it will be ignored when used inside of a Radio Group.
+[Radios](/docs/components/radio) and [Radio Buttons](/docs/components/radio-button) also have a `size` attribute. This can be useful in certain compositions, but it will be ignored when used inside of a Radio Group.
 :::
 
 ### Validation

docs/docs/components/radio.md

@@ -1,10 +1,10 @@
 ---
 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).
+Radios are designed to be used with [radio groups](/docs/components/radio-group).
 
 ```html {.example}
 <wa-radio-group label="Select an option" name="a" value="1">
@@ -15,7 +15,7 @@ Radios are designed to be used with [radio groups](/components/radio-group).
 ```
 
 :::info
-This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
+This component works with standard `<form>` elements. Please refer to the section on [form controls](/docs/form-controls) to learn more about form submission and client-side validation.
 :::
 
 ## Examples
@@ -46,7 +46,7 @@ Use the `disabled` attribute to disable a radio.
 
 ## Sizes
 
-Add the `size` attribute to the [Radio Group](/components/radio-group) to change the radios' size.
+Add the `size` attribute to the [Radio Group](/docs/components/radio-group) to change the radios' size.
 
 ```html {.example}
 <wa-radio-group size="small" value="1">

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}
@@ -9,7 +9,7 @@ layout: component.njk
 ```
 
 :::info
-This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
+This component works with standard `<form>` elements. Please refer to the section on [form controls](/docs/form-controls) to learn more about form submission and client-side validation.
 :::
 
 ## Examples
@@ -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}
@@ -16,7 +16,7 @@ layout: component.njk
 ```
 
 :::info
-This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
+This component works with standard `<form>` elements. Please refer to the section on [form controls](/docs/form-controls) to learn more about form submission and client-side validation.
 :::
 
 ## Examples
@@ -228,7 +228,7 @@ Use the `prefix` slot to prepend an icon to the control.
 
 When multiple options can be selected, you can provide custom tags by passing a function to the `getTag` property. Your function can return a string of HTML, a <a href="https://lit.dev/docs/templates/overview/">Lit Template</a>, or an [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement). The `getTag()` function will be called for each option. The first argument is an `<wa-option>` element and the second argument is the tag's index (its position in the tag list).
 
-Remember that custom tags are rendered in a shadow root. To style them, you can use the `style` attribute in your template or you can add your own [parts](/getting-started/customizing/#css-parts) and target them with the [`::part()`](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) selector.
+Remember that custom tags are rendered in a shadow root. To style them, you can use the `style` attribute in your template or you can add your own [parts](/docs/customizing/#css-parts) and target them with the [`::part()`](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) selector.
 
 ```html {.example}
 <wa-select

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}
@@ -9,7 +9,7 @@ layout: component.njk
 ```
 
 :::info
-This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
+This component works with standard `<form>` elements. Please refer to the section on [form controls](/docs/form-controls) to learn more about form submission and client-side validation.
 :::
 
 ## Examples

docs/docs/components/tab-group.md

@@ -1,10 +1,10 @@
 ---
 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.
+Tab groups make use of [tabs](/docs/components/tab) and [tab panels](/docs/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.
 
 ```html {.example}
 <wa-tab-group>

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}
@@ -19,5 +19,5 @@ layout: component.njk
 ```
 
 :::info
-Additional demonstrations can be found in the [tab group examples](/components/tab-group).
+Additional demonstrations can be found in the [tab group examples](/docs/components/tab-group).
 :::

docs/docs/components/tab.md

@@ -1,9 +1,9 @@
 ---
 title: Tab
 description: Tabs are used inside tab groups to represent and activate tab panels.
-layout: component.njk
+layout: component
 ---
 
 :::info
-Additional demonstrations can be found in the [tab group examples](/components/tab-group).
+Additional demonstrations can be found in the [tab group examples](/docs/components/tab-group).
 :::

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}
@@ -9,7 +9,7 @@ layout: component.njk
 ```
 
 :::info
-This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
+This component works with standard `<form>` elements. Please refer to the section on [form controls](/docs/form-controls) to learn more about form submission and client-side validation.
 :::
 
 ## Examples

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,88 +1,47 @@
 ---
 title: Customizing
 description: Learn how to customize Web Awesome through parts and custom properties.
-layout: page.njk
+layout: page-outline
 ---
 
-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.
+Web Awesome components can be customized at a high level through a theming API. 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.
 
-## Design Tokens
+## Themes
 
-Web Awesome makes use of several design tokens to provide a consistent appearance across components. You can customize them and use them in your own application with pure CSS — no preprocessor required.
+Web Awesome uses numerous CSS custom properties that make up a high-level theming API and provide a consistent look and feel across the entire library. You can customize them and use them in your own application just with CSS — no preprocessor required.
 
-Design tokens offer a high-level way to customize the library with minimal effort. There are no component-specific variables, however, as design tokens are intended to be generic and highly reusable. To customize an individual component, refer to the section entitled [CSS Parts](#css-parts).
+Because these custom properties live at the page level, they're prefixed with `--wa-` to avoid collisions with other libraries or your own custom properties.
 
-Design tokens are accessed through CSS custom properties that are defined in your theme. Because design tokens live at the page level, they're prefixed with `--wa-` to avoid collisions with other libraries.
-
-To customize a design token, simply override it in your stylesheet using a `:root` block. Here's an example that changes the primary theme to purple based on existing [color primitives](/tokens/color#primitives).
+To customize a theme, simply override any of these custom properties in your own stylesheet by scoping your styles to `:root`, `:host`, and, if needed, the class for the specific theme you want to override. Here's an example that changes the default brand color (blue) to violet in the light theme using existing [literal colors](/docs/theming/color/#literal-colors).
 
 ```css
-:root {
-  /* Changes the primary theme color to purple using primitives */
-  --wa-color-primary-50: var(--wa-color-purple-50);
-  --wa-color-primary-100: var(--wa-color-purple-100);
-  --wa-color-primary-200: var(--wa-color-purple-200);
-  --wa-color-primary-300: var(--wa-color-purple-300);
-  --wa-color-primary-400: var(--wa-color-purple-400);
-  --wa-color-primary-500: var(--wa-color-purple-500);
-  --wa-color-primary-600: var(--wa-color-purple-600);
-  --wa-color-primary-700: var(--wa-color-purple-700);
-  --wa-color-primary-800: var(--wa-color-purple-800);
-  --wa-color-primary-900: var(--wa-color-purple-900);
-  --wa-color-primary-950: var(--wa-color-purple-950);
+:root,
+:host,
+.wa-theme-default-light {
+  /* Changes the brand color to violet across the library */
+  --wa-color-brand-fill-quiet: var(--wa-color-violet-95);
+  --wa-color-brand-fill-normal: var(--wa-color-violet-90);
+  --wa-color-brand-fill-loud: var(--wa-color-violet-50);
+  --wa-color-brand-border-quiet: var(--wa-color-violet-90);
+  --wa-color-brand-border-normal: var(--wa-color-violet-80);
+  --wa-color-brand-border-loud: var(--wa-color-violet-60);
+  --wa-color-brand-on-quiet: var(--wa-color-violet-40);
+  --wa-color-brand-on-normal: var(--wa-color-violet-30);
+  --wa-color-brand-on-loud: white;
 }
 ```
 
-Many design tokens are described further along in this documentation. For a complete list, refer to `src/themes/default.css` in the project's [source code](https://github.com/shoelace-style/shoelace/blob/current/src/themes/default.css).
+For more examples and further guidance, refer to [Themes](/docs/themes) and the Theming section of this documentation. For a complete list of all custom properties used for theming, refer to `src/themes/default.css` in the project's source code.
 
-## CSS Parts
+## Components
 
-Whereas design tokens offer a high-level way to customize the library, CSS parts offer a low-level way to customize individual components. Again, this is done with pure CSS — no preprocessor required.
+Whereas a theme offers a high-level way to customize the library, components offer different hooks as a low-level way to customize them individually. 
 
-Web Awesome components use a [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to encapsulate their styles and behaviors. As a result, you can't simply target their internals with the usual CSS selectors. Instead, components expose "parts" that can be targeted with the [CSS part selector](https://developer.mozilla.org/en-US/docs/Web/CSS/::part), or `::part()`.
+Web Awesome components use a [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to encapsulate their styles and behaviors. As a result, you can't simply target their internals with the usual CSS selectors. Instead, components expose a set of custom properties and CSS parts that can be targeted to customize their appearance.
 
-Here's an example that modifies buttons with the `tomato-button` class.
+### Custom Properties
 
-```html {.example}
-<wa-button class="tomato-button"> Tomato Button </wa-button>
-
-<style>
-  .tomato-button::part(base) {
-    background: var(--wa-color-neutral-0);
-    border: solid 1px tomato;
-  }
-
-  .tomato-button::part(base):hover {
-    background: rgba(255, 99, 71, 0.1);
-  }
-
-  .tomato-button::part(base):active {
-    background: rgba(255, 99, 71, 0.2);
-  }
-
-  .tomato-button::part(base):focus-visible {
-    box-shadow: 0 0 0 3px rgba(255, 99, 71, 0.33);
-  }
-
-  .tomato-button::part(label) {
-    color: tomato;
-  }
-</style>
-```
-
-At first glance, this approach might seem a bit verbose or even limiting, but it comes with a few important advantages:
-
-- Customizations can be made to components with explicit selectors, such as `::part(icon)`, rather than implicit selectors, such as `.button > div > span + .icon`, that are much more fragile.
-
-- The internal structure of a component will likely change as it evolves. By exposing CSS parts through an API, the internals can be reworked without fear of breaking customizations as long as its parts remain intact.
-
-- It encourages us to think more about how components are designed and how customizations should be allowed before users can take advantage of them. Once we opt a part into the component's API, it's guaranteed to be supported and can't be removed until a major version of the library is released.
-
-Most (but not all) components expose parts. You can find them in each component's API documentation under the "CSS Parts" section.
-
-## Custom Properties
-
-For convenience, some components expose CSS custom properties you can override. These are not design tokens, nor do they have the same `--wa-` prefix since they're scoped to a component.
+Components expose custom properties that are scoped to the component, not global, so they do not have the same `--wa-` prefix as a theme's custom properties. These custom properties reflect common qualities of a component, such as `--background-color`, `--border-style`, `--size`, etc.
 
 You can set custom properties on a component in your stylesheet.
 
@@ -106,4 +65,47 @@ Alternatively, you can set them inline directly on the element.
 <wa-avatar style="--size: 6rem;"></wa-avatar>
 ```
 
-Not all components expose CSS custom properties. For those that do, they can be found in the component's API documentation.
+The custom properties exposed by each component can be found in the component's API documentation.
+
+### CSS Parts
+
+CSS parts offer further flexibility to customize individual components. The "parts" exposed by each component can be targeted with the [CSS part selector](https://developer.mozilla.org/en-US/docs/Web/CSS/::part), or `::part()`.
+
+Parts allow you to style *any* standard CSS property, not just those exposed through custom properties. Here's an example that modifies buttons with the `gradient-button` class.
+
+```html {.example}
+<wa-button class="gradient-button"> Gradient Button </wa-button>
+
+<style>
+  .gradient-button::part(base) {
+    background: linear-gradient(217deg, var(--wa-color-indigo-50), var(--wa-color-violet-50), var(--wa-color-red-50));
+    border: solid 1px var(--wa-color-violet-50);
+    transition: transform 100ms, box-shadow 100ms;
+  }
+
+  .gradient-button::part(base):hover {
+    box-shadow: var(--wa-shadow-m);
+    transform: translateY(-3px);
+  }
+
+  .gradient-button::part(base):active {
+    box-shadow: inset var(--wa-shadow-s);
+    transform: translateY(0);
+  }
+
+  .gradient-button::part(label) {
+    color: white;
+    text-shadow: rgb(0 0 0 / 0.3) 0 -1px;
+  }
+</style>
+```
+
+CSS parts have a few important advantages:
+
+- Customizations can be made to components with explicit selectors, such as `::part(icon)`, rather than implicit selectors, such as `.button > div > span + .icon`, that are much more fragile.
+
+- The internal structure of a component will likely change as it evolves. By exposing CSS parts through an API, the internals can be reworked without fear of breaking customizations as long as its parts remain intact.
+
+- It encourages us to think more about how components are designed and how customizations should be allowed before users can take advantage of them. Once we opt a part into the component's API, it's guaranteed to be supported and can't be removed until a major version of the library is released.
+
+Most (but not all) components expose parts. You can find them in each component's API documentation under the "CSS Parts" section.

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="outlined">Brand</wa-button>
+<wa-button variant="success" appearance="outlined">Success</wa-button>
+<wa-button variant="neutral" appearance="outlined">Neutral</wa-button>
+<wa-button variant="warning" appearance="outlined">Warning</wa-button>
+<wa-button variant="danger" appearance="outlined">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="outlined" variant="brand">Left</wa-button>
+  <wa-button appearance="outlined" variant="brand">Center</wa-button>
+  <wa-button appearance="outlined" variant="brand">Right</wa-button>
+</wa-button-group>
+
+<br /><br />
+
+<wa-button-group label="Alignment">
+  <wa-button appearance="outlined" variant="success">Left</wa-button>
+  <wa-button appearance="outlined" variant="success">Center</wa-button>
+  <wa-button appearance="outlined" variant="success">Right</wa-button>
+</wa-button-group>
+
+<br /><br />
+
+<wa-button-group label="Alignment">
+  <wa-button appearance="outlined">Left</wa-button>
+  <wa-button appearance="outlined">Center</wa-button>
+  <wa-button appearance="outlined">Right</wa-button>
+</wa-button-group>
+
+<br /><br />
+
+<wa-button-group label="Alignment">
+  <wa-button appearance="outlined" variant="warning">Left</wa-button>
+  <wa-button appearance="outlined" variant="warning">Center</wa-button>
+  <wa-button appearance="outlined" variant="warning">Right</wa-button>
+</wa-button-group>
+
+<br /><br />
+
+<wa-button-group label="Alignment">
+  <wa-button appearance="outlined" variant="danger">Left</wa-button>
+  <wa-button appearance="outlined" variant="danger">Center</wa-button>
+  <wa-button appearance="outlined" 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/form-controls.md

@@ -0,0 +1,179 @@
+---
+title: Form Controls
+description: Using Web Awesome form controls.
+layout: page-outline
+---
+
+Web Awesome form controls are form-associated custom elements, meaning they will submit with forms just like native `<form>` controls. They also support constraint validation, which is the platform's version of client-side form validation.
+
+## Constraint Validation
+
+Client-side validation can be enabled through the browser's [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation) for Web Awesome form controls. You can activate it using attributes such as `required`, `pattern`, `minlength`, `maxlength`, etc. Web Awesome implements many of the same attributes as native form controls, but check the documentation for a list of supported properties for each component.
+
+If you don't want to use client-side validation, you can suppress this behavior by adding `novalidate` to the surrounding `<form>` element.
+
+:::info
+If this syntax looks unfamiliar, don't worry! Most of what you're learning on this page is platform knowledge that applies to regular form controls, too.
+:::
+
+:::warning
+Client-side validation can be used to improve the UX of forms, but it is not a replacement for server-side validation. **You should always validate and sanitize user input on the server!**
+:::
+
+### Required Fields
+
+To make a field required, use the `required` attribute. Required fields will automatically receive an asterisk after their labels. The form will not be submitted if a required field is incomplete.
+
+```html {.example}
+<form class="input-validation-required">
+  <wa-input name="name" label="Name" required></wa-input>
+  <br />
+  <wa-select label="Favorite Animal" clearable required>
+    <wa-option value="birds">Birds</wa-option>
+    <wa-option value="cats">Cats</wa-option>
+    <wa-option value="dogs">Dogs</wa-option>
+    <wa-option value="other">Other</wa-option>
+  </wa-select>
+  <br />
+  <wa-textarea name="comment" label="Comment" required></wa-textarea>
+  <br />
+  <wa-checkbox required>Check me before submitting</wa-checkbox>
+  <br /><br />
+  <wa-button type="submit" variant="brand">Submit</wa-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.input-validation-required');
+
+  // Wait for controls to be defined before attaching form listeners
+  await Promise.all([
+    customElements.whenDefined('wa-button'),
+    customElements.whenDefined('wa-checkbox'),
+    customElements.whenDefined('wa-input'),
+    customElements.whenDefined('wa-option'),
+    customElements.whenDefined('wa-select'),
+    customElements.whenDefined('wa-textarea')
+  ]).then(() => {
+    form.addEventListener('submit', event => {
+      event.preventDefault();
+      alert('All fields are valid!');
+    });
+  });
+</script>
+```
+
+### Input Patterns
+
+To restrict a value to a specific [pattern](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern), use the `pattern` attribute. This example only allows the letters A-Z, so the form will not submit if a number or symbol is entered. This only works with `<wa-input>` elements.
+
+```html {.example}
+<form class="input-validation-pattern">
+  <wa-input name="letters" required label="Letters" pattern="[A-Za-z]+"></wa-input>
+  <br />
+  <wa-button type="submit" variant="brand">Submit</wa-button>
+  <wa-button type="reset" variant="neutral">Reset</wa-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.input-validation-pattern');
+
+  // Wait for controls to be defined before attaching form listeners
+  await Promise.all([
+    customElements.whenDefined('wa-button'),
+    customElements.whenDefined('wa-input')
+  ]).then(() => {
+    form.addEventListener('submit', event => {
+      event.preventDefault();
+      alert('All fields are valid!');
+    });
+  });
+</script>
+```
+
+### Input Types
+
+Some input types will automatically trigger constraints, such as `email` and `url`.
+
+```html {.example}
+<form class="input-validation-type">
+  <wa-input type="email" label="Email" placeholder="you@example.com" required></wa-input>
+  <br />
+  <wa-input type="url" label="URL" placeholder="https://example.com/" required></wa-input>
+  <br />
+  <wa-button type="submit" variant="brand">Submit</wa-button>
+  <wa-button type="reset" variant="neutral">Reset</wa-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.input-validation-type');
+
+  // Wait for controls to be defined before attaching form listeners
+  await Promise.all([
+    customElements.whenDefined('wa-button'),
+    customElements.whenDefined('wa-input')
+  ]).then(() => {
+    form.addEventListener('submit', event => {
+      event.preventDefault();
+      alert('All fields are valid!');
+    });
+  });
+</script>
+```
+
+### Custom Error Messages
+
+To create a custom validation error, pass a non-empty string to the `setCustomValidity()` method. This will override any existing validation constraints. The form will not be submitted when a custom validity is set and the browser will show a validation error when the containing form is submitted. To make the input valid again, call `setCustomValidity()` again with an empty string.
+
+```html {.example}
+<form class="input-validation-custom">
+  <wa-input label="Type webawesome" required></wa-input>
+  <br />
+  <wa-button type="submit" variant="brand">Submit</wa-button>
+  <wa-button type="reset" variant="neutral">Reset</wa-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.input-validation-custom');
+  const input = form.querySelector('wa-input');
+
+  // Wait for controls to be defined before attaching form listeners
+  await Promise.all([
+    customElements.whenDefined('wa-button'),
+    customElements.whenDefined('wa-input')
+  ]).then(() => {
+    form.addEventListener('submit', event => {
+      event.preventDefault();
+      alert('All fields are valid!');
+    });
+
+    input.addEventListener('wa-input', () => {
+      if (input.value === 'webawesome') {
+        input.setCustomValidity('');
+      } else {
+        input.setCustomValidity("Hey, you're supposed to type 'webawesome' before submitting this!");
+      }
+    });
+  });
+</script>
+```
+
+:::info
+Custom validation can be applied to any form control that supports the `setCustomValidity()` method. It is not limited to inputs and textareas.
+:::
+
+## Custom Validation Styles
+
+Due to the many ways form controls are used, Web Awesome doesn't provide out of the box validation styles for form controls as part of its default theme. Instead, the following attributes will be applied to reflect a control's validity as users interact with it. You can use them to create custom styles for any of the validation states you're interested in.
+
+- `data-wa-required` - the form control is required
+- `data-wa-optional` - the form control is optional
+- `data-wa-invalid` - the form control is invalid
+- `data-wa-valid` - the form control is valid
+- `data-wa-user-invalid` - the form control is invalid and the user has interacted with it
+- `data-wa-user-valid` - the form control is valid and the user has interacted with it
+
+These attributes map to the browser's built-in pseudo classes for validation: [`:required`](https://developer.mozilla.org/en-US/docs/Web/CSS/:required), [`:optional`](https://developer.mozilla.org/en-US/docs/Web/CSS/:optional), [`:invalid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:invalid), [`:valid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:valid), [`:user-invalid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:user-invalid), and [`:user-valid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:user-valid).
+
+:::info
+In the future, data attribute selectors will be replaced with custom states such as `:state(valid)` and `:state(invalid)`. Web Awesome is using data attributes as a workaround until browsers fully support [custom states](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/states).
+:::

docs/docs/installation.md

@@ -1,121 +1,66 @@
 ---
 title: Installation
 description: Choose the installation method that works best for you.
-layout: page.njk
+layout: page-outline
 ---
 
-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.
+Welcome to the Web Awesome alpha release for early backers! 👋
 
-## CDN Installation (Easiest)
+==This is a very early alpha release!== For this preview, we're only offering access to the free components through a temporary CDN. Please be aware: Things can change. Things can break. You probably shouldn't be using this software in production yet! But fear not, we're working hard to polish up the free stuff you see here _plus_ all the great stuff we have planned for Web Awesome Pro!
 
-<wa-tab-group>
-<wa-tab slot="nav" panel="autoloader" active>Autoloader</wa-tab>
-<wa-tab slot="nav" panel="traditional">Traditional Loader</wa-tab>
+==To be clear, this release _only_ includes a preview the components in Web Awesome Free!==
 
-<wa-tab-panel name="autoloader">
+Thank you so much for backing us!
 
-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.
+- [Report a bug](https://github.com/shoelace-style/webawesome-alpha/issues)
+- [Get help / ask a question](https://github.com/shoelace-style/webawesome-alpha/discussions)
+- [See what's new since the last version](/docs/resources/changelog)
 
-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.
+:::warning
+As a Web Awesome backer, this early alpha release is _just for you_. Please refrain from sharing it for the time being!
+:::
+
+---
+
+## Autoloading via CDN (Easiest)
+
+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>
+<link rel="stylesheet" href="{% cdnUrl 'themes/default.css' %}" />
+<script type="module" src="{% cdnUrl 'webawesome.loader.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).
+Now you can [start using Web Awesome!](/docs/usage)
 
 :::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.
+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 `webawesome.loader.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 -->
-<script src="bundle.js" data-webawesome="/path/to/web-awesome/%NPMDIR%"></script>
+<script src="bundle.js" data-webawesome="/path/to/web-awesome/dist"></script>
 
 <!-- Option 2: the setBasePath() method -->
 <script type="module">
-  import { setBasePath } from '/path/to/web-awesome/%NPMDIR%/webawesome.js';
-  setBasePath('/path/to/web-awesome/%NPMDIR%');
+  import { setBasePath } from '/path/to/web-awesome/dist/webawesome.js';
+  setBasePath('/path/to/web-awesome/dist');
 </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.
 
 ```html
 <script type="module">
-  import { getBasePath, setBasePath } from '/path/to/web-awesome/%NPMDIR%/webawesome.js';
+  import { getBasePath, setBasePath } from '/path/to/web-awesome/dist/webawesome.js';
 
   setBasePath('/path/to/assets');
 
@@ -129,7 +74,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.
 
@@ -139,22 +84,22 @@ Font Awesome users can set their kit code to unlock Font Awesome Pro icons. You
 
 <!-- Option 2: the setKitCode() method -->
 <script type="module">
-  import { setKitCode } from '/path/to/web-awesome/%NPMDIR%/webawesome.js';
-  setBasePath('/path/to/web-awesome/%NPMDIR%');
+  import { setKitCode } from '/path/to/web-awesome/dist/webawesome.js';
+  setBasePath('/path/to/web-awesome/dist');
 </script>
 ```
 
 ## 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" />
+<link rel="stylesheet" href="/path/to/web-awesome/dist/themes/default.css" />
 
-<script type="module" data-webawesome="/path/to/web-awesome/%NPMDIR%">
-  import '/path/to/web-awesome/%NPMDIR%/components/button/button.js';
+<script type="module" data-webawesome="/path/to/web-awesome/dist">
+  import '/path/to/web-awesome/dist/components/button/button.js';
 
   // <wa-button> is ready to use!
 </script>
@@ -166,44 +111,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 shown 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-outline
 ---
 
-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">
@@ -22,12 +22,43 @@ Through the magic of a mutation observer, changing the `lang` attribute will aut
 
 ## Available Translations
 
-Web Awesome ships with a number of translations. The default is English (US), which also serves as the fallback locale. As such, you do not need to import the English translation. To see a list of all available translations in the latest version, [refer to this directory](https://github.com/shoelace-style/shoelace/tree/current/src/translations).
+Web Awesome ships with a number of translations. The default is English (US), which also serves as the fallback locale. As such, you do not need to import the English translation.
 
-The location of translations depends on how you're consuming Web Awesome.
+Available translations include:
 
-- If you're using the CDN, [import them from the CDN](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace?path=%CDNDIR%%2Ftranslations)
-- If you're using a bundler, import them from `@shoelace-style/shoelace/%NPMDIR%/translations/[lang].js`
+<div style="columns: 3; gap: 1rem; margin-block-end: 1.5rem;">
+
+- ar
+- da
+- de-ch
+- de
+- en-gb
+- en
+- es
+- fa
+- fr
+- he
+- hr
+- hu
+- id
+- ja
+- nl
+- pl
+- pt
+- ru
+- sl
+- sv
+- tr
+- zh-cn
+- zh-tw
+
+</div>
+
+You can import translations using the following syntax, where `<code>` is replaced with any language code shown above.
+
+```js
+import '{% cdnUrl "translations/<code>.js" %}';
+```
 
 You do not need to load translations up front. You can import them dynamically even after updating the `lang` attribute. Once a translation is registered, localized components will update automatically.
 
@@ -36,7 +67,7 @@ You do not need to load translations up front. You can import them dynamically e
 document.documentElement.lang = 'de';
 
 // Import the translation
-import('/path/to/shoelace/dist/translations/de.js');
+import('{% cdnUrl "translations/<code>.js" %}');
 ```
 
 ### Translation Resolution
@@ -98,9 +129,9 @@ You can provide your own translations if you have specific needs or if you don't
 
 Let's create a Spanish translation as an example. The following assumes you're using TypeScript, but you can also create translations with regular JavaScript.
 
-```js
-import { registerTranslation } from '@shoelace-style/shoelace/dist/utilities/localize';
-import type { Translation } from '@shoelace-style/shoelace/dist/utilities/localize';
+```ts
+import { registerTranslation } from 'path/to/webawesome.js';
+import type { Translation } from 'path/to/webawesome.js';
 
 const translation: Translation = {
   $code: '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="outlined">View Order</wa-button>
+        <wa-button variant="neutral" appearance="outlined">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,20 +1,20 @@
 ---
 title: Themes
 description: Everything you need to know about theming Web Awesome.
-layout: page.njk
+layout: page-outline
 ---
 
-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`.
+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 `/dist/themes/*.styles.js`.
 :::
 
 ## 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/dist/themes/default.css" />
   </head>
 
   <body>
@@ -42,41 +44,18 @@ 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.
-
-```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>
-    <nav class="wa-theme-default-dark">
-      <!-- dark-themed sidebar -->
-    </nav>
-
-    <!-- light-themed content -->
-  </body>
-</html>
-```
-
-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](/docs/customizing#design-tokens) and adds [component styles](/docs/customizing#css-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 +65,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 +74,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 +91,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