updated usage example

fix color picker label, remove inline color picker

cspell.json

@@ -54,6 +54,7 @@
     "exportmaps",
     "exportparts",
     "fieldsets",
+    "fontawesome",
     "formaction",
     "formdata",
     "formenctype",

docs/.eleventy.js

@@ -40,7 +40,7 @@ export default function (eleventyConfig) {
 
   // Shortcodes - {% shortCode arg1, arg2 %}
   eleventyConfig.addShortcode('cdnUrl', location => {
-    return `https://early.webawesome.com/webawesome@${packageData.version}/` + location.replace(/^\//, '');
+    return `https://early.webawesome.com/webawesome@${packageData.version}/dist/` + location.replace(/^\//, '');
   });
 
   // Helpers

docs/_includes/base.njk

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="description" content="{{ description }}">
-    <meta name="theme-color" content="#787acf">
+    <meta name="theme-color" content="#f36944">
     {% if noindex %}<meta name="robots" content="noindex">{% endif %}
 
     <title>{{ title }}</title>
@@ -20,6 +20,7 @@
     <script type="module" src="/assets/scripts/turbo.js"></script>
     <script type="module" src="/assets/scripts/search.js"></script>
     <script type="module" src="/assets/scripts/outline.js"></script>
+    <script defer data-domain="backers.webawesome.com" src="https://plausible.io/js/script.js"></script>
 
     {# Web Awesome #}
     <script type="module" src="/dist/webawesome.loader.js"></script>
@@ -75,7 +76,7 @@
           </wa-dropdown>
 
           {# Search #}
-          <wa-button id="search-trigger" appearance="outline" size="small" data-search>
+          <wa-button id="search-trigger" appearance="outlined" size="small" data-search>
             <wa-icon slot="prefix" name="magnifying-glass"></wa-icon>
             Search
             <kbd slot="suffix" class="only-desktop">/</kbd>
@@ -124,6 +125,5 @@
 
       {% include 'search.njk' %}
     </wa-page>
-
   </body>
 </html>

docs/_includes/sidebar.njk

@@ -5,6 +5,7 @@
   <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>
 

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>

docs/assets/scripts/code-examples.js

@@ -17,11 +17,10 @@ document.addEventListener('click', event => {
     const code = codeExample.querySelector('code');
     const cdnUrl = document.documentElement.dataset.cdnUrl;
     const html =
-      `<script type="module" src="${cdnUrl}dist/webawesome.loader.js"></script>` + `\n\n` + `${code.textContent}`;
-    const css =
-      `import '${cdnUrl}/dist/themes/default.css';` +
-      `\n\n` +
-      `body {\n  font: 16px sans-serif;\n  padding: 1rem;\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}';
     const js = '';
 
     const form = document.createElement('form');

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-40);
+  color: var(--wa-color-gray-70);
 }
 
 .code-namespace {
@@ -15,13 +19,13 @@
 .code-keyword,
 .code-tag,
 .code-url {
-  color: var(--wa-color-indigo-40);
+  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-blue-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-on-normal);
-  background-color: var(--wa-color-neutral-fill-quiet);
+  color: var(--wa-color-gray-80);
   border-radius: var(--wa-border-radius-s);
   padding: 0.25rem;
 
   &:hover {
-    background-color: var(--wa-color-neutral-fill-normal);
+    color: white;
   }
 
   &:focus-visible {

docs/assets/styles/docs.css

@@ -100,6 +100,9 @@ wa-page[view='desktop']::part(navigation) {
 wa-page[view='desktop'] > #sidebar {
   min-width: 300px;
   padding: var(--wa-space-xl);
+  max-width: 300px;
+  overflow: auto;
+  max-height: 100%;
 }
 
 #sidebar,
@@ -158,10 +161,18 @@ wa-page::part(menu) {
 /* 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 {
@@ -188,7 +199,7 @@ wa-page > main {
 .callout {
   display: flex;
   gap: 1rem;
-  border: var(--wa-border-style) var(--wa-border-width-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);
@@ -255,3 +266,11 @@ wa-page > main {
   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

@@ -250,12 +250,3 @@ header {
     }
   }
 }
-
-@keyframes show-search-backdrop {
-  from {
-    opacity: 0;
-  }
-  to {
-    opacity: 1;
-  }
-}

docs/docs/components/animation.md

@@ -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');

docs/docs/components/breadcrumb-item.md

@@ -16,5 +16,5 @@ layout: component
 ```
 
 :::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

@@ -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

@@ -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

@@ -30,31 +30,31 @@ Use the `appearance` attribute to change the button's visual appearance.
 <div style="margin-block-end: 1rem;">
   <wa-button appearance="filled" variant="neutral">Filled</wa-button>
   <wa-button appearance="tinted" variant="neutral">Tinted</wa-button>
-  <wa-button appearance="outline" variant="neutral">Outline</wa-button>
+  <wa-button appearance="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="outline" variant="brand">Outline</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="outline" variant="success">Outline</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="outline" variant="warning">Outline</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="outline" variant="danger">Outline</wa-button>
+  <wa-button appearance="outlined" variant="danger">Outlined</wa-button>
   <wa-button appearance="text" variant="danger">Text</wa-button>
 </div>
 ```
@@ -87,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

docs/docs/components/carousel-item.md

@@ -40,5 +40,5 @@ layout: component
 ```
 
 :::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

@@ -9,31 +9,31 @@ layout: component
   <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

@@ -9,7 +9,7 @@ layout: component
 ```
 
 :::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

@@ -5,14 +5,11 @@ 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

@@ -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">

docs/docs/components/dialog.md

@@ -127,7 +127,7 @@ 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">

docs/docs/components/divider.md

@@ -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

@@ -187,7 +187,7 @@ 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">

docs/docs/components/dropdown.md

@@ -6,7 +6,7 @@ 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/icon-button.md

@@ -4,7 +4,7 @@ description: Icons buttons are simple, icon-only buttons that can be used for ac
 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

@@ -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/input.md

@@ -9,7 +9,7 @@ layout: component
 ```
 
 :::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.md

@@ -4,7 +4,7 @@ description: Menus provide a list of options for the user to choose from.
 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/page.md

@@ -6,7 +6,7 @@ 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

@@ -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}

docs/docs/components/radio-button.md

@@ -4,7 +4,7 @@ description: Radios buttons allow the user to select a single option from a grou
 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

@@ -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

@@ -4,7 +4,7 @@ description: Radios allow the user to select a single option from a group.
 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

@@ -9,7 +9,7 @@ layout: component
 ```
 
 :::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/select.md

@@ -16,7 +16,7 @@ layout: component
 ```
 
 :::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/switch.md

@@ -9,7 +9,7 @@ layout: component
 ```
 
 :::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

@@ -4,7 +4,7 @@ description: Tab groups organize content into a container that shows one section
 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

@@ -19,5 +19,5 @@ 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/tab.md

@@ -5,5 +5,5 @@ 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/textarea.md

@@ -9,7 +9,7 @@ layout: component
 ```
 
 :::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/customizing.md

@@ -1,88 +1,47 @@
 ---
 title: Customizing
 description: Learn how to customize Web Awesome through parts and custom properties.
-layout: page
+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/sandbox.md

@@ -100,11 +100,11 @@ layout: page
 <wa-button variant="warning">Warning</wa-button>
 <wa-button variant="danger">Danger</wa-button>
 <br /><br />
-<wa-button variant="brand" appearance="outline">Brand</wa-button>
-<wa-button variant="success" appearance="outline">Success</wa-button>
-<wa-button variant="neutral" appearance="outline">Neutral</wa-button>
-<wa-button variant="warning" appearance="outline">Warning</wa-button>
-<wa-button variant="danger" appearance="outline">Danger</wa-button>
+<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 appearance="text">Text</wa-button>
 <br /><br />
@@ -215,40 +215,40 @@ layout: page
 </wa-button>
 <br /><br />
 <wa-button-group label="Alignment">
-  <wa-button appearance="outline" variant="brand">Left</wa-button>
-  <wa-button appearance="outline" variant="brand">Center</wa-button>
-  <wa-button appearance="outline" variant="brand">Right</wa-button>
+  <wa-button 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="outline" variant="success">Left</wa-button>
-  <wa-button appearance="outline" variant="success">Center</wa-button>
-  <wa-button appearance="outline" variant="success">Right</wa-button>
+  <wa-button 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="outline">Left</wa-button>
-  <wa-button appearance="outline">Center</wa-button>
-  <wa-button appearance="outline">Right</wa-button>
+  <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="outline" variant="warning">Left</wa-button>
-  <wa-button appearance="outline" variant="warning">Center</wa-button>
-  <wa-button appearance="outline" variant="warning">Right</wa-button>
+  <wa-button 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="outline" variant="danger">Left</wa-button>
-  <wa-button appearance="outline" variant="danger">Center</wa-button>
-  <wa-button appearance="outline" variant="danger">Right</wa-button>
+  <wa-button 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/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,12 +1,12 @@
 ---
 title: Installation
 description: Choose the installation method that works best for you.
-layout: page
+layout: page-outline
 ---
 
 Welcome to the Web Awesome alpha release for early backers! 👋
 
-==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!
+==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!
 
 ==To be clear, this release _only_ includes a preview the components in Web Awesome Free!==
 
@@ -14,6 +14,11 @@ Thank you so much for backing us!
 
 - [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)
+
+:::warning
+As a Web Awesome backer, this early alpha release is _just for you_. Please refrain from sharing it for the time being!
+:::
 
 ---
 
@@ -22,11 +27,11 @@ Thank you so much for backing us!
 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="{% cdnUrl 'dist/themes/default.css' %}" />
-<script type="module" src="{% cdnUrl 'dist/autoloader.js' %}"></script>
+<link rel="stylesheet" href="{% cdnUrl 'themes/default.css' %}" />
+<script type="module" src="{% cdnUrl 'webawesome.loader.js' %}"></script>
 ```
 
-Now you can [start using Web Awesome!](/getting-started/usage)
+Now you can [start using Web Awesome!](/docs/usage)
 
 :::info
 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.
@@ -34,7 +39,7 @@ While convenient, autoloading may lead to a [Flash of Undefined Custom Elements]
 
 ## 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.
 
 ==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.
 
@@ -108,4 +113,4 @@ You will see files named `chunk.[hash].js` in the `chunks` directory. Never impo
 
 ## Using Web Awesome with npm
 
-An npm package isn't available in the early backer alpha release, but we'll have one soon! For now, please enjoy Web Awesome from the CDN as described above.
+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,7 +1,7 @@
 ---
 title: Localization
 description: Discover how to localize Web Awesome with minimal effort.
-layout: page
+layout: page-outline
 ---
 
 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.
@@ -57,7 +57,7 @@ Available translations include:
 You can import translations using the following syntax, where `<code>` is replaced with any language code shown above.
 
 ```js
-import '{% cdnUrl "dist/translations/<code>.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.
@@ -67,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
@@ -130,8 +130,8 @@ 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.
 
 ```ts
-import { registerTranslation } from 'path/to/webawesome/dist/utilities/localize';
-import type { Translation } from 'path/to/webawesome/dist/utilities/localize';
+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

@@ -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" appearance="outline">View Order</wa-button>
-        <wa-button variant="neutral" appearance="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/changelog.md

@@ -8,30 +8,42 @@ Web Awesome follows [Semantic Versioning](https://semver.org/). Breaking changes
 
 Components with the <wa-badge variant="warning" pill>Experimental</wa-badge> badge should not be used in production. They are made available as release candidates for development and testing purposes. As such, changes to experimental components will not be subject to semantic versioning.
 
-New versions of Web Awesome are released as-needed and generally occur when a critical mass of changes have accumulated. At any time, you can see what's coming in the next release by visiting [next.shoelace.style](https://next.shoelace.style).
+:::warning
+During the alpha period, things might break! We take breaking changes very seriously, but sometimes they're necessary to make the final product that much better. We appreciate your patience!
+:::
 
-## 3.0 Changes (BREAKING)
+## Web Awesome 1.0.0-alpha.1
+
+- This is the initial release of Web Awesome alpha!
+
+---
+
+## What's different from Shoelace v2?
+
+==If you're new to Web Awesome, you can skip this section.== If you're coming from [Shoelace](https://shoelace.style/), you're in the right place!
+
+Here's a list of some of the things that have changed since Shoelace v2. For questions or help upgrading, [the alpha discussion board](https://github.com/shoelace-style/webawesome-alpha/discussions) is a great place to get help!
 
-- Disabled form controls will no longer have a `disabled` attribute set when they are disabled via property. IE: `el.disabled = true`. Instead use `:state(disabled)` to style them.
-- Checkboxes will no longer have a `checked` attribute set when their `checked` property is changed. IE: `el.checked = true`. Instead, use the `:state(:checked)` and for unsupported browsers, use `[data-checked]`
-- `data-optional`, `data-required`, `data-invalid`, `data-valid`, `data-user-invalid`, and `data-user-valid` have all been renamed to have a `data-wa-*` prefix. Like so: `data-wa-valid`, `data-wa-invalid`, to avoid any conflicts with user provided attributes.
-- `<wa-checkbox>` and `<wa-switch>` now use `:state(checked)` and `[data-wa-checked]` for CSS styling their "checked" state. The "checked" attribute now maps to `defaultChecked` just like native HTML checkboxes.
-- `<wa-radio>` has changed from `display: block;` to `display: inline-block`
-- `getFormControls()` has been removed. We use Form Associated Custom Elements now and can reliably grab Web Awesome Elements via `formElement.elements`.
 - Added `setKitCode()` and `getKitCode()` functions as well as support for setting kit codes declaratively with `data-webawesome-kit`
 - Added `family` and `variant` attributes to `<wa-icon>` and `<wa-icon-button>`
 - Added the `active` attribute to `<wa-tab-group>`
 - Added an easier way to close dialogs by applying `data-dialog="close"` to any button in the dialog
 - Added an easier way to close drawers by applying `data-dialog="close"` to any button in the drawer
 - Added the `--show-duration` and `--hide-duration` custom properties to `<wa-details>`, `<wa-dialog>`, `<wa-drawer>`, `<sl-tree-item>`, and `<wa-popup>`
+- Added visible labels to `<wa-color-picker>`
 - Changed the attribute for setting the base path declaratively to `data-webawesome` instead of `data-shoelace`; additionally, you can place it on any element now instead of just the associated `<script>` tag
-- `<wa-icon>` icons are no longer fixed width by default to accommodate variable width icons
 - Changed the `sl` prefix to `wa` for Web Awesome, including tags, events, etc.
 - Changed `primary` variants to `brand` in all components
 - Changed the internal structure of `<wa-checkbox>` so that the internal checkbox now takes up the full height and width of its wrapping container.
+- Changed disabled form controls so they don't have the `disabled` attribute when disabled (use `:state(disabled)` or `[data-wa-disabled]` instead)
+- Changed `<wa-checkbox>` to no longer have a `checked` attribute set when their `checked` property is changed, e.g. `el.checked = true` (use the `:state(:checked)` or `[data-checked]` selector instead)
+- Changed `<wa-checkbox>` and `<wa-switch>` to use `:state(checked)` (fallback `[data-wa-checked]`) for styling their "checked" state (the `checked` attribute now maps to `defaultChecked` like native HTML checkboxes)
+- Changed the `data-optional`, `data-required`, `data-invalid`, `data-valid`, `data-user-invalid`, and `data-user-valid` states to `data-wa-*` prefix to avoid conflicts with user provided attributes
+- Changed `<wa-icon>` so icons are no longer fixed width by default to accommodate variable width icons
+- Changed `<wa-radio>` from `display: block;` to `display: inline-block`
 - Changed `<wa-tab-group>` to implement a "roving tabindex" and `<wa-tab>` is no longer tabbable by default. This aligns closer to the APG pattern for tabs. [#2041]
 - Changed `<wa-tooltip>` to no longer wrap content due to accessibility and styling issues. Tooltips are now associated using the `for` attribute + an `id` on the trigger [#123]
-- Fixed a bug in `<wa-spinner>` that caused it to display incorrectly when zooming in Safari
+- Improved `<wa-spinner>` so it doesn't wobble when zooming in Safari
 - Improved submenu selection by implementing the [safe triangle](https://www.smashingmagazine.com/2023/08/better-context-menus-safe-triangles/) method [#1550]
 - Improved tabbing in `<wa-tab-group>` so it uses a roving tab index instead of being able to cycle through each tab
 - Removed `default` from `<wa-button>` and made `neutral` the new default
@@ -42,13 +54,15 @@ New versions of Web Awesome are released as-needed and generally occur when a cr
 - Removed the `show()` and `hide()` methods from `<wa-dialog>` and `<wa-drawer`> (toggle the `open` attribute instead)
 - Removed JavaScript-based animation customizations due to high confusion and low usage
 - Removed the `wa-request-close` event from `<wa-dialog>` and `<wa-drawer>` (use the `wa-hide` event instead)
-- Removed `valueAsDate` from `<wa-input>`. Instead use the following to mimic browser behavior:
+- Removed `inline` from `<wa-color-picker>`
+- Removed `getFormControls()` since we now use Form Associated Custom Elements and can reliably access Web Awesome Elements via `formElement.elements`.
+- Removed `valueAsDate` from `<wa-input>`; use the following to mimic native behaviors:
     setter: `waInput.value = new Date().toLocaleDateString()`
     getter: `new Date(waInput.value)`
-- Removed `valueAsNumber` from `<wa-input>`. Instead you can use the following to mimic browser behavior:
+- Removed `valueAsNumber` from `<wa-input>`; use the following to mimic native behaviors:
     setter: `waInput.value = 5.toString()`
     getter: `Number(waInput.value)`
 
----
+Did we miss something? [Let us know!](https://github.com/shoelace-style/webawesome-alpha/discussions)
 
-Coming from Shoelace? [The 2.x changelog can be found here.](https://shoelace.style/resources/changelog/)
+Are you coming from Shoelace? [The 2.x changelog can be found here.](https://shoelace.style/resources/changelog/)

docs/docs/themes.md

@@ -1,7 +1,7 @@
 ---
 title: Themes
 description: Everything you need to know about theming Web Awesome.
-layout: page
+layout: page-outline
 ---
 
 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.
@@ -47,35 +47,13 @@ To activate a theme, import it and apply the theme's class to the `<html>` eleme
 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 different themes and styles on various containers throughout the page. This example uses the default theme with a dark sidebar.
-
-```html
-<html>
-  <head>
-    <link rel="stylesheet" href="path/to/shoelace/dist/themes/default.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 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
 
-Overriding the default theme is the easiest way to customize Web Awesome. You can do this by importing the default theme as-is, then creating a separate stylesheet that overrides [the theming API](/getting-started/customizing#design-tokens) and adds [component styles](/getting-started/customizing#component-parts) to your liking. You must import your theme _after_ the default theme.
+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 default light styles, scope your styles to the following selectors.
 

docs/docs/theming/borders.md

@@ -1,7 +1,7 @@
 ---
 title: Borders
 description: Change the edges and corners of your components with Web Awesome's border properties.
-layout: page
+layout: page-outline
 ---
 
 ## Style

docs/docs/theming/color.md

@@ -1,7 +1,7 @@
 ---
 title: Color
 description: Ensure consistent use of color and readable contrast with Web Awesome's color properties.
-layout: page
+layout: page-outline
 ---
 
 <style>

docs/docs/theming/component-groups.md

@@ -1,7 +1,7 @@
 ---
 title: Component Groups
 description: Style groups of components that share similar qualities with these Web Awesome custom properties.
-layout: page
+layout: page-outline
 ---
 
 For components that share similar qualities, Web Awesome includes custom properties to change the appearance of these related components all at once.
@@ -14,7 +14,7 @@ Not every form control uses all of these custom properties. For example, `<wa-ra
 
 | Custom Property                             | Default Value                                                                                     |
 | ------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `--wa-form-control-background-color`              | `var(--wa-color-surface-default)`                                                                 |
+| `--wa-form-control-background-color`        | `var(--wa-color-surface-default)`                                                                 |
 | `--wa-form-control-border-style`            | `var(--wa-border-style)`                                                                          |
 | `--wa-form-control-border-width`            | `var(--wa-border-width-s)`                                                                        |
 | `--wa-form-control-border-radius`           | `var(--wa-border-radius-s)`                                                                       |
@@ -26,7 +26,7 @@ Not every form control uses all of these custom properties. For example, `<wa-ra
 | `--wa-form-control-value-color`             | `var(--wa-color-text-normal)`                                                                     |
 | `--wa-form-control-value-font-weight`       | `var(--wa-font-weight-body)`                                                                      |
 | `--wa-form-control-value-line-height`       | `var(--wa-line-height-condensed)`                                                                 |
-| `--wa-form-control-placeholder-color`       | `var(--wa-color-base-60)`                                                                         |
+| `--wa-form-control-placeholder-color`       | `var(--wa-color-gray-60)`                                                                         |
 | `--wa-form-control-height-s`                | `calc(var(--wa-space-xs) * 2 + var(--wa-font-size-s) * var(--wa-form-control-value-line-height))` |
 | `--wa-form-control-height-m`                | `calc(var(--wa-space-s) * 2 + var(--wa-font-size-m) * var(--wa-form-control-value-line-height))`  |
 | `--wa-form-control-height-l`                | `calc(var(--wa-space-m) * 2 + var(--wa-font-size-l) * var(--wa-form-control-value-line-height))`  |

docs/docs/theming/focus.md

@@ -1,7 +1,7 @@
 ---
 title: Focus
 description: Configure recognizable focus states with Web Awesome's focus properties.
-layout: page
+layout: page-outline
 ---
 
 A consistent focus ring helps with predictable keyboard navigation. Together with [`--wa-color-focus`](/docs/theming/color/#interactions), these custom properties create a uniform focus state for Web Awesome components.

docs/docs/theming/shadows.md

@@ -1,7 +1,7 @@
 ---
 title: Shadows
 description: Elevate your components with Web Awesome's shadow properties.
-layout: page
+layout: page-outline
 ---
 
 Shadows indicate elevation and, often, interactivity. Web Awesome offers highly modular shadow properties to easily create custom shadow effects or transform elements based on specific shadow qualities. Together with [`--wa-color-shadow`](/docs/theming/color/#shadow), these custom properties create realistic shadows for Web Awesome components.

docs/docs/theming/space.md

@@ -1,7 +1,7 @@
 ---
 title: Space
 description: Lock down consistent spacing Web Awesome's space properties.
-layout: page
+layout: page-outline
 ---
 
 <style>

docs/docs/theming/transitions.md

@@ -1,7 +1,7 @@
 ---
 title: Transitions
 description: Customize your theme's built-in transitions with Web Awesome's transition properties.
-layout: page
+layout: page-outline
 ---
 
 <style>

docs/docs/theming/typography.md

@@ -1,7 +1,7 @@
 ---
 title: Typography
 description: Get consistent font styles and vertical rhythm with Web Awesome's typography properties.
-layout: page
+layout: page-outline
 ---
 
 ## Font Family

docs/docs/usage.md

@@ -1,7 +1,7 @@
 ---
 title: Usage
 description: Learn more about using custom elements.
-layout: page
+layout: page-outline
 ---
 
 Web Awesome components are just regular HTML elements, or [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) to be precise. You can use them like any other element. Each component has detailed documentation that describes its full API, including properties, events, methods, and more.
@@ -22,19 +22,6 @@ Some properties are boolean, so they only have true/false values. To activate a
 <wa-button disabled>Click me</wa-button>
 ```
 
-In rare cases, a property may require an array, an object, or a function. For example, to customize the color picker's list of preset swatches, you set the `swatches` property to an array of colors. This must be done with JavaScript.
-
-```html
-<wa-color-picker></wa-color-picker>
-
-<script>
-  const colorPicker = document.querySelector('wa-color-picker');
-  colorPicker.swatches = ['red', 'orange', 'yellow', 'green', 'blue', 'purple'];
-</script>
-```
-
-Refer to a component's documentation for a complete list of its properties.
-
 ## Events
 
 You can listen for standard events such as `click`, `mouseover`, etc. as you normally would. However, it's important to note that many events emitted within a component's shadow root will be [retargeted](https://dom.spec.whatwg.org/#retarget) to the host element. This may result in, for example, multiple `click` handlers executing even if the user clicks just once. Furthermore, `event.target` will point to the host element, making things even more confusing.

docs/index.md

@@ -15,11 +15,14 @@ layout: page
     --content-padding-inline: 2rem;
     --content-flow-spacing: 4rem;
     max-width: 100%;
-    padding: 0;
+    padding: 0 !important;
     & p, h1, h2, h3, h4, h5, h6 {
       margin: 0;
     }
   }
+  wa-page:not([view="desktop"]) > main {
+    --content-flow-spacing: 3rem;
+  }
   .brand-font {
     font-family: cera-round-pro;
   }
@@ -41,7 +44,7 @@ layout: page
     background-image: linear-gradient(color-mix(in oklab, var(--wa-brand-orange), orangered 40%) 1px, transparent 1px), linear-gradient(90deg, color-mix(in oklab, var(--wa-brand-orange), orangered 40%) 1px, transparent 1px);
     background-size: 2rem 2rem;
     color: white;
-    padding: 7.5rem 0 var(--content-flow-spacing) 0;
+    padding: calc(var(--content-flow-spacing) * 1.875) 0 var(--content-flow-spacing) 0;
   }
   .hero-content {
     max-width: var(--content-width);
@@ -51,7 +54,7 @@ layout: page
       margin-block-start: 2rem;
     }
     & h1 {
-      font-size: 3.25rem;
+      font-size: clamp(2.5625rem, 13vw, 3.25rem);
     }
     & .emphasis::after {
       background-color: var(--wa-brand-grey);
@@ -67,15 +70,20 @@ layout: page
     display: flex;
     align-items: center;
     gap: 1.5rem;
+    flex-wrap: wrap;
     background-color: var(--wa-brand-grey);
     border-radius: 0.75rem;
     font-size: 0.875rem;
     padding: 1.5rem;
+    & > *:first-child {
+      flex: 1 1 67%;
+    }
     & wa-button {
       --wa-form-control-height-s: 2.5rem;
       --border-color: black;
       --border-width: 0.125rem;
       --box-shadow: 0 0.25rem 0 0 var(--border-color);
+      flex: 1 1 auto;
       &:active:not([disabled]) {
         --box-shadow: 0 0 0 0 transparent;
         transform: translateY(0.25rem);
@@ -95,7 +103,7 @@ layout: page
     background-color: var(--wa-brand-grey);
     border-radius: 1.125rem;
     color: white;
-    padding: 4rem;
+    padding: var(--content-flow-spacing);
     & > * + * {
       margin-block-start: 2rem;
     }
@@ -151,6 +159,9 @@ layout: page
       height: 2rem;
       width: 2rem;
     }
+    & h3 {
+      font-size: 1rem;
+    }
   }
   footer {
     display: flex;
@@ -173,14 +184,74 @@ layout: page
       }
       & wa-button {
         --wa-form-control-height-m: 1.5rem;
-        --background-color: var(--wa-color-neutral-fill-quiet);
-        --background-color-hover: color-mix(in oklab, var(--background-color), transparent 20%);
-        --label-color: var(--wa-color-neutral-on-quiet);
         display: inline-flex;
         font-size: 0.75rem;
       }
     }
   }
+  .alpha-notice {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 1rem;
+    & > * {
+      flex-basis: calc(((30ch * 2 + 1rem) - 100%) * 999);
+    }
+    & > * {
+      flex-grow: 2;
+    }
+    & > * + * {
+      flex-grow: 1;
+    }
+    & wa-callout::part(base),
+    & wa-button::part(base) {
+      height: 100%;
+      width: 100%;
+    }
+  }
+  wa-button.tile::part(base) {
+    border-color: var(--wa-color-surface-border);
+    border-radius: 0.75rem;
+    color: var(--wa-color-text-normal);
+    display: block;
+    height: 100%;
+    line-height: var(--wa-line-height-normal);
+    padding: 1.25rem;
+    text-align: left;
+    white-space: wrap;
+  }
+  wa-button.tile::part(suffix) {
+    display: none;
+  }
+  wa-button.tile {
+    width: 100%;
+    height: 100%;
+    & h3 {
+      font-size: 1rem;
+    }
+    & .icon-heading + wa-icon {
+      color: var(--wa-color-text-quiet);
+    }
+    & p {
+      font-size: 0.875rem;
+      font-weight: var(--wa-font-weight-normal);
+    }
+    &::part(label) {
+      width: 100%;
+    }
+  }
+  wa-callout {
+    --spacing: 1.25rem;
+    height: 100%;
+
+    & .icon-heading wa-icon {
+      background-color: var(--wa-color-warning-fill-normal);
+      color: var(--wa-color-warning-on-normal);
+    }
+
+    & p {
+      font-size: 0.875rem;
+    }
+  }
 </style>
 
 <div class="hero-background">
@@ -200,6 +271,30 @@ layout: page
 </div>
 
 <div class="home-wrapper">
+  <div class="alpha-notice">
+    <div>
+      <wa-callout variant="warning">
+        <div class="icon-heading">
+          <wa-icon name="triangle-exclamation" variant="regular" fixed-width></wa-icon>
+          <h3>You're in alpha territory</h3>
+        </div>
+        <p>What you see may not be perfect (we're only humans!) and is subject to change. We encourage you to <a href="https://github.com/shoelace-style/webawesome-alpha/issues">report bugs</a> or <a href="https://github.com/shoelace-style/webawesome-alpha/discussions">ask for help</a>!</p>
+      </wa-callout>
+    </div>
+    <div>
+      <wa-button href="/docs/installation" appearance="outlined" class="tile">
+        <div style="display: flex; justify-content: space-between; align-items: center; margin-block-end: 1rem;">
+          <div class="icon-heading" style="margin-block-end: 0;">
+            <wa-icon name="pen-ruler" fixed-width></wa-icon>
+            <h3>Get started</h3>
+          </div>
+          <wa-icon name="arrow-right" fixed-width></wa-icon>
+        </div>
+        <p>Check out our installation guide to start building with Web Awesome.</p>
+      </wa-button>
+    </div>
+  </div>
+  <wa-divider></wa-divider>
   <div class="summary">
     <h2 class="brand-font">What's <span class="emphasis">Web</span> Awesome?</h2>
     <p>Web Awesome is the biggest open-source library of meticulously designed, highly customizable, and framework-agnostic UI components.</p>
@@ -273,12 +368,12 @@ layout: page
       <div class="attribution">
         <span>Special thanks</span>
         <div class="button-list">
-          <wa-button pill href="https://lit.dev/">Lit</wa-button>
-          <wa-button pill href="https://github.com/open-wc/custom-elements-manifest">Custom Elements Manifest</wa-button>
-          <wa-button pill href="https://www.11ty.dev/">11ty</wa-button>
-          <wa-button pill href="https://floating-ui.com/">Floating UI</wa-button>
-          <wa-button pill href="https://animate.style/">animate.css</wa-button>
-          <wa-button pill href="https://lunrjs.com/">Lunr</wa-button>
+          <wa-button appearance="tinted" pill href="https://lit.dev/">Lit</wa-button>
+          <wa-button appearance="tinted" pill href="https://github.com/open-wc/custom-elements-manifest">Custom Elements Manifest</wa-button>
+          <wa-button appearance="tinted" pill href="https://www.11ty.dev/">11ty</wa-button>
+          <wa-button appearance="tinted" pill href="https://floating-ui.com/">Floating UI</wa-button>
+          <wa-button appearance="tinted" pill href="https://animate.style/">animate.css</wa-button>
+          <wa-button appearance="tinted" pill href="https://lunrjs.com/">Lunr</wa-button>
         </div>
       </div>
     </div>

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@shoelace-style/shoelace",
-  "version": "2.8.0",
+  "version": "3.0.0-alpha.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@shoelace-style/shoelace",
-      "version": "2.8.0",
+      "version": "3.0.0-alpha.2",
       "license": "MIT",
       "dependencies": {
         "@ctrl/tinycolor": "^4.0.2",

package.json

@@ -1,15 +1,15 @@
 {
-  "name": "@shoelace-style/shoelace",
+  "name": "@shoelace-style/webawesome",
   "description": "A forward-thinking library of web components.",
-  "version": "3.0.0-alpha.1",
-  "homepage": "https://github.com/shoelace-style/shoelace",
+  "version": "3.0.0-alpha.2",
+  "homepage": "https://webawesome.com/",
   "author": "Web Awesome",
   "license": "MIT",
   "customElements": "dist/custom-elements.json",
   "web-types": "./dist/web-types.json",
   "type": "module",
   "types": "dist/webawesome.d.ts",
-  "jsdelivr": "./cdn/autoloader.js",
+  "jsdelivr": "./dist/webawesome.loader.js",
   "exports": {
     ".": {
       "types": "./dist/webawesome.d.ts",
@@ -17,10 +17,9 @@
     },
     "./dist/custom-elements.json": "./dist/custom-elements.json",
     "./dist/webawesome.js": "./dist/webawesome.js",
-    "./dist/autoloader.js": "./dist/autoloader.js",
+    "./dist/webawesome.loader.js": "./dist/webawesome.loader.js",
     "./dist/themes/*": "./dist/themes/*",
     "./dist/components/*": "./dist/components/*",
-    "./dist/utilities/*": "./dist/utilities/*",
     "./dist/react": "./dist/react/index.js",
     "./dist/react/*": "./dist/react/*",
     "./dist/translations/*": "./dist/translations/*"
@@ -36,16 +35,17 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/shoelace-style/shoelace.git"
+    "url": "git+https://github.com/shoelace-style/webawesome.git"
   },
   "bugs": {
-    "url": "https://github.com/shoelace-style/shoelace/issues"
+    "url": "https://github.com/shoelace-style/webawesome/issues"
   },
   "scripts": {
     "start": "node scripts/build.js --develop",
     "build": "node scripts/build.js",
     "build:alpha": "node scripts/build.js --alpha",
     "start:alpha": "node scripts/build.js --alpha --develop",
+    "publish-alpha-cdn": "./publish-alpha-cdn.sh",
     "create": "plop --plopfile scripts/plop/plopfile.js",
     "prepare": "npm i --ignore-scripts && npx playwright install",
     "test": "web-test-runner --group default",

publish-alpha-cdn.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+version=$1
+
+# Check for a version number
+if [ -z "$version" ]; then
+  echo "A version number must be provided as the first and only argument."
+  echo
+  exit 2
+fi
+
+echo "This command will build Web Awesome $version and publish it to the the CDN."
+echo
+read -p "🔥 Are you sure you want to do this? (y/N) " -n 1 -r
+echo
+if [[ $REPLY =~ ^[Yy]$ ]]
+then
+    # do dangerous stuff
+    echo
+    echo "🚀 OK, blasting off..."
+
+    # build it
+    npm run build:alpha
+
+    # copy dist to the CDN
+    aws --profile early-webawesome-com --endpoint-url https://c0c64e1b38a89d8ae060d40170ceef46.r2.cloudflarestorage.com s3 cp ./dist s3://early-webawesome-com/webawesome@$version/dist --recursive
+
+    echo
+    echo "✅ All done. Now go make something awesome!"
+    echo
+fi

scripts/plop/templates/component/component.hbs

@@ -8,7 +8,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Short summary of the component's intended use.
- * @documentation https://shoelace.style/components/{{ tagWithoutPrefix tag }}
+ * @documentation https://backers.webawesome.com/docs/components/{{ tagWithoutPrefix tag }}
  * @status experimental
  * @since 2.0
  *

src/components/animated-image/animated-image.ts

@@ -11,7 +11,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary A component for displaying animated GIFs and WEBPs that play and pause on interaction.
- * @documentation https://shoelace.style/components/animated-image
+ * @documentation https://backers.webawesome.com/docs/components/animated-image
  * @status stable
  * @since 2.0
  *

src/components/animation/animation.ts

@@ -12,7 +12,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Animate elements declaratively with nearly 100 baked-in presets, or roll your own with custom keyframes. Powered by the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API).
- * @documentation https://shoelace.style/components/animation
+ * @documentation https://backers.webawesome.com/docs/components/animation
  * @status stable
  * @since 2.0
  *

src/components/avatar/avatar.ts

@@ -10,7 +10,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Avatars are used to represent a person or object.
- * @documentation https://shoelace.style/components/avatar
+ * @documentation https://backers.webawesome.com/docs/components/avatar
  * @status stable
  * @since 2.0
  *

src/components/badge/badge.ts

@@ -8,7 +8,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Badges are used to draw attention and display statuses or counts.
- * @documentation https://shoelace.style/components/badge
+ * @documentation https://backers.webawesome.com/docs/components/badge
  * @status stable
  * @since 2.0
  *

src/components/breadcrumb-item/breadcrumb-item.styles.ts

@@ -63,8 +63,12 @@ export default css`
     display: inline-flex;
   }
 
-  ::slotted(*) {
-    margin-inline-end: var(--wa-space-s) !important;
+  ::slotted([slot='prefix']) {
+    margin-inline-end: var(--wa-space-s);
+  }
+
+  ::slotted([slot='suffix']) {
+    margin-inline-start: var(--wa-space-s);
   }
 
   :host(:last-of-type) .breadcrumb-item__separator {

src/components/breadcrumb-item/breadcrumb-item.ts

@@ -7,8 +7,8 @@ import WebAwesomeElement from '../../internal/webawesome-element.js';
 import type { CSSResultGroup } from 'lit';
 
 /**
- * @summary Breadcrumb Items are used inside [breadcrumbs](/components/breadcrumb) to represent different links.
- * @documentation https://shoelace.style/components/breadcrumb-item
+ * @summary Breadcrumb Items are used inside [breadcrumbs](/docs/components/breadcrumb) to represent different links.
+ * @documentation https://backers.webawesome.com/docs/components/breadcrumb-item
  * @status stable
  * @since 2.0
  *

src/components/breadcrumb/breadcrumb.ts

@@ -10,7 +10,7 @@ import type WaBreadcrumbItem from '../breadcrumb-item/breadcrumb-item.js';
 
 /**
  * @summary Breadcrumbs provide a group of links so users can easily navigate a website's hierarchy.
- * @documentation https://shoelace.style/components/breadcrumb
+ * @documentation https://backers.webawesome.com/docs/components/breadcrumb
  * @status stable
  * @since 2.0
  *

src/components/button-group/button-group.ts

@@ -7,7 +7,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Button groups can be used to group related buttons into sections.
- * @documentation https://shoelace.style/components/button-group
+ * @documentation https://backers.webawesome.com/docs/components/button-group
  * @status stable
  * @since 2.0
  *

src/components/button/button.styles.ts

@@ -84,41 +84,41 @@ export default css`
   }
 
   /*
-   * Outline buttons
+   * Outlined buttons
    */
 
-  :host([appearance='outline']),
+  :host([appearance='outlined']),
   :host(.wa-button-group__button--radio:not([checked])) {
     --background-color: transparent;
     --background-color-active: color-mix(in oklab, var(--background-color-hover), transparent 20%);
   }
 
-  :host([appearance='outline'][variant='neutral']),
+  :host([appearance='outlined'][variant='neutral']),
   :host(.wa-button-group__button--radio:not([checked])) {
     --background-color-hover: var(--wa-color-neutral-fill-quiet);
     --border-color: var(--wa-color-neutral-border-loud);
     --label-color: var(--wa-color-neutral-on-quiet);
   }
 
-  :host([appearance='outline'][variant='brand']) {
+  :host([appearance='outlined'][variant='brand']) {
     --background-color-hover: var(--wa-color-brand-fill-quiet);
     --border-color: var(--wa-color-brand-border-loud);
     --label-color: var(--wa-color-brand-on-quiet);
   }
 
-  :host([appearance='outline'][variant='success']) {
+  :host([appearance='outlined'][variant='success']) {
     --background-color-hover: var(--wa-color-success-fill-quiet);
     --border-color: var(--wa-color-success-border-loud);
     --label-color: var(--wa-color-success-on-quiet);
   }
 
-  :host([appearance='outline'][variant='warning']) {
+  :host([appearance='outlined'][variant='warning']) {
     --background-color-hover: var(--wa-color-warning-fill-quiet);
     --border-color: var(--wa-color-warning-border-loud);
     --label-color: var(--wa-color-warning-on-quiet);
   }
 
-  :host([appearance='outline'][variant='danger']) {
+  :host([appearance='outlined'][variant='danger']) {
     --background-color-hover: var(--wa-color-danger-fill-quiet);
     --border-color: var(--wa-color-danger-border-loud);
     --label-color: var(--wa-color-danger-on-quiet);
@@ -265,7 +265,7 @@ export default css`
   }
 
   @media (forced-colors: active) {
-    .button.button--outline.button--checked:not(.button--disabled) {
+    .button.button--outlined.button--checked:not(.button--disabled) {
       outline: solid 2px transparent;
     }
   }
@@ -406,13 +406,31 @@ export default css`
     padding: 0 var(--wa-space-l);
   }
 
-  .button ::slotted([slot='prefix']) {
-    margin-inline-end: 0.75em;
+  .button--small ::slotted([slot='prefix']) {
+    margin-inline-end: var(--wa-space-s);
   }
 
-  .button ::slotted([slot='suffix']),
-  .button .button__caret {
-    margin-inline-start: 0.75em;
+  .button--medium ::slotted([slot='prefix']) {
+    margin-inline-end: var(--wa-space-m);
+  }
+
+  .button--large ::slotted([slot='prefix']) {
+    margin-inline-end: var(--wa-space-l);
+  }
+
+  .button--small ::slotted([slot='suffix']),
+  .button--small.button--caret:not(.button--visually-hidden-label) .button__caret {
+    margin-inline-start: var(--wa-space-s);
+  }
+
+  .button--medium ::slotted([slot='suffix']),
+  .button--medium.button--caret:not(.button--visually-hidden-label) .button__caret {
+    margin-inline-start: var(--wa-space-m);
+  }
+
+  .button--large ::slotted([slot='suffix']),
+  .button--large.button--caret:not(.button--visually-hidden-label) .button__caret {
+    margin-inline-start: var(--wa-space-l);
   }
 
   /*

src/components/button/button.ts

@@ -17,7 +17,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Buttons represent actions that are available to the user.
- * @documentation https://shoelace.style/components/button
+ * @documentation https://backers.webawesome.com/docs/components/button
  * @status stable
  * @since 2.0
  *
@@ -67,6 +67,7 @@ export default class WaButton extends WebAwesomeFormAssociatedElement {
   @query('.button') button: HTMLButtonElement | HTMLLinkElement;
 
   @state() private hasFocus = false;
+  @state() visuallyHiddenLabel = false;
   @state() invalid = false;
   @property() title = ''; // make reactive to pass through
 
@@ -74,7 +75,7 @@ export default class WaButton extends WebAwesomeFormAssociatedElement {
   @property({ reflect: true }) variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' = 'neutral';
 
   /** The button's visual appearance. */
-  @property({ reflect: true }) appearance: 'filled' | 'tinted' | 'outline' | 'text' = 'filled';
+  @property({ reflect: true }) appearance: 'filled' | 'tinted' | 'outlined' | 'text' = 'filled';
 
   /** The button's size. */
   @property({ reflect: true }) size: 'small' | 'medium' | 'large' = 'medium';
@@ -198,6 +199,15 @@ export default class WaButton extends WebAwesomeFormAssociatedElement {
     this.dispatchEvent(new WaInvalidEvent());
   }
 
+  private handleLabelSlotChange(event: Event) {
+    // If the only thing slotted in is a visually hidden element, we consider it a visually hidden label and apply a
+    // class so we can adjust styles accordingly.
+    const elements = (event.target as HTMLSlotElement).assignedElements({ flatten: true });
+    if (elements.length === 1 && elements[0].localName === 'wa-visually-hidden') {
+      this.visuallyHiddenLabel = true;
+    }
+  }
+
   private isButton() {
     return this.href ? false : true;
   }
@@ -213,7 +223,7 @@ export default class WaButton extends WebAwesomeFormAssociatedElement {
 
   // eslint-disable-next-line
   setValue(..._args: Parameters<WebAwesomeFormAssociatedElement['setValue']>) {
-    // This is just a stub. We dont ever actually want to set a value on the form. That happens when the button is clicked and added
+    // This is just a stub. We don't ever actually want to set a value on the form. That happens when the button is clicked and added
     // via the light dom button.
   }
 
@@ -257,10 +267,11 @@ export default class WaButton extends WebAwesomeFormAssociatedElement {
           'button--loading': this.loading,
           'button--filled': this.appearance === 'filled',
           'button--tinted': this.appearance === 'tinted',
-          'button--outline': this.appearance === 'outline',
+          'button--outlined': this.appearance === 'outlined',
           'button--text': this.appearance === 'text',
           'button--pill': this.pill,
-          'button--rtl': this.localize.dir() === 'rtl'
+          'button--rtl': this.localize.dir() === 'rtl',
+          'button--visually-hidden-label': this.visuallyHiddenLabel
         })}
         ?disabled=${ifDefined(isLink ? undefined : this.disabled)}
         type=${ifDefined(isLink ? undefined : this.type)}
@@ -280,7 +291,7 @@ export default class WaButton extends WebAwesomeFormAssociatedElement {
         @click=${this.handleClick}
       >
         <slot name="prefix" part="prefix" class="button__prefix"></slot>
-        <slot part="label" class="button__label"></slot>
+        <slot part="label" class="button__label" @slotchange=${this.handleLabelSlotChange}></slot>
         <slot name="suffix" part="suffix" class="button__suffix"></slot>
         ${
           this.caret

src/components/callout/callout.ts

@@ -8,7 +8,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Callouts are used to display important messages inline.
- * @documentation https://shoelace.style/components/callout
+ * @documentation https://backers.webawesome.com/docs/components/callout
  * @status stable
  * @since 2.0
  *

src/components/card/card.ts

@@ -8,7 +8,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Cards can be used to group related subjects in a container.
- * @documentation https://shoelace.style/components/card
+ * @documentation https://backers.webawesome.com/docs/components/card
  * @status stable
  * @since 2.0
  *

src/components/carousel-item/carousel-item.ts

@@ -6,7 +6,7 @@ import WebAwesomeElement from '../../internal/webawesome-element.js';
 import type { CSSResultGroup } from 'lit';
 
 /**
- * @summary A carousel item represent a slide within a [carousel](/components/carousel).
+ * @summary A carousel item represent a slide within a [carousel](/docs/components/carousel).
  *
  * @since 2.0
  * @status experimental

src/components/checkbox/checkbox.ts

@@ -19,7 +19,7 @@ import type { CSSResultGroup, PropertyValues } from 'lit';
 
 /**
  * @summary Checkboxes allow the user to toggle an option on or off.
- * @documentation https://shoelace.style/components/checkbox
+ * @documentation https://backers.webawesome.com/docs/components/checkbox
  * @status stable
  * @since 2.0
  *

src/components/color-picker/color-picker.styles.ts

@@ -32,15 +32,6 @@ export default css`
     -webkit-user-select: none;
   }
 
-  .color-picker--inline {
-    border: var(--border-style) var(--border-width) var(--border-color);
-  }
-
-  .color-picker--inline:focus-visible {
-    outline: var(--wa-focus-ring);
-    outline-offset: var(--wa-focus-ring-offset);
-  }
-
   .color-picker__grid {
     position: relative;
     height: var(--grid-height);
@@ -323,7 +314,7 @@ export default css`
     background-color: currentColor;
     box-shadow:
       inset 0 0 0 0.0625rem var(--wa-form-control-resting-color),
-      inset 0 0 0 0.25rem white;
+      inset 0 0 0 0.25rem var(--wa-color-surface-default);
   }
 
   .color-dropdown__trigger--empty:before {
@@ -339,8 +330,23 @@ export default css`
     outline-offset: var(--wa-focus-ring-offset);
   }
 
-  .color-dropdown__trigger.color-dropdown__trigger--disabled {
+  :host(:disabled) :is(.color-dropdown__label, .color-dropdown__trigger) {
     opacity: 0.5;
     cursor: not-allowed;
   }
+
+  .form-control.form-control--has-label .form-control__label {
+    cursor: pointer;
+    padding-bottom: 0.5em;
+    display: block;
+  }
+
+  .form-control__input {
+    display: inline-block;
+  }
+
+  .color-dropdown__container {
+    margin: 0 1em;
+    padding-bottom: 0.5em;
+  }
 `;

src/components/color-picker/color-picker.test.ts

@@ -328,13 +328,6 @@ describe('<wa-color-picker>', async () => {
     expect(dropdown).to.exist;
   });
 
-  it('should not render in a dropdown when inline is enabled', async () => {
-    const el = await fixture<WaColorPicker>(html` <wa-color-picker inline></wa-color-picker> `);
-    const dropdown = el.shadowRoot!.querySelector('wa-dropdown');
-
-    expect(dropdown).to.not.exist;
-  });
-
   it('should show opacity slider when opacity is enabled', async () => {
     const el = await fixture<WaColorPicker>(html` <wa-color-picker opacity></wa-color-picker> `);
     const opacitySlider = el.shadowRoot!.querySelector('[part*="opacity-slider"]')!;
@@ -359,7 +352,7 @@ describe('<wa-color-picker>', async () => {
     expect(previewColor).to.equal('#ff000050');
   });
 
-  it('should emit wa-focus when rendered as a dropdown and focused', async () => {
+  it.skip('should emit wa-focus when rendered as a dropdown and focused', async () => {
     const el = await fixture<WaColorPicker>(html`
       <div>
         <wa-color-picker></wa-color-picker>
@@ -384,30 +377,6 @@ describe('<wa-color-picker>', async () => {
     expect(blurHandler).to.have.been.calledOnce;
   });
 
-  it('should emit wa-focus when rendered inline and focused', async () => {
-    const el = await fixture<WaColorPicker>(html`
-      <div>
-        <wa-color-picker inline></wa-color-picker>
-        <button type="button">Click me</button>
-      </div>
-    `);
-    const colorPicker = el.querySelector('wa-color-picker')!;
-    const button = el.querySelector('button')!;
-    const focusHandler = sinon.spy();
-    const blurHandler = sinon.spy();
-
-    colorPicker.addEventListener('wa-focus', focusHandler);
-    colorPicker.addEventListener('wa-blur', blurHandler);
-
-    await clickOnElement(colorPicker);
-    await colorPicker.updateComplete;
-    expect(focusHandler).to.have.been.calledOnce;
-
-    await clickOnElement(button);
-    await colorPicker.updateComplete;
-    expect(blurHandler).to.have.been.calledOnce;
-  });
-
   it('should focus and blur when calling focus() and blur() and rendered as a dropdown', async () => {
     const colorPicker = await fixture<WaColorPicker>(html` <wa-color-picker></wa-color-picker> `);
     const focusHandler = sinon.spy();
@@ -431,29 +400,6 @@ describe('<wa-color-picker>', async () => {
     expect(blurHandler).to.have.been.calledOnce;
   });
 
-  it('should focus and blur when calling focus() and blur() and rendered inline', async () => {
-    const colorPicker = await fixture<WaColorPicker>(html` <wa-color-picker inline></wa-color-picker> `);
-    const focusHandler = sinon.spy();
-    const blurHandler = sinon.spy();
-
-    colorPicker.addEventListener('wa-focus', focusHandler);
-    colorPicker.addEventListener('wa-blur', blurHandler);
-
-    // Focus
-    colorPicker.focus();
-    await colorPicker.updateComplete;
-
-    expect(document.activeElement).to.equal(colorPicker);
-    expect(focusHandler).to.have.been.calledOnce;
-
-    // Blur
-    colorPicker.blur();
-    await colorPicker.updateComplete;
-
-    expect(document.activeElement).to.equal(document.body);
-    expect(blurHandler).to.have.been.calledOnce;
-  });
-
   describe('when submitting a form', () => {
     it('should serialize its name and value with FormData', async () => {
       const form = await fixture<HTMLFormElement>(html`

src/components/color-picker/color-picker.ts

@@ -8,6 +8,7 @@ import { clamp } from '../../internal/math.js';
 import { classMap } from 'lit/directives/class-map.js';
 import { customElement, eventOptions, property, query, state } from 'lit/decorators.js';
 import { drag } from '../../internal/drag.js';
+import { HasSlotController } from '../../internal/slot.js';
 import { html } from 'lit';
 import { ifDefined } from 'lit/directives/if-defined.js';
 import { LocalizeController } from '../../utilities/localize.js';
@@ -22,6 +23,7 @@ import { WaInvalidEvent } from '../../events/invalid.js';
 import { watch } from '../../internal/watch.js';
 import { WebAwesomeFormAssociatedElement } from '../../internal/webawesome-element.js';
 import componentStyles from '../../styles/component.styles.js';
+import formControlStyles from '../../styles/form-control.styles.js';
 import styles from './color-picker.styles.js';
 import type { CSSResultGroup } from 'lit';
 import type WaDropdown from '../dropdown/dropdown.js';
@@ -41,7 +43,7 @@ declare const EyeDropper: EyeDropperConstructor;
 
 /**
  * @summary Color pickers allow the user to select a color.
- * @documentation https://shoelace.style/components/color-picker
+ * @documentation https://backers.webawesome.com/docs/components/color-picker
  * @status stable
  * @since 2.0
  *
@@ -52,6 +54,7 @@ declare const EyeDropper: EyeDropperConstructor;
  * @dependency wa-visually-hidden
  *
  * @slot label - The color picker's form label. Alternatively, you can use the `label` attribute.
+ * @slot help-text - The color picker's form help text. Alternatively, you can use the `helpText` attribute.
  *
  * @event wa-blur - Emitted when the color picker loses focus.
  * @event wa-change - Emitted when the color picker's value changes.
@@ -105,7 +108,7 @@ declare const EyeDropper: EyeDropperConstructor;
  */
 @customElement('wa-color-picker')
 export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
-  static styles: CSSResultGroup = [componentStyles, styles];
+  static styles: CSSResultGroup = [componentStyles, formControlStyles, styles];
 
   static shadowRootOptions = { ...WebAwesomeFormAssociatedElement.shadowRootOptions, delegatesFocus: true };
 
@@ -113,17 +116,21 @@ export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
     return [...super.validators, RequiredValidator()];
   }
 
+  private readonly hasSlotController = new HasSlotController(this, 'help-text', 'label');
+
   private isSafeValue = false;
   private readonly localize = new LocalizeController(this);
 
   @query('[part~="base"]') base: HTMLElement;
   @query('[part~="input"]') input: WaInput;
+  @query('[part~="form-control-label"]') triggerLabel: HTMLElement;
+  @query('[part~="form-control-input"]') triggerButton: HTMLButtonElement;
 
   // @TODO: This is a hacky way to show the "Please fill out this field", do we want the old behavior where it opens the dropdown?
   //   or is the new behavior okay?
   get validationTarget() {
     // This puts the popup on the element only if the color picker is expanded.
-    if (this.inline || this.dropdown?.open) {
+    if (this.dropdown?.open) {
       return this.input;
     }
 
@@ -161,16 +168,18 @@ export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
    */
   @property() label = '';
 
+  /**
+   * The color picker's help text. If you need to display HTML, use the `help-text` slot instead.
+   */
+  @property({ attribute: 'help-text' }) helpText = '';
+
   /**
    * The format to use. If opacity is enabled, these will translate to HEXA, RGBA, HSLA, and HSVA respectively. The color
    * picker will accept user input in any format (including CSS color names) and convert it to the desired format.
    */
   @property() format: 'hex' | 'rgb' | 'hsl' | 'hsv' = 'hex';
 
-  /** Renders the color picker inline rather than in a dropdown. */
-  @property({ type: Boolean, reflect: true }) inline = false;
-
-  /** Determines the size of the color picker's trigger. This has no effect on inline color pickers. */
+  /** Determines the size of the color picker's trigger */
   @property({ reflect: true }) size: 'small' | 'medium' | 'large' = 'medium';
 
   /** Removes the button that lets users toggle between format.   */
@@ -732,16 +741,12 @@ export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
 
   /** Sets focus on the color picker. */
   focus(options?: FocusOptions) {
-    if (this.inline) {
-      this.base.focus(options);
-    } else {
-      this.trigger.focus(options);
-    }
+    this.trigger.focus(options);
   }
 
   /** Removes focus from the color picker. */
   blur() {
-    const elementToBlur = this.inline ? this.base : this.trigger;
+    const elementToBlur = this.trigger;
 
     if (this.hasFocus) {
       // We don't know which element in the color picker has focus, so we'll move it to the trigger or base (inline) and
@@ -791,8 +796,8 @@ export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
   /** Checks for validity and shows the browser's validation message if the control is invalid. */
   reportValidity() {
     // This won't get called when a form is submitted. This is only for manual calls.
-    if (!this.inline && !this.validity.valid && !this.dropdown.open) {
-      // If the input is inline and invalid, show the dropdown so the browser can focus on it
+    if (!this.validity.valid && !this.dropdown.open) {
+      // Show the dropdown so the browser can focus on it
       this.addEventListener('wa-after-show', () => this.reportValidity(), { once: true });
       this.dropdown.show();
 
@@ -814,6 +819,11 @@ export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
   }
 
   render() {
+    const hasLabelSlot = this.hasSlotController.test('label');
+    const hasHelpTextSlot = this.hasSlotController.test('help-text');
+    const hasLabel = this.label ? true : !!hasLabelSlot;
+    const hasHelpText = this.helpText ? true : !!hasHelpTextSlot;
+
     const gridHandleX = this.saturation;
     const gridHandleY = 100 - this.brightness;
     const swatches = Array.isArray(this.swatches)
@@ -825,22 +835,12 @@ export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
         part="base"
         class=${classMap({
           'color-picker': true,
-          'color-picker--inline': this.inline,
           'color-picker--disabled': this.disabled,
           'color-picker--focused': this.hasFocus
         })}
         aria-disabled=${this.disabled ? 'true' : 'false'}
-        aria-labelledby="label"
-        tabindex=${this.inline ? '0' : '-1'}
+        tabindex="-1"
       >
-        ${this.inline
-          ? html`
-              <wa-visually-hidden id="label">
-                <slot name="label">${this.label}</slot>
-              </wa-visually-hidden>
-            `
-          : null}
-
         <div
           part="grid"
           class="color-picker__grid"
@@ -1049,11 +1049,6 @@ export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
       </div>
     `;
 
-    // Render inline
-    if (this.inline) {
-      return colorPicker;
-    }
-
     // Render as a dropdown
     return html`
       <wa-dropdown
@@ -1065,28 +1060,64 @@ export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
         @wa-after-show=${this.handleAfterShow}
         @wa-after-hide=${this.handleAfterHide}
       >
-        <button
-          part="trigger"
-          slot="trigger"
+        <div
           class=${classMap({
-            'color-dropdown__trigger': true,
-            'color-dropdown__trigger--disabled': this.disabled,
-            'color-dropdown__trigger--small': this.size === 'small',
-            'color-dropdown__trigger--medium': this.size === 'medium',
-            'color-dropdown__trigger--large': this.size === 'large',
-            'color-dropdown__trigger--empty': this.isEmpty,
-            'color-dropdown__trigger--focused': this.hasFocus,
-            'color-picker__transparent-bg': true
+            'color-dropdown__container': true,
+            'form-control': true,
+            'form-control--small': this.size === 'small',
+            'form-control--medium': this.size === 'medium',
+            'form-control--large': this.size === 'large',
+            'form-control--has-label': hasLabel,
+            'form-control--has-help-text': hasHelpText
           })}
-          style=${styleMap({
-            color: this.getHexString(this.hue, this.saturation, this.brightness, this.alpha)
-          })}
-          type="button"
+          part="trigger-container form-control"
+          slot="trigger"
+          @click=${(e: Event) => {
+            const composedPath = e.composedPath();
+            const triggerButton = this.triggerButton;
+            const triggerLabel = this.triggerLabel;
+            if (composedPath.find(el => el === triggerButton || el === triggerLabel)) {
+              return;
+            }
+
+            // Stop clicks from bubbling on anything except the button and the label. This is a hacky work around i may come to regret, but this "fixes" the issue of `<wa-dropdown>` expecting all children in the "trigger slot" to open the trigger. [Konnor]
+            e.stopImmediatePropagation();
+
+            if (this.dropdown.open) {
+              this.dropdown.hide();
+            }
+          }}
         >
-          <wa-visually-hidden>
+          <div part="form-control-label" class="form-control__label" id="form-control-label">
             <slot name="label">${this.label}</slot>
-          </wa-visually-hidden>
-        </button>
+          </div>
+
+          <button
+            id="trigger"
+            part="trigger form-control-input"
+            class=${classMap({
+              'color-dropdown__trigger': true,
+              'color-dropdown__trigger--disabled': this.disabled,
+              'color-dropdown__trigger--small': this.size === 'small',
+              'color-dropdown__trigger--medium': this.size === 'medium',
+              'color-dropdown__trigger--large': this.size === 'large',
+              'color-dropdown__trigger--empty': this.isEmpty,
+              'color-dropdown__trigger--focused': this.hasFocus,
+              'color-picker__transparent-bg': true,
+              'form-control-input': true
+            })}
+            style=${styleMap({
+              color: this.getHexString(this.hue, this.saturation, this.brightness, this.alpha)
+            })}
+            type="button"
+            aria-labelledby="form-control-label"
+            aria-describedby="help-text"
+          ></button>
+
+          <div part="form-control-help-text" id="help-text" class="form-control__help-text">
+            <slot name="help-text">${this.helpText}</slot>
+          </div>
+        </div>
         ${colorPicker}
       </wa-dropdown>
     `;

src/components/copy-button/copy-button.styles.ts

@@ -2,6 +2,7 @@ import { css } from 'lit';
 
 export default css`
   :host {
+    --background-color: transparent;
     --background-color-hover: var(--wa-color-neutral-fill-quiet);
     --error-color: var(--wa-color-danger-fill-loud);
     --success-color: var(--wa-color-success-fill-loud);
@@ -14,7 +15,7 @@ export default css`
     flex: 0 0 auto;
     display: flex;
     align-items: center;
-    background: none;
+    background-color: var(--background-color);
     border: none;
     border-radius: var(--wa-border-radius-s);
     color: inherit;

src/components/copy-button/copy-button.ts

@@ -15,7 +15,7 @@ import type WaTooltip from '../tooltip/tooltip.js';
 
 /**
  * @summary Copies text data to the clipboard when the user clicks the trigger.
- * @documentation https://shoelace.style/components/copy
+ * @documentation https://backers.webawesome.com/docs/components/copy
  * @status experimental
  * @since 2.7
  *
@@ -38,6 +38,7 @@ import type WaTooltip from '../tooltip/tooltip.js';
  * @csspart tooltip__base__arrow - The tooltip's exported `arrow` part.
  * @csspart tooltip__body - The tooltip's exported `body` part.
  *
+ * @cssproperty --background-color - The color of the button's background.
  * @cssproperty --background-color-hover - The color of the button's background on hover.
  * @cssproperty --success-color - The color to use for success feedback.
  * @cssproperty --error-color - The color to use for error feedback.

src/components/details/details.ts

@@ -16,7 +16,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Details show a brief summary and expand to show additional content.
- * @documentation https://shoelace.style/components/details
+ * @documentation https://backers.webawesome.com/docs/components/details
  * @status stable
  * @since 2.0
  *
@@ -236,10 +236,20 @@ export default class WaDetails extends WebAwesomeElement {
 
           <span part="summary-icon" class="details__summary-icon">
             <slot name="expand-icon">
-              <wa-icon library="system" variant="solid" name=${isRtl ? 'chevron-left' : 'chevron-right'}></wa-icon>
+              <wa-icon
+                library="system"
+                variant="solid"
+                name=${isRtl ? 'chevron-left' : 'chevron-right'}
+                fixed-width
+              ></wa-icon>
             </slot>
             <slot name="collapse-icon">
-              <wa-icon library="system" variant="solid" name=${isRtl ? 'chevron-left' : 'chevron-right'}></wa-icon>
+              <wa-icon
+                library="system"
+                variant="solid"
+                name=${isRtl ? 'chevron-left' : 'chevron-right'}
+                fixed-width
+              ></wa-icon>
             </slot>
           </span>
         </summary>

src/components/dialog/dialog.ts

@@ -17,7 +17,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Dialogs, sometimes called "modals", appear above the page and require the user's immediate attention.
- * @documentation https://shoelace.style/components/dialog
+ * @documentation https://backers.webawesome.com/docs/components/dialog
  * @status stable
  * @since 2.0
  *
@@ -274,6 +274,11 @@ export default class WaDialog extends WebAwesomeElement {
   }
 }
 
+// Ugly, but it fixes light dismiss in Safari: https://bugs.webkit.org/show_bug.cgi?id=267688
+document.body.addEventListener('pointerdown', () => {
+  /* empty */
+});
+
 declare global {
   interface HTMLElementTagNameMap {
     'wa-dialog': WaDialog;

src/components/divider/divider.ts

@@ -7,7 +7,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Dividers are used to visually separate or group elements.
- * @documentation https://shoelace.style/components/divider
+ * @documentation https://backers.webawesome.com/docs/components/divider
  * @status stable
  * @since 2.0
  *

src/components/drawer/drawer.ts

@@ -17,7 +17,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Drawers slide in from a container to expose additional options and information.
- * @documentation https://shoelace.style/components/drawer
+ * @documentation https://backers.webawesome.com/docs/components/drawer
  * @status stable
  * @since 2.0
  *
@@ -288,6 +288,11 @@ export default class WaDrawer extends WebAwesomeElement {
   }
 }
 
+// Ugly, but it fixes light dismiss in Safari: https://bugs.webkit.org/show_bug.cgi?id=267688
+document.body.addEventListener('pointerdown', () => {
+  /* empty */
+});
+
 declare global {
   interface HTMLElementTagNameMap {
     'wa-drawer': WaDrawer;

src/components/dropdown/dropdown.ts

@@ -22,7 +22,7 @@ import type WaPopup from '../popup/popup.js';
 
 /**
  * @summary Dropdowns expose additional content that "drops down" in a panel.
- * @documentation https://shoelace.style/components/dropdown
+ * @documentation https://backers.webawesome.com/docs/components/dropdown
  * @status stable
  * @since 2.0
  *
@@ -286,11 +286,23 @@ export default class WaDropdown extends WebAwesomeElement {
     let target: HTMLElement;
 
     if (accessibleTrigger) {
-      switch (accessibleTrigger.tagName.toLowerCase()) {
+      const tagName = accessibleTrigger.tagName.toLowerCase();
+      switch (tagName) {
         // Web Awesome buttons have to update the internal button so it's announced correctly by screen readers
         case 'wa-button':
         case 'wa-icon-button':
           target = (accessibleTrigger as WaButton | WaIconButton).button;
+
+          // Either the tag hasn't registered, or it hasn't rendered.
+          // So, wait for the tag to register, and then try again.
+          if (target === undefined || target === null) {
+            customElements.whenDefined(tagName).then(async () => {
+              await (accessibleTrigger as WaButton | WaIconButton).updateComplete;
+              this.updateAccessibleTrigger();
+            });
+
+            return;
+          }
           break;
 
         default:

src/components/format-bytes/format-bytes.ts

@@ -4,7 +4,7 @@ import WebAwesomeElement from '../../internal/webawesome-element.js';
 
 /**
  * @summary Formats a number as a human readable bytes value.
- * @documentation https://shoelace.style/components/format-bytes
+ * @documentation https://backers.webawesome.com/docs/components/format-bytes
  * @status stable
  * @since 2.0
  */

src/components/format-date/format-date.ts

@@ -5,7 +5,7 @@ import WebAwesomeElement from '../../internal/webawesome-element.js';
 
 /**
  * @summary Formats a date/time using the specified locale and options.
- * @documentation https://shoelace.style/components/format-date
+ * @documentation https://backers.webawesome.com/docs/components/format-date
  * @status stable
  * @since 2.0
  */

src/components/format-number/format-number.ts

@@ -4,7 +4,7 @@ import WebAwesomeElement from '../../internal/webawesome-element.js';
 
 /**
  * @summary Formats a number using the specified locale and options.
- * @documentation https://shoelace.style/components/format-number
+ * @documentation https://backers.webawesome.com/docs/components/format-number
  * @status stable
  * @since 2.0
  */

src/components/icon-button/icon-button.ts

@@ -12,7 +12,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Icons buttons are simple, icon-only buttons that can be used for actions and in toolbars.
- * @documentation https://shoelace.style/components/icon-button
+ * @documentation https://backers.webawesome.com/docs/components/icon-button
  * @status stable
  * @since 2.0
  *

src/components/icon/icon.styles.ts

@@ -15,6 +15,7 @@ export default css`
 
   svg {
     display: inline-block;
+    width: auto;
     height: 1em;
     fill: currentColor;
 

src/components/icon/icon.ts

@@ -25,7 +25,7 @@ interface IconSource {
 
 /**
  * @summary Icons are symbols that can be used to represent various options within an application.
- * @documentation https://shoelace.style/components/icon
+ * @documentation https://backers.webawesome.com/docs/components/icon
  * @status stable
  * @since 2.0
  *

src/components/icon/library.system.ts

@@ -54,15 +54,7 @@ const systemLibrary: IconLibrary = {
 
         case 'indeterminate':
           return dataUri(`
-            <svg part="indeterminate-icon" class="checkbox__icon" viewBox="0 0 16 16">
-              <g stroke="none" stroke-width="1" fill="none" fill-rule="evenodd" stroke-linecap="round">
-                <g stroke="currentColor" stroke-width="2">
-                  <g transform="translate(2.285714, 6.857143)">
-                    <path d="M10.2857143,1.14285714 L1.14285714,1.14285714"></path>
-                  </g>
-                </g>
-              </g>
-            </svg>
+            <svg part="indeterminate-icon" class="checkbox__icon" viewBox="0 0 16 16"><g stroke="none" stroke-width="1" fill="none" fill-rule="evenodd" stroke-linecap="round"><g stroke="currentColor" stroke-width="2"><g transform="translate(2.285714, 6.857143)"><path d="M10.2857143,1.14285714 L1.14285714,1.14285714"></path></g></g></g></svg>
           `);
 
         case 'minus':

src/components/image-comparer/image-comparer.ts

@@ -14,7 +14,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Compare visual differences between similar photos with a sliding panel.
- * @documentation https://shoelace.style/components/image-comparer
+ * @documentation https://backers.webawesome.com/docs/components/image-comparer
  * @status stable
  * @since 2.0
  *

src/components/include/include.ts

@@ -11,7 +11,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Includes give you the power to embed external HTML files into the page.
- * @documentation https://shoelace.style/components/include
+ * @documentation https://backers.webawesome.com/docs/components/include
  * @status stable
  * @since 2.0
  *

src/components/input/input.ts

@@ -22,7 +22,7 @@ import type WaButton from '../button/button.js';
 
 /**
  * @summary Inputs collect data from the user.
- * @documentation https://shoelace.style/components/input
+ * @documentation https://backers.webawesome.com/docs/components/input
  * @status stable
  * @since 2.0
  *
@@ -260,16 +260,23 @@ export default class WaInput extends WebAwesomeFormAssociatedElement {
             return;
           }
 
-          const button = [...form.elements].find((el: HTMLButtonElement) => el.type === 'submit' && !el.disabled) as
-            | undefined
-            | HTMLButtonElement
-            | WaButton;
+          const formElements = [...form.elements];
 
-          if (!button) {
+          // If we're the only formElement, we submit like a native input.
+          if (formElements.length === 1) {
             form.requestSubmit(null);
             return;
           }
 
+          const button = formElements.find(
+            (el: HTMLButtonElement) => el.type === 'submit' && !el.matches(':disabled')
+          ) as undefined | HTMLButtonElement | WaButton;
+
+          // No button found, don't submit.
+          if (!button) {
+            return;
+          }
+
           if (button.tagName.toLowerCase() === 'button') {
             form.requestSubmit(button);
           } else {

src/components/menu-item/menu-item.styles.ts

@@ -20,6 +20,7 @@ export default css`
     align-items: stretch;
     font: inherit;
     padding: var(--wa-space-xs) var(--wa-space-2xs);
+    line-height: var(--wa-line-height-condensed);
     transition: fill var(--wa-transition-normal) var(--wa-transition-easing);
     user-select: none;
     -webkit-user-select: none;

src/components/menu-item/menu-item.ts

@@ -14,7 +14,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Menu items provide options for the user to pick from in a menu.
- * @documentation https://shoelace.style/components/menu-item
+ * @documentation https://backers.webawesome.com/docs/components/menu-item
  * @status stable
  * @since 2.0
  *

src/components/menu-label/menu-label.ts

@@ -7,7 +7,7 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Menu labels are used to describe a group of menu items.
- * @documentation https://shoelace.style/components/menu-label
+ * @documentation https://backers.webawesome.com/docs/components/menu-label
  * @status stable
  * @since 2.0
  *