Merge branch 'next' into llms-txt

* Fix tree-item initial RTL check

* Update packages/webawesome/src/components/tree-item/tree-item.ts

---------

Co-authored-by: Cory LaViska <cory@abeautifulsite.net>

.prettierignore

@@ -20,4 +20,5 @@ packages/**/*/src/react/index.ts
 node_modules
 
 packages/**/*/_site
+packages/**/*/_bundle_
 packages/webawesome/docs/assets/scripts/prism-downloaded.js

VERSIONS.txt

@@ -1 +1,2 @@
 3.0.0
+3.1.0

cspell.json

@@ -70,6 +70,7 @@
     "exportparts",
     "fetchpriority",
     "fieldsets",
+    "flexbox",
     "focusin",
     "focusout",
     "fontawesome",
@@ -114,6 +115,9 @@
     "listbox",
     "listitem",
     "litelement",
+    "llm",
+    "llms",
+    "llmstxt",
     "longform",
     "lowercasing",
     "Lucide",
@@ -151,6 +155,7 @@
     "ParamagicDev",
     "peta",
     "petabit",
+    "pointercancel",
     "Preact",
     "preconnect",
     "prerendered",
@@ -204,6 +209,8 @@
     "thead",
     "Themer",
     "tinycolor",
+    "touchcancel",
+    "touchend",
     "transitionend",
     "treeitem",
     "treeshaking",
@@ -237,8 +244,6 @@
     "src/translations/!(en).ts",
     "**/*.min.js"
   ],
-  "ignoreRegExpList": [
-    "(^|[^a-z])sl[a-z]*(^|[^a-z])"
-  ],
+  "ignoreRegExpList": ["(^|[^a-z])sl[a-z]*(^|[^a-z])"],
   "useGitignore": true
 }

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@webawesome/monorepo",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@webawesome/monorepo",
-      "version": "3.0.0",
+      "version": "3.1.0",
       "license": "MIT",
       "workspaces": [
         "packages/*"
@@ -14023,7 +14023,7 @@
     },
     "packages/webawesome": {
       "name": "@awesome.me/webawesome",
-      "version": "3.0.0",
+      "version": "3.1.0",
       "license": "MIT",
       "dependencies": {
         "@ctrl/tinycolor": "4.1.0",
@@ -14040,6 +14040,7 @@
         "@wc-toolkit/jsx-types": "^1.3.0",
         "eleventy-plugin-git-commit-date": "^0.1.3",
         "esbuild": "^0.25.11",
+        "gray-matter": "^4.0.3",
         "npm-check-updates": "^19.1.2"
       },
       "engines": {
@@ -14048,7 +14049,7 @@
     },
     "packages/webawesome-pro": {
       "name": "@awesome.me/webawesome-pro",
-      "version": "3.0.0",
+      "version": "3.1.0",
       "dependencies": {
         "@ctrl/tinycolor": "4.1.0",
         "@floating-ui/dom": "^1.6.13",

package.json

@@ -2,7 +2,7 @@
   "name": "@webawesome/monorepo",
   "private": true,
   "description": "A forward-thinking library of web components.",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "homepage": "https://webawesome.com/",
   "author": "Web Awesome",
   "license": "MIT",

packages/webawesome/custom-elements-manifest.js

@@ -7,6 +7,7 @@ import fs from 'fs';
 import * as path from 'node:path';
 import { pascalCase } from 'pascal-case';
 import * as url from 'url';
+import { llmsTxtPlugin } from './scripts/llms.js';
 const __dirname = url.fileURLToPath(new URL('.', import.meta.url));
 
 const packageData = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf8'));
@@ -188,6 +189,13 @@ export default {
       },
     }),
 
+    // Generate llms.txt
+    llmsTxtPlugin({
+      outdir,
+      docsDir: path.join(__dirname, 'docs'),
+      baseUrl: 'https://webawesome.com',
+    }),
+
     //
     // TODO - figure out why this broke when events were updated
     //

packages/webawesome/docs/_includes/sidebar.njk

@@ -29,8 +29,12 @@
   <li><a href="/docs/resources/contributing">Contributing</a></li>
   <li><a href="/docs/resources/changelog">Changelog</a></li>
   <li><a href="/docs/resources/visual-tests">Visual Tests</a></li>
-
-
+  <li>
+    <a class="wa-cluster wa-gap-xs" href="/docs/resources/llms">
+      LLMs
+      <wa-icon name="flask" aria-hidden="true" class="icon-shrink"></wa-icon>
+    </a>
+  </li>
 </ul>
 
 <!-- Components -->
@@ -196,6 +200,8 @@
   </h2>
   <ul>
     <li><a href="/docs/utilities/align-items/">Align Items</a></li>
+    <!-- Pending 3.2.0 release -->
+    <!-- <li><a href="/docs/utilities/justify-content/">Justify Content</a></li> -->
     <li><a href="/docs/utilities/gap/">Gap</a></li>
     <li><a href="/docs/utilities/cluster/">Cluster</a></li>
     <li><a href="/docs/utilities/flank/">Flank</a></li>

packages/webawesome/docs/assets/scripts/search.js

@@ -1,12 +1,24 @@
 // Search data
 const version = document.documentElement.getAttribute('data-version') || '';
-const res = await Promise.all([import('https://cdn.jsdelivr.net/npm/lunr/+esm'), fetch(`/search.json?v=${version}`)]);
+const res = await Promise.all([
+  import('https://cdn.jsdelivr.net/npm/lunr/+esm'),
+  fetch(`/search.json?v=${version}`),
+  import('/assets/scripts/track.js').catch(() => null),
+]);
 const lunr = res[0].default;
 const searchData = await res[1].json();
 const searchIndex = lunr.Index.load(searchData.searchIndex);
 const map = searchData.map;
 const searchDebounce = 200;
+const queryTrackDelay = 1000;
 let searchTimeout;
+let queryTrackTimeout;
+let lastTrackedQuery = '';
+let resultSelected = false;
+
+// Optional event tracking - works standalone if track.js isn't available
+const trackModule = res[2];
+const trackEvent = trackModule?.trackEvent || window.trackEvent || (() => {});
 
 // We're using Turbo, so references to these elements aren't guaranteed to remain intact
 function getElements() {
@@ -17,6 +29,24 @@ function getElements() {
   };
 }
 
+function trackQuerySubmit(query, resultSelectedValue) {
+  if (!query || query.length === 0) return;
+
+  const { results } = getElements();
+  if (!results) return;
+
+  const matches = results.querySelectorAll('li').length;
+  const truncatedQuery = query.length > 500 ? query.substring(0, 500) : query;
+
+  trackEvent('navigation:search_query_submit', {
+    query: truncatedQuery,
+    query_length: query.length,
+    result_count: matches,
+    has_results: matches > 0,
+    result_selected: resultSelectedValue,
+  });
+}
+
 // Show the search dialog when slash (or CMD+K) is pressed and focus is not inside a form element
 document.addEventListener('keydown', event => {
   if (
@@ -42,40 +72,98 @@ document.addEventListener('click', event => {
 
 function show() {
   const { dialog, input, results } = getElements();
+  if (!dialog || !input || !results) return;
 
+  const wasAlreadyOpen = dialog.open;
+
+  // Remove existing listeners before adding to prevent duplicates
+  input.removeEventListener('input', handleInput);
+  results.removeEventListener('click', handleSelection);
+  dialog.removeEventListener('keydown', handleKeyDown);
+  dialog.removeEventListener('wa-hide', handleClose);
+  resultSelected = false;
+  lastTrackedQuery = '';
   input.addEventListener('input', handleInput);
   results.addEventListener('click', handleSelection);
   dialog.addEventListener('keydown', handleKeyDown);
   dialog.addEventListener('wa-hide', handleClose);
   dialog.open = true;
+  if (!wasAlreadyOpen) {
+    trackEvent('navigation:search_dialog_open');
+  }
 }
 
-function hide() {
+function cleanup() {
   const { dialog, input, results } = getElements();
-
+  if (!dialog || !input || !results) return;
+  clearTimeout(searchTimeout);
+  clearTimeout(queryTrackTimeout);
   input.removeEventListener('input', handleInput);
   results.removeEventListener('click', handleSelection);
   dialog.removeEventListener('keydown', handleKeyDown);
   dialog.removeEventListener('wa-hide', handleClose);
-  dialog.open = false;
+
+  // Reset state to prevent leakage between dialog sessions
+  resultSelected = false;
+  lastTrackedQuery = '';
 }
 
-function handleClose() {
-  const { input } = getElements();
+async function handleClose() {
+  const { dialog, input } = getElements();
+  if (!dialog || !input) return;
+  clearTimeout(queryTrackTimeout);
+  queryTrackTimeout = null;
+  dialog.removeEventListener('wa-hide', handleClose);
+  if (!resultSelected) {
+    const query = input.value.trim();
+    if (query.length > 0 && query !== lastTrackedQuery) {
+      trackQuerySubmit(query, false);
+      lastTrackedQuery = query;
+    }
+  }
 
   input.value = '';
-  updateResults();
+  try {
+    await updateResults();
+  } catch (error) {
+    // Silently handle errors - UI cleanup should continue
+  }
+  cleanup();
+  trackEvent('navigation:search_dialog_close');
 }
 
 function handleInput() {
   const { input } = getElements();
-
+  if (!input) return;
   clearTimeout(searchTimeout);
-  searchTimeout = setTimeout(() => updateResults(input.value), searchDebounce);
+  clearTimeout(queryTrackTimeout);
+
+  const query = input.value.trim();
+
+  if (query.length === 0) {
+    lastTrackedQuery = '';
+  }
+
+  searchTimeout = setTimeout(async () => {
+    await updateResults(query);
+    if (query.length > 0 && query !== lastTrackedQuery) {
+      queryTrackTimeout = setTimeout(() => {
+        const { input: currentInput, results } = getElements();
+        if (!currentInput || resultSelected) return;
+
+        const currentQuery = currentInput.value.trim();
+        if (currentQuery === query && currentQuery !== lastTrackedQuery) {
+          trackQuerySubmit(currentQuery, false);
+          lastTrackedQuery = currentQuery;
+        }
+      }, queryTrackDelay);
+    }
+  }, searchDebounce);
 }
 
 function handleKeyDown(event) {
   const { input, results } = getElements();
+  if (!input || !results) return;
 
   // Handle keyboard selections
   if (['ArrowDown', 'ArrowUp', 'Home', 'End', 'Enter'].includes(event.key)) {
@@ -104,7 +192,12 @@ function handleKeyDown(event) {
         nextEl = items[items.length - 1];
         break;
       case 'Enter':
-        currentEl?.querySelector('a')?.click();
+        if (currentEl) {
+          const link = currentEl.querySelector('a');
+          if (link) {
+            selectResult(link, 'keyboard_enter');
+          }
+        }
         break;
     }
 
@@ -121,27 +214,62 @@ function handleKeyDown(event) {
   }
 }
 
+function selectResult(link, selectionMethod) {
+  const { input, results } = getElements();
+  if (!input || !link) return;
+
+  // Clear pending query tracking timeout to prevent duplicate events
+  clearTimeout(queryTrackTimeout);
+  queryTrackTimeout = null;
+  resultSelected = true; // Set immediately so timeout callback (if executing) sees it
+
+  const query = input.value.trim();
+  if (!link.dataset.searchResultIndex) return;
+  const resultIndex = parseInt(link.dataset.searchResultIndex, 10);
+  if (isNaN(resultIndex) || resultIndex < 1) return;
+
+  const resultUrl = link.dataset.searchResultUrl || link.getAttribute('href');
+  if (!resultUrl) return;
+  lastTrackedQuery = query;
+  trackQuerySubmit(query, true);
+  trackEvent('navigation:search_result_click', {
+    query,
+    result_index: resultIndex,
+    result_url: resultUrl,
+    selection_method: selectionMethod,
+  });
+
+  const { dialog } = getElements();
+  if (dialog) {
+    dialog.removeEventListener('wa-hide', handleClose);
+    cleanup();
+    trackEvent('navigation:search_dialog_close');
+    dialog.open = false;
+  }
+
+  if (window.Turbo) {
+    Turbo.visit(resultUrl);
+  } else {
+    location.href = resultUrl;
+  }
+}
+
 function handleSelection(event) {
   const link = event.target.closest('a');
 
   if (link) {
     event.preventDefault();
-    hide();
-
-    if (window.Turbo) {
-      Turbo.visit(link.href);
-    } else {
-      location.href = link.href;
-    }
+    selectResult(link, 'mouse_click');
   }
 }
 
 // Queries the search index and updates the results
 async function updateResults(query = '') {
   const { dialog, input, results } = getElements();
-
+  if (!dialog || !input || !results) return;
   try {
-    const hasQuery = query.length > 0;
+    const trimmedQuery = query.trim();
+    const hasQuery = trimmedQuery.length > 0;
     let matches = [];
 
     if (hasQuery) {
@@ -149,13 +277,13 @@ async function updateResults(query = '') {
       const seenRefs = new Set();
 
       // Start with a standard search to get the best "exact match" result
-      searchIndex.search(`${query}`).forEach(match => {
+      searchIndex.search(`${trimmedQuery}`).forEach(match => {
         matches.push(match);
         seenRefs.add(match.ref);
       });
 
       // Add wildcard matches if not already included
-      searchIndex.search(`${query}*`).forEach(match => {
+      searchIndex.search(`${trimmedQuery}*`).forEach(match => {
         if (!seenRefs.has(match.ref)) {
           matches.push(match);
           seenRefs.add(match.ref);
@@ -163,11 +291,10 @@ async function updateResults(query = '') {
       });
 
       // Add fuzzy search matches last
-      const fuzzyTokens = query
+      const fuzzyTokens = trimmedQuery
         .split(' ')
         .map(term => `${term}~1`)
         .join(' ');
-
       searchIndex.search(fuzzyTokens).forEach(match => {
         if (!seenRefs.has(match.ref)) {
           matches.push(match);
@@ -180,12 +307,12 @@ async function updateResults(query = '') {
 
     dialog.classList.toggle('has-results', hasQuery && hasResults);
     dialog.classList.toggle('no-results', hasQuery && !hasResults);
-
     input.setAttribute('aria-activedescendant', '');
     results.innerHTML = '';
-
     matches.forEach((match, index) => {
       const page = map[match.ref];
+      if (!page || !page.url) return;
+
       const li = document.createElement('li');
       const a = document.createElement('a');
       const displayTitle = page.title ?? '';
@@ -197,12 +324,10 @@ async function updateResults(query = '') {
       li.setAttribute('role', 'option');
       li.setAttribute('id', `search-result-item-${match.ref}`);
       li.setAttribute('data-selected', index === 0 ? 'true' : 'false');
-
       if (page.url === '/') icon = 'home';
       if (page.url.startsWith('/docs/utilities/native')) icon = 'code';
       if (page.url.startsWith('/docs/components')) icon = 'puzzle-piece';
       if (page.url.startsWith('/docs/theme') || page.url.startsWith('/docs/restyle')) icon = 'palette';
-
       a.href = page.url;
       a.innerHTML = `
         <div class="site-search-result-icon" aria-hidden="true">
@@ -218,6 +343,9 @@ async function updateResults(query = '') {
       a.querySelector('.site-search-result-description').textContent = displayDescription;
       a.querySelector('.site-search-result-url').textContent = displayUrl;
 
+      // Use 1-based indexing for analytics
+      a.dataset.searchResultIndex = (index + 1).toString();
+      a.dataset.searchResultUrl = page.url;
       li.appendChild(a);
       results.appendChild(li);
     });

packages/webawesome/docs/assets/styles/docs.css

@@ -10,6 +10,13 @@
 :root {
   --wa-brand-orange: #f36944;
   --wa-brand-grey: #30323b;
+
+  /* layout-based example style aspects */
+  --layout-example-border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
+  --layout-example-border-radius: var(--wa-border-radius-l);
+  --layout-example-padding: var(--wa-space-s);
+  --layout-example-element-background: var(--wa-color-indigo-60);
+  --layout-example-element-border-radius: var(--wa-border-radius-m);
 }
 
 .wa-dark .only-light,

packages/webawesome/docs/assets/styles/utils.css

@@ -130,6 +130,13 @@
     }
   }
 
+  /* dialogs */
+  wa-dialog:has([slot='footer']) [slot='footer'] {
+    border-block-start: var(--wa-border-width-s) solid var(--wa-color-surface-border);
+    flex-grow: 1; /* make footer contents span entire width of dialog */
+    padding-block-start: var(--wa-space-l);
+  }
+
   /* anchor headings  */
   .anchor-heading a {
     opacity: 0;
@@ -250,7 +257,6 @@
       z-index: 0;
     }
   }
-  /* #endregion */
 
   /* buttons with icon toggle on hover */
   wa-button .icon-hover {
@@ -262,6 +268,13 @@
   wa-button:hover .icon-hover {
     display: inline-flex;
   }
+
+  /* buttons that are "shushed" (visually muted) by default, but have their full presentation otherwise  */
+  wa-button.shush {
+    &:not(:hover):not(active)::part(base) {
+      color: var(--wa-color-text-quiet);
+    }
+  }
   /* #endregion */
 
   /* #region resets */

packages/webawesome/docs/docs/components/dialog.md

@@ -178,11 +178,11 @@ If you want the dialog to close when the user clicks on the overlay, add the `li
 
 ### Preventing the Dialog from Closing
 
-By default, dialogs will close when the user clicks the close button, clicks the overlay, or presses the [[Escape]] key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.
+By default, dialogs will close when the user clicks the close button or presses the [[Escape]] key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.
 
 To keep the dialog open in such cases, you can cancel the `wa-hide` event. When canceled, the dialog will remain open and pulse briefly to draw the user's attention to it.
 
-You can use `event.detail.source` to determine which element triggered the request to close. This example prevents the dialog from closing when the overlay is clicked, but allows the close button or [[Escape]] to dismiss it.
+You can use `event.detail.source` to determine which element triggered the request to close. This example prevents the dialog from closing unless a specific button is clicked.
 
 ```html {.example}
 <wa-dialog label="Dialog" class="dialog-deny-close">

packages/webawesome/docs/docs/components/divider.md

@@ -41,7 +41,7 @@ Use the `--spacing` custom property to change the amount of space between the di
 
 ### Orientation
 
-The default orientation for dividers is `horizontal`. Set `orientation` attribute to `vertical` to draw a vertical divider. The divider will span the full height of its container.
+The default orientation for dividers is `horizontal`. Set `orientation` attribute to `vertical` to draw a vertical divider. The divider will span the full height of its [Flexbox](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox) or [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/grid) container.
 
 ```html {.example}
 <div style="display: flex; align-items: center;">
@@ -53,6 +53,10 @@ The default orientation for dividers is `horizontal`. Set `orientation` attribut
 </div>
 ```
 
+:::info
+If your container isn't Flexbox or CSS Grid, you may need to set an explicit height for the divider.
+:::
+
 ### Dropdown Dividers
 
 Use dividers in [dropdowns](/docs/components/dropdown) to visually group dropdown items.

packages/webawesome/docs/docs/resources/changelog.md

@@ -11,6 +11,24 @@ Web Awesome follows [Semantic Versioning](https://semver.org/). Breaking changes
 
 Components with the <wa-badge variant="warning">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.
 
+## Next
+
+- Added llms.txt to assist AI agents with using Web Awesome [discuss:1100]
+- Added `justify-content` CSS utilities [pr:1930]
+- Added missing `.wa-gap-4xl` utility class [pr:1931]
+- Added `pointercancel` and `touchcancel` event handling to draggable elements to prevent drags from getting stuck
+- Added `wa-justify-content-*` utility classes [pr:1930]
+- Added missing `wa-gap-4xl` utility class [pr:1931]
+- Added `track` and `indicator` CSS parts to `<wa-progress-ring>` [pr:1863]
+- Fixed a bug in `<wa-combobox>` that prevented the listbox from opening when options were preselected [issue:1883]
+- Fixed a bug in `<wa-popup>` and `<wa-dropdown-item>` that caused an error when removing a popup while it was opening [issue:1910]
+- Fixed a bug in `<wa-popup>` and `<wa-dropdown>` that caused errors when shadow DOM queries returned null [issue:1911]
+- Fixed a bug in `<wa-combobox>` that prevented the listbox from opening when options were preselected [issue:1883]
+- Fixed a bug in draggable elements that caused a TypeError on `touchend` events when `event.touches` was empty
+- Fixed a bug in `<wa-tree-item>` that caused the cursor to show a pointer when no expand icon was present [pr:1936]
+- Fixed a bug in `<wa-tree-item>` that caused the chevron to render the wrong direction in RTL [pr:1798]
+- Modified `wa-align-items-*` utility classes to apply `display: flex` by default [pr:1943]
+
 ## 3.1.0
 
 - Added `<wa-combobox>` as an experimental pro component [issue:1074]
@@ -516,4 +534,4 @@ Many of these changes and improvements were the direct result of feedback from u
 
 </details>
 
-Did we miss something? [Let us know!](https://github.com/shoelace-style/webawesome/discussions)
+Did we miss something? [Let us know!](https://github.com/shoelace-style/webawesome/discussions)

packages/webawesome/docs/docs/resources/llms.md

@@ -0,0 +1,86 @@
+---
+title: LLMs
+description: Web Awesome provides an llms.txt file to help AI assistants understand and work with our components.
+layout: page-outline
+---
+
+The [llms.txt specification](https://llmstxt.org/) is a proposed standard for providing information to large language models (LLMs) in a format they can easily consume. It's like a robots.txt, but instead of telling search engines how to crawl your site, it helps AI assistants understand your project.
+
+Web Awesome publishes an `llms.txt` file that provides AI tools with structured information about our components, including their APIs, properties, events, methods, slots, and CSS custom properties.
+
+:::warning
+This feature is experimental! The llms.txt format and its contents may change as we refine the output based on feedback and evolving AI capabilities.
+:::
+
+## Why Use It?
+
+When working with AI coding assistants like Claude, ChatGPT, Copilot, or Cursor, you can reference the llms.txt file to give the AI context about Web Awesome components. This can lead to more accurate code suggestions and fewer hallucinations when the AI generates Web Awesome code.
+
+## Accessing the File
+
+The llms.txt file is available in every Web Awesome build at:
+
+```
+/dist/llms.txt
+/dist-cdn/llms.txt
+```
+
+You can also find it in your `node_modules` directory if you've installed Web Awesome via npm:
+
+```
+node_modules/@awesome.me/webawesome/dist/llms.txt
+```
+
+## How to Use It
+
+How you reference the file depends on which AI tool you're using.
+
+### Claude Projects
+
+If you're using [Claude Projects](https://www.anthropic.com/news/projects), you can add the llms.txt URL to your project knowledge. Claude will use this context when helping you write Web Awesome code.
+
+### Cursor
+
+In [Cursor](https://cursor.sh/), you can add the file to your project's documentation sources via **Cursor Settings > Features > Docs**. You can also reference the file directly in chat using `@Docs` after adding it, or paste the content into the chat context.
+
+### VS Code + Copilot
+
+GitHub Copilot in VS Code doesn't have a built-in way to reference external documentation files, but you can:
+
+1. Copy the llms.txt file into your project's root directory
+2. Open it in a VS Code tab (Copilot considers open files as context)
+3. Use `#file` in Copilot Chat to explicitly reference it (e.g., `#file:llms.txt how do I create a dialog?`)
+
+### VS Code + Claude Code
+
+If you're using the [Claude Code extension](https://marketplace.visualstudio.com/items?itemName=anthropics.claude-code), you can reference the file directly by path:
+
+```
+@node_modules/@awesome.me/webawesome/dist/llms.txt
+```
+
+Or simply ask Claude to read it — Claude Code can access files in your project directly.
+
+### Other AI Tools
+
+Most AI coding assistants allow you to provide context through URLs, file uploads, or direct pasting. Check your tool's documentation for the best way to include external references.
+
+## What's Included
+
+The llms.txt file contains:
+
+- An overview of Web Awesome and its capabilities
+- Links to documentation sections
+- A complete list of all components with descriptions
+- Detailed API reference for each component including:
+  - Slots
+  - Properties and their types
+  - Methods and their signatures
+  - Events
+  - CSS custom properties
+  - CSS parts
+  - CSS states
+
+## Feedback
+
+Since this is experimental, we'd love to hear how it works for you! If you find issues with the generated content or have suggestions for improvement, please [open an issue on GitHub](https://github.com/shoelace-style/webawesome/issues).

packages/webawesome/docs/docs/utilities/align-items.md

@@ -1,35 +1,37 @@
 ---
 title: Align Items
-description: Align items utilities set the gap property of flex and grid containers, like other Web Awesome layout utilities.
+description: Align items utilities align items within flex and grid containers on the cross axis.
 layout: docs
 tags: layoutUtilities
 ---
 
 <style>
   .preview-wrapper {
-    border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
+    border: var(--layout-example-border);
     border-radius: var(--wa-border-radius-m);
     min-block-size: 3em;
+    min-inline-size: 5em;
     padding: var(--wa-space-2xs);
   }
+  
   .preview-block {
     aspect-ratio: 1 / 1;
-    background-color: var(--wa-color-neutral-fill-loud);
+    background-color: var(--layout-example-element-background);
     border-radius: var(--wa-border-radius-s);
     min-block-size: 1em;
   }
 </style>
 
-Web Awesome includes classes to set the `align-items` property of flex and grid containers. They can be used alongside other Web Awesome layout utilities, like [cluster](/docs/utilities/cluster) and [stack](/docs/utilities/stack), to align children in container on the container's cross axis.
+Web Awesome includes classes to set the `align-items` property of flex and grid containers. Use them alongside other Web Awesome layout utilities, like [cluster](/docs/utilities/cluster) and [stack](/docs/utilities/stack), to align items in a container on the container's [cross axis](#whats-the-cross-axis).
 
-| Class Name                | `align-items` Value | Preview                                                                                                                                  |
-| ------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `wa-align-items-baseline` | `baseline`          | <div class="wa-cluster wa-align-items-baseline preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div> |
-| `wa-align-items-center`   | `center`            | <div class="wa-cluster wa-align-items-center preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div>   |
-| `wa-align-items-end`      | `flex-end`          | <div class="wa-cluster wa-align-items-end preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div>      |
-| `wa-align-items-start`    | `flex-start`        | <div class="wa-cluster wa-align-items-start preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div>    |
-| `wa-align-items-stretch`  | `stretch`           | <div class="wa-cluster wa-align-items-stretch preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div>  |
+| Class Name                | `align-items` Value | Preview                                                                                                                                             |
+| ------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `wa-align-items-baseline` | `baseline`          | <div class="wa-cluster wa-gap-2xs wa-align-items-baseline preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div> |
+| `wa-align-items-center`   | `center`            | <div class="wa-cluster wa-gap-2xs wa-align-items-center preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div>   |
+| `wa-align-items-end`      | `flex-end`          | <div class="wa-cluster wa-gap-2xs wa-align-items-end preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div>      |
+| `wa-align-items-start`    | `flex-start`        | <div class="wa-cluster wa-gap-2xs wa-align-items-start preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div>    |
+| `wa-align-items-stretch`  | `stretch`           | <div class="wa-cluster wa-gap-2xs wa-align-items-stretch preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div>  |
 
-## What's a Cross Axis?
+## What's the Cross Axis?
 
-The cross axis runs perpendicular to a flex container's content direction. For containers where `flex-direction` is `row` and content flows in the inline direction, the cross axis runs in the block direction. For containers where `flex-direction` is `column` and content flows in the block direction, the cross axis runs in the inline direction.
+The cross axis runs perpendicular to a container's content direction. For containers where `flex-direction` is `row` and content flows in the inline direction, the cross axis runs in the block direction. For containers where `flex-direction` is `column` and content flows in the block direction, the cross axis runs in the inline direction.

packages/webawesome/docs/docs/utilities/cluster.md

@@ -7,19 +7,21 @@ tags: layoutUtilities
 
 <style>
   :is(.wa-flank, .wa-grid, .wa-stack) > [class*='wa-cluster']:has(div:empty) {
-    border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
-    border-radius: var(--wa-border-radius-l);
-    padding: var(--wa-space-s);
+    border: var(--layout-example-border);
+    border-radius: var(--layout-example-border-radius);
+    padding: var(--layout-example-padding);
   }
 
   [class*='wa-cluster'] div:empty {
-    background-color: var(--wa-color-indigo-60);
-    border-radius: var(--wa-border-radius-m);
+    background-color: var(--layout-example-element-background);
+    border-radius: var(--layout-example-element-border-radius);
     min-block-size: 4rem;
     min-inline-size: 4rem;
   }
 </style>
 
+{{ description }}
+
 ```html {.example}
 <div class="wa-cluster">
   <div></div>

packages/webawesome/docs/docs/utilities/flank.md

@@ -7,20 +7,20 @@ tags: layoutUtilities
 
 <style>
   :is(.wa-flank, .wa-grid, .wa-stack) > [class*='wa-flank']:has(div:empty) {
-    border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
-    border-radius: var(--wa-border-radius-l);
-    padding: var(--wa-space-s);
+    border: var(--layout-example-border);
+    border-radius: var(--layout-example-border-radius);
+    padding: var(--layout-example-padding);
   }
 
   [class*='wa-flank'] div:empty {
-    background-color: var(--wa-color-indigo-60);
-    border-radius: var(--wa-border-radius-m);
+    background-color: var(--layout-example-element-background);
+    border-radius: var(--layout-example-element-border-radius);
     min-block-size: 4rem;
     min-inline-size: 4rem;
   }
 </style>
 
-When space is limited, the items wrap.
+{{ description }} When space is limited, the items wrap.
 
 ```html {.example}
 <div class="wa-flank">

packages/webawesome/docs/docs/utilities/frame.md

@@ -7,18 +7,20 @@ tags: layoutUtilities
 
 <style>
   [class*='wa-frame']:has(div:empty) {
-    border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
-    padding: var(--wa-space-s);
+    border: var(--layout-example-border);
+    padding: var(--layout-example-padding);
   }
 
   [class*='wa-frame'] div:empty {
-    background-color: var(--wa-color-indigo-60);
-    border-radius: var(--wa-border-radius-m);
+    background-color: var(--layout-example-element-background);
+    border-radius: var(--layout-example-element-border-radius);
     min-block-size: 4rem;
     min-inline-size: 4rem;
   }
 </style>
 
+{{ description }}
+
 ```html {.example}
 <div class="wa-frame" style="max-inline-size: 20rem;">
   <div></div>

packages/webawesome/docs/docs/utilities/gap.md

@@ -6,28 +6,37 @@ tags: layoutUtilities
 ---
 
 <style>
+  .preview-wrapper {
+    border: var(--layout-example-border);
+    border-radius: var(--wa-border-radius-m);
+    min-block-size: 3em;
+    min-inline-size: 5em;
+    padding: var(--wa-space-2xs);
+  }
+
   .preview-block {
     aspect-ratio: 1 / 1;
-    background-color: var(--wa-color-neutral-fill-loud);
+    background-color: var(--layout-example-element-background);
     border-radius: var(--wa-border-radius-s);
-    min-block-size: 1.5em;
+    min-block-size: 1em;
   }
 </style>
 
-Web Awesome includes classes to set the `gap` property of flex and grid containers. They can be used alongside other Web Awesome layout utilities, like [cluster](/docs/utilities/cluster) and [stack](/docs/utilities/stack), to change the space between items.
-Or even by themselves — all gap properties also set `display: flex` with a specificity of 0 so that it can be trivially overridden.
+Web Awesome includes classes to set the `gap` property of flex and grid containers. Use them alone to create a flex container with a gap, or use them alongside other Web Awesome layout utilities, like [cluster](/docs/utilities/cluster) and [stack](/docs/utilities/stack), to change the space between items.
 
 Besides `wa-gap-0`, which sets `gap` to zero, each class corresponds to one of the [`--wa-space-*`](/docs/tokens/space) tokens in your theme.
 
 | Class Name   | `gap` Value      | Preview                                                                                                     |
 | ------------ | ---------------- | ----------------------------------------------------------------------------------------------------------- |
-| `wa-gap-0`   | `0`              | <div class="wa-cluster wa-gap-0"><div class="preview-block"></div><div class="preview-block"></div></div>   |
-| `wa-gap-3xs` | `--wa-space-3xs` | <div class="wa-cluster wa-gap-3xs"><div class="preview-block"></div><div class="preview-block"></div></div> |
-| `wa-gap-2xs` | `--wa-space-2xs` | <div class="wa-cluster wa-gap-2xs"><div class="preview-block"></div><div class="preview-block"></div></div> |
-| `wa-gap-xs`  | `--wa-space-xs`  | <div class="wa-cluster wa-gap-xs"><div class="preview-block"></div><div class="preview-block"></div></div>  |
-| `wa-gap-s`   | `--wa-space-s`   | <div class="wa-cluster wa-gap-s"><div class="preview-block"></div><div class="preview-block"></div></div>   |
-| `wa-gap-m`   | `--wa-space-m`   | <div class="wa-cluster wa-gap-m"><div class="preview-block"></div><div class="preview-block"></div></div>   |
-| `wa-gap-l`   | `--wa-space-l`   | <div class="wa-cluster wa-gap-l"><div class="preview-block"></div><div class="preview-block"></div></div>   |
-| `wa-gap-xl`  | `--wa-space-xl`  | <div class="wa-cluster wa-gap-xl"><div class="preview-block"></div><div class="preview-block"></div></div>  |
-| `wa-gap-2xl` | `--wa-space-2xl` | <div class="wa-cluster wa-gap-2xl"><div class="preview-block"></div><div class="preview-block"></div></div> |
-| `wa-gap-3xl` | `--wa-space-3xl` | <div class="wa-cluster wa-gap-3xl"><div class="preview-block"></div><div class="preview-block"></div></div> |
+| `wa-gap-0`   | `0`              | <div class="preview-wrapper wa-cluster wa-gap-0"><div class="preview-block"></div><div class="preview-block"></div></div>   |
+| `wa-gap-3xs` | `--wa-space-3xs` | <div class="preview-wrapper wa-cluster wa-gap-3xs"><div class="preview-block"></div><div class="preview-block"></div></div> |
+| `wa-gap-2xs` | `--wa-space-2xs` | <div class="preview-wrapper wa-cluster wa-gap-2xs"><div class="preview-block"></div><div class="preview-block"></div></div> |
+| `wa-gap-xs`  | `--wa-space-xs`  | <div class="preview-wrapper wa-cluster wa-gap-xs"><div class="preview-block"></div><div class="preview-block"></div></div>  |
+| `wa-gap-s`   | `--wa-space-s`   | <div class="preview-wrapper wa-cluster wa-gap-s"><div class="preview-block"></div><div class="preview-block"></div></div>   |
+| `wa-gap-m`   | `--wa-space-m`   | <div class="preview-wrapper wa-cluster wa-gap-m"><div class="preview-block"></div><div class="preview-block"></div></div>   |
+| `wa-gap-l`   | `--wa-space-l`   | <div class="preview-wrapper wa-cluster wa-gap-l"><div class="preview-block"></div><div class="preview-block"></div></div>   |
+| `wa-gap-xl`  | `--wa-space-xl`  | <div class="preview-wrapper wa-cluster wa-gap-xl"><div class="preview-block"></div><div class="preview-block"></div></div>  |
+| `wa-gap-2xl` | `--wa-space-2xl` | <div class="preview-wrapper wa-cluster wa-gap-2xl"><div class="preview-block"></div><div class="preview-block"></div></div> |
+| `wa-gap-3xl` | `--wa-space-3xl` | <div class="preview-wrapper wa-cluster wa-gap-3xl"><div class="preview-block"></div><div class="preview-block"></div></div> |
+<!-- Pending 3.2.0 release -->
+<!-- | `wa-gap-4xl` | `--wa-space-4xl` | <div class="preview-wrapper wa-cluster wa-gap-4xl"><div class="preview-block"></div><div class="preview-block"></div></div> | -->

packages/webawesome/docs/docs/utilities/grid.md

@@ -7,19 +7,21 @@ tags: layoutUtilities
 
 <style>
   :is(.wa-flank, .wa-grid, .wa-stack) > [class*='wa-grid']:has(div:empty) {
-    border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
-    border-radius: var(--wa-border-radius-l);
-    padding: var(--wa-space-s);
+    border: var(--layout-example-border);
+    border-radius: var(--layout-example-border-radius);
+    padding: var(--layout-example-padding);
   }
 
   [class*='wa-grid'] div:empty {
-    background-color: var(--wa-color-indigo-60);
-    border-radius: var(--wa-border-radius-m);
+    background-color: var(--layout-example-element-background);
+    border-radius: var(--layout-example-element-border-radius);
     min-block-size: 4rem;
     min-inline-size: 4rem;
   }
 </style>
 
+{{ description }}
+
 ```html {.example}
 <div class="wa-grid">
   <div></div>

packages/webawesome/docs/docs/utilities/justify-content.md

@@ -0,0 +1,40 @@
+---
+title: Justify Content
+description: Justify content utilities determine how space is distributed between items in flex and grid containers.
+layout: docs
+tags: layoutUtilities
+unpublished: true
+unlisted: true
+---
+
+<style>
+  .preview-wrapper {
+    border: var(--layout-example-border);
+    border-radius: var(--wa-border-radius-m);
+    min-block-size: 3em;
+    min-inline-size: 5em;
+    padding: var(--wa-space-2xs);
+  }
+
+  .preview-block {
+    aspect-ratio: 1 / 1;
+    background-color: var(--layout-example-element-background);
+    border-radius: var(--wa-border-radius-s);
+    min-block-size: 1em;
+  }
+</style>
+
+Web Awesome includes classes to set the `justify-content` property of flex and grid containers. Use them alongside other Web Awesome layout utilities, like [cluster](/docs/utilities/cluster) and [stack](/docs/utilities/stack), to distribute space between items along the container's [main axis](#whats-the-main-axis).
+
+| Class Name                         | `justify-content` Value | Preview                                                                                                                                                      |
+| ---------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `wa-justify-content-start`         | `flex-start`            | <div class="wa-cluster wa-gap-2xs wa-justify-content-start preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div>         |
+| `wa-justify-content-end`           | `flex-end`              | <div class="wa-cluster wa-gap-2xs wa-justify-content-end preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div>           |
+| `wa-justify-content-center`        | `center`                | <div class="wa-cluster wa-gap-2xs wa-justify-content-center preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div>        |
+| `wa-justify-content-space-around`  | `space-around`          | <div class="wa-cluster wa-gap-2xs wa-justify-content-space-around preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div>  |
+| `wa-justify-content-space-between` | `space-between`         | <div class="wa-cluster wa-gap-2xs wa-justify-content-space-between preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div> |
+| `wa-justify-content-space-evenly`  | `space-evenly`          | <div class="wa-cluster wa-gap-2xs wa-justify-content-space-evenly preview-wrapper"><div class="preview-block"></div><div class="preview-block"></div></div>  |
+
+## What's the Main Axis?
+
+The main axis runs parallel to a container's content direction. For grid containers and flex containers where `flex-direction` is `row`, the main axis runs in the inline direction. For containers where `flex-direction` is `column`, the main axis runs in the block direction.

packages/webawesome/docs/docs/utilities/split.md

@@ -7,19 +7,21 @@ tags: layoutUtilities
 
 <style>
   :is(.wa-flank, .wa-grid, .wa-stack) > [class*='wa-split']:has(div:empty) {
-    border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
-    border-radius: var(--wa-border-radius-l);
-    padding: var(--wa-space-s);
+    border: var(--layout-example-border);
+    border-radius: var(--layout-example-border-radius);
+    padding: var(--layout-example-padding);
   }
 
   [class*='wa-split'] div:empty {
-    background-color: var(--wa-color-indigo-60);
-    border-radius: var(--wa-border-radius-m);
+    background-color: var(--layout-example-element-background);
+    border-radius: var(--layout-example-element-border-radius);
     min-block-size: 4rem;
     min-inline-size: 4rem;
   }
 </style>
 
+{{ description }}
+
 ```html {.example}
 <div class="wa-split">
   <div></div>

packages/webawesome/docs/docs/utilities/stack.md

@@ -7,19 +7,21 @@ tags: layoutUtilities
 
 <style>
   :is(.wa-flank, .wa-grid, .wa-stack) > [class*='wa-stack']:has(div:empty) {
-    border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
-    border-radius: var(--wa-border-radius-l);
-    padding: var(--wa-space-s);
+    border: var(--layout-example-border);
+    border-radius: var(--layout-example-border-radius);
+    padding: var(--layout-example-padding);
   }
 
   [class*='wa-stack'] div:empty {
-    background-color: var(--wa-color-indigo-60);
-    border-radius: var(--wa-border-radius-m);
+    background-color: var(--layout-example-element-background);
+    border-radius: var(--layout-example-element-border-radius);
     min-block-size: 4rem;
     min-inline-size: 4rem;
   }
 </style>
 
+{{ description }}
+
 ```html {.example}
 <div class="wa-stack">
   <div></div>

packages/webawesome/package.json

@@ -92,6 +92,7 @@
     "@wc-toolkit/jsx-types": "^1.3.0",
     "eleventy-plugin-git-commit-date": "^0.1.3",
     "esbuild": "^0.25.11",
+    "gray-matter": "^4.0.3",
     "npm-check-updates": "^19.1.2"
   }
 }

packages/webawesome/scripts/llms.js

@@ -0,0 +1,257 @@
+import fs from 'fs';
+import matter from 'gray-matter';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { getAllComponents } from './shared.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** Removes newlines from text to keep llms.txt formatting clean. */
+function removeNewlines(str) {
+  return str ? str.replace(/\n/g, ' ').trim() : '';
+}
+
+/** Loads front-matter from all component markdown files. */
+function loadAllFrontMatter(components, docsDir) {
+  const cache = new Map();
+
+  for (const component of components) {
+    const componentName = component.tagName.replace(/^wa-/, '');
+    const mdPath = path.join(docsDir, 'docs/components', `${componentName}.md`);
+
+    if (fs.existsSync(mdPath)) {
+      try {
+        const content = fs.readFileSync(mdPath, 'utf-8');
+        const { data } = matter(content);
+        cache.set(component.tagName, data);
+      } catch {
+        // Skip if parsing fails
+      }
+    }
+  }
+
+  return cache;
+}
+
+/** Generates the API reference section for a single component. */
+function generateComponentApiSection(component, frontMatterCache, baseUrl) {
+  const lines = [];
+  const frontMatter = frontMatterCache.get(component.tagName);
+  const componentSlug = component.tagName.replace(/^wa-/, '');
+  const description = removeNewlines(frontMatter?.description || component.summary || '');
+
+  lines.push(`#### \`<${component.tagName}>\``);
+  lines.push('');
+  lines.push(`**Description:** ${description || 'No description available.'}`);
+  lines.push('');
+  lines.push(`**Documentation:** ${baseUrl}/docs/components/${componentSlug}`);
+  lines.push('');
+
+  // Slots
+  if (component.slots?.length > 0) {
+    lines.push('**Slots:**');
+    lines.push('');
+    for (const slot of component.slots) {
+      const slotName = slot.name || '(default)';
+      lines.push(`- \`${slotName}\`: ${removeNewlines(slot.description) || 'No description.'}`);
+    }
+    lines.push('');
+  }
+
+  // Properties
+  const properties =
+    component.members?.filter(m => m.kind === 'field' && m.privacy !== 'private' && m.description) || [];
+
+  if (properties.length > 0) {
+    lines.push('**Properties:**');
+    lines.push('');
+    for (const prop of properties) {
+      // Find corresponding attribute if any
+      const attr = component.attributes?.find(a => a.fieldName === prop.name);
+      const attrNote = attr && attr.name !== prop.name ? ` (attribute: \`${attr.name}\`)` : '';
+      const typeStr = prop.type?.text ? `Type: \`${removeNewlines(prop.type.text)}\`` : '';
+      const defaultStr = prop.default ? `Default: \`${prop.default}\`` : '';
+      const meta = [typeStr, defaultStr].filter(Boolean).join(', ');
+
+      lines.push(
+        `- \`${prop.name}\`${attrNote}: ${removeNewlines(prop.description) || 'No description.'}${meta ? ` (${meta})` : ''}`,
+      );
+    }
+    lines.push('');
+  }
+
+  // Methods
+  const methods = component.members?.filter(m => m.kind === 'method' && m.privacy !== 'private' && m.description) || [];
+
+  if (methods.length > 0) {
+    lines.push('**Methods:**');
+    lines.push('');
+    for (const method of methods) {
+      const params = method.parameters?.length
+        ? `(${method.parameters.map(p => `${p.name}: ${removeNewlines(p.type?.text) || 'unknown'}`).join(', ')})`
+        : '()';
+      lines.push(`- \`${method.name}${params}\`: ${removeNewlines(method.description) || 'No description.'}`);
+    }
+    lines.push('');
+  }
+
+  // Events
+  const events = component.events?.filter(e => e.name) || [];
+  if (events.length > 0) {
+    lines.push('**Events:**');
+    lines.push('');
+    for (const event of events) {
+      lines.push(`- \`${event.name}\`: ${removeNewlines(event.description) || 'No description.'}`);
+    }
+    lines.push('');
+  }
+
+  // CSS Custom Properties
+  if (component.cssProperties?.length > 0) {
+    lines.push('**CSS Custom Properties:**');
+    lines.push('');
+    for (const prop of component.cssProperties) {
+      const defaultStr = prop.default ? ` (Default: \`${prop.default}\`)` : '';
+      lines.push(`- \`${prop.name}\`: ${removeNewlines(prop.description) || 'No description.'}${defaultStr}`);
+    }
+    lines.push('');
+  }
+
+  // CSS Parts
+  if (component.cssParts?.length > 0) {
+    lines.push('**CSS Parts:**');
+    lines.push('');
+    for (const part of component.cssParts) {
+      lines.push(`- \`${part.name}\`: ${removeNewlines(part.description) || 'No description.'}`);
+    }
+    lines.push('');
+  }
+
+  // CSS States
+  if (component.cssStates?.length > 0) {
+    lines.push('**CSS States:**');
+    lines.push('');
+    for (const state of component.cssStates) {
+      lines.push(`- \`${state.name}\`: ${removeNewlines(state.description) || 'No description.'}`);
+    }
+    lines.push('');
+  }
+
+  return lines;
+}
+
+/**
+ * Generates the complete llms.txt content.
+ */
+function generateLlmsTxt({ components, packageData, frontMatterCache, baseUrl }) {
+  const lines = [];
+
+  // H1 Title (required by llmstxt.org spec)
+  lines.push('# Web Awesome');
+  lines.push('');
+
+  // Blockquote summary
+  lines.push(`> ${packageData.description} Version ${packageData.version}.`);
+  lines.push('');
+
+  // Overview section
+  lines.push(
+    `
+Web Awesome provides a comprehensive set of customizable, accessible web components for building modern
+web applications. All components use shadow DOM and are framework-agnostic, working with vanilla JavaScript
+or any framework including React, Vue, Angular, and Svelte.
+
+Form controls are form-associated custom elements that work with native form validation and the
+Constraint Validation API.
+
+Font Awesome is the default icon library, so \`<wa-icon name="...">\` values should reference Font Awesome
+icon names.
+`.trim(),
+  );
+  lines.push('');
+
+  //
+  // Documentation
+  //
+  lines.push('## Documentation');
+  lines.push('');
+  lines.push(`For comprehensive documentation, visit ${baseUrl}/docs/`);
+  lines.push('');
+  lines.push(`- [Getting Started](${baseUrl}/docs/getting-started): Installation and setup guide`);
+  lines.push(`- [Components Overview](${baseUrl}/docs/components): Complete component reference`);
+  lines.push(`- [Theming](${baseUrl}/docs/theming): Customization and design tokens`);
+  lines.push(`- [Form Controls](${baseUrl}/docs/form-controls): Form integration and validation`);
+  lines.push('');
+
+  //
+  // Components
+  //
+  lines.push('## Components');
+  lines.push('');
+
+  const sortedComponentsList = [...components].sort((a, b) => a.tagName.localeCompare(b.tagName));
+
+  for (const component of sortedComponentsList) {
+    const frontMatter = frontMatterCache.get(component.tagName);
+    const description = removeNewlines(frontMatter?.description || component.summary || '');
+    const componentSlug = component.tagName.replace(/^wa-/, '');
+    const title = frontMatter?.title || componentSlug;
+
+    lines.push(
+      `- [${title}](${baseUrl}/docs/components/${componentSlug}): ${description || 'No description available.'}`,
+    );
+  }
+  lines.push('');
+
+  //
+  // Optional
+  //
+  lines.push('## Optional');
+  lines.push('');
+  lines.push(
+    `The following is a quick reference describing every component's API. For comprehensive documentation, refer to the component documentation using the URLs provided above.`,
+  );
+  lines.push('');
+
+  // Sort components alphabetically by tag name for the API reference
+  const sortedComponents = [...components].sort((a, b) => a.tagName.localeCompare(b.tagName));
+
+  for (const component of sortedComponents) {
+    lines.push(...generateComponentApiSection(component, frontMatterCache, baseUrl));
+  }
+
+  return lines.join('\n').trim();
+}
+
+/**
+ * A CEM plugin that generates an llms.txt file following the llmstxt.org specification.
+ */
+export function llmsTxtPlugin(options = {}) {
+  const {
+    outdir = 'dist-cdn',
+    docsDir = path.resolve(__dirname, '../docs'),
+    baseUrl = 'https://webawesome.com',
+  } = options;
+
+  return {
+    name: 'wa-llms-txt',
+    packageLinkPhase({ customElementsManifest }) {
+      const components = getAllComponents(customElementsManifest);
+      const packageData = customElementsManifest.package || {};
+      const frontMatterCache = loadAllFrontMatter(components, docsDir);
+
+      const llmsTxt = generateLlmsTxt({
+        components,
+        packageData,
+        frontMatterCache,
+        baseUrl,
+      });
+
+      // Write to the output directory
+      const outputPath = path.join(outdir, 'llms.txt');
+      fs.writeFileSync(outputPath, llmsTxt, 'utf-8');
+    },
+  };
+}
+
+export default llmsTxtPlugin;

packages/webawesome/scripts/plop/plopfile.js

@@ -37,7 +37,7 @@ export default function (plop) {
       },
       {
         type: 'add',
-        path: '../../src/components/{{ tagWithoutPrefix tag }}/{{ tagWithoutPrefix tag }}.css',
+        path: '../../src/components/{{ tagWithoutPrefix tag }}/{{ tagWithoutPrefix tag }}.styles.ts',
         templateFile: 'templates/component/styles.hbs',
       },
       {

packages/webawesome/scripts/plop/templates/component/component.hbs

@@ -2,7 +2,7 @@ import { html } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { watch } from '../../internal/watch.js';
 import WebAwesomeElement from '../../internal/webawesome-element.js';
-import styles from './{{ tagWithoutPrefix tag }}.css';
+import styles from './{{ tagWithoutPrefix tag }}.styles.js';
 
 /**
  * @summary Short summary of the component's intended use.
@@ -21,7 +21,7 @@ import styles from './{{ tagWithoutPrefix tag }}.css';
  */
  @customElement("{{ tag }}")
 export default class {{ properCase tag }} extends WebAwesomeElement {
-  static css = styles;
+  static css = [styles];
 
   /** An example attribute. */
   @property() attr = 'example';

packages/webawesome/scripts/plop/templates/component/styles.hbs

@@ -1,3 +1,7 @@
-:host {
-  display: block;
+import { css } from "lit";
+
+export default css`
+  :host {
+    display: block;
 }
+`

packages/webawesome/scripts/update-root-version.js

@@ -10,8 +10,8 @@ const monorepoRoot = path.resolve(__dirname, '..', '..', '..');
 const rootPackageJSONFile = path.join(monorepoRoot, 'package.json');
 const webawesomePackageJSONFile = path.join(path.resolve(__dirname, '..'), 'package.json');
 
-const rootPackageJSON = JSON.parse(fs.readFileSync(rootPackageJSONFile, { encoding: "utf8" }));
-const webawesomePackageJSON = JSON.parse(fs.readFileSync(webawesomePackageJSONFile, { encoding: "utf8" }));
+const rootPackageJSON = JSON.parse(fs.readFileSync(rootPackageJSONFile, { encoding: 'utf8' }));
+const webawesomePackageJSON = JSON.parse(fs.readFileSync(webawesomePackageJSONFile, { encoding: 'utf8' }));
 
 const currentVersion = webawesomePackageJSON.version;
 rootPackageJSON.version = currentVersion;
@@ -19,7 +19,7 @@ rootPackageJSON.version = currentVersion;
 fs.writeFileSync(rootPackageJSONFile, JSON.stringify(rootPackageJSON, null, 2));
 
 const versionsFile = path.join(monorepoRoot, 'VERSIONS.txt');
-const versions = fs.readFileSync(versionsFile, { encoding: "utf8" }).split(/\r?\n/);
+const versions = fs.readFileSync(versionsFile, { encoding: 'utf8' }).split(/\r?\n/);
 
 // TODO: Make this smart and understand semver and "insert" in the correct spot instead of appending.
 if (!versions.includes(currentVersion)) {

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

@@ -1277,7 +1277,14 @@ export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
         })}
         part="trigger-container form-control"
       >
-        <div part="form-control-label" class="label" id="form-control-label">
+        <div
+          part="form-control-label"
+          class=${classMap({
+            label: true,
+            'has-label': hasLabel,
+          })}
+          id="form-control-label"
+        >
           <slot name="label">${this.label}</slot>
         </div>
 

packages/webawesome/src/components/dropdown-item/dropdown-item.ts

@@ -155,20 +155,21 @@ export default class WaDropdownItem extends WebAwesomeElement {
 
   /** Opens the submenu. */
   async openSubmenu() {
-    if (!this.hasSubmenu || !this.submenuElement) return;
+    const submenu = this.submenuElement;
+    if (!this.hasSubmenu || !submenu || !this.isConnected) return;
 
     // Notify parent dropdown to handle positioning
     this.notifyParentOfOpening();
 
     // Use Popover API to show the submenu
-    this.submenuElement.showPopover();
-    this.submenuElement.hidden = false;
-    this.submenuElement.setAttribute('data-visible', '');
+    submenu.showPopover?.();
+    submenu.hidden = false;
+    submenu.setAttribute('data-visible', '');
     this.submenuOpen = true;
     this.setAttribute('aria-expanded', 'true');
 
     // Animate the submenu
-    await animateWithClass(this.submenuElement, 'show');
+    await animateWithClass(submenu, 'show');
 
     // Set focus to the first submenu item
     setTimeout(() => {
@@ -210,16 +211,19 @@ export default class WaDropdownItem extends WebAwesomeElement {
 
   /** Closes the submenu. */
   async closeSubmenu() {
-    if (!this.hasSubmenu || !this.submenuElement) return;
+    const submenu = this.submenuElement;
+    if (!this.hasSubmenu || !submenu) return;
 
     this.submenuOpen = false;
     this.setAttribute('aria-expanded', 'false');
 
-    if (!this.submenuElement.hidden) {
-      await animateWithClass(this.submenuElement, 'hide');
-      this.submenuElement.hidden = true;
-      this.submenuElement.removeAttribute('data-visible');
-      this.submenuElement.hidePopover();
+    if (!submenu.hidden) {
+      await animateWithClass(submenu, 'hide');
+      if (submenu?.isConnected) {
+        submenu.hidden = true;
+        submenu.removeAttribute('data-visible');
+        submenu.hidePopover?.();
+      }
     }
   }
 

packages/webawesome/src/components/dropdown/dropdown.ts

@@ -138,9 +138,9 @@ export default class WaDropdown extends WebAwesomeElement {
 
   /** Gets all dropdown items slotted in the menu. */
   private getItems(includeDisabled = false): WaDropdownItem[] {
-    const items = this.defaultSlot
-      .assignedElements({ flatten: true })
-      .filter(el => el.localName === 'wa-dropdown-item') as WaDropdownItem[];
+    const items = (this.defaultSlot?.assignedElements({ flatten: true }) ?? []).filter(
+      el => el.localName === 'wa-dropdown-item',
+    ) as WaDropdownItem[];
 
     return includeDisabled ? items : items.filter(item => !item.disabled);
   }
@@ -165,9 +165,9 @@ export default class WaDropdown extends WebAwesomeElement {
 
   /** Syncs item sizes with the dropdown's size property. */
   private syncItemSizes() {
-    const items = this.defaultSlot
-      .assignedElements({ flatten: true })
-      .filter(el => el.localName === 'wa-dropdown-item') as WaDropdownItem[];
+    const items = (this.defaultSlot?.assignedElements({ flatten: true }) ?? []).filter(
+      el => el.localName === 'wa-dropdown-item',
+    ) as WaDropdownItem[];
     items.forEach(item => (item.size = this.size));
   }
 
@@ -230,7 +230,7 @@ export default class WaDropdown extends WebAwesomeElement {
   /** Shows the dropdown menu. This should only be called from within updated(). */
   private async showMenu() {
     const anchor = this.getTrigger();
-    if (!anchor) return;
+    if (!anchor || !this.popup || !this.menu) return;
 
     const showEvent = new WaShowEvent();
     this.dispatchEvent(showEvent);
@@ -270,6 +270,8 @@ export default class WaDropdown extends WebAwesomeElement {
 
   /** Hides the dropdown menu. This should only be called from within updated(). */
   private async hideMenu() {
+    if (!this.popup || !this.menu) return;
+
     const hideEvent = new WaHideEvent({ source: this });
     this.dispatchEvent(hideEvent);
     if (hideEvent.defaultPrevented) {
@@ -720,12 +722,12 @@ export default class WaDropdown extends WebAwesomeElement {
     nativeButton.setAttribute('aria-haspopup', 'menu');
     nativeButton.setAttribute('aria-expanded', this.open ? 'true' : 'false');
 
-    this.menu.setAttribute('aria-expanded', 'false');
+    this.menu?.setAttribute('aria-expanded', 'false');
   }
 
   render() {
     // On initial render, we want to use this.open, for everything else, we sync off of this.popup.active to get animations working.
-    let active = this.hasUpdated ? this.popup.active : this.open;
+    let active = this.hasUpdated ? this.popup?.active : this.open;
 
     return html`
       <wa-popup

packages/webawesome/src/components/input/input.styles.ts

@@ -6,7 +6,6 @@ export default css`
   }
 
   .text-field {
-    flex: auto;
     display: flex;
     align-items: stretch;
     justify-content: start;

packages/webawesome/src/components/input/input.test.ts

@@ -48,6 +48,27 @@ describe('<wa-input>', () => {
         expect(input.title).to.equal('Test');
       });
 
+      it('should have label with "has-label" class if label has a slotted element', async () => {
+        const el = await fixture<WaInput>(html` <wa-input><span slot="label">Name</span></wa-input> `);
+        await el.updateComplete;
+        const label = el.shadowRoot!.querySelector('[part~="form-control-label"]')!;
+        expect(label.classList.contains('has-label')).to.equal(true);
+      });
+
+      it('should have label with "has-label" class if label is provided as an attribute', async () => {
+        const el = await fixture<WaInput>(html` <wa-input label="Name"></wa-input> `);
+        await el.updateComplete;
+        const label = el.shadowRoot!.querySelector('[part~="form-control-label"]')!;
+        expect(label.classList.contains('has-label')).to.equal(true);
+      });
+
+      it('should not have "has-label" class on label if no label content is provided', async () => {
+        const el = await fixture<WaInput>(html` <wa-input></wa-input> `);
+        await el.updateComplete;
+        const label = el.shadowRoot!.querySelector('[part~="form-control-label"]')!;
+        expect(label.classList.contains('has-label')).to.equal(false);
+      });
+
       it('should be disabled with the disabled attribute', async () => {
         const el = await fixture<WaInput>(html` <wa-input disabled></wa-input> `);
         await el.updateComplete;

packages/webawesome/src/components/input/input.ts

@@ -342,7 +342,15 @@ export default class WaInput extends WebAwesomeFormAssociatedElement {
       (typeof this.value === 'number' || (this.value && this.value.length > 0));
 
     return html`
-      <label part="form-control-label label" class="label" for="input" aria-hidden=${hasLabel ? 'false' : 'true'}>
+      <label
+        part="form-control-label label"
+        class=${classMap({
+          label: true,
+          'has-label': hasLabel,
+        })}
+        for="input"
+        aria-hidden=${hasLabel ? 'false' : 'true'}
+      >
         <slot name="label">${this.label}</slot>
       </label>
 

packages/webawesome/src/components/popup/popup.ts

@@ -286,11 +286,11 @@ export default class WaPopup extends WebAwesomeElement {
 
   private start() {
     // We can't start the positioner without an anchor
-    if (!this.anchorEl || !this.active) {
+    if (!this.anchorEl || !this.active || !this.isConnected) {
       return;
     }
 
-    this.popup.showPopover?.();
+    this.popup?.showPopover?.();
 
     this.cleanup = autoUpdate(this.anchorEl, this.popup, () => {
       this.reposition();
@@ -299,7 +299,7 @@ export default class WaPopup extends WebAwesomeElement {
 
   private async stop(): Promise<void> {
     return new Promise(resolve => {
-      this.popup.hidePopover?.();
+      this.popup?.hidePopover?.();
 
       if (this.cleanup) {
         this.cleanup();
@@ -317,7 +317,7 @@ export default class WaPopup extends WebAwesomeElement {
   /** Forces the popup to recalculate and reposition itself. */
   reposition() {
     // Nothing to do if the popup is inactive or the anchor doesn't exist
-    if (!this.active || !this.anchorEl) {
+    if (!this.active || !this.anchorEl || !this.popup) {
       return;
     }
 
@@ -498,7 +498,7 @@ export default class WaPopup extends WebAwesomeElement {
   }
 
   private updateHoverBridge = () => {
-    if (this.hoverBridge && this.anchorEl) {
+    if (this.hoverBridge && this.anchorEl && this.popup) {
       const anchorRect = this.anchorEl.getBoundingClientRect();
       const popupRect = this.popup.getBoundingClientRect();
       const isVertical = this.placement.includes('top') || this.placement.includes('bottom');

packages/webawesome/src/components/progress-ring/progress-ring.ts

@@ -15,6 +15,8 @@ import styles from './progress-ring.styles.js';
  *
  * @csspart base - The component's base wrapper.
  * @csspart label - The progress ring label.
+ * @csspart track - The progress ring's track.
+ * @csspart indicator - The progress ring's indicator.
  *
  * @cssproperty --size - The diameter of the progress ring (cannot be a percentage).
  * @cssproperty --track-width - The width of the track.
@@ -70,8 +72,8 @@ export default class WaProgressRing extends WebAwesomeElement {
         style="--percentage: ${this.value / 100}"
       >
         <svg class="image">
-          <circle class="track"></circle>
-          <circle class="indicator" style="stroke-dashoffset: ${this.indicatorOffset}"></circle>
+          <circle part="track" class="track"></circle>
+          <circle part="indicator" class="indicator" style="stroke-dashoffset: ${this.indicatorOffset}"></circle>
         </svg>
 
         <slot id="label" part="label" class="label"></slot>

packages/webawesome/src/components/radio-group/radio-group.ts

@@ -352,7 +352,10 @@ export default class WaRadioGroup extends WebAwesomeFormAssociatedElement {
         <label
           part="form-control-label"
           id="label"
-          class="label"
+          class=${classMap({
+            label: true,
+            'has-label': hasLabel,
+          })}
           aria-hidden=${hasLabel ? 'false' : 'true'}
           @click=${this.handleLabelClick}
         >

packages/webawesome/src/components/select/select.ts

@@ -938,7 +938,10 @@ export default class WaSelect extends WebAwesomeFormAssociatedElement {
         <label
           id="label"
           part="form-control-label label"
-          class="label"
+          class=${classMap({
+            label: true,
+            'has-label': hasLabel,
+          })}
           aria-hidden=${hasLabel ? 'false' : 'true'}
           @click=${this.handleLabelClick}
         >

packages/webawesome/src/components/slider/slider.ts

@@ -807,7 +807,7 @@ export default class WaSlider extends WebAwesomeFormAssociatedElement {
         id="label"
         part="label"
         for=${this.isRange ? 'thumb-min' : 'text-box'}
-        class=${classMap({ vh: !hasLabel })}
+        class=${classMap({ vh: !hasLabel, 'has-label': hasLabel })}
         @pointerdown=${this.handleLabelPointerDown}
       >
         <slot name="label">${this.label}</slot>

packages/webawesome/src/components/textarea/textarea.ts

@@ -331,7 +331,15 @@ export default class WaTextarea extends WebAwesomeFormAssociatedElement {
     const hasHint = this.hint ? true : !!hasHintSlot;
 
     return html`
-      <label part="form-control-label label" class="label" for="input" aria-hidden=${hasLabel ? 'false' : 'true'}>
+      <label
+        part="form-control-label label"
+        class=${classMap({
+          label: true,
+          'has-label': hasLabel,
+        })}
+        for="input"
+        aria-hidden=${hasLabel ? 'false' : 'true'}
+      >
         <slot name="label">${this.label}</slot>
       </label>
 

packages/webawesome/src/components/tooltip/tooltip.ts

@@ -79,7 +79,7 @@ export default class WaTooltip extends WebAwesomeElement {
   /** The amount of time to wait before showing the tooltip when the user mouses in. */
   @property({ attribute: 'show-delay', type: Number }) showDelay = 150;
 
-  /** The amount of time to wait before hiding the tooltip when the user mouses out.. */
+  /** The amount of time to wait before hiding the tooltip when the user mouses out. */
   @property({ attribute: 'hide-delay', type: Number }) hideDelay = 0;
 
   /**

packages/webawesome/src/components/tree-item/tree-item.styles.ts

@@ -85,6 +85,10 @@ export default css`
     display: none;
   }
 
+  .tree-item:not(.tree-item-has-expand-button):not(.tree-item-loading) .expand-button {
+    cursor: default;
+  }
+
   .tree-item-loading .expand-icon-slot wa-icon {
     display: none;
   }

packages/webawesome/src/components/tree-item/tree-item.ts

@@ -243,7 +243,7 @@ export default class WaTreeItem extends WebAwesomeElement {
   }
 
   render() {
-    const isRtl = this.hasUpdated ? this.localize.dir() === 'rtl' : this.dir === 'rtl';
+    const isRtl = this.localize.dir() === 'rtl';
     const showExpandButton = !this.loading && (!this.isLeaf || this.lazy);
 
     return html`

packages/webawesome/src/events/events.ts

@@ -28,3 +28,4 @@ export type { WaSlideChangeEvent } from './slide-change.js';
 export type { WaStartEvent } from './start.js';
 export type { WaTabHideEvent } from './tab-hide.js';
 export type { WaTabShowEvent } from './tab-show.js';
+export type { WaVideoChangeEvent } from './video-change.js';

packages/webawesome/src/events/video-change.ts

@@ -0,0 +1,26 @@
+export class WaVideoChangeEvent extends Event {
+  readonly detail: WaVideoChangeEventDetail;
+
+  constructor(detail: WaVideoChangeEventDetail) {
+    super('wa-video-change', { bubbles: true, cancelable: false, composed: true });
+    this.detail = detail;
+  }
+}
+
+export interface WaVideoChangeEventDetail {
+  previousIndex: number;
+  currentIndex: number;
+  video: {
+    title?: string;
+    poster?: string;
+    duration?: string;
+    sources: { src: string; type: string }[];
+    tracks: { src: string; kind: string; srclang: string; label: string }[];
+  };
+}
+
+declare global {
+  interface GlobalEventHandlersEventMap {
+    'wa-video-change': WaVideoChangeEvent;
+  }
+}

packages/webawesome/src/internal/drag.ts

@@ -99,20 +99,24 @@ export class DraggableElement {
 
     document.addEventListener('pointerup', this.handleDragStop);
     document.addEventListener('pointermove', this.handleDragMove);
+    document.addEventListener('pointercancel', this.handleDragStop);
     document.addEventListener('touchend', this.handleDragStop);
     document.addEventListener('touchmove', this.handleDragMove);
+    document.addEventListener('touchcancel', this.handleDragStop);
     this.options.start(clientX, clientY);
   };
 
   private handleDragStop = (event: PointerEvent | TouchEvent) => {
-    const clientX = 'touches' in event ? event.touches[0].clientX : (event as PointerEvent).clientX;
-    const clientY = 'touches' in event ? event.touches[0].clientY : (event as PointerEvent).clientY;
+    const clientX = 'changedTouches' in event ? event.changedTouches[0].clientX : (event as PointerEvent).clientX;
+    const clientY = 'changedTouches' in event ? event.changedTouches[0].clientY : (event as PointerEvent).clientY;
 
     this.isDragging = false;
     document.removeEventListener('pointerup', this.handleDragStop);
     document.removeEventListener('pointermove', this.handleDragMove);
+    document.removeEventListener('pointercancel', this.handleDragStop);
     document.removeEventListener('touchend', this.handleDragStop);
     document.removeEventListener('touchmove', this.handleDragMove);
+    document.removeEventListener('touchcancel', this.handleDragStop);
     this.options.stop(clientX, clientY);
   };
 
@@ -141,8 +145,10 @@ export class DraggableElement {
   public stop() {
     document.removeEventListener('pointerup', this.handleDragStop);
     document.removeEventListener('pointermove', this.handleDragMove);
+    document.removeEventListener('pointercancel', this.handleDragStop);
     document.removeEventListener('touchend', this.handleDragStop);
     document.removeEventListener('touchmove', this.handleDragMove);
+    document.removeEventListener('touchcancel', this.handleDragStop);
     this.element.removeEventListener('pointerdown', this.handleDragStart);
     if (supportsTouch) {
       this.element.removeEventListener('touchstart', this.handleDragStart);

packages/webawesome/src/styles/component/form-control.styles.ts

@@ -6,8 +6,14 @@ export default css`
     flex-direction: column;
   }
 
+  /* Treat wrapped labels, inputs, and hints as direct children of the host element */
+  [part~='form-control'] {
+    display: contents;
+  }
+
   /* Label */
-  :is([part~='form-control-label'], [part~='label']):has(*:not(:empty)) {
+  :is([part~='form-control-label'], [part~='label']):has(*:not(:empty)),
+  :is([part~='form-control-label'], [part~='label']).has-label {
     display: inline-flex;
     color: var(--wa-form-control-label-color);
     font-weight: var(--wa-form-control-label-font-weight);
@@ -29,7 +35,6 @@ export default css`
     line-height: var(--wa-form-control-hint-line-height);
     margin-block-start: 0.5em;
     font-size: var(--wa-font-size-smaller);
-    line-height: var(--wa-form-control-label-line-height);
 
     &:not(.has-slotted) {
       display: none;

packages/webawesome/src/styles/utilities.css

@@ -5,6 +5,7 @@
 @import url('utilities/scroll-lock.css');
 @import url('utilities/placeholder.css');
 @import url('utilities/align-items.css');
+@import url('utilities/justify-content.css');
 @import url('utilities/border-radius.css');
 @import url('utilities/gap.css');
 @import url('utilities/text.css');

packages/webawesome/src/styles/utilities/align-items.css

@@ -1,4 +1,15 @@
 @layer wa-utilities {
+  /* Apply Flexbox with 0 specificity to ensure an align-items util produces a visible change */
+  :where(
+    .wa-align-items-start,
+    .wa-align-items-end,
+    .wa-align-items-center,
+    .wa-align-items-stretch,
+    .wa-align-items-baseline
+  ) {
+    display: flex;
+  }
+
   .wa-align-items-start {
     align-items: flex-start;
   }

packages/webawesome/src/styles/utilities/gap.css

@@ -45,4 +45,7 @@
   .wa-gap-3xl {
     gap: var(--wa-space-3xl);
   }
+  .wa-gap-4xl {
+    gap: var(--wa-space-4xl);
+  }
 }

packages/webawesome/src/styles/utilities/justify-content.css

@@ -0,0 +1,32 @@
+@layer wa-utilities {
+  /* Apply Flexbox with 0 specificity to ensure a justify-content util produces a visible change */
+  :where(
+    .wa-justify-content-start,
+    .wa-justify-content-end,
+    .wa-justify-content-center,
+    .wa-justify-content-space-around,
+    .wa-justify-content-space-between,
+    .wa-justify-content-space-evenly
+  ) {
+    display: flex;
+  }
+
+  .wa-justify-content-start {
+    justify-content: flex-start;
+  }
+  .wa-justify-content-end {
+    justify-content: flex-end;
+  }
+  .wa-justify-content-center {
+    justify-content: center;
+  }
+  .wa-justify-content-space-around {
+    justify-content: space-around;
+  }
+  .wa-justify-content-space-between {
+    justify-content: space-between;
+  }
+  .wa-justify-content-space-evenly {
+    justify-content: space-evenly;
+  }
+}

packages/webawesome/src/styles/utilities/layout.css

@@ -27,11 +27,11 @@
   [class*='wa-cluster'] {
     display: flex;
     flex-wrap: wrap;
-    justify-content: flex-start;
   }
 
   :where([class*='wa-cluster']) {
     align-items: center;
+    justify-content: flex-start;
   }
   /* #endregion */
 
@@ -75,7 +75,6 @@
   [class*='wa-frame'] {
     display: flex;
     aspect-ratio: 1 / 1;
-    justify-content: center;
     overflow: hidden;
   }
 
@@ -98,6 +97,7 @@
 
   :where([class*='wa-frame']) {
     align-items: center;
+    justify-content: center;
   }
   /* #endregion */
 
@@ -118,7 +118,6 @@
   [class*='wa-split'] {
     display: flex;
     flex-wrap: wrap;
-    justify-content: space-between;
   }
 
   [class*='wa-split'],
@@ -141,6 +140,7 @@
 
   :where([class*='wa-split']) {
     align-items: center;
+    justify-content: space-between;
   }
 
   /* #endregion */
@@ -149,11 +149,11 @@
   [class*='wa-stack'] {
     display: flex;
     flex-direction: column;
-    justify-content: flex-start;
   }
 
   :where([class*='wa-stack']) {
     align-items: stretch;
+    justify-content: flex-start;
   }
   /* #endregion */
 }